Identity Providers and Federation
RapidIdentity Federation Overview
Use RapidIdentity Federation Partners to exchange secure identity information across two or more federated domains. When an application or service is in one network and a user account is in another network, typically the user is prompted for secondary credentials when he or she attempts to access the application or service. These secondary credentials represent the user's identity in the realm where the application or service resides.
Identity federation allows secure identity information exchange across two or more federated domains. Secure exchange requires business agreements between the asserting party sending information and the relying party receiving information. These agreements also require both parties to engage in cryptographic key exchange.
RapidIdentity Federation uses various security realms to perform the mandatory operations to facilitate secure information exchange between requesting and relying parties across different domains. A requestor and the relying party must exchange configuration metadata before beginning to exchange protocol messages that specify unique identifiers to indicate the security realms represented and distinguish them from other possible federation partners and applicable URLs that indicate where protocol messages are to be sent.
Attributes: User account information and associated values used to authenticate the users/principals
Federation: Identity Federation is the process of delegating an individual's or entity's authentication responsibility to a trusted external party. Each partner in federation plays the role of either an identity provider or a service provider.
FQDN (Fully Qualified Domain Name): The complete domain name for a specific computer, or host, on the internet and consists of two parts, the hostname and the domain name.
IdP (Identity Provider): Provides attributes to identify and authenticate the end user and sends that data to the service provider along with the user’s access rights for the service to enforce the Service Provider's authentication policies.
LDAP (Lightweight Directory Access Protocol): Application protocol for querying and modifying directory services running over TCP/IP. A directory consists of a set of Entries and their attributes, typically organized hierarchically.
Relying Party: Relies on authentication and identification services provided by the IdP
SAML (Security Assertion Markup Language): Allows identity providers (IdP) to pass authorization credentials to service providers for SSO. SAML is the link between the authentication of a user’s identity and the authorization to use a service.
SAML Assertion: The XML document which the Identity Provider sends to the Service Provider that asserts if the user has authenticated successfully. Usually contains attributes about the authenticating user which the Service Provider uses for various identification and authorization purposes.
Authentication Assertions: Asserts that the user identified by the assertion successfully authenticated at a particular timestamp and with a particular method.
Attribute Assertions: Passes SAML attributes (provides information about the user) to the service provider
SP (Service Provider): Requires authentication from the identity provider to grant access rights for a service to the user.
SSO (Single Sign-on): Allows users to log in once and those same credentials are reused to log into other service providers.
RapidIdentity Federation contains a joined User and Administrator guide, as the end user is most often a system administrator or otherwise equivalent level technology professional.
RapidIdentity IdP and Portal Sessions
When a user logs into RapidIdentity, they establish both an Identity Provider (IdP) session and a Portal session. The best practice to securely complete user interaction with RapidIdentity dictates that Portal users must log out of Portal and completely close their web browser to terminate a session.
RapidIdentity Federation provides the IdP for federated authentication. The IdP is accessed by Portal for user authentication, and the session timeout is set to 9 hours. Currently, there is not an option to modify the IdP Session timeout.
IdP sessions are invalidated under any of these conditions:
IdP session timeout expires
User logs out of Portal, which redirects to the IdP logout
User logs out of the IdP directly or is redirected to the IdP logout by some other means (e.g., logging out of another federated web application)
User completely closes the web browser
Portal sessions are relevant to browser interactions with RapidIdentity Portal, and are managed by an administrator in the Configuration module. Administrators can kill portal sessions from Configuration > Security > Session Management. Portal session timeouts default to 8 hours, and can be set from Configuration > General > Settings > Authentication.
Note that when a Portal session is closed either manually or through a session timeout, the user loses access to web interaction with Portal. However, while the IdP session remains active, users will not be prompted to re-authenticate when accessing Portal again.
Federation IdP and Federation Partners Configuration
RapidIdentity Federation IdP Setup
The RapidIdentity Federation Identity Provider setup requires access to the RapidIdentity Configuration Module. Users must log in to RapidIdentity as a user with the System Administrator or Tenant Administrator role.
From Configuration, click Identity Providers in the Security options.
New Identity Provider Setup
If the Identity Provider has not yet been set up, follow the below steps.
From Identity Providers, select IDP Configuration and click Create New Configuration.
From the Identity Provider Configuration window enter the following values:
Identity Provider Configuration Type*: Automatic/Quick Configuration
Domain*: Enter the IP address of the appliance that will serve as the portal that users will access and that is allocated to the Federation activity.
The Identity Configuration workspace will then be populated with the Identity Provider Configuration data. Click here for more information on Identity Provider configuration data.
From the Configuration menu, click Integration from the Security section.
From the Integration menu, click Federation.
Federation Hostname: "localhost'
Federation Username: Enter your domain adminstrator's name
Federation Debug Level: None
Click Update Password.
Enter the Domain Administrator's password.
Click Save.
Important
You must select to Trigger Service Reload and Trigger Web Reload to activate the new attributes, or upon logging out, the server configuration will not be saved and future access will fail. An error similiar to this will appear
Validate the Identity Provider Setup
If the Identity Provider setup was performed successfully, you will be able to validate the Adminstrator login in the RapidIdeintity Portal.
Perform these steps using an appliance that has Portal_UI capability.
Log into your Portal using the Domain Administrator account used above in the IdP configuration as the Internal-Appliance Configuration-LDAP.
Answer the Setup Security Questions.
Choose either the Pre-defined or the custom Your Choice questions.
RapidIdentity IdP Configuration
The Identity Provider Configuration page contains various URL sites, links to download metadata and certificate information, the certificate fingerprint, and an option to ensure consistent client addresses. This page provides administrators with their Registered Identity Provider information for user authentication in web applications.
Expand Identity Providers from the Left Menu Items, and click IDP Configuration.
 |
The current Identity Provider Configuration will be displayed in the workspace. For details, refer to the below table.
Field | Description |
|---|---|
Entity ID | The SAML EntityID of the Identity Provider |
Base URL | The base URL to the IdP |
Logout URL | The IdP's logout URL |
Live Metadata URL | The URL to view the metadata associated with the provider which allows the remote vendor to access the metadata at any time. |
Metadata | Click to download the registered metadata for the Identity Provider to save as an XML file. |
Signing Certificate .PEM File | Click to download the (.PEM) encryption certificate used by the Identity Provider. |
Signing Certificate .CER File | Click to download the (.CER) signing certificate used by the Identity Provider. |
Certificate Fingerprint | The SHA1 fingerprint of the IdP's signing and encryption certificate |
Ensure Consistent Client Address Checkbox | When this box is checked, the client address is maintained across clustering and is bound to a particular client IP address. Requests from that session are only considered valid when used from that same IP address. WarningChecking this box can cause users to be forced to re-authenticate from devices any time their connection changes cell towers or wireless access points, or when the DHCP lease expires. |
The Delete Configuration function should be used only if there is an issue with the IdP configuration, such as a mismatch of IP address or a change to the DNS name, as the IdP configuration will be deleted and must be reconfigured completely.
Caution
Deleting an IdP configuration will also result in deleting all SAML Relying Party configurations and will require reconfiguration of the IdP, Relying Parties, and all federated Service Providers.
Certificate Management
Certificates are created and signed with an expiration date, and Relying Parties use this certificate to establish trust between the Relying Party and the Identity Provider. Once this certificate expires, it will need to be rotated out with a newly generated certificate that is not expired to retain trust with the Relying Parties.
At the bottom of IdP Configuration screen is an option to Rotate certificate now. Click this to generate a new certificate and nullify the old one.
A sidebar with a notification will pop up with a note and a checkbox. The Proceed button will not activate until I Understand has been checked.
Note
Doing this is instant, and may cause some authentication failures with SAML integrations. Ensure you update all service providers with the new certificate once it has been rotated.
Important
Due to a known issue, a bounce of RapidIdentity Federation servers will be required before the new certificate is fully active.
Federation Partners Overview
Use RapidIdentity Federation Partners to exchange secure identity information across two or more federated domains. When an application or service is in one network and a user account is in another network, typically the user is prompted for secondary credentials when he or she attempts to access the application or service. These secondary credentials represent the user's identity in the realm where the application or service resides.
RapidIdentity Federation uses various security realms to perform the mandatory operations to facilitate secure information exchange between requesting and relying parties across different domains. A requestor and the relying party must exchange configuration metadata before beginning to exchange protocol messages that specify unique identifiers to indicate the security realms represented and distinguish them from other possible federation partners and applicable URLs that indicate where protocol messages are to be sent.
Refer to the following currently supported Federation Partner sections for configuration information.
SAML 2.0 Overview
The overall goal of the SAML SSO Configuration Process is to federate the Customer and Service Provider to provide Customer-environment users a Single Sign-On (SSO) experience to access the Service Provider's web-based service. Users access the web-based service through an Applications icon in the RapidIdentity Portal. This document focuses on configuring a third-party application to be authenticated via SAML to the RapidIdentity Portal as an Identity Provider.
SAML 2.0 SSO Settings and Attribute Mapping
The SAML authentication process typically begins when the Identity Provider (IdP) receives an Authentication Request <AuthnRequest> generated by a SAML Service Provider and conveyed by the authenticating user's web browser. The <AuthnRequest> often indicates where the IdP is to send the SAML Response/Assertion after the authentication completes successfully. Under normal circumstances, the IdP will only honor that requested URL if it is defined as a valid "Assertion Consumer Service" in the Relying Party metadata.
RapidIdentity Federation supports the Oasis SAML V2.0 Enhanced Client or Proxy (ECP) profile. RapidIdentity supports ECP and can be enabled if required by a particular Federation Partner which may require SAML ECP to authenticate and their ECP Advanced Settings, such as Microsoft Office 365™.
The SAML SSO and ECP Advanced Settings are both configured utilizing similar Federation Partners SSO Settings Menu options, therefore, the configuration options are combined below in the SAML SSO / ECP Advanced Settings Table.
Access the SAML SSO Advanced Settings from the Configuration menu and select Federation Partners from the left-hand menu items.
If there are Federation Partners that have been configured, they will display in the workspace. Hover in the far right of the row and click the Edit button.
If there are no Federation Partners already configured, click Add Federation Partner and select SAML 2.0 from the drop-down to open the configuration settings.
The Community Federation Partners workspace will load. Refer to the Community section to learn more about that topic.
Click Create SAML Relying Party to open the configuration options.
Enter all relevant settings in the General section.
Field
Description
Name (Required)
Give the Relying Party a unique name.
Description (Optional)
Provide a short but accurate description if desired.
Is InCommon
Check this box if the Relying Party is a registered entity in the InCommon Federation.
Note
This will require two specific Attributes to be added and open a Metadata Refresh Interval* field. Metadata must be pulled from an InCommon configuration for this setting.
*Metadata Refresh Interval (Hours) -- InCommon Only
Set the interval in hours between RapidIdentity refreshing the Relying Party's metadata by retreiving it from the InCommon Metadata Service. Valid refresh intervals are from 1-24 hours.
Metadata (Required)
Enter the metadata for the Relying Party.
From the Federation Partners configuration screen, click on SSO Settings.
Note
By default, the ECP Settings are not active. Click Enable ECP Settings to enable ECP Settings. When selecting the Enable ECP Settings checkbox, the ECP Settings section will become available beneath the SSO Settings along with the configuration options.
 |
When selecting the Enable ECP Settings checkbox, the ECP Settings section will become available beneath the SSO Settings along with the configuration options.
 |
|
Field |
Description |
|---|---|
|
Include SAML2 Attribute Statement |
If selected the SAML2 SSO or ECP Assertion generated for this Relying Party will contain an <AttributeStatement> element. |
|
SAML2 SSO Assertion Lifetime |
Defines the period of time that a SAML2 SSO Assertion generated for this Relying Party will be valid in hours, minutes, and seconds. This setting directly affects the "NotOnOrAfter" attribute in the SAML Assertion which indicates to the Relying Party who receives the Assertion that the Assertion should only be considered valid if it is received before this time instant. |
|
Sign SAML2 SSO or ECP Responses |
Determines if the SAML2 SSO or ECP Responses should be cryptographically signed. Choose "Always" to enable signatures on the Response and "Never" to disable signatures on the Response. |
|
Sign SAML2 SSO or ECP Assertions |
Determines if the SAML2 SSO or ECP Assertions should be cryptographically signed. Choose "Always" to enable signatures on the Response and "Never" to disable signatures on the Response. |
|
Encrypt SAML2 SSO or ECP Assertions |
Determines if the SAML2 SSO or ECP Assertions should be encrypted. Note: this is only possible if the IdP is provided with an "encryption" certificate in the SAML metadata for the Relying Party. Choose "Always" to enable encryption and "Never" to disable encryption. |
|
Encrypt SAML2 SSO or ECP Name IDs |
Determines if the Name IDs present in the SAML2 SSO Assertions should be encrypted. Note: this is only possible if the IdP is provided with an "encryption" certificate in the SAML metadata for the Relying Party. Choose "Always" to enable encryption and "Never" to disable encryption. |
|
Signature Algorithm |
The algorithm to use when cryptographically signing the SAML2 SSO or ECP Responses and/or SAML2 SSO or ECP Assertions. SHA-1: Use only when the Relying Party does not support SHA-256. SHA-256: In general, "SHA-256" should be chosen unless the Relying Party does not support it. |
|
Skip Endpoint Validation When Signed |
If the <AuthnRequest> is cryptographically signed and if the IdP can successfully verify that signature by using a public signing key present in the Relying Party's metadata, then the IdP can be instructed to comply with an un-recognized Assertion Consumer Service URL by enabling this option. |
Note
After a user authenticates successfully, a SAML Assertion is generated by the IdP. The SAML Assertion contains attributes about the user (e.g. name, email address, etc) and other information describing how and when authentication occurred at the IdP. The SAML Assertion is then embedded inside of a more consolidated generic SAML Response and it is the SAML Response, containing the Assertion, which is ultimately conveyed to the Relying Party.
Attribute Mapping
The SAML Attributes available for assignments will have been set up already under the Federation Partners SAML Attributes section.
Select the Federation Partner from the Federation Partners workspace, and click Edit by hovering in the last column.
From the Federation Partners window, scroll down to Attribute Mapping.
Click Choose an Attribute to DENY or PERMIT.
Click to expand the drop-down of available attributes to deny or permit mapping.
The Add New Attribute window will load. Select the attribute type from the drop-down.
Based on the type of attribute being added, different menu options will display. Refer to the SAML Attributes section for details on completing the configuration for each attribute type.
For InCommon configurations, the two following attributes must be set:
eduPersonPrincipalName - this attribute must correspond to the name of the user
eduPersonScopedAffiliation - this attribute must correspond to the user's relationship to the institution (e.g., Student, Teacher, etc.)
Note
An error message will display until these attributes are configured.
Select to Permit or Deny the attribute mapping.
Click Add New Attribute+ to add additional SAML attributes. Repeat steps 2-8.
Click Save to add the attribute to the selected Federation Partner.
A confirmation notice will display if updates are successful.
Click to Trigger Service Reload from the attributes screen and Trigger Web Reload from the Identity Providers screen to activate the new attributes.
SAML Attribute Configuration
SAML Attributes are added during the setup or editing of a SAML Federation Partner and define attributes which may be released to SAML Relying Parties after a user successfully authenticates.
Technology professionals can view the SAML 2.0 technical overview .
The SAML protocol there are several important aspects, the Identity Provider, SAML transactions use Extensible Markup Language (XML) for standardized communications between the identity provider and service providers.
In the SAML protocol, the Identity Provider (IdP) is in charge of authenticating users and if successful, generating a SAML assertion which relays to the Relying Party that the user has successfully authenticated. Often times this information includes when and how they authenticated, and other information about the user required by the Relying Party. This information about the authenticating user is referred to as the attributes of the authenticating user. Common attributes are user's email address and name, but ultimately the Relying Party must communicate which attributes are required from the Identity Provider to release.
From the Configuration menu, select Identity Providers from the Security menu.
Expand Identity Providers in the left hand menu items and click Federation Partners.
Click Add Federation Partner and select SAML2.0 from the drop-down selector.
If configuring the SAML Attributes after the Federation Partner has been added, hover and click the edit icon on the far right column of the workspace to select existing attributes.
The current Federation Partners will be displayed in the workspace. Click the SAML Attributes icon in the action buttons at the bottom of the page.
Note
The SAML Attributes icon will only display if there are SAML Federation Partners in the system.
The SAML Attributes will load with four separate attribute tabs, LDAP, Static, Name ID, and Static Name ID. Required fields are marked with an asterisk when setting up each attribute.
The first tab is the LDAP Attributes tab. This is where administrators define attributes for values that come directly from LDAP.
Important
Administrators define the total pool of attributes which might be allowed to be released to any Relying Party. After the attributes are defined, administrators can choose from the pool which attributes will actually be released to each Relying Party, individually.
Click the Add LDAP Attribute + button to open the LDAP attribute window.
LDAP Attribute: The name of the LDAP attribute holding the values which are intended to be released. Each attribute can have one or more values.
SAML Name: The name of the attribute as it will appear in SAML assertions. Different Relying Parties might require the same attribute value, such as a user email address, to be released for them, but could require different names. For example, for a user email address, multiple names such as "EMAIL", "mail", or "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/address."
Friendly Name: This is the name as the LDAP attribute will appear in the SAML Assertion.
Name Format Friendly Name: Select the format value type to be used for the LDAP Attribute Value. SAML Name Formats are typically URIs which convey information to the Relying Party of what format the attribute takes. Depending upon the requirements of the Relying Party, a certain value may or may not be required. This drop-down allows you to choose from some common values or allows you to choose "Custom Name Format" in the event the required value is not one of the provided common values. If the Relying Party does not require a specific value, select "Unspecified."
Unspecified: urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
URI Reference: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
Basic: urn:oasis:names:tc:SAML:2.0:attrname-format:basic
Custom Name Format: The format value is a free form text field to enter the custom name format.
Name Format Value: The format will adjust based on the Name Format Friendly Name selected
The next tab is the Static tab. Static Attributes are attributes whose values are based on values which generally do not change from user to user. For instance, if a Relying Party wants the IdP to release a common value for all users in a particular organization, then a Static Attribute should be used. When using an LDAP Attribute, then every user in your organization must have the attribute on their LDAP entry containing the same value.
Click the Add Static Attribute + button to open the Create Static Attribute window.
Friendly Name: This is the name as the Static attribute will appear in the SAML Assertion.
SAML Name: The name of the attribute as it will appear in SAML assertions. Different Relying Parties might require the same attribute value, such as a user email address, to be released for them, but could require different names. For example, for a user email address, multiple names such as "EMAIL", "mail", or "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/address."
Values: Enter the Static Attribute
Click +Add Another Value to enter multiple acceptable values
Resolvable: Allows the static value to contain tokens which can be resolved to real value(s) at the time the SAML Assertion is being generated.
For example, If two Static attributes exist, first being "givenname" that contains a user's first name and the second "sn" which contains a user's surname, then a third attribute can be generated representing the first two attributes. The Relying Party could request that the Identity Provider release an attribute called "name" containing the surname followed by a comma and space, then by the first name. This could be accomplished with a "Resolvable" static attribute where the value is defined as "%sn%, %givenName%."
Name Format Friendly Name: Select the format value type to be used for the Static Attribute Value. Name ID Formats are typically URIs which convey information to the Relying Party of what format the attribute takes. Depending upon the requirements of the Relying Party, a certain value may or may not be required.
Unspecified: urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
URI Reference: urn:oasis:names:tc:SAML:2.0:attrname-format:uri
Basic: urn:oasis:names:tc:SAML:2.0:attrname-format:basic
Custom Name Format: If the provided common values in the drop-down do not provide the correct format choose "Custom Name Format." If the Relying Party does not require a specific value, select "Unspecified." The format will adjust the Name Format Value.
Name Format Value: This value will adjust based on the Name Format Friendly Name selected.
The next tab is the Name ID Tab. A SAML Assertion may contain 0 or 1 Name ID attribute and 0 or more non-Name ID attributes. Name ID attributes will typically provide information about the format of the value. The Relying Party must specify any requirements that may exist for the Name Format.
Click Add Name ID Attribute+. Name ID attributes are typically used to convey the "primary identifying attribute" about the user to the Relying Party. Often times, this will be the user's email address, but ultimately it's up to the Relying Party to communicate what value is expected, if any, and define the format, etc.
LDAP Attribute: Enter the name of the LDAP Attribute
Name Format Friendly Name: Select the format value type to be used for the Name ID Value. Name ID Formats are typically URIs which convey information to the Relying Party of what format the attribute takes. Depending upon the requirements of the Relying Party, a certain value may or may not be required.
Unspecified: Allows a free from entry (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified)
Email Address: Uses the email format ( (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
X.509 Subject Name: Uses the subject name of the X509 Certificate (urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName)
Windows Domain Qualified Name: Uses the FQDN of the hostname and domain name (urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName)
Kerberos Principal Name: Uses the Principal Name to identify the user or service (urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos)
Entity Identifier: Uses a URI is a URL that contains the domain name of the entity (urn:oasis:names:tc:SAML:2.0:nameid-format:entity)
Persistent Identifier: Reliably points to a digital entity as an identifier to build trusted connections (Directsurn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
Transient Identifier: An identifier intended to be used for a single session only (urn:oasis:names:tc:SAML:2.0:nameid-format:transient)
Custom Name Format: The drop-down contains some common Name Format values, but if the required value is not present in the list of available values, choose the Custom Name Format option and provide a custom value. If the Relying Party does not require a specific value, select "Unspecified. "The format will adjust the Name Format Value.
Name Format Value: This value will adjust based on the Name Format Friendly Name selected.
The last tab is the Static Name ID tab. Static Name ID Attributes are like Static Attributes, except they define the value of the Name ID Attribute in the SAML Assertion.
Click Add Static Name ID Attribute+.
Values: Enter a Name ID Attribute
Click +Add Another Value to enter multiple acceptable values
Resolvable: Allows the static value to contain tokens which can be resolved to real value(s) at the time the SAML Assertion is being generated.
For example, If two Static attributes exist, first being "givenname" that contains a user's first name and the second "sn" which contains a user's surname, then a third attribute can be generated representing the first two attributes. The Relying Party could request that the Identity Provider release an attribute called "name" containing the surname followed by a comma and space, then by the first name. This could be accomplished with a "Resolvable" static attribute where the value is defined as "%sn%, %givenName%."
Name Format Friendly Name: Select the format value type to be used for the Static Name ID Value. SAML, Static Name ID Formats are typically URIs which convey information to the Relying Party of what format the attribute takes. Depending upon the requirements of the Relying Party, a certain value may or may not be required.
Unspecified: Allows a free from entry (urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified)
Email Address: Uses the email format (urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)
X.509 Subject Name: Uses the subject name of the X509 Certificate (urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName)
Windows Domain Qualified Name: Uses the FQDN of the hostname and domain name (urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName)
Kerberos Principal Name: Uses the Principal Name to identify the user or service (urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos)
Entity Identifier: Uses a URI is a URL that contains the domain name of the entity (urn:oasis:names:tc:SAML:2.0:nameid-format:entity)
Persistent Identifier: Reliably points to a digital entity as an identifier to build trusted connections (Directsurn:oasis:names:tc:SAML:2.0:nameid-format:persistent)
Custom Name Format: If the provided common values in the drop-down do not provide the correct format choose "Custom Name Format". If the Relying Party does not require a specific value, select "Unspecified."The format will adjust the Name Format Value.
Name Format Value: This value will adjust and populate based on the Name Format Friendly Name selected.
SAML Relying Party Authentication Configuration Examples
There are a variety of web-based applications that support a SAML-based Single Sign-On service to configure your Identity Provider (IdP) server connection. In the information provided in the link above, the third-party identity provider is Identity Automation through RapidIdentity Federation.
This guide provides steps to configure the following SAML Relying Parties with RapidIdentity:
RapidIdentity Pre-configured SAML Relying Parties (Using the Community)
Follow the steps in each section above to configure SAML authentication for the appropriate web-based application.
Sample RapidIdentity SAML Integrations
Identity Automation supports SAML authentication for numerous web-based applications. For example, Google Apps and Salesforce SAML authentication configurations are examples, and are not required for all RapidIdentity Federation deployments. The Identity Automation Federation guides detail SAML integration, where available, on an application-specific basis.
RapidIdentity Community SAML Relying Party Configuration - New UI
Google supports a SAML-based Single Sign-On service for its web-based application to configure your Identity Provider (IdP) server connection. In the information provided in the link above, the third party identity provider is Identity Automation through RapidIdentity Federation.
The RapidIdentity Community provides preconfigured SAML Relying Parties to supported web-based applications to simplify the IdP server connection. Importing from the Community preconfigures required relying party data for the IdP.
Follow these steps to configure a SAML Relying Party authentication configuration using the Community.
Note
Third party SAML Relying Parties may update their setup sequence without notification, therefore, the steps below may vary slightly.
From the RapidIdentity Configuration Module, select Identity Providers from the Security menu.
The Identity Provider Configuration workspace will launch. Select Federation Partners from the Identity Providers left menu items. From the Add Federation Partner drop-down button, select SAML 2.0.
The Community-SAML Relying Parties workspace will launch.
The Community contains basic configuration for commonly used SAML Relying Parties. Before manually adding a new SAML Relying Party, search the Community for the entry. The Community will be updated on an ongoing basis with new SAML Relying Parties.
Tip
The Community provides some general information about the available preconfigured SAML Relying Parties. Community entries can be created by individual users or by RapidIdentity. Click Federation Partners in the path "Federation Partners>Community>SAML Relying Parties" to return to the main Federation Partners page.
Check Marks:
Green = Verified (RapidIdentity Administrators have validated operability.)
Grey = Unverified (RapidIdentity Administrators have not validated operability.)
Headphones:
Green = Supported (Contact RapidIdentity Support for questions or issues.)
Grey = Unsupported (RapidIdentity Support is not available for questions or issues.)
Hover over an entry in the Community - SAML Relying Parties workspace and click Import.
A confirmation message will appear and the imported SAML Relying Parties will be imported into the Federation Partners workspace and will display.
All information to register the SAML Relying Party will automatically be configured. Click Edit next to the SAML Relying Party to view the details.
Salesforce SAML Integration Guide - New UI
Salesforce supports SAML Single Sign-on and provides a SAML Single Sign-on overview with a Single Sign-on Implementation Guide.
Fortunately, within RapidIdentity Federation, Salesforce SAML authentication configuration is very similar to G Suite SAML authentication configuration.
The preliminary Salesforce SAML authentication configuration steps require that both RapidIdentity Portal and RapidIdentity Federation (IdP) are internet accessible and are configured as described in the provided links. In this topic, the IdP is the Identity Provider which is the system that is logged into using credentials, which is RapidIdentity. The Service Provider (SP) is the system that automatically receives the credentials for login, which is Salesforce, in this case.
Follow these steps to configure Salesforce SAML Authentication.
From the RapidIdentity Configuration Module, select Identity Providers from the Security menu.
The Identity Provider Configuration workspace will launch. The following RapidIdentity fields will be mapped into Salesforce as shown below:
Entity ID = Issuer = https://saml.salesforce.com
Entity ID + /profile/SAML2/POST/SSO = Identity Provider Login URL
Logout URL = Identity Provider Logout URL
Table 71. Salesforce Fields' URL ValuesField Name
URL
Issuer
Enter your identity provider URL, such as https://company.net/idp
Identity Provider Login
Enter your identity provider login URL, such as https://company.net/idp/profile/SAML2/POST/SSO
Identity Provider Logout
Enter your identity provider logout URL, such as https://company.net/idp/logout
Entity ID
Enter the Salesforce SAML URL, such as https://saml.salesforce.com
Select which format of the certificate to download, either a .PEM or a .CER file and click the download link to the signing/encryption certificate used by the Identity Provider.
Log in to the service provider, Salesforce, as an administrator.
Navigate to the Setup Gear, and select Setup.
Search in Setup for Single Sign-On Settings.
Click New and fill out the form using the data from Step 2, including the Certificate.
Click Save.
Navigate to Security Controls | Single Sign-on Settings.
Click on the Name of the SSO (IdAuto_IDP).
Click Download Metadata.
Return to the RapidIdentity IdP Configuration page.
Click Federation Partners from the Identity Providers left menu items and click the Add Federation Partner drop-down button, select SAML 2.0.
The Community- SAML Relying Parties workspace loads. Search the list for Salesforce, as the list will be updated on an ongoing basis. If Salesforce is not in the list, click Create New SAML Relying Party+.
The Create SAML Relying Party window will load.
Enter the following:
Return to the RapidIdentity Appliance IdP Configuration page and click Edit Attributes.
Name: Salesforce
Description: Salesforce for SAML
Metadata: Paste the Salesforce metadata in the box.
Click Save.
Salesforce will now be listed as a Federation Partner under the Identity Providers section in theConfiguration module.
Click SAML Attributes from the action bar.
Select the Name ID tab.
Click Add Name ID Attribute+.
The example used is for the mail attribute for the username.
Add a Name ID Attribute that contains the Salesforce information.
LDAP Attribute: Enter a value that contains the Salesforce username (Ex. "mail").
Name Format Friendly Name: Select "Unspecified" from the drop-down list.
The value will be similar to: "urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified."
Click Save. A confirmation will display at the top of the workspace and the Name ID Attribute will be added.
Return to Federation Partners and select to Edit the Salesforce entry.
Click Attribute Mapping in the Salesforce (SAML) details screen.
Click Choose an Attribute to DENY or PERMIT.
From Add Attribute Mapping, select the newly created attribute from the drop-down
Click Permit to add as a permitted attribute.
A confirmation message will display and requests a Trigger Service Reload. Perform the additional steps first.
From Choose an Attribute to DENY or PERMIT, select the [INTERNAL] SAML Transient ID attribute from the drop-down, if applicable, and click Deny.
From the bottom action buttons, click Trigger Service Reload.
After the confirmation appears at the top, return to the IDP Configuration workspace, and click Trigger Web Reload.
When both reloads are complete, access Salesforce from the RapidIdentity Portal, and the <https://{SALESFORCE DOMAIN}.my.salesforce.com >properly configured SAML authentication will direct to the user's homepage.
Google SAML Integration Guide - New UI
Google supports a SAML-based Single Sign-On service for its web-based application to configure your Identity Provider (IdP) server connection. In the information provided in the link above, the third party identity provider is Identity Automation through RapidIdentity Federation.
The preliminary SAML authentication configuration steps require that both RapidIdentity Portal and RapidIdentity Federation IdP are internet accessible and are configured as described.
Follow these steps to configure G Suite for SAML. A G Suite Admin Console login is required to complete this configuration.
Note
Google may update their setup sequence without notification, therefore, the steps below may vary slightly.
From the RapidIdentity Configuration Module, select Identity Providers from the Security menu.
The Identity Provider Configuration workspace will launch.
Click Download the certificate used by the Identity Provider (.pem) to download the certificate.
Keep this browser window open as the Base URL and Logout URL are necessary during upcoming steps. At that time, the certificate will be uploaded to the G-Suite Admin portal.
Set up SSO in the G Suite Admin Console In a different browser window, authenticate to G Suite Admin Console with an administrator account and click Security.
Click Set up single sign-on (SSO) with a third party IdP. .
For the Third-party Identity Provider section, enter the information as described below: Sign-in page URL and the Sign-out page URL.
Enter the Sign-in page URL.
Enter the Sign-out page URL.
Note
The base URL for these values must be entered using the format: "**/idp/profile/SAML2/Redirect/SSO"
Click REPLACE CERTIFICATE to upload the certificate that was downloaded in Step 3.
Click Save at the bottom of the page to save the configuration.
Click Download IDP Metadata and copy the information to the clipboard. The metadata ends with "</EntityDescriptor>."
Create a SAML 2.0 Federation Partner for G Suite In the RapidIdentity Configuration module, click Federation Partners from the Identity Providers section.
Click the Add Federation Partner drop-down button and select SAML 2.0.
The Federation Partners>Community-SAML Relying Parties workspace will launch.
Tip
The Community contains basic configuration for commonly used SAML Relying Parties. Before manually adding a new SAML Relying Party, search the Community for the G-Suite entry. The Community will be updated on an ongoing basis with new SAML Relying Parties.
Click Create SAML Relying Party+. Enter the following information in the Federation Partners > Create SAML Relying Party window.
The tables and respective screens below depict the values that are to be entered for each section, "General," and "SSO Settings," for the G Suite Relying Party registration the Register SAML Relying Party window.
Table 72. GeneralField
Value
Name
G-Suite
Description
G Suite SAML Authentication Configuration
Metadata
Paste the metadata from the previously copied metadata from the Google Admin console.
The metadata should appear similar to what is shown in the image; modify the GOOGLE_DOMAIN, as necessary.
Click SSO Settings at the bottom of the General page to expand the SSO Settings optons.
- Table 73. SSO Advanced Settings
Field
Value
Description
Include SAML2 Attribute Statement
True
If selected the SAML2 SSO Assertion generated for this Relying Party will contain an <AttributeStatement> element. Default value.
SAML2 SSO Assertion Lifetime
Hours = 0
Minutes = 5
Seconds = 0
Defines the period of time that a SAML2 SSO Assertion generated for this Relying Party will be valid in hours, minutes, and seconds. This setting directly affects the "NotOnOrAfter" attribute in the SAML Assertion which indicates to the Relying Party who receives the Assertion that the Assertion should only be considered valid if it is received before this time instant.
Sign SAML2 SSO Response
Conditional
Determines if the SAML2 SSO Responses should be cryptographically signed. The default value is "Conditional" and should be used to query for assertions that meet particular criteria. Choose "Always" to enable signatures on the Response and "Never" to disable signatures on the Response.
Sign SAML2 SSO Assertions
Never
Determines if the SAML2 SSO Assertions should be cryptographically signed. Choose "Always" to enable signatures on the Response and "Never" to disable signatures on the Response. Default value.
Encrypt SAML2 SSO Assertions
Never
Determines if the SAML2 SSO Assertions should be encrypted. Note: this is only possible if the IdP is provided with an "encryption" certificate in the SAML metadata for the Relying Party. Choose "Always" to enable encryption and "Never" to disable encryption. Default value is "Conditional."
Encrypt SAML2 SSO Name IDs
Never
Determines if the Name IDs present in the SAML2 SSO Assertions should be encrypted. Note: this is only possible if the IdP is provided with an "encryption" certificate in the SAML metadata for the Relying Party. Choose "Always" to enable encryption and "Never" to disable encryption.
Signature Algorithm
SHA-1
The algorithm to use when cryptographically signing the SAML2 SSO Responses and/or SAML2 SSO Assertions.
SHA-256: In general, "SHA-256" should be chosen unless the Relying Party does not support it.
SHA-1: Use only when the Relying Party does not support SHA-256.
Skip Endpoint Validation When Signed
False
If the <AuthnRequest> is cryptographically signed and if the IdP can successfully verify that signature by using a public signing key present in the Relying Party's metadata, then the IdP can be instructed to comply with an un-recognized Assertion Consumer Service URL by enabling this option.
Enable ECP Settings
False
When selecting the Enable ECP Settings checkbox, the ECP Settings section will become available beneath the SSO Settings along with the configuration options. In this case, ECP settings are not to be enabled.
DEFINE the LDAP ATTRIBUTES SAML Service Providers typically define one or more attributes required from the Identity Provider to release to Google during SAML authentication about the authenticating user. These attributes are typically things like Email and Name, but could also be things like Group Membership.
From the Security menu, access to SAML 2.0 Federation Partner that was created earlier in this process. Click SAML Attributes at the bottom of the workspace to view or add attributes.
In this example, the Name ID will be the attribute used for authentication.
A SAML assertion typically contains a single "Name ID" attribute and 0 or more other attributes about the authenticated user.
A Name ID attribute is typically the main identifier of the user and is associated with a particular "Name Format." The Name Format generally indicates the type of value to the Relying Party.
For example, a value of "urn:oasis:names:tc:SAML:2.0:nameid-format:email" indicates that the Name ID attribute is an email address.
A value of "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" indicates the value is of an "unspecified" type.
The Federation Partners > SAML Attributes workspace will load. Click the Name ID tab.
Enter Name ID for the LDAP Attribute, and select the Name Format Friendly Name from the drop-down list. In this example, the name format is an email address.
Refer to the SAML Attributes section for additional information on the available options.
Click Save.
The Name ID attribute will now be populated in the workspace.
From the newly added Name ID Attribute, Click Edit.
The urn will be similar to this: "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified." Ensure the SAML version and the format matches the information that is in the metadata from G Suite. In this case, the updated urn will be" urn:oasis:names:tc:SAML:2.0:nameid-format:email ." Click Save.
Note
Editing attributes creates a link from the LDAP attributes to the “Name Format” defined by the service provider. Editing attribute mappings specifies what attributes to allow and deny for a specific service provider. It is often recommended to deny the [INTERNAL] SAML Transient ID as in many cases conflicts with some service providers. [INTERNAL] attributes are the attributes defined by default by Rapid Identity to processes SAML interactions between internal apps like the Portal and Connect.
A service reload is required.
Navigate to IDP Configuration.
Click Trigger Service Reload in the action bar buttons.
A confirmation message will appear briefly at the top of the workspace.
Navigate to the G Suite Admin console, Security section.
Select Set up single sign-on (SSO).
Enter the data fields that were entered in step 2a. These values will vary based on setup.
The Sign-in page URL is the IdP Base URL to sign into your system and G Suite.
The Sign-out page URL is the Logout URL for redirecting users to sign out.
The Change password URL is the organization specific URL to allow users to change their password.
Upload the IdP security certificate and ensure Use a domain specific issuer is unchecked. Network masks are optional and organization specific.
Create a G Suite App link in the RapidIdentity Portal.
Once the application is created, click the icon in the portal to initiate a valid IdP initiated SAML connection to your G-Suite tenant.
Access http://mail.google.com/a/{GOOGLE_DOMAIN}to be directed to a user's homepage.
OAuth 2.0 Federation Partner Authentication Configuration
There are a variety of web-based applications that support the OAuth 2.0 protocol.
Follow the steps in each section to configure OAuth authentication for RapidIdentity.
From the Configuration menu, select Identity Providers.
From the Security section in the left menu items, click the caret to expand the Identity Providers menu and select Federation Partners.
From the Federation Partners workspace, select OAuth 2.0 from the Add Federation Partner selector.
In the Create New OAuth 2.0 Partner window, enter the required information. Refer to the below table for details.
Click Save to add the OAuth 2.0 Partner.
Once the OAuth 2.0 Partner has been saved, in the details of the configuration both a "Client ID" and a "Client Secret Key" field will be displayed. Click the Copy Icon to copy the Client ID to the clipboard.
Click the Show Client Secret Key bar to see the key. There is an option to Regenerate Client Secret Key on the bottom action bar.
Note
If there is at least one External Authentication Realm enabled, a drop-down list will be available on the login page to allow selection of which realm to authenticate against.
Field | Description | ||
|---|---|---|---|
Name | Enter name of the OAuth 2.0 Partner | ||
Description | Enter description of the OAuth 2.0 Partner | ||
Internal Realm Name | This value is editable. If a custom name is not used, the internal realm name will be listed as "internal." | ||
Callback URLs | Enter one or multiple callback URLs. | ||
AUTH Code Expiration Seconds | Default value is "60" | ||
Token Expiration Seconds | Default value is "32400" | ||
Allow Refresh Tokens | Select checkbox to allow refresh tokens | ||
Refresh Expiration Seconds | Default value is "2592000" | ||
Attributes |
Click +Add Attribute and enter the following information:
|
OpenID Connect is an OAuth 2.0 Federation Partner with OpenID Connect Support enabled. Much of the configuration required for OpenID Connect will have already been performed during the OAuth 2.0 setup. View the OpenID Connect Federation Partner section for additional details on configuring OpenID Connect,
OpenID Connect Federation Partners Authentication Configuration
There are a variety of web-based applications that support the OpenID Connect protocol.
OpenID Connect is an OAuth 2.0 Federation Partner with OpenID Connect Support enabled. Much of the configuration required for OpenID Connect will have already been performed during the OAuth 2.0 setup. View the OAuth 2.0 Federation Partner section for additional details on configuring
Follow the steps in each section to configure OpenID Connect authentication for RapidIdentity.
From the Configuration menu, select Identity Providers.
From the Security section in the left menu items, click the caret to expand the Identity Providers menu and select Federation Partners.
From the Federation Partners workspace, select OpenID Connect from the Add Federation Partner selector.
In the Create New OpenID Connect Partner window, enter the required information. Refer to the below table for details.
Click Save to add the OpenID Connect Partner. After saving an OpenID Connect Partner, the configuration details will display a field for both a "Client ID" and a "Client Secret Key."
Field | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
Name | Enter the name for the OpenID Connect Federation Partner. | |||||||||
Description | Enter a description for the OpenID Connect Federation Partner. | |||||||||
Callback URLs | Any and all callback URLs requested by the client must be present in this list to be honored. | |||||||||
AUTH Code Expiration Seconds | The number of seconds before authorization codes issued to this client expire. The default value is "60" (1 minute). | |||||||||
Token Expiration Seconds | Default value is "32400." | |||||||||
Allow Refresh Tokens | Select checkbox to designate if refresh tokens should be issued to this client. The default value is "true." | |||||||||
Refresh Expiration Seconds | The number of seconds before refresh tokens issued to this client expire. A value of "0" indicates that refresh tokens do not expire. The default value is "2592000" (30 days). | |||||||||
Attributes |
If primarily using the OpenID Connect protocol, these values can be left blank, as these attributes are required when operating as an OAuth 2.0 client instead of an OpenID Connect client. NoteRapidIdentity only supports releasing LDAP attributes to OAuth 2.0 clients.
| |||||||||
OpenID Connect Configuration |
|
WS-Federation Partner Authentication Configuration
There are a variety of web-based applications that support the WS-Federation protocol.
Follow the steps in each section to configure WS-Federation authentication for RapidIdentity.
From the configuration menu, select Identity Providers.
From the Security section in the left menu items, click the caret to expand the Identity Providers menu and select Federation Partners.
From the Federation Partners workspace, select WS-Federation from the Add Federation Partner selector.
In the Create New WS-Federation Partner window, enter the required information. Refer to the Create New WS-Federation Relying Party Configuration Table for details.
Click Save to add the WS-Federation Partner.
A confirmation message will display at the top of the page.
After the WS-Federation Partner has been created, the Issuer Entity IDs and SAML Audiences & ReplyTo Urls sections will become available. Click the section title, Issuer Entity IDs or SAML Audiences ReplyTo URLs to expand the section and to add entries. Adding, reordering, and deleting entries will not be saved until the Federation Partner is saved. Refer to the Advanced Configuration Table for configuration details.
Field | Description | ||
|---|---|---|---|
General |
| ||
Configuration |
| ||
Attribute Release - Name Identifier |
| ||
Attribute Release - Attributes |
Assign attributes by clicking the +Add Attribute
| ||
WS-Trust Configuration |
When the username and password is entered by the end-user during Windows login, some cases the username will match exactly the user's RapidIdentity username or the username will require to be transformed in some manner and possibly mapped to a different LDAP attribute than what RapidIdentity uses natively. Configure either Transform Type or Lookup. Type options.
|
Field | Description | ||
|---|---|---|---|
Issuer Entity IDs | If interaction with a single RapidIdentity IdP is required for multiple domains, such as "Staff" and "Students," unique issuer IDs are used to allow these types of alternate dynamic issuer values based on the user that is authenticating. Add a new Issuer Entity ID configuration and associate it with a set of users based on a particular LDAP attribute and attribute value pattern.
| ||
SAML Audiences & ReplyTo Urls |
|
Setting Up RapidIdentity with Central Authentication Service (CAS)
The Central Authentication Service (CAS) is a single sign-on protocol that allows potentially untrusted websites to authenticate users against a central, trusted authentication service without ever exposing the user's credentials to the website. A CAS Client is called a Service, and in the RapidIdentity CAS implementation, every Service that needs to interact with the server must be registered.
Registering a CAS Service means giving it a unique name and optionally providing protocol-specific configuration including ticket lifetimes, URL matching rules, a proxy policy, and defining which attributes (if any) should be released to the Service.
This procedure begins in Configuration > Security > Identity Providers > Federation Partners.
Click Add Federation Partner and choose the CAS option from the drop-down menu.
This will open the Federation Partners > Central Authentication Service (CAS) configuration screen. There are multiple sections on this screen with fields that make up CAS Configuration for RapidIdentity. First, give the service a name. Descriptions are optional.
The CAS protocol revolves around the issuing of tickets with various types: Ticket-Granting, Service, Proxy-Granting, and Proxy. The Ticket Lifetime fields show the default ticket lifetimes set by RapidIdentity by ticket type. These values can be changed or added to.
Table 76. Ticket LifetimesTicket Type
Description
Default Value
Proxy Granting Ticket Lifetime
Issued to a particular CAS Service upon successful validation of a Service or Proxy ticket. These are used by the server to issue Proxy Tickets and will only be issued if the CAS Service has been configured to allow proxying.
9 Hours
Service Ticket Lifetime
Issued to a particular CAS Service and invalidated by the server in exchange for user attributes and/or a Proxy-Granting Ticket.
60 Seconds
Proxy Ticket Lifetime
Issued to a particular CAS Service after a Proxy-Granting ticket is successfully validated.
60 Seconds
The Username Attribute field has multiple options that are determined by the Type of Username Attribute chosen. These fields are LDAP attribute value definitions and their required settings.
Random - Requires a Length setting. The default is 16 characters.
Static - Allows users to add Values and has the capacity for a Regex filter
LDAP - Requires the name of an LDAP Attribute and also has the capacity for a Regex filter.
Proxy Policies instruct the registry application to determine whether it is allowed for proxy authentication. Choose from Reject, Exact, and Regex.
Note
Take care when allowing a Service to use proxy authentication. Misuse of this feature can leave RapidIdentity open to security leaks or other attacks.
Reject - Rejects all proxy attempts. This is the default.
Exact - Allows proxying. The Proxy Callback URL presented must exactly match the URL defined for the CAS Service.
Regex - Allows proxying. The Proxy Callback URL must match a regular expression pattern defined for the CAS Service.
The Attributes section allows you to add attributes to the partner to be used during authentication to define the attribute to be passed through to the service by RapidIdentity. This will open a sidebar with fields for attribute preferences.
Field
Description
Name
Provide a unique name for this attribute.
Description
Add an optional description to further define its purpose.
Attribute Value
Choose the type of value definition to be used for this attribute. As in Step 4, note that the three options are Random, Static, and LDAP with the associated settings for each value.
Attribute Name
Add an attribute name.
A CAS Service is generally identified by a URL during protocol operations. Since RapidIdentity will only allow interaction with Services that have been pre-registered, the Service URL must exactly match one registered CAS Service. This final section defines the URL Matching Rules for the Service. Rules can be set to Exact or Regex, with the same rules and setting requirements as these rules had in Proxy Policies.
Click Create in the final sidebar and then click Save on the main screen. The newly set up CAS Federation Partner should now be visible on the Federation Partners main screen.
Integrating RapidIdentity with a Third-party Identity Provider
Third-party Identity Provider Integration with RapidIdentity
Setting up RapidIdentity to Use a Third-party Identity Provider
This procedure will detail how an Administrator of a third-party Identity Provider (IdP) will set up the integration with RapidIdentity as a Service Provider. The following is an overview of the steps that must be completed to perform the integration:
Gather the SAML metadata for the Identity Provider. These steps will vary based on the Identity Provider that is being used. Refer to the documentation for the Identity Provider to obtain details.
Create a new Service Provider Configuration for RapidIdentity. The Identity Provider's metadata will be required during this step.
Ensure that the Service Provider Entity ID is a unique value.
Provide the IdP logout URL
Set up RapidIdentity as a Relying Party for the Third-party IdP.
Assign the new Service Provider configuration to RapidIdentity.
Create a New Service Provider Configuration for RapidIdentity
When integrating with a third-party IdP, RapidIdentity must be configured to be a Service Provider.
As an administrator, log in to the SAML Identity Provider and retrieve the Federation Metadata XML file.
Note
Refer to the third-party IdP documentation for additional details on locating the metadata.xml file.
Log in to the RapidIdentity portal as an Administrator and access the Service Providers section from the Configuration workspace.
Click the Register Service Provider+ button.
The Register Service Provider window will open.
Hover over the question marks (?) for additional information on completing the fields and for an example.
The table below describes how to complete the Service Provider information. Fields with an asterisk (*) depict a required field.
Field
Description
Name
Enter a name for the Service Provider. For example, RapidIdentity to <Third-party IdP>.
Description
Optionally, enter a description for the service provider.
Entity ID*
The unique identifier for RapidIdentity as the SAML 2.0 Service Provider. When federating with a particular Identity Provider, it must be unique among all of the Relying Parties the Identity Provider federates with.
This value must be a valid URI or URN and it is recommended to use the base RapidIdentity URL (e.g. "https://{host}/"). For example, <https://localhost.riexample.com/thirdpartyidp>.
Base URL
Enter the URL from which to construct SAML endpoints; the URL must be comprised of protocol, server, port, and context path. The URL is the base URL to the Rapididentity instance (e.g. "https://{host}[:{port}]/").
This can be exactly the same as the Entity ID, but is not a requirement. For example, <https://localhost.riexample.com>.
Logout URL*
A URL to redirect the user's browser to after logging out of the local RapidIdentity session. This typically points to the logout URL of the Identity Provider, such as "https://idp-host/idp/logout."
The URL must be comprised of protocol, server, port, and context path.
Organization Name
Enter the name of the organization associated with the provider. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata.
Organization URL
Enter the website of the organization associated with the provider. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata.
Contact Email Address
Email address for the contact at the organization. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata.
IDP Metadata*
Paste the XML metadata from the third-party IdP.
Tip
A metadata URL can not be used as metadata.
After entering the required information, click Save.
The service provider configuration will be listed in the workspace and can be made active by "Assigning" it in RapidIdentity. Refer to Assign the Third-Party IdP to RapidIdentity for details.
Set up RapidIdentity as a Relying Party for the Third-party Identity Provider
It is necessary to create a relying party in the third-party Identity Provider. A relying party object consists of a variety of identifiers, names, and rules that identify this partner to the local Federation Service.
In order to successfully integrate with any third-party IdP, that IdP is required to return either the idautoID or the unique email address of the authenticating user.
Release the idautoID value:
The IdP instance must be able to communicate with a datastore that contains the idautoID attribute, such as an Active Directory DC.
Must be released as "idautoid" (case-insensitive) or "urn:idauto.net:saml:attribute:idautoID".
Release the unique email address:
RapidIdentity is required to have the same value provisioned in its backing directory where the email address is unique.
Must be released as "
mail", "email", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"or"http://schemas.xmlsoap.org/claims/EmailAddress"
Note
When RapidIdentity receives a SAML assertion with multiple email address values (and no idautoID), the values will be processed in the order received and the first one which uniquely identifies a User will be accepted.
Follow the configuration steps for creating a relying party for RapidIdentity in the third-party IdP.
Assign the Third-party Identity Provider to RapidIdentity
After creating a new service provider configuration for RapidIdentity with a third-party IdP, RapidIdentity will be listed as a service provider in the workspace and can be assigned applications for login.
Tip
It is helpful to open an additional browser window and log in to the RapidIdentity Portal simultaneously before altering the Service Provider configuration. This will allow an administrator to cancel changes in the case of an error during configuration.
RapidIdentity as a service provider will be listed in the workspace and can be assigned applications for login. Refer to Assign the third-party IdP to RapidIdentity for details.
If successful, the Assigned to RapidIdentity column will display a "Yes" value. A brief confirmation message, "Saved" will be displayed at the top of the workspace.
Close all browser sessions.
You should be forwarded to the third-party IdP for authentication.
Test SAML SSO for the Third-party IdP
In a new browser window navigate to RapidIdentity.
If configured properly, users should be redirected to the third-party IdP to authenticate. Once authenticated, when accessing RapidIdentity, you should be logged in.
Integrating RapidIdentity with ADFS as a Third-party Identity Provider
Configuring ADFS as a SAML Identity Provider for RapidIdentity
This procedure will detail how an ADFS Administrator will configure ADFS as an Identity Provider (IdP) for RapidIdentity as a Service Provider.
When users access RapidIdentity they are directed to ADFS to authenticate. Once the user authenticates successfully in ADFS they will be redirected to RapidIdentity.
Refer to the following sections for details on the integration and configuration.
Configuring the Claim Issuance Policy
Configuring the Release of the idautoID
Configuring the release of the unique Email Address
Set up the Service Provider Configuration in RapidIdentity
This procedure will detail the first step of how an ADFS Administrator will set up the integration with RapidIdentity as a Service Provider.
As an administrator, log in to ADFS and retrieve the Federation Metadata XML file.
Note
Refer to the ADFS documentation for additional details on locating the metadata.xml file.
Log in to the RapidIdentity portal as an Administrator and access the Service Providers section from the Configuration workspace.
Click the Register Service Provider+ button.
The Register Service Provider window will open.
Hover over the question marks (?) for additional information on completing the fields and for an example.
The table below describes how to complete the Service Provider information.
Field
Description
Name
Enter a name for the Service Provider. For example, RapidIdentity to ADFS.
Description
Optionally, enter a description for the service provider.
Entity ID
The unique identifier for RapidIdentity as the SAML 2.0 Service Provider. When federating with a particular Identity Provider, it must be unique among all of the Relying Parties the Identity Provider federates with. This value must be a valid URI or URN and it is recommended to use the base RapidIdentity URL (e.g. "https://{host}/"). For example, <https://localhost.riexample.com/ADFS>.
Base URL
Enter the URL from which to construct SAML endpoints; the URL must be comprised of protocol, server, port, and context path. and is the base URL to the Rapididentity instance (e.g. "https://{host}[:{port}]/"). This can be exactly the same as the Entity ID, but is not a requirement. For example, <https://localhost.riexample.com>.
Logout URL
A URL to redirect the user's browser to after logging out of the local RapidIdentity session. This typically points to the logout URL of the Identity Provider, such as "https://idp-host/idp/logout." The URL must be comprised of protocol, server, port, and context path. Click to automatically populate with the current IdP logout URL. For example, <https//:3rdpartyidp.com/signout>.
Organization Name
Enter the name of the organization associated with the provider. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata.
Organization URL
Enter the website of the organization associated with the provider. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata .
Contact Email Address
Email address for the contact at the organization. Optional, and if specified, shows up in the Service Provider's SAML 2.0 metadata.
IDP Metadata
Paste the XML metadata from the server.
Tip
A metadata URL can not be used as metadata.
Export the Service Providers' metadata.
After entering the required information, click Save. The RapidIdentity service provider will be listed in the workspace and can be assigned applications for login.
To activate this Service Provider configuration and enable SAML authentication for RapidIdentity, select the entry in the list and click Assign to RapidIdentity in the action bar.
If successful, the Assigned to RapidIdentity column will display a "Yes" value. A brief confirmation message, "Saved" will be displayed at the top of the workspace.
Set up a Relying Party Trust in ADFS
It is necessary to create a relying party trust in ADFS. A relying party trust object consists of a variety of identifiers, names, and rules that identify this partner to the local Federation Service.
Tip
It is helpful to open an additional browser window and log in to the RapidIdentity Portal simultaneously before altering the Service Provider configuration. This will allow an administrator to cancel changes in the case of an error during configuration that may prevent logging back in as an administrator.
Log in to ADFS and navigate to the ADFS Management application.
Click Relying Party Trusts and choose Add Relying Party Trust... to launch the wizard.
Click Claims aware
Claim tokens are issued by the IdP after authenticating the user. The login for the application will be the Service Provider, RapidIdentity.
Either import the Service Provider metadata or choose Enter data about the relying party manually.
Tip
For ease of access, import the metadata from a local file and name it a Display Name of "RapidIdentity."
In the Choose Access Control Policy step, select Permit everyone.
In the Ready to Add Trust option, no additional configuration is required.
Configuring the Claim Issuance Policy
In this step, ADFS will be configured to release assertion attributes to RapidIdentity. In order to successfully integrate with ADFS as an IdP, either the idautoID or the unique email address of the authenticating user must be returned.
Possible if the IdP instance can communicate with an Active Directory DC which contains that attribute.
Must be released as "idautoid" (case-insensitive) or "urn:idauto.net:saml:attribute:idautoID."
RapidIdentity is required to have the same value provisioned in its backing directory and the email address is unique.
Must be released as "mail", "email", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" or "http://schemas.xmlsoap.org/claims/EmailAddress."
Note
When RapidIdentity receives a SAML assertion with multiple email address values (and no idautoID), the values will be processed in the order received. The first value which uniquely identifies a User will be accepted.
Configuring the Release of idautoID
In ADFS Management, navigate to Claim Description and choose Add Claim Description.
Enter the required values. Below is a sample of values to be entered.
Table 77. Claim Description ValuesField Name
Value
Display Name
IDautoID
Short Name
idautoID
Claim Identifier
idautoID
Description
<blank>
<Publish this claim description...>
<both boxes unchecked>
Navigate to Relying Party Trusts and choose the "RapidIdentity" relying party. Select Edit the Claim Issuance Policy.
Click Add Rule....
Choose the Send LDAP Attributes as Claims claim rule template.
Name the Claim rule similar to "Send IdautoID."
Choose the Active Directory attribute store.
Map the "IdautoID" LDAP Attribute to the "IdautoID" Outgoing Claim Type.
Click Finish and then OK to finish editing the Claim Issuance Policy.
Configuring the release of Email Address
Navigate to Relying Party Trusts and choose the "RapidIdentity" relying party.
Click Edit the Claim Issuance Policy.
Click Add Rule.
Chose the "Send LDAP Attributes as Claims" claim rule template.
Name the claim rule similar to "Send Email Address."
Choose the Active Directory Attribute store.
Map the E-Mail-Addresses LDAP Attribute to the E-Mail Address Outgoing Claim Type.
Click Finish and then click OK to complete editing the Claim Issuance Policy.
Test SAML SSO with ADFS
In a new browser window navigate to RapidIdentity.
If configured properly, users should be redirected to ADFS to authenticate. Once authenticated, when accessing RapidIdentity, you should be logged in.
Editing the Web Template
The RapidIdentity Federation login page supports CSS configuration enhancements to allow organizations to brand their login page to best serve their organization and user population.
Follow these steps to edit the web template used in the login screen.
From the Portal Module Selector, choose Configuration. Then from the Security menu, choose Identity Providers.
From the Left Menu Items, select Web Template.
The Edit IDP Web Customizations page contains fields to edit the HTML web template. Click a checkbox to activate a function, or enter text in the blank field for the selection to enter the value.
Field
Description
Load Helplinks in Same Tab/Window
Allows administrators to determine whether the Forgot My Username and Forgot My Password dialogs open in new tabs or windows, based on the current browser configuration. If checked, the dialog boxes will load in the same tab or window; if unchecked, these dialog boxes proceed in different browser tabs. Currently, in order to facilitate the same tab or window feature, the help links are loaded in an <iframe>.
Page Title
Enter a title for the web template for the login page
Favicon URL
Used to include a URL for the browser to display a logo
Custom Logo Image URL
Enter a URL for a custom logo image. After entering a URL for a logo image, a box appears underneath called "Custom Logo Preview" to show the image that was entered.
Header Background Color, Header Text Color, Body Background Color, Body Text Color
Basic mode is the default mode and allows administrators to configure colors from a color picker to be configured. For each of these four selections, optionally click the drop-down for the color box, and customize the scheme.
Enable Custom CSS (Advanced) , Enable Custom HTML (Advanced)
Advanced mode allows administrators to configure the login page through writing their own CSS and also to include HTML for additional divisions.
Click the checkbox to allow Administrators to use CSS to configure the login page further to suit any organization's branding requirements. To ensure Basic mode color selections are retained upon upgrade, click the Enable Custom CSS (Advanced) checkbox. Custom styling from versions prior to 3.5 are not migrated.
Note
Any valid HTML entered into the text area will manifest as new HTML on the login pages. Note that javascript included in Custom HTML is not supported and will not function as expected.
An authentication policy has to be activated for Custom HTML to function properly.
Note
Custom HTML is invisible by default, but can be made visible by CSS. You must add the CSS visibility property to the Custom CSS field and set it to visible as it applies to the custom HTML. For example, if your custom HTML uses a
<div>tag, you would need to add the following code to the Custom CSS:.custom-html{ height:auto; visibility:visible; }For additional information on CSS, refer to CSS Styling later in this topic.
Logout Body
Allows administrators to write custom HTML to be included in the body of the logout web page. Administrators can include, for example, custom messages and styling to redirect users to a different site. Use {i18n:<key>} syntax in the custom HTML to localize it. Those custom i18n values can, themselves, contain HTML.
Claim Account Link Label
The text that will be used at the login screen for new users to claim their account.
Claim Account URL
The URL that the user will be redirected to in order to claim their account with RapidIdentity. The default for this field is
/portal/claim.Help Links
Provide the URLs and display names that will be used for Forgot My Username and Forgot My Password actions.
Click Trigger Web Reload at the bottom of the workspace to activate the changes or Reset to Defaults to overwrite any updates.
To ensure customizations are not modified from future product development updates, reference specific CSS identifiers/selectors with the prefix ".cs-" as shown in the screenshot below.
 |
Letter | CSS identifiers with the prefix ".cs-" | Style |
A | ".cs-body" | Page Body Style |
B | ".cs-header" | Page Header Style |
C | ".cs-heading" | Heading Text |
D | ".cs-login-logo" | Logo Image |
E | ".cs-button-aslink" | Help Links |
F | ".cs-button" | Primary Buttons |
G | ".cs-wrapper.content" | Body Below Header |
CSS Styling
Custom CSS styling may be written as follows:
.cs-wrapper
{ background-color: #afbce1; }
.cs-login-logo
{ background: url(//abc.def.com/example); }
.cs-header
{ background-color: #0d66b2; }
.cs-button
{ color: #0d66b2; background-color: #d7ddf0; }
.cs-button:hover
{ color: #d7ddf0; background-color: #0d66b2; }
.cs-button-aslink
{ top: 240px; } More advanced, custom CSS styling configurations are possible. One example is shown below.
 |
The whitespace above the light blue box containing the username and password fields is reserved for the official organization logo. The CSS for this particular configuration for use as a representative example to edit is as follows:
.cs-body, .cs-wrapper {
background-color: #fff;
font-family: 'Century Gothic', Arial, sans-serif;
}
.cs-container {
position: relative;
}
.cs-header {
display: none;
}
.cs-login-logo {
margin: auto;
width: 192px;
height: 100px;
margin-bottom: 40px;
background-image: url(http://[yourOrganizationLogoUrlWithImageExtention);
background-size: 192px 102px;
}
.cs-login-container {
text-align: center;
color: #0032a0;
font-size: 16px;
clear: left;
padding: 20px;
border: 1px solid #c4cfe6;
background: #E3EAFC;
border-radius: 20px;
box-shadow: 0px 2px 7px rgba(100,140,220,.6);
}
.cs-login-container:after {
content: "For password help call 123-456-7890";
font-size: 12px;
}
.input {
display: block;
width: 100%;
height: 40px;
margin-bottom: 15px;
padding-right: 10px;
padding-left: 10px;
background-color: #F6F8FF;
border-radius: 3px;
color: #445963;
outline: 0;
border: 1px solid #e6e6e6;
}
.cs-button-wrapper {
margin: 0;
}
.cs-button[type="submit"] {
background-color: #0032a0;
color: #F9F9F9;
width: 80px;
height: 80px;
text-indent: -99999px;
line-height: 0;
border-radius: 100px;
margin: 40px 0;
}
.cs-button[type="submit"]::after {
content: "Sign In";
text-indent: -18px;
display: block;
line-height: initial;
font-weight: 300;
}
.cs-button[type="button"] {
background-color: transparent;
text-indent: -99999px;
line-height: 0;
background: url(https://www.wpclipart.com/signs_symbol/button/
metal_buttons/arrow_button_metal_blue_right.png)
240px center no-repeat;
background-size: 20px 20px;
}
.cs-button[type="button"]:hover {
background-color: transparent;
}
.cs-button[type="button"]::after {
content: "New users set up your account";
text-indent: 0;
display: block;
color: #0032a0;
font-size: 12px;
font-weight: normal;
font-family: 'Century Gothic', Arial, sans-serif;
}
.cs-nav-next-button {
background-image: none;
}
.claim-account-text, .cs-heading-container {
display: none;
}
.need-help-link {
margin: 0;
display: inline-block;
position: absolute;
top: 310px;
right: 55px;
}
.cs-button-aslink {
color: #2749A5;
font-size: 10px;
float: none;
margin: 0;
}
.button:hover {
background-color: #021a4c;
transition: background-color 60ms ease-out;
}
.placeholder-container {
position: relative;
}
span.placeholder-text {
display: block;
top: 0;
left: 15px;
color: #2749A5;
font-size: 12px;
}
.placeholder-input {
position: relative;
top: 16px;
border-radius: 30px;
}
.input-toggle {
background-image: none;
width: 80px;
top: -2px;
color: #2749A5;
}
.input-toggle::after {
content: "Show Password";
font-size: 10px;
}
#pwd {
margin-top: 30px;
}
::-webkit-input-placeholder { /* WebKit browsers */
color: #fff;
}
:-moz-placeholder { /* Mozilla Firefox 4 to 18 */
color: #fff;
opacity: 1;
}
::-moz-placeholder { /* Mozilla Firefox 19+ */
color: #fff;
opacity: 1;
}
:-ms-input-placeholder { /* Internet Explorer 10+ */
color: #fff;
}
.error-message {
margin-bottom: 0;
margin-left: 16px;
padding-top: 5px;
font-size: 12px;
}
.content:after {
content: "Please note that the use of the [organizationName]
network, computer equipment, and resources are not private
and may be monitored for appropriate use. For further
information, please refer to the [organizationName]
Acceptance Use Policy to understand appropriate use.";
text-align: center;
width: 310px;
margin: 40px auto;
font-size: 12px;
color: grey;
} Adapter Actions
Active Directory Adapter Reference
The Active Directory adapter depends on the Connect Active Directory Password Filter to be able to capture password changes in AD.
Install and configure the password filter only if the environment is using Active Directory.
Adds a member to a Group on the Active Directory Server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
groupDn* | text, expression, variable | theDN of the Group |
memberDn* | text, expression, variable | the DN of the member |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection()
groupDn = "CN=TestGroup,OU=Groups,DC=test,DC=local"
newDn = "CN=Test User,OU=People,DC=test,DC=local"
result = addADGroupMember(session, groupDn, newDn)
if(result) {
log("User added to Group " + groupDn)
} else {
log("User not added to Group " + opegroupDn)
}
close(session)Adds members to a Group on the Active Directory Server.
Property | Value | Description |
|---|---|---|
memberDns* | expression, variable | array of DNs of the members |
groupDn* | text, expression, variable | theDN of the Group |
adConnection* | expression, variable | the AD connection |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
groupDn = "CN=TestGroup,OU=Groups,DC=test,DC=local"
newMembers = createArray()
appendArrayItem(newMembers, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(newMembers, "CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(newMembers, "CN=Test User 3,OU=People,DC=test,DC=local")
result = addADGroupMembers(session, groupDn, newMembers)
if(result) {
log("Users added to Group " + groupDn)
} else {
log("Users not added to Group " + groupDn)
}
close(session)Add a User to the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
record* | expression, variable | the Record containing fields to set - must contain the dn in the @dn field |
password* | password, string, expression, variable | the initial password |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
record = createRecord()
# Set default values
setRecordFieldValue(record, "objectClass", "User")
setRecordFieldValue(record, "sn", "User")
setRecordFieldValue(record, "givenName", "Test")
setRecordFieldValue(record, "mail", "TestUser@test.local")
setRecordFieldValue(record, "sAMAccountName", "TestUser")
setRecordFieldValue(record, "homeDirectory", "\\\\Server\\Share\\Users\\"
+ record['sAMAccountName'])
setRecordFieldValue(record, "homeDrive", "H:")
password = "changeme"
# Set DN
destinationDN = "OU=People,DC=test,DC=local"
setRecordFieldValue(record, "cn", record['givenName'] + " "
+ record['sn'])
setRecordFieldValue(record, "@dn", "cn=\"" + record.cn + "\","
+ destinationDN)
removeRecordField(record, "cn")
if(!record['sn'] || !record['givenName'] || !record['mail'] ||
!record['sAMAccountName']) {
log("Minimum requirements not met for add - " + record)
return null
} else {
}
# Add User
result = addADUser(session, record, *********)
if(result) {
log("Record added - " + record)
if(record['homeDirectory']) {
result = createADHomeDirectory(system['session'],
record['@dn'], record['homeDirectory'])
if(result) {
log("Directory created - " + record['homeDirectory'])
} else {
log("Unable to create directory - "
+ record['homeDirectory'])
}
} else {
}
} else {
log("Record not added - " + record)
}
close(session)Add an array of Users to the Active Directory Server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
records* | expression, variable | array of Records containing fields to set - must contain the dn in the @dn field |
passwords* | expression, variable | array of initial passwords |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
# Build arrays of User records and passwords to add
newUserRecords = createArray()
newUserPasswords = createArray()
i = 0
while(i < 10) {
record = createRecord()
# Set default values
setRecordFieldValue(record, "objectClass", "User")
setRecordFieldValue(record, "sn", "User" + i)
setRecordFieldValue(record, "givenName", "Test")
setRecordFieldValue(record, "mail", "TestUser" + i "@test.local")
setRecordFieldValue(record, "sAMAccountName", "TestUser" + i)
setRecordFieldValue(record, "homeDirectory",
"\\\\Server\\Share\\Users\\" +
record['sAMAccountName'])
setRecordFieldValue(record, "homeDrive", "H:")
password = "changeme"
# Set DN
destinationDN = "OU=People,DC=test,
DC=local"setRecordFieldValue(record, "cn",
record['givenName']
+ " " + record['sn'])
setRecordFieldValue(record, "@dn", "cn=\"" + record['cn'] + "\"," + destinationDN)
removeRecordField(record, "cn")
if(record['sn'] && record['givenName'] && record['mail'] &&
record['sAMAccountName']) {
appendArrayItem(newUserRecords, record)
appendArrayItem(newUserPasswords, password)
} else {
log("Minimum requirements not met for add - " + record)
}
i = i + i
}
if(newUserRecords['length'] == 0) {
# No users to add
return
}
# Add Users
results = addADUsers(session, newUserRecords, newUserPasswords)
i = 0;
forEach(record, newUserRecords) {
result = results && results[i];
if(result) {
log("Record added - " + record)
if(record['homeDirectory']) {
result = createADHomeDirectory(system['session'],
record['@dn'],
record['homeDirectory'])
if(result) {
log("Directory created - "
+ record['homeDirectory'])
} else {
log("Unable to create directory - "
+ record['homeDirectory'])
}
} else {
}
} else {
log("Record not added - " + record)
}
i = i + 1
}
close(session)Compare a Record field on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dn* | expression, variable | the DN of the Record |
fieldName | text, expression, variable | name of the field to be compared |
fieldValue | text, expression, variable | value of the field to be compared |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
mail = "testuser@test.local"
isEqual = compareADField(session, dn, "mail", mail)
if(isEqual == true) {
log("mail = " + mail)
} else {
log("mail <> " + mail)
}
close(session)Create a Home Directory for a User on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
record* | expression, variable | The record to save |
uncPath* | text, expression, variable | the UNC path of the home directory |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
extraProperties | expression, variable | extra possible properties supported for JCIFS NG |
Example
session = openADConnection(...)
setRecordFieldValue(record, "homeDirectory",
"\\\\server1.test.local\\share\\users\\testuser")
setRecordFieldValue(userRecord, "userPrincipalName", idautotestuser@test1.local
result = createADHomeDirectory(session, record['userPrincipalName'],
record['homeDirectory'])
if(result) {
log("Directory created - " + record['homeDirectory'])
} else {
log("Unable to create directory - " + record['homeDirectory'])
}
close(session)Delete a Home Directory for a User on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
userDn* | text, expression, variable | the DN of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
extraProperties | expression, variable | extra possible properties supported for JCIFS NG |
Example
session = openADConnection(...)
setRecordFieldValue(record, "homeDirectory",
"\\\\server1.test.local\\share\\users\\testuser")
setRecordFieldValue(record, "@dn",
"CN=test user,OU=People,DC=test,DC=local")
result = deleteADHomeDirectory(session, record['@dn'],
record['homeDirectory'])
if(result) {
log("Directory deleted - " + record['homeDirectory'])
} else {
log("Unable to delete directory - " + record['homeDirectory'])
}
close(session)Delete a record from the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dn* | text, expression, variable | the DN of the Record |
recursive | boolean, expression, variable | recursively delete subtree rooted at dn (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dn = "CN=test user,OU=People,DC=test,DC=local"
result = deleteADRecord(session, dn)
if(result) {
log("Record deleted - " + dn)
} else {
log("Unable to delete record - " + dn)
}
close(session)Delete array of Records from the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dns* | expression, variable | array of DNs of the Records |
recursive | boolean, expression, variable | recursively delete subtree rooted at dn (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 3,OU=People,DC=test,DC=local")
results = deleteADRecords(session, dns)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("Record deleted - " + dn)
} else {
log("Unable to delete record - " + dn
}
i = i + 1
}
close(session)Get 'Account is Disabled' flag.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
accountDn* | text, expression, variable | the DN of the account |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
setRecordFieldValue(record, "@dn",
"CN=test user,OU=People,DC=test,DC=local")
result = getADAccountDisabled (Session, record['@dn'])
if(result) {
log("Active Directory Account Disabled", "green")
} else {
log("Active Directory Account NOT Disabled", "red")
}
close(session)Get 'Account is Disabled' flag from multiple accounts.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
accountDns* | expression, variable | array of DNs of the accounts |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 3,OU=People,DC=test,DC=local")
results = getADAccountsDisabled(session, dns)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("Account is disabled - " + dn)
} else {
log("Account is enabled - " + dn)
}
i = i + 1
}
close(session)Get changed Records from an Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
filter* | text, expression, variable | the search filter expression or an example Record |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
cookie | expression, variable | cookie returned from previous invocation (default: none, which will return all objects) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Warning
This action, as shown in the example below, provides valid results when configured properly. However, getADChanges is no longer the preferred method to obtain changed record results within an Action Set.
The current preferred method to obtain changed record results is to use the openADChangeIterator action, as shown below.
Example
session = openADConnection(...)
cookieFile = "/cookie/studentsAD.cookie"
fileExists = isFile(cookieFile)
if(!fileExists) {
saveToFile(cookieFile, "")
} else {
}
varCookie = loadFileAsBytes(cookieFile)
# getRecords
moreResults = 1
while(moreResults != 0) {
recordChanges = getADChanges(session,
"OU=People,DC=test,DC=local", "sub",
"(employeeType=Student)", "cn,sn,givenName", varCookie)
moreResults = 0
if(recordChanges) {
log("Count: " + recordChanges.length)
} else {
}
# foreach
forEach(recordChange, recordChanges) {
if(recordChange.objectClass == "cookie") {
saveToFile(cookieFile, recordChange.cookie)
varCookie = recordChange.cookiemoreResults =
Number(recordChange.moreResults)
} else {
record = getADRecord(session, recordChange['@dn'], "*")
# transformations
if(!record) {
continue()
} else {
log("Name information has changed: " + record.sn
+ " " + record['givenName'])
}
}
}
}
# Close Connections
close(session)Get 'Password does not expire' flag.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
accountDn* | text, expression, variable | the DN of the account |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dn = "CN=Test User,OU=People,DC=test,DC=local"
result = getADDontExpirePassword(session, dn)
if(result != null) {
if(result == true) {
log("Password expires")
} else {
log("Password does not expire")
}
} else {
log("Unable to get UserCannotChangePassword")
}
close(session)Get 'Password does not expire' flag from multiple accounts.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
accountDns* | expression, variable | array of DNs of the accounts |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 3,OU=People,DC=test,DC=local")
results = getADDontExpirePasswords(session, dns)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("Account password doesn't expire - " + dn)
} else {
log("Account password expires - " + dn)
}
i = i + 1
}
close(session)Gets decrypted password stored by RapidIdentity password filter from an Active Directory entry.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dn* | text, expression, variable | the DN of the Record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
password = "password1"
dn = "CN=Test User,OU=People,DC=test,DC=local"
adPwd = getADPassword(session, dn)
if(adPwd && adPwd == password) {
log("User has not changed their default password!")
} else {
log("Password has been changed from default.")
}
close(session)Gets an array of decrypted passwords stored by RapidIdentity password filter from Active Directory entries.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dns* | expression, variable | array of DNs of the Records |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
password = "password1"
dns = createArray()
appendArrayItem(newMembers,
"CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(newMembers,
"CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(newMembers,
"CN=Test User 3,OU=People,DC=test,DC=local")
adPwds = getADPasswords(session, dns)
i = 0
forEach(dn, dns) {
adPwd = adPwds && adPwds[i]
if(adPwd == password) {
log("User has not changed their default password!")
} else {
log("Password has been changed from default.")
}
i = i + i
}
close(session)Get a Record from the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dn* | expression, variable | the DN of the Record |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dn = "CN=Test User,OU=People,DC=test,DC=local"
record = getADRecord(session, dn, "cn,sn,givenName")
if(record) {
log("User found: " + record)
} else {
log("User not found: " + dn)
}
close(session)Get multiple Records from the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
filter* | text, expression, variable | the search filter expression or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: the server maximum) |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
baseDn = "OU=People,DC=test,DC=local"
filter = "(objectClass=user)"
records = getADRecords(session, baseDn, "sub", filter,
"cn,sn,givenName")
log("Found: " + records.length)
forEach(record,records) {
log("User found: " + record)
}
close(session)Get an array of Records from the Active Directory server by DN.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dns* | expression, variable | array of DNs of the Records |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(newMembers,
"CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(newMembers,
"CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(newMembers,
"CN=Test User 3,OU=People,DC=test,DC=local")
records = getADRecordsByDN(session, dns, "cn,sn,givenName")
i = 0
forEach(dn, dns) {
record = records && records[i]
if(record) {
log("User found: " + record)
} else {
log("User not found: " + dn)
}
i = i + 1
}
close(session)Get AD 'User Cannot Change Password' flag.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
userDn* | text, expression, variable | the DN of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dn = "CN=Test User,OU=People,DC=test,DC=local"
result = getADUserCannotChangePassword(session, dn)
if(result != null) {
if(result == true) {
log("User cannot change password")
} else {
log("User can change password")
}
} else {
log("Unable to get UserCannotChangePassword")
}
close(session)Get AD 'User Cannot Change Password' flag from multiple Users.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
userDns* | expression, variable | array of DNs of the Users |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 3,OU=People,DC=test,DC=local")
results = getADUsersCannotChangePassword(session, dns)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("User cannot change password - " + dn)
} else {
log("User can change password - " + dn)
}
i = i + 1
}
close(session)Modify a Record on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dn* | expression, variable | the DN of the Record |
removeRecord | expression, variable | a Record containing attributes/values to be removed |
addRecord | expression, variable | a Record containing attribute values to be added |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
addRecord = createRecord()
removeRecord = createRecord()
setRecordFieldValue(addRecord, "objectClass", "customObjectClass")
addRecordField(removeRecord, "telephoneNumber")
dn = "CN=Test User,OU=People,DC=test,DC=local"
result = modifyADRecord(session, dn, removeRecord, addRecord)
if(result) {
log("Record modified - Added " + addRecord)
log("Record modified - Removed " + removeRecord)
} else {
log("Record not modified - " + dn)
}
close(session)Modify an array of Records on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dns* | expression, variable | array of DNs of the Records |
removeRecords | expression, variable | array of Records containing attributes/values to be removed |
addRecords | expression, variable | array of Records containing attribute values to be added |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
addRecord = createRecord()
removeRecord = createRecord()
setRecordFieldValue(addRecord, "objectClass", "customObjectClass")
addRecordField(removeRecord, "telephoneNumber")
addRecords = createArray()
removeRecords = createArray()
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(addRecords, addRecord)
appendArrayItem(removeRecords, removeRecord)
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(addRecords, addRecord)
appendArrayItem(removeRecords, removeRecord)
appendArrayItem(dns, "CN=Test User 3,OU=People,DC=test,DC=local")
appendArrayItem(addRecords, addRecord)
appendArrayItem(removeRecords, removeRecord)
results = modifyADRecords(session, dns, removeRecords, addRecords)
i = 0
forEach(dn, dns) {
result = results && result[i]
if(result) {
log("Record modified - Added " + addRecords[i] + " to "
+ dn)
log("Record modified - Removed " + removeRecords[i]
+ " to " + dn)
} else {
log("Record not modified - " + dn)
}
i = i + 1
}
close(session)Moves a Home Directory for a User on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
userDn* | text, expression, variable | the DN of the User |
uncPath* | text, expression, variable | the new UNC path of the home directory |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
extraProperties | expression, variable | extra possible properties supported for JCIFS NG |
Example
session = openADConnection(...)
homeDirectory = "\\\\server1.test.local\\share\\users\\testuser"
dn = "CN=test user,OU=People,DC=test,DC=local"
result = moveADHomeDirectory(session, dn, homeDirectory)
if(result) {
log("Directory moved - " + homeDirectory)
} else {
log("Unable to move directory - " + homeDirectory)
}
close(session)Open AD Change Iterator.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
filter* | text, expression, variable | the search filter expression or an example Record |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
cookieFile* | text, expression, variable | path to file to load/save cookie |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Warning
The cookie file can impact the results obtained when running openADChangeIterator. If the cookie file does not exist in the path, the results when running the Action Set will show all records based on the listed action properties and their values. If the cookie file does exist in the path, the results when running the Action Set will show the results that have changed since the Action Set was last run relative to the existing cookie file. Thus, the presence of a cookie file could lead to inaccurate results when running the Action Set. If it is necessary to ensure the Action Set is run for all targeted records, one option is to rename or move the cookie file.
Example
session = openADConnection(...)
cookieFile = "/cookie/studentsAD.cookie"
recordChanges = openADChangeIterator(session,
"OU=People,DC=test,DC=local", "sub",
"(employeeType=Student)", "cn,sn,givenName", cookieFile)
# foreach
forEach(recordChange, recordChanges) {
record = getADRecord(session, recordChange['@dn'], "*")
# transformations
if(!record) {
continue()
} else {
log("Name information has changed: " + record['sn'] + " "
+ record['givenName'])
}
}
# Close Connections
close(session)Open a connection to an Active Directory server.
Property | Value | Description |
|---|---|---|
adHost* | text, expression, variable | the host name or IP address of the Active Directory server |
adPort | expression, variable | the TCP port of the Active Directory server (default: 636 if using SSL, 389 otherwise.) |
useSSL | boolean, expression, variable | use SSL/TLS (default: false.) |
userDn | text, expression, variable | the user DN for authenticating to the Active Directory server |
password | password, string, expression, variable | the user password for authenticating to the Active Directory server |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
extraProperties | expression, variable | Defined below as applicable |
Property | Description |
|---|---|
abandonOnTimeout | Indicates whether the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period |
captureConnectStackTrace | Indicates whether the LDAP SDK should capture a thread stack trace for each attempt made to establish a connection |
useKeepAlive | Indicates whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections |
useTCPNoDelay | Indicates whether to use the TCP_NODELAY option for the underlying sockets used by associated connections |
followReferrals | Indicates whether associated connections should attempt to follow any referrals that they encounter |
usePassiveSSLSocketVerifier | If true, corresponds to RapidIdentity setting a |
Property | Description |
|---|---|
connectTimeoutMillis | The maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up |
useLinger | The SO_LINGER timeout for the underlying sockets used by associated connections |
referralHopLimit | The maximum number of hops that a connection should take when trying to follow a referral |
responseTimeoutMillis | The maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server |
Example
host = "server1.test.local"
port = "636"
ssl = true
user = "test.local\\administrator"
password = "mySecur3p@ssw0rd"
session = openADConnection(host,port,ssl,user,password)
if(session) {
log("Successfully connected to AD!")
} else {
log("Unable to connect to AD")
}
close(session)Open Record Iterator for AD server to sort large sets of records.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
baseDn* | text, expression, password, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
filter* | text, expression, password, variable | the search filter expression or an example record |
initialOffset | expression, variable | the number of records to skip initially. (default: 0) |
pageSize | expression, variable | the preferred number of records to fetch at a time from AD server. (default: 100) |
attributes | text, expression, password, variable | comma-separated list of attributes to check/return (default: none) |
sortKey | text, expression, password, variable | comma-separated list of attributes to use as sort keys, with optional +/- to indicate sort direction. (default: unsorted) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
sessionAD = openADConnection("10.100.30.35", "636", true,
"administrator@test.local",<Password>)
# Record Iterator
i = 0
recordChanges = openADRecordIterator(sessionAD,
"ou=students,ou=people,dc=test,dc=local", "sub",
"(employeeType=Student)", undefined, undefined, "cn", undefined)
recordIterator: forEach(recordChange, recordChanges) {
log(recordChange)
i = i +1
if(i >= 30) {
break(recordIterator)
} else {
}
}
}
# Close
close(sessionLDAP)Removes a member from a Group on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
groupDn* | text, expression, variable | theDN of the Group |
memberDn* | text, expression, variable | the DN of the member |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
groupDn = "CN=TestGroup,OU=Groups,DC=test,DC=local"
newDn = "CN=Test User,OU=People,DC=test,DC=local"
result = removeADGroupMember(session, groupDn, newDn)
if(result) {
log("User removed from Group " + groupDn)
} else {
log("User not removed from Group " + groupDn)
}
close(session)Removes multiple members from a Group on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
groupDn* | text, expression, variable | theDN of the Group |
memberDns* | expression, variable | array of DNs of the members |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
groupDn = "CN=TestGroup,OU=Groups,DC=test,DC=local"
newMembers = createArray()
appendArrayItem(newMembers,
"CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(newMembers,
"CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(newMembers,
"CN=Test User 3,OU=People,DC=test,DC=local")
result = removeADGroupMembers(session, groupDn, newMembers)
if(result) {
log("Users removed from Group " + groupDn)
} else {
log("Users not removed from Group " + groupDn)
}
close(session)Rename and/or move an object on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
oldDn* | text, expression, variable | the original DN of the object |
newDn* | text, expression, variable | the new DN of the object |
keepOldRdn* | boolean, expression, variable | preserve that attribute values used by the old dn (default: false.) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
oldDn = "CN=Test User,OU=People,DC=test,DC=local"
newDn = "CN=Test User,OU=Staff,OU=Internal,OU=People,DC=test,DC=local"
result = renameADRecord(session, oldDn, newDn)
if(result) {
log("User moved or renamed to " + newDn)
} else {
log("User not moved or renamed " + oldDn)
}
close(session)Save a Record to the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
record* | expression, variable | the Record to save - must contain the dn in the @dn field |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
record = createRecord()
setRecordFieldValue(record, "telephoneNumber", "555-555-1234")
addRecordFieldValue(record, "telephoneNumber", "555-555-9876")
dn = "CN=Test User,OU=People,DC=test,DC=local"
setRecordFieldValue(record, "@dn", dn)
result = saveADRecord(session, record)
if(result) {
log("Record saved - " + record)
} else {
log("Record not saved - " + record)
}
close(session)Save an array of Records to the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
records* | expression, variable | the array of Records to save - must contain the dn in the @dn field |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
records = createArray()
record = createRecord()
setRecordFieldValue(record, "telephoneNumber", "555-555-1234")
addRecordFieldValue(record, "telephoneNumber", "555-555-9876")
setRecordFieldValue(record, "@dn",
"CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(records, record)
record = createRecord()
setRecordFieldValue(record, "telephoneNumber", "555-555-4321")
addRecordFieldValue(record, "telephoneNumber", "555-555-6789")
setRecordFieldValue(record, "@dn",
"CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(records, record)
record = createRecord()
setRecordFieldValue(record, "telephoneNumber", "555-555-2468")
addRecordFieldValue(record, "telephoneNumber", "555-555-1357")
setRecordFieldValue(record, "@dn",
"CN=Test User 3,OU=People,DC=test,DC=local")
appendArrayItem(records, record)
results = saveADRecords(session, records)
i = 0
forEach(dn, dns) {
result = results && result[i]
if(result) {
log("Record saved - " + record)
} else {
log("Record not saved - " + record)
}
i = i + 1
}
close(session)Set/clear AD 'Account is Disabled' flag.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the AD connection |
accountDn* | text, expression, variable | the DN of the account |
state* | boolean, expression, variable | true to disable the account, false otherwise |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
setRecordFieldValue(record, "@dn",
"CN=test user,OU=People,DC=test,DC=local")
result = setADAccountDisabled (Session, record['@dn'], false)
if(result) {
log("setADAccountDisabled worked", "green")
} else {
log("setADAccountDisabled failed", "red")
}
close(session)Set/clear AD 'Account is Disabled' flag on multiple accounts.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
accountDns* | expression, variable | array of DNs of the accounts |
state* | boolean, expression, variable | true to disable the account, false otherwise |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
results = setADAccountsDisabled(session, dns, true)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("Account set to disabled - " + dn)
} else {
log("Account not set to disabled " + dn)
}
i = i + 1
}
close(session)Set/clear AD 'Password does not expire' flag.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
accountDn* | text, expression, variable | the DN of the account |
state* | boolean, expression, variable | true to disable the account, false otherwise |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dn = "CN=Test User,OU=People,DC=test,DC=local"
result = setADDontExpirePassword(session, dn, true)
if(result) {
log("Password does not expire")
} else {
log("Unable to set DontExpirePassword")
}
close(session)Set/clear AD 'Password does not expire' flag on multiple accounts.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
accountDns* | expression, variable | array of DNs of the accounts |
state* | boolean, expression, variable | true to disable the account, false otherwise |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
results = setADDontExpirePasswords(session, dns, true)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("Account set to not expire passwords - " + dn)
} else {
log("Account not set to not expire passwords " + dn)
}
i = i + 1
}
close(session)Sets password on a Record on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dn* | text, expression, variable | the DN of the Record |
password* | password, string, expression, variable | the password |
oldPassword | password, string, expression, variable | the old password (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
password = "password1"
dn = "CN=Test User,OU=People,DC=test,DC=local"
result = setADPassword(session, dn, password)
if(result) {
log("Password has been set")
} else {
log("Password was not set")
}
close(session)Sets passwords on Records on the Active Directory server.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
dns* | text, expression, variable | array of DNs of Records |
passwords* | expression, variable | array of passwords |
oldPasswords | expression, variable | array of old passwords (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
passwords = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(passwords, "password1")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
appendArrayItem(passwords, "password2")
results = setADPasswords(session, dns, passwords)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("Password has been set for " + dn)
} else {
log("Password was not set for " + dn)
}
i = i + 1
}
close(session)Set/clear AD 'User Cannot Change Password' flag.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
userDn* | text, expression, variable | the DN of the User |
state* | boolean, expression, variable | true to disallow user from changing password, false otherwise |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dn = "CN=Test User,OU=People,DC=test,DC=local"
result = setADUserCannotChangePassword(session, dn, true)
if(result) {
log("User cannot change password")
} else {
log("Unable to set UserCannotChangePassword")
}
close(session)Set/clear AD 'User Cannot Change Password' flag on multiple Users.
Property | Value | Description |
|---|---|---|
adConnection* | expression, variable | the AD connection |
userDns* | expression, variable | array of DNs of the Users |
state* | boolean, expression, variable | true to disallow user from changing password, false otherwise |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openADConnection(...)
dns = createArray()
appendArrayItem(dns, "CN=Test User 1,OU=People,DC=test,DC=local")
appendArrayItem(dns, "CN=Test User 2,OU=People,DC=test,DC=local")
results = setADUsersCannotChangePassword(session, dns, true)
i = 0
forEach(dn, dns) {
result = results && results[i]
if(result) {
log("Account set to not allow password change - " + dn)
} else {
log("Account not set to not allow password change - " + dn)
}
i = i + 1
}
close(session)AWS IAM Actions
Add an AWS IAM User to an AWS IAM Group.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
groupName* | text, expression, variable | the groupname |
userName* | text, expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# add John Doe to the PowerUsers group memberAdded = addAWSIAMGroupMember(conn, "PowerUsers, "JDoe")
Create an Access Key for an AWS IAM User.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# create a new access key for John Doe
accessKey = createAWSIAMAccessKey(conn, , "JDoe")
# and EMail it to him because this is the only time we have
access to the secret key
sendEmail(Global.emailHost, Global.emailUser,, Global.emailUser,
"JDoe@example.com, "AWS Access", "John Doe,
Here are your new AWS API access keys:
aws_access_key_id = " + accessKey.accessKeyId + "
aws_secret_access_key = " +accessKey.secretAccessKey)Delete Access Key from AWS IAM User.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | text, expression, variable | the username |
accessKeyId* | text, expression, variable | the access key id |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# find and delete all of John Doe's access keys
accessKeys = getAWSIAMAccessKeys(conn, "JDoe")
forEach(accesskey, accessKeys) {
deleteAWSIAMAccessKey(conn, "JDoe", accessKey.accessKeyId)
}Delete an AWS IAM Group.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
groupName* | text, expression, variable | the groupname |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# delete power users group deleteAWSIAMGroup(conn, "PowerUsers")
Delete an AWS IAM User.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | text, expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# delete John Doe deleteAWSIAMUser(conn, "JDoe")
Delete an AWS IAM User password.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | text, expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# delete John Doe's password deleteAWSIAMUserPassword(conn, "JDoe")
Get the Access Key metadata for an AWS IAM User.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# find and delete all of John Doe's access keys
accessKeys = getAWSIAMAccessKeys(conn, "JDoe")
forEach(accesskey, accessKeys) {
deleteAWSIAMAccessKey(conn, "JDoe", accessKey.accessKeyId)
}Get an AWS IAM Group.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
groupName | text, expression, variable | the groupname |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the power users group powerUsersGroup = getAWSIAMGroup(conn, "PowerUsers")
Get usernames that are members of an AWS IAM Group.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
groupName* | text, expression, variable | the groupname |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the power users group members and log them
powerUsers = getAWSIAMGroup(conn, "PowerUsers")
forEach(powerUser, powerUsers) {
log(powerUser)
}Get AWS IAM Groups.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
pathPrefix | text, expression, variable | the path prefix for filter results (default: all paths) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the existing groups and log the names
groups = getAWSIAMGroups(conn)
forEach(group, groups) {
log(group["groupName"])
}Get an AWS IAM User.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName | text, expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the John Doe user jdoe = getAWSIAMUser(conn, "JDoe")
Get names of the groups to which an AWS IAM User belongs.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | text, expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get and log the groups that John Doe belongs to
groups = getAWSIAMUserGroups(conn, "JDoe")
forEach(group, groups) {
log(group)
}Get AWS IAM Users.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
pathPrefix | text, expression, variable | the path prefix for filter results (default: all paths) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get and log all the user names
users = getAWSIAMUsers(conn)
forEach(user, users) {
log(user["userName"])
}Checks if an AWS IAM User has a password.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | text, expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# check if John Doe has a password and set the default one if not
hasPassword = hasAWSIAMUserPassword(conn, "JDoe")
if(!hasPassword) {
setAWSIAMUserPassword(conn, "JDoe",<Password>)
} else {
}Open a connection to AWS Identity Access Management.
Property | Value | Description |
|---|---|---|
accessKey | text, expression, variable | the AWS access key (default: use appliance credentials) |
secretKey | password, string, expression, variable | the AWS secret key (default: use appliance credentials) |
stsRoleArn | text, expression, password, variable | The AWS ARN. Depending upon the environment, it may be necessary to create Temporary Security Credentials or use IAM Roles. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# open the connection conn = openAWSIAMConnection(Global.awsAccessKey,) # do some stuff # close the connection close(conn)
Open an AWS IAM Group iterator.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
pathPrefix | text, expression, variable | the path prefix for filter results (default: all paths) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# iterate the existing groups and log the names
groupIterator = openAWSIAMGroupIterator(conn)
forEach(group, groupIterator) {
log(group["groupName"])
}Open an AWS IAM User iterator.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
pathPrefix | text, expression, variable | the path prefix for filter results (default: all paths) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# iterate the existing groups and log the names
userIterator = openAWSIAMUserIterator(conn)
forEach(user, userIterator) {
log(user["userName"])
}Remove an AWS IAM User from an AWS IAM Group.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
groupName* | text, expression, variable | the groupname |
userName* | text, expression, variable | the username |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# remove John Doe from the PowerUsers group memberRemoved = removeAWSIAMGroupMember(conn, "PowerUsers, "JDoe")
Create or update an AWS IAM Group.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
record* | expression, variable | the AWS IAM Group Record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# create power users group groupTemplate = createRecord(false) setRecordFieldValue(groupTemplate, "groupName", "PowerUsers") setRecordFieldValue(groupTemplate, "path", "/") group = saveAWSIAMGroup(conn, groupTemplate) # rename group and change path renameGroupRecord = createRecord(false) setRecordFieldValue(renameGroupRecord, "groupName", "PowerUsers") setRecordFieldValue(renameGroupRecord, "newGroupName", "MyPowerUsers") setRecordFieldValue(renameGroupRecord, "Path", "/mygroups/") renamedGroupRecord = saveAWSIAMGroup(conn, renameGroupRecord)
Create or update an AWS IAM User.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
record* | expression, variable | the AWS IAM User Record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# create John Doe user userTemplate = createRecord(false) setRecordFieldValue(userTemplate, "userName", "JDoe") setRecordFieldValue(userTemplate, "path", "/") jdoe = saveAWSIAMUser(conn, userTemplate) # rename user and change path renameUserRecord = createRecord(false) setRecordFieldValue(renameUserRecord, "userName", "JDoe") setRecordFieldValue(renameUserRecord, "newUserName", "JohnDoe") setRecordFieldValue(renameUserRecord, "Path", "/myusers/") renamedUserRecord = saveAWSIAMUser(conn, renameUserRecord)
Set the activation status of an Access Key for AWS IAM User.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | text, expression, variable | the username |
accessKeyId* | text, expression, variable | the access key id |
status* | choice (Active, Inactive), text, expression, variable | the desired status |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# find and deactivate all of John Doe's access keys
accessKeys = getAWSIAMAccessKeys(conn, "JDoe")
forEach(accesskey, accessKeys) {
setAWSIAMAccessKeyStatus(conn, "JDoe", accessKey.accessKeyId,
"Inactive")
}Set an AWS IAM User password.
Property | Value | Description |
|---|---|---|
iamConnection* | expression, variable | the AWS IAM connection |
userName* | text, expression, variable | the username |
password* | password, string, expression, variable | the new password |
resetRequired | boolean, expression, variable | whether or not the user is required to reset password on next login (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# check if John Doe has a password and set the default one if not
hasPassword = hasAWSIAMUserPassword(conn, "JDoe")
if(!hasPassword) {
setAWSIAMUserPassword(conn, "JDoe",<Password>)
} else {
}AWS IAM Record Fields Reference
Field | Description |
|---|---|
userName | Required for create or update as the primary key. Update using newUserNameField |
path | The path for the user. For more information about paths, see IAM Identifiers in the Using IAM guide. Must begin and end with "/" Defaults to: "/" |
userID | The user's unique ID (read-only) |
ARN | The user's Amazon Resource Name (read-only) |
createDate | The user's creation timestamp (read-only) |
passwordLastUsed | Timestamp of the last time password was used to log in to console (read-only) |
newUserName | Used to rename the user. See Renaming a User for implications. |
Field | Description |
|---|---|
groupName | Required for create or update as the primary key. Update using newGroupNameField |
path | The path for the group. For more information about paths, see IAM Identifiers in the Using IAM guide. Must begin and end with "/" Defaults to: "/" |
userID | The group's unique ID (read-only) |
ARN | The group's Amazon Resource Name (read-only) |
createDate | The group's creation timestamp (read-only) |
newGroupName | Used to rename the group. See Renaming a Group for implications. |
Field | Description |
|---|---|
accessKeyId | The ID of the access key (read-only) |
userName | The userName of the user the access key belongs to (read-only) |
status | The access key's status: "Active" or "Inactive" |
ARN | The group's Amazon Resource Name (read-only) |
createDate | The access key's creation timestamp (read-only) |
secretAccessKey | The access key's secret key (read-only and only returned from a successful create) |
Command Line Interface (CLI) Actions
Open an SSH connection to a remote system.
Property | Value | Description |
|---|---|---|
host* | text, expression, variable | the remote host name or address |
port | expression, variable | the remote port (default: 22) |
user* | text, expression, variable | the username for remote host |
password* | password, string, expression, variable | the password for remote host |
options | expression, variable | the value of the ciphers (allowed encryption algorithms), macs (allowed hashing algorithms), or whether to allow debugging to facilitate troubleshooting (debug: true) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openRemoteCLI("host1.acme.org", 22, "root","password")
close(session)Open an SSH connection to a remote system using public/private key authentication.
Property | Value | Description |
|---|---|---|
host* | text, expression, variable | the remote host name or address |
port | expression, variable | the remote port (default: 22) |
user* | text, expression, variable | the username for remote host |
privateKey* | text, expression, variable | the path of the private key file within the project file store or the private key loaded as a byte array |
publicKey | text, expression, variable | the path of the public key file within the project file store or the public key loaded as a byte array (default: none) |
passPhrase | password, string, expression, variable | the passPhrase for private key (default: none) |
options | expression, variable | the value of the ciphers (allowed encryption algorithms), macs (allowed hashing algorithms), or whether to allow debugging to provide more information to facilitate troubleshooting (debug: true) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# assumes public and private key have been uploaded to project
files store,
# and public key has been added as a trusted identity on SSH
remote server
session = openRemoteCLIWithCert("host1.acme.org", 22, "root",
"/.ssh/id_rsa", "/.ssh/id_rsa.pub", <Password>)
close(session)Open a CLI connection to a remote Windows system.
Property | Value | Description |
|---|---|---|
host* | text, expression, variable | the remote host name or address |
user* | text, expression, variable | the username for remote host (must be an administrator) |
domain* | text, expression, variable | the domain for the user |
password* | password, string, expression, variable | the password for remote host |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openRemoteWindowsCLI("windows.acme.org", "Administrator",
"ACME", <Password>)
close(session)Quote a CLI command parameter so that no characters have special meaning to the CLI interpreter.
Property | Value | Description |
|---|---|---|
param* | text, expression, variable | the command parameter to quote |
method* | choice (cmd, powershell, sh), text, expression, variable | the cli quoting method |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# open file with windows local users to create
varNewUsersInput = openDelimitedTextInput(newwindowslocalusers.csv,
"username, givenName, surname, password")
varSession = openRemoteWindowsCLI("windows.acme.org", "Administrator",
"ACME", <Password>)
close(session)
forEach(varNewUserRecord, newUsersInput) {
# quote the dynamic data for use with powershell
varQuotedUsername = quoteCLIParam(varNewUserRecord[\'username\'],
"powershell")
varQuotedFullName = quoteCLIParam(varNewUserRecord[\'givenName\']
+ " " + varNewUserRecord[\'surname\'], "powershell")
varQuotedPassword = quoteCLIParam(varNewUserRecord[\'username\'],
"powershell")
# build the powershell command using the quoted data
varPSCommand = "$Computer = [ADSI]\\"WinNT://$Env:COMPUTERNAME,
Computer\\""
varPSCommand = $varPSCommand + ";$LocalAdmin = $Computer.Create
(\'User\" + varQuotedUsername + ")"
varPSCommand = $varPSCommand + ";$LocalAdmin.SetPassword
(" + varQuotedPassword + ")"\n varPSCommand = $varPSCommand +
";$LocalAdmin.SetFullName(" + varQuotedQuotedFullname + ")"
varPSCommand = varPSCommand + ";$LocalAdmin.UserFlags = 64 + 65536"
varPSCommand = varPSCommand + ";$LocalAdmin.SetInfo()"
# quote the entire powershell command for cmd
varQuotedPSCommand = quoteCLIParam(varPSCommand, "cmd")
runRemoteCLICommand(varSession, "powershell -command " +
varQuotedPSCommand)
}
close(varSession)
close(varNewUsersInput)Run a CLI command. Returns a record with 3 fields: exitStatus, output, and error.
Property | Value | Description |
|---|---|---|
command* | text, expression, variable | the command to run |
input | text, expression, variable | a string to feed to the command as standard input (default: none) |
env | expression, variable | a Record containing environment variables to set (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = runCLICommand("date")
# Should return current date/time
log(, u"result['output']", )Run a CLI command on a remote system. Returns a record with 3 fields: exitStatus, output, and error.
Property | Value | Description |
|---|---|---|
remoteCLI* | expression, variable | the remote CLI connection |
command* | text, expression, variable | the command to run. |
input | text, expression, variable | a string to feed to the command as standard input (default: none) |
env | expression, variable | a Record containing environment variables to set (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
session = openRemoteCLI("host1.acme.org","root","password")
result = runRemoteCLICommand(session,"date")
close(session)
# Should return current date/time
log(, u"result['output']", )Database Adapter Actions
Create a database table definition.
Property | Value | Description |
|---|---|---|
table* | text, expression, variable | the name of the table |
schema | text, expression, variable | the name of the schema that table is in |
catalog | text, expression, variable | the name of the catalog the table is in |
key* | text, expression, variable | comma separated list of primary key columns format for each column: [alias=]name |
keygen | choice (assigned, native), text, expression, variable | the primary key generation algorithm - one of 'assigned','native' (default: 'assigned')(ignored if multiple key columns specified) |
columns* | text, expression, variable | comma separated list of other columns format for each column: [alias=]name[;child-table;join-col[;parent-join-col]] |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# With auto-increment
tableDef = createTableDefinition("senators", "id", "native",
"lastname,firstname,title,email")
# Without auto-increment
tableDef = createTableDefinition("senators", "email", "assigned",
"lastname,firstname,title,email") Delete Record from the database.
Property | Value | Description |
|---|---|---|
dbConnection* | expression, variable | the database connection |
table* | text, expression, variable | the database table |
key* | text, expression, variable | the primary key of the Record to delete - also accepts a Record that contains the primary key |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
tableDef = createTableDefinition("usr", "id"," native",
"fname,lname,status")
outputDB = openDatabaseConnection(...)
queryExample = createRecord()
setRecordValue(queryExample, "status", "I")
inactiveRecords = getDatabaseRecords(outputDB, "usr", queryExample)
forEach(inactive, inactiveRecords) {
delStatus = deleteDatabaseRecord(outputDB, "usr", inactive)
if(Boolean(delStatus)) {
log("Deletion Successful!")
} else {
log("Deletion Failed!")
}
close(outputDB) Get a Record from the database.
Property | Value | Description |
|---|---|---|
dbConnection* | expression, variable | the database connection |
table* | text, expression, variable | the database table |
key* | text, expression, variable | the primary key of the Record - also accepts a Record that contains the primary key |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
tableDef = createTableDefinition("usr", "email", "assigned",
"fname,lname,status,email")
outputDB = openDatabaseConnection(...)
resultRecord = getDatabaseRecord(outputDB, "user",
"john.doe@example.com")
resultFName = getRecordFieldValue(resultRecord, "fname")Get Records from the database.
Property | Value | Description |
|---|---|---|
dbConnection* | expression, variable | the database connection |
table* | text, expression, variable | the database table |
example | expression, variable | example Record |
ignoreCase | boolean, expression, variable | Ignore case when matching example fields (default: false) |
maxResults | expression, variable | maximum number of Records to return (default: unlimited) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
tableDef = createTableDefinition("usr", "id","native",
"fname,lname,status")
outputDB = openDatabaseConnection(...)
queryExample = createRecord()
setRecordValue(queryExample, "status", "I")
inactiveRecords = getDatabaseRecords(outputDB, "usr",
queryExample)
log("There are " + inactiveRecords.length + " inactive records.")
forEach(inactive,inactiveRecords) {
delStatus = deleteDatabaseRecord(outputDB,"usr",inactive)
}
close(outputDB)Open a connection to a database.
Property | Value | Description |
|---|---|---|
jdbcDriverClass* | text, expression, variable | the name of JDBC driver class to use to connect to the database |
jdbcURL* | text, expression, variable | the JDBC connection URL |
tableDefinitions | text, expression, variable | the definitions of the tables that connection will use |
user | text, expression, variable | the user name for authenticating to the database |
password | password, string, expression, variable | the user password for authenticating to the database |
extraProperties | expression, variable | object or Record containing extra Hibernate properties to customize the connection |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
tableDef = createTableDefinition("usr", "id", "native",
"fname,lname,status")
# MySQL Database example
outputDB = openDatabaseConnection("com.mysql.jdbc.Driver",
"jdbc:mysql://127.0.0.1/indirect", tableDef, "root", "password")
if(Boolean(outputDB)) {
log(Database connection successful!)
} else {
log(Database connection failed!)
}Get Records from the database using SQL.
Property | Value | Description |
|---|---|---|
dbConnection* | expression, variable | the database connection |
sql* | text, expression, variable | the SQL query |
params | expression, variable | array of positional parameters to bind to the SQL query |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
tableDef = createTableDefinition("usr", "id", "native",
"fname,lname,status")# MySQL Database example
outputDB = openDatabaseConnection("com.mysql.jdbc.Driver",
"jdbc:mysql://127.0.0.1/indirect", tableDef, "root", "password")
if (Boolean(outputDB)) {
id = "12345"
sql = "SELECT fname,lname,status FROM usr WHERE id='" + id + "'"
users = queryDatabaseSQL(outputDB, sql)
forEach(user, users) {
log("User: " + user)
}
} else {
}
close(outputDB)
### RapidIdentity Connect supports parameterized queries.
For example, in each iteration of the forEach loop, log
the user 's name to be their first and last name
separated by a single space. Parameters (params) could
be used in the example above as follows.
sql = "SELECT fname,lname,status FROM usr WHERE ID = ?"
users = queryDatabaseSQL(outputDB, sql, [user.fname + " "
user.lname, user.id
])
tableDef = createTableDefinition("usr", "id", "native",
"fname,lname,status")
# MySQL Database example
outputDB = openDatabaseConnection("com.mysql.jdbc.Driver",
"jdbc:mysql://127.0.0.1/indirect", tableDef, "root", "password")
if (Boolean(outputDB)) {
id = "12345"
sql = "SELECT fname,lname,status FROM usr WHERE id='" + id + "'"
users = queryDatabaseSQL(outputDB, sql)
forEach(user, users) {
log("User: " + user)
}
} else {
}
close(outputDB)Save a Record to the database.
Property | Value | Description |
|---|---|---|
dbConnection* | expression, variable | the database connection |
table* | text, expression, variable | the database table |
record* | expression, variable | the Record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
textInput = openDelimitedTextInput("/root/senators.csv",
"fname,lname,status,email")
tableDef = ("usr", "email", "assigned", "fname,lname,status,email")
outputDB = openDatabaseConnection(...)
forEach(senator, textInput) {
saveResult = saveDatabaseRecord(outputDB, "user", senator)
if (Boolean(saveResult)) {
log("Save Successful!")
} else {
Log("Save Failed!")
}
}
close(outputDB)
close(textInput)Update database using SQL.
Property | Value | Description |
|---|---|---|
dbConnection* | expression, variable | the database connection |
sql* | text, expression, variable | the SQL statement |
params | expression, variable | array of positional parameters to bind to SQL statement |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
tableDef = createTableDefinition("usr", "id", "native",
"fname,lname,status")# MySQL Database example
outputDB = openDatabaseConnection("com.mysql.jdbc.Driver",
"jdbc:mysql://127.0.0.1/indirect", tableDef, "root", "password")
if (Boolean(outputDB)) {
id = "12345"
sql = "SELECT fname,lname,status FROM usr WHERE id='" + id + "'"
users = queryDatabaseSQL(outputDB, sql)
forEach(user, users) {
log("User: " + user)
updateSQL = "UPDATE usr SET name='" + user.fname + " "
user.lname + "' WHERE ID='" + user.id + "'"
result = updateDatabaseSQL(outputDB, updateSQL)
if (result) {
log("User updated successfully")
} else {
log("User not updated")
}
}
} else {
}
close(outputDB)
### RapidIdentity Connect supports parameterized queries.
For example, in each iteration of the forEach loop, set the
user 's id field value to be their first and last name
separated by a single space. Parameters (params) could
be used in the example above as follows.
updateSQL = "UPDATE usr SET name = ? WHERE ID = ?"
result = updateDatabaseSQL(outputDB, updateSQL, [user.fname + " "
user.lname, user.id
])Example
# Input from text file
textInput = openDelimitedTextInput("/root/senators.csv",
"LastName,FirstName,Title,Email,Phone,Description")
# Define table and open DB connection(MySQL w / auto - increment)
tableDef = createTableDefinition("senators", "id", "native",
"lastname,firstname,title,email,phone")
outputDB = openDatabaseConnection("com.mysql.jdbc.Driver",
"jdbc:mysql://server/dbSchema", tableDef, "root", "password")
# Loop through input records
forEach(inputRecord, textInput) {
# Schema mapping
renameRecordFields(inputRecord, "LastName,FirstName,Title,Email,Phone",
"lastname,firstname,title,email,phone")
# Check for existance in target
queryRecord = createRecord()
queryValue = getRecordFieldValue(inputRecord, "email")
setRecordValue(queryRecord, "email", queryValue)
matchingRecords = getDatabaseRecords(outputDB, "senators",
queryRecord)
if (matchingRecords.length == 1) {
# Match found.Add primary key to current record from source.
matchingKeyValue = getRecordFieldValue(matchingRecords[0], "id")
setRecordFieldValue(inputRecord, "id", matchingKeyValue)
} else {
# No match found.Nothing more to do.
}
# Write(insert / update) record to database
saveDatabaseRecord(outputDB, "senators", inputRecord)
}
# Close database and file connections
close(outputDB)
close(textInput)# Input from text file
JDBC Drivers
Driver: jt400.jar Supports: DB2/400 (tested on v6r1) jdbcDriverClass: com.ibm.as400.access.AS400JDBCDriver jdbcURL: jdbc:as400://[server]/[library]
Hibernate does support DB2/400, but the dialect is not automatically detected; so a hibernate dialect must be specified and must be passed into the openDatabaseConnection action as an extra parameter. org.hibernate.dialect.DB2400Dialect will work perfectly.
Driver: db2jcc4.jar
Supports: DB2 (tested on DB2/LINUXX8664 - SQL09077)
jdbcDriverClass: com.ibm.db2.jcc.DB2Driver
jdbcURL: jdbc:db2://[server]:
[port]/NCANCV:retrieveMessagesFromServerOnGetMessage=true;
currentSchema=[database];currentFunctionPath="[database]";
Driver: fmjdbc.jar Supports: Filemaker 11 jdbcDriverClass: com.filemaker.jdbc.Driver jdbcURL: jdbc:filemaker://[server]/[database]
Hibernate does NOT support Filemaker, so a hibernate dialect must be selected that is similar, and must be passed into the openDatabaseConnection action as an extra parameter. org.hibernate.dialect.ProgressDialect has successfully worked to READ from a Filemaker Pro 11 database.
Driver: multiple .jar files in lib.zip jdbcDriverClass: com.informix.jdbc.IfxDriver jdbcURL: jdbc:informix-sqli://[host]:[port]/DB_name:informixserver=server_name
Driver: sqljdbc4.jar Supports: MS SQL Server 2000, 2005 & 2008 jdbcDriverClass: com.microsoft.sqlserver.jdbc.SQLServerDriver jdbcURL: jdbc:sqlserver://[host]:[port];databaseName=[db]
When Connecting to a MS SQL 2012 Server, use Sun JTDS.
For a Normal Session:
jdbc:jtds:sqlserver://"+Global.dbHostStudent+":"+Global.dbPort+"/
;domain="+Global.dbHostDomain.For a Session with an instance, use:
jdbc:jtds:<server_type>://<server>[:<port>][/<database>];
instance=<instance_name>.driver: Included in RapidIdentity Connect jdbcDriverClass: org.mariadb.jdbc.Driver jdbcURL: jdbc:mysql://[host]:[port]/[database] Advanced Options
Amazon Aurora DB Cluster and RapidIdentity 2018.6.19
Beginning with RapidIdentity 2018.6.19, when using the Amazon Aurora DB Cluster with either MySQL or PostgreSQL, use the Cluster endpoint directly instead of indirectly with a DNS CNAME record.
Driver: ojdbc6.jar Supports: Oracle 10g and 11g up to 11.2.0.2.0 jdbcDriverClass: oracle.jdbc.OracleDriver jdbcURL: jdbc:oracle:thin:@[host]:[port]:[sid]
Driver: Included in RapidIdentity Connect Supports: postgreSQL jdbcDriverClass: org.postgresql.Driver jdbcURL: jdbc:postgresql://[host]:[port]/[db]?stringtype=unspecified
postgreSQL connections can occasionally take a long time to process. To speed up the connection, metadata can be added in the corresponding Action Set as follows.
hibernate = createRecord()
setRecordFieldValue(hibernate, "hibernate.dialect",
"org.hibernate.dialect.PostgreSQLDialect")
setRecordFieldValue(hibernate, "hibernate.temp.use_jdbc_metadata_defaults",
"false")
Driver: openedge.jar, util.jar, base.jar (ALL REQUIRED) Supports: Progress/OpenEdge jdbcDriverClass: com.ddtek.jdbc.openedge.OpenEdgeDriver jdbcURL: jdbc:datadirect:openedge://[host]:[port];databaseName=[db]
The current driver supports JDBC logging. An acceptable Action Set is shown:
hibernate = createRecord()
setRecordFieldValue(hibernate, "hibernate.dialect",
"org.hibernate.dialect.ProgressDialect")
SkywardSession = openDatabaseConnection(
"com.ddtek.jdbc.openedge.OpenEdgeDriver",
"jdbc:datadirect:openedge://IP:PORT;databaseName=SKYWARD;
SpyAttributes=(log=(file)/var/opt/idauto/dss/files/SkywardLogs/jdbc.log;
logTName=yes;timestamp=yes;)", "USERNAME",<Password>, hibernate)
Connecting to a Progress DB (example SKYWARD) via SSL, requires a modification to the connection string (encryptionMethod=SSL):
jdbc:datadirect:openedge://<ip> :<port>;databaseName= SKYWARD;encryptionMethod=SSL
Driver: Included in RapidIdentity Connect Supports: SQLite3 formatted database files jdbcDriverClass: org.sqlite.JDBC jdbcURL: jdbc:sqlite:<path to db file> Hibernate Dialect: com.enigmabridge.hibernate.dialect.SQLiteDialect
SQLite is an embedded database that can be used only for a database file accessible via the RapidIdentity appliance native filesystem and writeable by the tomcat user. In the context of RapidIdentity Connect, it is primarily useful only for storing locally managed state, as opposed to being used for integration with an external system. It is not recommended for a cluster with multiple RapidIdentity Connect instances.
sqliteSession = openDatabaseConnection("org.sqlite.JDBC",
"jdbc:sqlite:/var/opt/idauto/dss/files/my.db",null,null,
{"hibernate.dialect": "com.enigmabridge.hibernate.dialect.SQLiteDialect"})
results = updateDatabaseSQL(sqliteSession, "DROP TABLE IF EXISTS contacts;")
results = updateDatabaseSQL(sqliteSession, "CREATE TABLE contacts
(\n contact_id integer PRIMARY KEY,\n first_name text NOT NULL,
\n last_name text NOT NULL,\n email text NOT NULL UNIQUE,\n phone text
NOT NULL UNIQUE\n);")
close(sqliteSession)Driver: jconn4.jar Supports: Sybase SQL Anywhere jdbcDriverClass: com.sybase.jbdc4.jdbc.sybDriver jdbcURL:jdbc:sybase:Tds:[host]:[port]?ServiceName=[databasename] Hibernate Dialect: org.hibernate.dialect.SybaseAnywhereDialect
Driver: Included in RapidIdentity Connect
Supports: Microsoft SQL Server (6.5, 7, 2000, 2005 and 2008) and
Sybase (10, 11, 12, 15)
jdbcDriverClass: net.sourceforge.jtds.jdbc.Driver
jdbcURL: jdbc:jtds:sqlserver://[host]:[port]/[databasename]
Additionally, to connect to Microsoft SQLServer, using Windows / NTLM authentication, rather than native SQL authentication, you must append the following to the end of the JDBC URL:
;useNTLMv2=true;domain=<domainname>;
If the database you are accessing is a NAMED INSTANCE rather than the default database, the PORT will most likely be dynamic. The SQL Server Browser service on the database server should take care of establishing the conversation, but you will need to discard the default port of 1433.
For example, to connect with a domain account to a named instance, it would look like this:
jdbc:jtds:sqlserver://<servername>/<databasename>;instance=<instancename>;
domain=<domain>Driver: unijdbc.jar unijdbc.jar and asjava.jar asjava.jar are both required.
Supports: UniData and UniVerse (tested on UniData 8.1.2) jdbcDriverClass: com.rs.u2.jdbc.UniJDBCDriver jdbcURL: jdbc:rs-u2://host[:port-num]/[account];dbmstype=UNIDATA
Hibernate does support UniData, but the dialect is not automatically detected; so a hibernate dialect must be specified and must be passed into the openDatabaseConnection action as an extra parameter. will work perfectly.
hibernate = createRecord()
setRecordFieldValue(hibernate, "hibernate.dialect",
"org.hibernate.dialect.DB2Dialect")
External Documentation
JDBC Driver Downloads
Specifying a Hibernate Dialect
To capitalize on the RapidIdentity Connect database adapter, it may be necessary to specify a dialect to make the connection even if the correct JDBC driver is used.
Dialects can be integrated as a record field value.
sessionDB = openDatabaseConnection("com.filemaker.jdbc.Driver",
Global.FilemakerStaffDB, Global.FilemakerDBUser,<Password>,
{"hibernate.dialect": "org.hibernate.dialect.ProgressDialect"})
Secure Database Connection with SSL
A secure database connection can be attempted by modifying the connection string by adding ?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory.
Complete example: jdbc:postgresql://"+Global.dbHostFocus+":"+Global.dbPortFocus+"/"+Global.dbNameFocus+"?ssl=true&sslfactory=org.postgresql.ssl.NonValidatingFactory
Attachments:
asjava.jar (application/java-archive)
db2jcc4.zip (application/zip)
fmjdbc.zip (application/zip)
jconn4.jar.zip (application/zip)
jt400.zip (application/zip)
jtds-1.2.5-dist.zip (application/zip)
lib.zip (application/zip)
mysql-connector-java-5.1.19-bin.zip (application/zip)
ojdbc6.jar.zip (application/zip)
openedge.zip (application/zip)
SkywardJDBCJarFiles.zip (application/zip)
sqljdbc4.jar.zip (application/zip)
unijdbc.jar (application/java-archive)
Edmodo Adapter Actions
Define an OAuth2 connection to Edmodo.
Property | Value | Description |
|---|---|---|
credentialName* | text, expression, variable | OAuth2 credential for authentication to Edmodo |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
conn = defineEdmodoOAuthConnection(Global.edmodoOAuthCredentialName)
Delete an Edmodo Record.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
id* | text, expression, variable | id of the Edmodo Record to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteEdmodoRecord(conn, "users", record.id)
Delete an array of Edmodo Records.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
ids* | text, expression, variable | Array of Edmodo Record ids |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteEdmodoRecords(conn, "users",
[record[0].id, record[1].id])Get an Edmodo Record.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
id* | text, expression, variable | the Edmodo Record id |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
record = getEdmodoRecord(conn, "users", record.id)
Get Edmodo Records.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
filter | expression, variable | filter record or object that determines which Edmodo records to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
records = getEdmodoRecords(conn, "users")
Get an Edmodo Record.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
ids* | text, expression, variable | Array of Edmodo Record ids |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
records = getEdmodoRecords(conn, "users", [record[0].id,
record[1].id])Open Edmodo Record Iterator.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
filter | expression, variable | filter record or object that determines which Edmodo records to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
it = openEdmodoRecordIterator(conn, "student")
forEach(record, it) {
# process record
}Create or update an Edmodo Record.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
record* | expression, variable | the Edmodo Record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
record = createRecordFromObject({
type: "student",
username: "student27",
first_name: "student",
last_name: "Twentyseven",
email: "student27@example.com",
password: "password@123",
school_id: 1234567,
verified_institution_member: true
})
createdRecord = saveEdmodoRecord(conn, "users", record)Create or update an array of Edmodo Records.
Property | Value | Description |
|---|---|---|
edmodoConnection* | expression, variable | the Edmodo Agent connection |
type* | choice (users, groups, group_memberships, districts, schools), text, expression, variable | the type of Edmodo Record |
records* | expression, variable | Array of the Edmodo Records to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
savedRecords = saveEdmodoRecords(conn, "users", [record[0].id,
record[1].id])Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
id | integer | unique record identifier | Yes | No | Required |
type | string | the User type. Valid options: - student - parent - teacher | Yes | Required | No |
password | string | the User's password | No | Required | Optional |
username | string | username - must be universally unique within Edmodo | Yes | Required | No |
first_name | string | the User's first name | Yes | Required | No |
last_name | string | the User's last name | Yes | Required | No |
user_title | string | the User's title - Valid options: - Mr - Mrs - Ms - Dr | Yes | Optional | No |
locale | string | the User's locale | Yes | Optional | No |
timezone | string | the User's timezone | Yes | Optional | No |
string | the User's email address - required for teachers and parents - must be universally unique within Edmodo | Yes | Optional | No | |
parent_code | string | if the User is a parent, this must be a valid parent code returned from a student | No | Optional | No |
parent_relationship | string | if the User is a parent - Valid options: - Mom - Dad - description of other parent-student relationship | Yes | Optional | No |
school_id | integer | id of the associated school - can be set to null to disassociate from the school/district | Yes | Required | Yes |
district_id | integer | id of a the district | Yes | No | No |
verified_institution_member | boolean | true if verified as belonging to the institution represented by school_id | Yes | Optional | Yes |
admin_rights | record | administrative rights - Sub-fields: - institution - either schools/school_id or districts/district_id - can_grant_rights - boolean - can_allocate_funds - boolean | Yes | Optional | Yes |
Field | Type | Description |
|---|---|---|
school_id | integer | filter Users by the associated school |
district_id | integer | filter Users by the associated district |
query | string | filter Users to those where the query matches their name |
type | string | filter Users by user type - valid options: - all (default) - student - teacher - school_admin - district_admin |
status | string | filter by the status of the User - valid options: - all (default) - verified - unverified |
sort | string | sort Users by the given property - valid options: - name |
sort_direction | string | if sort is provided, sets the direction of the sort - valid options: - ascending (default) - descending |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
id | integer | unique record identifier | Yes | No | Required |
title | string | title of Group | Yes | Required | Yes |
description | string | description of Group | Yes | Optional | Yes |
start_level | string | starting grade of the Group - see Supported Levels | Yes | Required | Yes |
end_level | string | ending grade of the Group - see Supported Levels defaults to same value as start_level | Yes | Optional | Yes |
expected_group_size | string | the expected size of the Group - see Supported Expected Group Sizes | Yes | Optional | Yes |
subject | string | the subject of the Group - see Supported Subjects | Yes | Required | Yes |
subject_area | string | the subject area of the Group - see Supported Subject Areas (set automatically based on subject) | Yes | No | No |
moderate_posts_and_replies | boolean | whether all posts and replies to this Group are moderated (default: false) | Yes | Optional | Yes |
default_membership_type | string | the initial membership type for new group memberships - valid options: - read_only_member - read_write_member (default) | Yes | Optional | Yes |
parent_group_id | integer | id of the parent group | Yes | Optional | No |
creator_id | integer | id of user that created the group may be overridden on creation by school/district admin to the id of a verified teachers in their school/district | Yes | Optional | No |
archived | boolean | true if the Group is archived | Yes | No | No |
num_members | boolean | the current number of members in the Group | Yes | No | No |
owner_id | boolean | the user id(s) of the group owner(s) | Yes | No | No |
Field | Type | Description |
|---|---|---|
query | string | filter Groups by query match on title & description (NOT YET AVAILABLE as of 01JUL2014) |
status | string | filter Groups by status - valid options: - active (default) - archived |
directory | string | filter Groups by directory - valid options: - unlisted (default) - public - schools/school_id - district/district_id |
subject_area | string | filter Groups by subject area - see Supported Subject Areas |
min_level | string | filter Groups by lower bound (inclusive) for a Group's end level - see Supported Levels |
max_level | string | filter Groups by upper bound (inclusive) for a Group's start level - see Supported Levels |
parent_group_id | integer | filter Groups by parent Group |
user_id | integer | filter Groups by those the given User belongs to |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
id | integer | unique record identifier | Yes | No | Required |
group_id | integer | id of the Group | Yes | Required | No |
user_id | integer | id of the User | Yes | Required | No |
type | string | membership type of the user - valid options: - read_only_member - read_write_member - co_teacher - owner | Yes | Required | Yes |
send_notifications | boolean | whether to send notifications about Group activity to User (default: true) | Yes | Optional | Yes |
show_posts_in_stream | boolean | whether to send notifications about Group posts in User's messages stream (default: true) | Yes | Optional | Yes |
color | string | the color code assigned to this group | Yes | Optional | Yes |
Field | Type | Description |
|---|---|---|
group_id | integer | filter memberships by those the for the given Group |
user_id | integer | filter Groups by those for the given User |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
id | integer | unique record identifier | Yes | No | Required |
name | string | name of the School | Yes | Required | Yes |
abbreviated_name | string | abbreviated name of the School | Yes | Optional | Yes |
motto | string | the School motto | Yes | Optional | Yes |
lead_id | integer | user id of the school lead | Yes | Optional | Yes |
lead_title | string | title of the school lead (e.g. “principal”, “headmaster”) | Yes | Optional | Yes |
start_level | string | starting grade of the School - see Supported Levels | Yes | Required | Yes |
end_level | string | ending grade of the School - see Supported Levels defaults to same value as start_level | Yes | Optional | Yes |
district_id | integer | id of the School's district | Yes | Optional | Yes |
address | string | the School street address | Yes | Required | Yes |
zip_code | string | the School postal code | Yes | Required | Yes |
state | string | the School two-letter state code | Yes | Required | Yes |
website | string | URL of the School website | Yes | Optional | Yes |
phone_number | string | phone number for the School | Yes | Optional | Yes |
code_contact | string | code contact of the School | Yes | Optional | Yes |
code_phone | string | code phone number of the School | Yes | Optional | Yes |
code_email | string | code email of the School | Yes | Optional | Yes |
avatars | record | URL's of the School avatars - Sub-fields: - small - large (set to null to revert to defaults) | Yes | Optional | Yes |
Field | Type | Description |
|---|---|---|
query | string | filter Schools by query match on school name |
user_id | integer | filter Schools to those the User is a member/admin of |
district_id | integer | filter Schools by the associated district |
min_level | string | filter Schools by lower bound (inclusive) for a Group's end level - see Supported Levels |
max_level | string | filter Schools by upper bound (inclusive) for a Group's start level - see Supported Levels |
sort | string | sort schools by the given property - valid options: - name |
sort_direction | string | if sort is provided, sets the direction of the sort - valid options: - ascending (default) - descending |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
id | integer | unique record identifier | Yes | No | Required |
name | string | name of the District | Yes | Required | Yes |
abbreviated_name | string | abbreviated name of the District | Yes | Optional | Yes |
motto | string | the District motto | Yes | Optional | Yes |
lead_id | integer | user id of the District lead | Yes | Optional | Yes |
lead_title | string | title of the District lead (e.g. “superintendent”, “headmaster”) | Yes | Optional | Yes |
address | string | the District street address | Yes | Required | Yes |
zip_code | string | the District postal code | Yes | Required | Yes |
state | string | the District two-letter state code | Yes | Required | Yes |
website | string | URL of the District website | Yes | Optional | Yes |
phone_number | string | phone number for the District | Yes | Optional | Yes |
avatars | record | URL's of the District avatars - Sub-fields: - small - large (set to null to revert to defaults) | Yes | Optional | Yes |
Field | Type | Description |
|---|---|---|
query | string | filter Schools by query match on school name |
user_id | integer | filter Schools to those the User is a member/admin of |
sort | string | sort schools by the given property - valid options: - name |
sort_direction | string | if sort is provided, sets the direction of the sort - valid options: - ascending (default) - descending |
science
language_arts
mathematics
social_studies
health_pe
creative_arts
world_languages
professional_development
special_education
vocational_studies
computer_technology
other
all
english
reading
esl
journalism
speech
basic_math
algebra
geometry
trigonometry
calculus
statistics
computer_science
basic_science
biology
chemistry
physics
psychology
environmental_science
history
world_history
us_history
government
economics
european_history
geography
health_education
physical_education
art
music
dance
drama
spanish
french
latin
german
japanese
chinese_mandarin
italian
drivers_education
edmodo_training
pre_kindergarten
kindergarten
first
second
third
fourth
fifth
sixth
seventh
eighth
ninth
tenth
eleventh
twelfth
higher_education
not_sure
one_to_five
six_to_ten
eleven_to_fifteen
sixteen_to_twenty
twenty_one_to_twenty_five
twenty_six_or_more
Configure OAuth for Edmodo Adapter
You will need an Edmodo Account with District or School administrator privileges. While you can use the default administrative account, it is usually a good idea to create a separate User and grant the necessary administrative privileges.
In RapidIdentity, Navigate to Connect > OAuth2 Credentials.
Select the project you want the credential associated with. For security reasons an OAuth credential is associated with a single project only, though it can be shared with any number of actions sets within the project and used on any RapidIdentity Connect node in the same cluster.
Click the Add… button and select Edmodo.
Give the credential a name (must be unique within the project.)
Enter the username of the administrator account you wish to use in the Username field.
Review the permissions that will be requested. The default selection represents the permissions that are required for the Edmodo adapter to be fully functional, but if you don't need all the capabilities you may wish to adjust the requested permissions.
Click the Request OAuth Credential button.
Press OK to redirect to Edmodo to authorize the credential.
If necessary, log in as the Edmodo administrator account you entered above.
Review the requested permissions and press the Accept button.
Select and copy the code from the resulting page.
Switch back to the RapidIdentity Connect tab or window, paste the code, and press the OK button.
Insert the defineEdmodoOAuthConnection() action.
Enter the domain.
After selecting the credentialName field, select OAuth Credential… in the combo box.
Select the desired credential in the dialog and press OK.
Navigate to Connect > OAuth2 Credentials. Select the credential and press the Delete… button.
Exchange Adapter Actions
The Exchange adapter depends on the Exchange Agent. Access the Exchange/Office 365 Agent Guides to download and install the correct agent.
Add a member to an Exchange Distribution Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
groupIdentity* | text, expression, variable | the identity of the DistributionGroup |
memberIdentity* | text, expression, variable | the identity of the object to add to the DistributionGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
addExchangeDistributionGroupMember(sessionExch,"idautotestgroup",
"idautotestuser")Create an Exchange MoveRequest record. (Exchange 2010 or higher)
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
moveRequest = createRecord() setRecordFieldValue(moveRequest, "Identity", "testuser") setRecordFieldValue(moveRequest, "TargetDatabase", "db2") queuedMoveRequest = createExchangeMoveRequest(conn, moveRequest)
Delete an Exchange DistributionGroup record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange DistributionGroup to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleteExchangeDistributionGroup(sessionExch,"idautotestgroup")
Delete a member from an Exchange DistributionGroup.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
groupIdentity* | text, expression, variable | the identity of the DistributionGroup |
memberIdentity* | text, expression, variable | the identity of the object to delete from the DistributionGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleteExchangeDistributionGroupMember(sessionExch,"idautotestgroup",
"idautotestuser")Delete an Exchange Mailbox record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange Mailbox to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleteExchangeMailbox(sessionExch,"idautotestuser")
Delete an Exchange MailContact record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MailContact to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleteExchangeMailContact(sessionExch,"testcontact")
Delete an Exchange MailUser record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MailUser to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleteExchangeMailUser(sessionExch,"idautotestmailuser")
Delete an Exchange MoveRequest record by Id. (Exchange 2010 or higher)
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MoveRequest to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# cleanup completed and failed move requests so those mailboxes
can be moved again
# first - get the move requests that have completed
filter = createRecord()
setRecordFieldValue(filter, "Status", "Completed")
completedRequests = getExchangeMoveRequests(sessionExch, filter)
forEach(completedRequest, completedRequests) {
deleteExchangeMoveRequest(conn, completedRequest.identity)
}Disable an Exchange DistributionGroup record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange DistributionGroup to disable |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
disableExchangeDistributionGroup(sessionExch,"idautotestgroup")
Disable an Exchange Mailbox record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange Mailbox to disable |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
disableExchangeMailbox(sessionExch,"idautotestuser")
Disable an Exchange MailContact record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MailContact to disable |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
disableExchangeMailContact(sessionExch,"mailcontact")
Disable an Exchange MailUser record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MailUser to disable |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
disableExchangeMailUser(sessionExch,"idauttestmailuser")
Get an Exchange DistributionGroup record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange DistributionGroup to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeDistributionGroup(sessionExch, "idautotestgroup")
Get Exchange DistributionGroup records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeDistributionGroups(sessionExch,exchFilter)
Get an Exchange Mailbox record by Identity.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange Mailbox to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeMailbox(sessionExch,"idautotestuser")
Get Exchange Mailbox records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeMailboxes(sessionExch,exchFilter)
Get an Exchange MailContact record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MailContact to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeMailContact(sessionExch, "idautotestmailuser")
Get Exchange MailContact records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeMailContacts(sessionExch)
Get an Exchange MailUser record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MailUser to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeMailUser(sessionExch,"idautotestmailuser")
Get Exchange MailUser records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeMailUsers(sessionExch)
Get an Exchange MoveRequest record by Identity.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
identity* | text, expression, variable | the identity of the Exchange MoveRequest to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
getExchangeMoveRequest(sessionExch, "testuser")
Get Exchange MoveRequest records. (Exchange 2010 or higher)
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
filter | text, expression, variable | an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
See deleteExchangeMoveRequest
Open a connection to Exchange.
Property | Value | Description |
|---|---|---|
exchangeServer* | text, expression, variable | the DNS name or IP address of the Exchange server) |
dc | text, expression, variable | the domain qualified name of the Active Directory DC to use (default: automatic) |
exchangeAgentURL* | text, expression, variable | the URL of the Exchange Administrative Web Service agent (e.g. https://hostname:port/idautoExchangeAdminWS) |
username* | text, expression, variable | username for authentication to Exchange |
password* | password, string, expression, variable | password for authentication to Exchange |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.ExchURL = "https://10.10.10.10/idautoExchangeAdminWS"
Global.ExchUser = "exchangeadmin@idauto.net"
Global.ExchPwd = Password
Global.ExchServer = "10.10.10.10"
sessionExch = openExchangeConnection(Global.ExchServer,Global.ExchURL,
Global.ExchUser,Password>)Create/Update an Exchange DistributionGroup record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupRecord = createRecord() setRecordFieldValue(groupRecord, "Name","idautotestgroup") saveExchangeDistributionGroup(sessionExch,groupRecord)
Create/Update an Exchange Mailbox record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userRecord = createRecord()
setRecordFieldValue(userRecord, "Name","idautotestuser")
setRecordFieldValue(userRecord, "Password",<Password>)
setRecordFieldValue(userRecord, "userPrincipalName",
"idautotestuser@test1.local")
setRecordFieldValue(userRecord, "LastName","user1")
setRecordFieldValue(userRecord, "FirstName","Bob")
saveExchangeMailbox(sessionExch,userRecord)Create/Update an Exchange MailContact record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
contactRecord = createRecord()
setRecordFieldValue(contactRecord, "Name","testcontact")
setRecordFieldValue(contactRecord, "EmailAddresses",
"testcontact@somewhere.org")
saveExchangeMailContact(sessionExch,contactRecord)Create/Update an Exchange MailUser record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Exchange connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userRecord2 = createRecord()
setRecordFieldValue(userRecord2, "Name", "testmailuser")
setRecordFieldValue(userRecord2, "EmailAddresses",
"testmailuser@idauto.net")
saveExchangeMailUSer(sessionExch,userRecord2)Fields supported for creating/updating on Exchange objects are documented as parameters to the New-* and Set-* Exchange Shell Cmdlets Because many objects are polymorphic, there are different cmdlets that can be applied to the same object and the set of supported attributes is based on all the applicable cmdlets, e.g. a Mailbox is also a User, a Recipient, a CASMailbox, and a MailboxRegionalConfiguration, so the set of supported attributes is the union of the Cmdlets for those 5 object types.
For all record types, the Identity field serves as the identifier for the corresponding Exchange object. On save, a record that has the Identity field will be treated as an update, whereas any record without the Identity field will be treated as a create or enable, depending on whether or not the corresponding object in AD already exists. Records returned from Exchange will always have the Identity field populated, though for purposes of getting or updating the object, any of the following can be used interchangeably as the Identity: ADObjectID, Alias, Distinguished name (DN), Domain\Account, GUID, LegacyExchangeDN, SmtpAddress, or User principal name (UPN).
For search filters, only one Exchange object type is supported for each record type, which means that searches cannot be performed across all the attributes that are supported for create/update on each record type. The list of attributes supported in search filters can be found here: http://technet.microsoft.com/en-us/library/bb738155.aspx. The syntax for searching is called OPath and is documented here: http://technet.microsoft.com/en-us/library/bb124268.aspx#OPATH. Filters should NOT be enclosed in braces { } because the adapter automatically takes care of that.
Record Type | New Cmdlet | Set Cmdslet(s) | Supported Attributes | Search Filter Object Type |
|---|---|---|---|---|
Mailbox | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, ActiveSyncAllowedDeviceIDs, ActiveSyncBlockedDeviceIDs, ActiveSyncDebugLogging, ActiveSyncEnabled, ActiveSyncMailboxPolicy, Alias, ApplyMandatoryProperties, AssistantName, BypassModerationFromSendersOrMembers, CalendarRepairDisabled, CalendarVersionStoreDisabled, City, Company, CountryOrRegion, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, DeliverToMailboxAndForward, Department, Discovery, DisplayName, EmailAddresses, EmailAddressPolicyEnabled, EvictLiveId, ExternalOofOptions, Fax, FederatedIdentity, FirstName, Force, ForwardingAddress, GrantSendOnBehalfTo, HomePhone, Identity, ImapEnabled, ImapMessagesRetrievalMimeFormat, ImapUseProtocolDefaults, ImmutableId, ImportLiveId, Initials, Languages, LastName, MAPIEnabled, MailTip, MailTipTranslations, MailboxPlan, Manager, MessageTrackingReadStatusEnabled, MobilePhone, ModeratedBy, ModerationEnabled, Name, Notes, OWAEnabled, Office, OrganizationalUnit, OtherFax, OtherHomePhone, OtherTelephone, Pager, Password, Phone, PopEnabled, PopMessagesRetrievalMimeFormat, PopUseProtocolDefaults, PostOfficeBox, PostalCode, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, RemotePowerShellEnabled, RemovedMailbox, RequireSenderAuthenticationEnabled, ResetPasswordOnNextLogon, ResourceCapacity, ResourceCustom, SecondaryAddress, SendModerationNotifications, SimpleDisplayName, StateOrProvince, StreetAddress, Title, Type, UseExistingLiveId, UserCertificate, UserSMimeCertificate, WebPage, WindowsEmailAddress, DateFormat, Language, LocalizeDefaultFolderName, TimeFormat, TimeZone, PictureData | Recipient | ||
DistributionGroup | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, Alias, BypassModerationFromSendersOrMembers, BypassNestedModerationEnabled, CopyOwnerToMember, CreateDTMFMap, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, DisplayName, EmailAddresses, GrantSendOnBehalfTo, HiddenFromAddressListsEnabled, Identity, MailTip, MailTipTranslations, ManagedBy, MemberDepartRestriction, MemberJoinRestriction, Members, ModeratedBy, ModerationEnabled, Name, Notes, OrganizationalUnit, PhoneticDisplayName, PrimarySmtpAddress, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, ReportToManagerEnabled, ReportToOriginatorEnabled, RequireSenderAuthenticationEnabled, RoomList, SendModerationNotifications, SendOofMessageToOriginatorEnabled, SimpleDisplayName, Type, Universal, WindowsEmailAddress | Recipient | ||
MailContact | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, Alias, AllowUMCallsFromNonUsers, AssistantName, BypassModerationFromSendersOrMembers, City, Company, CountryOrRegion, CreateDTMFMap, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, Department, DisplayName, EmailAddresses, ExternalEmailAddress, Fax, FirstName, GrantSendOnBehalfTo, HiddenFromAddressListsEnabled, HomePhone, Identity, Initials, LastName, MacAttachmentFormat, MailTip, MailTipTranslations, Manager, MessageBodyFormat, MessageFormat, MobilePhone, ModeratedBy, ModerationEnabled, Name, Notes, Office, OrganizationalUnit, OtherFax, OtherHomePhone, OtherTelephone, Pager, Phone, PhoneticDisplayName, PostOfficeBox, PostalCode, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, RequireSenderAuthenticationEnabled, SecondaryAddress, SecondaryDialPlan, SendModerationNotifications, SimpleDisplayName, StateOrProvince, StreetAddress, TelephoneAssistant, Title, UMCallingLineIds, UMDialPlan, UseMapiRichTextFormat, UsePreferMessageFormat, WebPage, WindowsEmailAddress | Recipient | ||
MailUser | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, Alias, AllowUMCallsFromNonUsers, AssistantName, BypassModerationFromSendersOrMembers, City, Company, CountryOrRegion, CreateDTMFMap, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, Department, DisplayName, EmailAddresses, ExternalEmailAddress, Fax, FirstName, GrantSendOnBehalfTo, HiddenFromAddressListsEnabled, HomePhone, Identity, Initials, LastName, MacAttachmentFormat, MailTip, MailTipTranslations, Manager, MessageBodyFormat, MessageFormat, MobilePhone, ModeratedBy, ModerationEnabled, Name, Notes, Office, OrganizationalUnit, OtherFax, OtherHomePhone, OtherTelephone, Pager, Phone, PhoneticDisplayName, PostOfficeBox, PostalCode, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, RequireSenderAuthenticationEnabled, SecondaryAddress, SecondaryDialPlan, SendModerationNotifications, SimpleDisplayName, StateOrProvince, StreetAddress, TelephoneAssistant, Title, UMCallingLineIds, UMDialPlan, UseMapiRichTextFormat, UsePreferMessageFormat, WebPage, WindowsEmailAddress | Recipient | ||
MoveRequest | N/A | Identity, Remote, RemoteCredential, RemoteGlobalCatalog, RemoteHostName, RemoteLegacy, AcceptLargeDataLoss, ArchiveDomain, ArchiveOnly, ArchiveTargetDatabase, BadItemLimit, BatchName, Confirm, DoNotPreserveMailboxSignature, DomainController, IgnoreRuleLimitErrors, MRSServer, PrimaryOnly, Protect, RemoteOrganizationName, RemoteTargetDatabase, Suspend, SuspendComment, SuspendWhenReadyToComplete, TargetDatabase, TargetDeliveryDomain | MoveRequest |
Starting in Exchange 2010, you can initiate moving a mailbox from one database to another using createExchangeMoveRequest. There are a lot of different options provided by the cmdlet so make sure you review the Understanding Move Requests in the Exchange documentation to know which properties to set for a particular scenario.
Some scenarios require providing a credential field. A credential field requires two values, the first being the username and the second the password.
Once a move is requested you can track it's progress using getExchangeMoveRequest. You can also search for MoveRequests (with optional filter) getExchangeMoveRequests. Note that optional filter does not support OPath like all the other Exchange object types do, and that the criteria in the record used as a filter is limited to the parameters available for the Get-MoveRequest cmdlet.
One thing to keep in mind about MoveRequests is that the MoveRequest has to be deleted once mailbox move has completed before another MoveRequest can be created for that mailbox. One way to accomplish that would be to create a job that uses getExchangeMoveRequests to get a list of all the existing requests, and use deleteExchangeMoveRequest to delete any MoveRequests that have Status “Completed”. You may also want to check for and requests with Statuses “CompletedWithWarning” and “Failed” and send notification to an administrator for remediation. Deleting a MoveRequest that has not yet completed will effectively cancel the move.
The Adapter does not currently support modifying, suspending or resuming an existing MoveRequest.
Force.com Adapter Actions
Deletes the record in ForceCom. Returns a success boolean.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ForceCom connection object |
id* | text, expression, variable | The Id of the ForceCom record to delete. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# Delete the incident
if(incident){
deleted = deleteForceComRecord(sessionForce, newIncidentId)
if(deleted){
log("incident deleted")
} else {
log("Unable to delete incident", "ERROR")
}
} else {
}Deletes the records in ForceCom. Returns a result object containing the fields 'id','success', and 'errors', which are either single entries or arrays.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ForceCom connection object |
ids* | text, expression, variable | The Ids of the ForceCom records to delete. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteForceComRecords(sessionForce, [idToDeleteA,
idToDeleteB])Gets a given ForceCom Record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ForceCom connection object |
objectType* | text, expression, variable | The ForceCom object type |
id* | text, expression, variable | The Id of the ForceCom record. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
records = getForceComRecords(sessionForce, "Account", "Id, Name,
OwnerId"Get multiple ForceCom Records matching the given filter, or all records if no filter is supplied.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ForceCom connection object |
objectType* | text, expression, variable | The ForceCom object type |
filter | text, expression, variable | The filter used to limit results. Can either be an encoded query as specified by ForceCom, or a Record example object. |
fields | text, expression, variable | The fields returned in the query. Defaults to all fields. |
limit | expression, variable | The maximum number of records to return. Defaults to all objects. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
records - getForceComRecords(sessionForce, "Account", query,
"Id, Name, OwnerId")Opens a connection to a ForceCom Server.
Property | Value | Description |
|---|---|---|
username* | text, expression, variable | Username for authentication to the ForceCom web service |
password* | password, string, expression, variable | Password for authentication to the ForceCom web service. When authenticating through the API or client it is necessary to append the security token to the password in the form passwordSecurityToken. The security token is a case-sensitive, alphanumeric string and it can be obtained through the Salesforce UI Personal Settings through Reset Your Security Token or by changing the Salesforce password. |
apiVersion | text, expression, variable | API Version to use |
options | expression, variable | A record or JavaScript object with a field for each additional option. The currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# Open Connections
{
sessionAD = openADConnection(Global.idautoHost, Global.idautoPort,
Global.idautoSSL, Global.idautoUser, <Password>)
sessionForce = openForceComConnection(Global.forceUser, <Password>)
if(!sessionAD || !sessionForce){
# --- Error making connections. Terminating process.
return null
} else {
}
}Open ForceCom Record Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ForceCom connection object |
objectType* | text, expression, variable | The ForceCom object type |
filter | text, expression, variable | The filter used to limit results. Can either be an encoded query as specified by ForceCom, or a Record example object. |
fields | text, expression, variable | The fields returned in the query. Defaults to all fields. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
records = openForceComRecordIterator(sessionForce, "Contact", filter)
Creates or updates the record in ForceCom. Returns the id of the object, or null on failure.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ForceCom connection object |
record* | text, expression, variable | A Record object containing the fields you want to save. If 'Id' is set, an update will be performed, otherwise a create will be performed. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = saveForceComRecord(sessionForce, recordForce)
Creates or updates multiple records in ForceCom. Returns a result object containing the fields 'id','success', and 'errors', which are either single entries or arrays.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ForceCom connection object |
records* | text, expression, variable | An array of Record objects containing the fields you want to save. If 'Id' is set for a given Record, an update will be performed, otherwise a create will be performed. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
results = saveForceComRecords(sessionForce, records)
Example
# open csv file containing new leads
csvInput = openDelimitedTextInput("data/leads.csv",
"FirstName,LastName,Email,Company")
# open session to Force.com to access Salesforce app
sessionSalesforce = openForceComConnection("user@example.com",
<Password> , {
socketTimeout: 10000
})
# loop through new leads
forEach(csvRecord, csvInput) {
# check for existing lead with same email address
existing = getForceComRecords(sessionSalesforce, "Lead", {
Email: "'" + csvRecord["Email"] + "'"
})
if (existing & amp; & amp; existing[0]) {
# lead exists, update the other fields
record = createRecord(true) setRecordFieldValue(record, "type",
"Lead")
setRecordFieldValue(record, "Id", existing[0]["Id"])
copyRecordFields(csvRecord, record, "FirstName, LastName,
Company")
updatedId = saveForceComRecord(sessionSalesforce, record)
if (updatedId) {
log("Updated existing lead for: " + toJSON(csvRecord),
"INFO")
} else {
log("Error updating existing lead for: " +
toJSON(csvRecord), "ERROR")
}
} else {
# lead doesn 't exist, so add
record = createRecord(true)
setRecordFieldValue(record, "type", "Lead")
copyRecordFields(csvRecord, record, "FirstName, LastName,
Email, Company")
createdId = saveForceComRecord(sessionSalesforce, record)
if (createdId) {
log("Added new lead for: " + toJSON(csvRecord), "INFO")
} else {
log("Error updating existing lead for: " + toJSON(csvRecord),
"ERROR")
Go }
}
}
close(sessionSalesforce)
close(csvInput)Google Classroom Adapter Actions
The Google Classroom Adapter depends on the Google Apps Adapter and requires it to be licensed. Google Classroom actions require a connection created with defineGoogleAppsOAuthConnection(). The OAuth Credential used must have the classroom related scopes enabled, which are not selected by default.
Add an Alias to a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
alias* | text, expression, variable | the Alias to add |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# add a domain scoped alias to the course
newAlias = addGoogleClassroomCourseAlias(conn, courseId,
"d:English101Section2")Add a Google Apps User to a Google Classroom Course as a Student.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userId* | text, expression, variable | the id of the Student to add to the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# add a student to course
newStudent = addGoogleClassroomCourseStudent(conn,
"d:English101Section2", "john.doe@example.com")Add a batch of Google Apps Users to a Google Classroom Course as Students.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userIds* | text, expression, variable | array of ids to add to the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# add students to course
newStudents = addGoogleClassroomCourseStudents(conn,
"d:English101Section2", ["john.doe@example.com",
"jane.doe@example.com"])Add a Google Apps User to a Google Classroom Course as a Teacher.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userId* | text, expression, variable | the id of the Teacher to add to the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# add a teacher to course
newTeacher = addGoogleClassroomCourseTeacher(conn,
"d:English101Section2", "juan.fulano@example.com")Add a batch of Google Apps Users to a Google Classroom Course as Teachers.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userIds* | text, expression, variable | array of ids to add to the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# add teachers to course
newStudents = addGoogleClassroomCourseTeachers(conn,
"d:English101Section2", ["juan.fulano@example.com",
"maria.fulano@example.com"])Delete a Google Classroom Course record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
id* | text, expression, variable | the id of the Course to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# delete a course
deleted = deleteGoogleClassroomCourse(conn,
"d:English101Section2")Delete an Alias from a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
alias* | text, expression, variable | the Alias to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# delete the alias from the course
deleted = deleteGoogleClassroomCourse(conn, courseId,
"d:English101Section2")Delete an Invitation to a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
id* | text, expression, variable | the id of the Invitation |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the invitation so we can find its id
invitation = getGoogleClassroomCourseInvitations(conn,
{courseId: courseId, userId: "juan.fulano@example.com"})
# delete the invitation
deleted = deleteGoogleClassroomCourseInvitation(conn, invitation.id)Delete a batch of Invitations to Google Classroom Courses.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
ids* | text, expression, variable | array of ids to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get all invitations to a course
invitations = getGoogleClassroomCourseInvitations(conn,
{courseId: courseId})
# extract the ids
invitationIds = createArray()
forEach(invitation, invitations) {
appendArrayElement(invitationIds, invitation.id)
}
deleted = deleteGoogleClassroomCourseInvitations(conn,
invitationIds)Delete a batch of Google Classroom Course record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
ids* | text, expression, variable | array of the Google Classroom User ids to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# delete courses deleted = deleteGoogleClassroomCourses(conn, [course1Id, course2Id])
Delete a Student from a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userId* | text, expression, variable | the id of the Student to delete from the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# remove a student from course
deleted = deleteGoogleClassroomCourseStudent(conn, courseId,
"john.doe@example.com")Delete a batch of Students from a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userIds* | text, expression, variable | array of ids to remove from the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# remove students from course
deleted = deleteGoogleClassroomCourseStudents(conn, courseId,
["john.doe@example.com", "jane.doe@example.com"])Delete a Teacher from a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userId* | text, expression, variable | the id of the Teacher to delete from the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# remove a teacher from course
deleted = deleteGoogleClassroomCourseTeacher(conn, courseId,
"juan.fulano@example.com")Delete a batch of Teachers from a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userIds* | text, expression, variable | array of ids to remove from the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# remove teachers from course
deleted = deleteGoogleClassroomCourseTeachers(conn, courseId,
["juan.fulano@example.com", "maria.fulano@example.com"])Get a Google Classroom Course record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
id* | text, expression, variable | the id of the Course to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get a course course = getGoogleClassroomCourse(conn, courseId, English101Section2")
Get the aliases for a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the aliases for a course aliases = getGoogleClassroomCourseAliases(conn, courseId)
Get list of outstanding Google Classroom Course Invitations.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
filter* | text, expression, variable | filter to limit the Invitations returned (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the outstanding invitations for a course
invitations = getGoogleClassroomCourseInvitations(conn, {courseId:
courseId})Get Google Classroom Course records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
filter | text, expression, variable | filter to limit the Courses returned (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the courses that a student is enrolled in
courses = getGoogleClassroomCourses(conn,
{studentId: "john.doe@example.com"})Get batch of Google Classroom Course records by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
ids* | text, expression, variable | array of the Google Classroom User ids to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the courses by id courses = getGoogleClassroomCoursesByID(conn, [course1Id, course2Id])
Get the list of Students from a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the students from a course students = getGoogleClassroomCourseStudents(conn, courseId)
Get the list of Teachers from a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# get the students from a course teacher = getGoogleClassroomCourseTeachers(conn, courseId)
Invite a batch of Google Apps Users to a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userIds* | text, expression, variable | array of ids to invite to the Course |
role* | choice (STUDENT, TEACHER), text, expression, variable | the role of the invited Users |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# invite students to a course
invitations = inviteUsersToGoogleClassroomCourse(conn, courseId,
["john.doe@example.com", "jane.doe@example.com"], "STUDENT")Invite a Google Apps User to a Google Classroom Course.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
courseId* | text, expression, variable | the id of the Course |
userId* | text, expression, variable | the id of the User to invite to the Course |
role* | choice (STUDENT, TEACHER), text, expression, variable | the role of the invited User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# invite a teacher to a course
invitations = inviteUserToGoogleClassroomCourse(conn, courseId,
"maria.fulano.doe@example.com"], "TEACHER")Open Google Classroom Course Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
filter | text, expression, variable | filter to limit the Courses returned (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# iterate all the courses in the domain
courses = openGoogleClassroomCourseIterator(conn)
forEach(course, courses) {
# do something
}Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# create a new course
courseTemplate = createRecord()
setRecordFieldValue(courseTemplate, "name", "English 101");
setRecordFieldValue(courseTemplate, "section", "A");
setRecordFieldValue(courseTemplate, "descriptionHeading",
"Welcome to English 101");
setRecordFieldValue(courseTemplate, "description", "Remedial English");
setRecordFieldValue(courseTemplate, "room", "222", false);
setRecordFieldValue(courseTemplate, "ownerId", "admin@example.com");
setRecordFieldValue(courseTemplate, "courseState", "ACCEPTED");
setRecordFieldValue(courseTemplate, "alias", "English-101-Section-A");
newCourse = saveGoogleClassroomCourse(conn, courseTemplate); Create/Update a batch of Google Classroom Course records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Google Apps connection definition |
records* | expression, variable | array of records to save |
array of records to save | expression, variable | name of the variable to be assigned to the return value |
Example
# create 3 sections of new course
courseTemplates = createArray()
forEach(section, ["A", "B", "C"])
courseTemplate = createRecord()
setRecordFieldValue(courseTemplate, "name", "English 101")
setRecordFieldValue(courseTemplate, "section", section)
setRecordFieldValue(courseTemplate, "descriptionHeading",
"Welcome to English 101")
setRecordFieldValue(courseTemplate, "description", "Remedial English")
setRecordFieldValue(courseTemplate, "room", "222", false)
setRecordFieldValue(courseTemplate, "ownerId", "admin@example.com")
setRecordFieldValue(courseTemplate, "courseState", "ACCEPTED")
setRecordFieldValue(courseTemplate, "alias", "English-101-Section-"
+ section)
appendArrayElement(courseTemplates, courseTemplate)
}
newCourse = saveGoogleClassroomCourses(conn, courseTemplates)Google Apps Adapter Record Fields Reference
See also: Google Classroom API Reference
Field | Read-Only | Description |
|---|---|---|
id | Y | Identifier for this course assigned by Classroom (exclude on create) |
name | N | Name of the course (required) |
section | N | Section of the course |
descriptionHeading | N | Heading for the description |
description | N | Description |
room | N | Room location. |
courseState | N | State of the course (ACTIVE|ARCHIVED|PROVISIONED|DECLINED) (default: PROVISIONED) |
alias | N | Initial alias on creation, not readable and ignored on updates. |
ownerId | Y | the Google Apps id of the owner of the course (required on create, but read-only after that) |
enrollmentCode | Y | Enrollment code to use when joining this course |
alternateLink | Y | indicates if the User's IP address is white listed |
creationTime | Y | Creation timestamp |
updateTime | Y | Update timestamp |
Field | Read-Only | Description |
|---|---|---|
alias | Y | Alias string. The format of the string indicates the desired alias scoping.
Once assigned, an alias can be used in place of the id |
Field | Read-Only | Description |
|---|---|---|
courseId | Y | the id of the course |
userId | Y | uniqueid of the Teacher/Student |
profile | Y | User information of the Teacher/Student |
profile.name | Y | Name of the user |
profile.name.givenName | Y | The first name |
profile.name.familyName | Y | The last name |
profile.name.fullName | Y | The full name |
profile.emailAddress | Y | The email address |
profile.photoUrl | Y | The photo url |
profile.permissions | Y | List of permissions |
Field | Read-Only | Description |
|---|---|---|
id | Y | the id of the invitation |
userId | Y | uniqueid of the invited Teacher/Student |
courseId | Y | the id of the course |
role | Y | STUDENT | TEACHER |
Google Apps Adapter Filter Fields Reference
Where allowed or required, the filter property is a Record or object with the described fields.
|
Field |
Description |
|---|---|
|
studentId |
Restricts returned Courses to those having the specified Student |
|
teacherId |
Restricts returned Courses to those having the specified Teacher |
|
Field |
Description |
|---|---|
|
userId |
Restricts returned invitations to those for the specified Student/Teacher |
|
courseId |
Restricts returned invitations to those for the specified Course |
G-Suite Adapter Actions
The RapidIdentity Rolling Release versions include updated nomenclature of the Google actions to align with Google's renaming of Google Apps to G-Suite.
The adapter is now referred to as G-Suite and the actions all have "Apps" removed from their names. RapidIdentity includes a mapping from the older G-Suite action names to the newer G-Suite action names.
Add a G-Suite Alias to a Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
alias* | text, expression, variable | the Alias to add |
groupId* | text, expression, variable | the id of the Group |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = addGoogleGroupAlias(sessionGoogle, "test-group@example.com",
"test-group-alias@example.com")Add a member to a G-Suite Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
groupId* | text, expression, variable | the id of the group |
memberId* | text, expression, variable | the id of the object to add to the Group |
role | choice (MEMBER, MANAGER, OWNER), text, expression, variable | the role of the member (default: MEMBER) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = addGoogleGroupMember(sessionGoogle, "test-group@example.com",
"joeuser@example.com", "MEMBER")Add a batch of members to a G-Suite Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
groupId* | text, expression, variable | the id of the group |
memberIds* | text, expression, variable | array of ids to add to the Group |
role | choice (MEMBER, MANAGER, OWNER), text, expression, variable | the role of the members (default:MEMBER) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
members = createArray()
appendArrayItem(members, "joeuser@example.com")
appendArrayItem(members, "freduser@example.com")
appendArrayItem(members, "tomuser@example.com")
result = addGoogleGroupMembers(sessionGoogle, "test-group@example.com",
members, "MEMBER")Add a G-Suite Alias to a User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
alias* | text, expression, variable | the Alias to add |
userId* | text, expression, variable | the id of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Note
result = addGoogleUserAlias(sessionGoogle, "joeuser@example.com",
"joeuser@students.example.com")Call an arbitrary Google API endpoint.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
method* | choice (GET, POST, PATCH, PUT, DELETE), text, expression, variable | the HTTP method to use |
url* | text, expression, variable | The url of the Google API endpoint |
headers | expression, variable | a Record or Object containing additional HTTP header fields |
data | expression, variable | the data (PATCH/POST/PUT methods only) |
contentType | choice (application/json, application/atom+xml), text, expression, variable | the Content-Type of data (PATCH/POST/PUT methods only) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.GoogleDomain = "example.com"
Global.GoogleOAuthCredentialName = "MyGoogleExtendedCredential"
sessionGoogle = defineGoogleExtendedOAuthConnection(Global.GoogleDomain,
Global.MyGoogleExtendedCredential,
["https://www.googleapis.com/auth/drive"], currentUser.id)
# upload test string as a file to google drive
response = callGoogleAPI(sessionGoogle, "POST",
"https://www.googleapis.com/upload/drive/v3/files?uploadType=media",
null, "This is a test", "text/plain");
# if successfully uploaded, rename from auto-generated name to
one of our choice
if(response.statusCode == 200 && response.data && response.data.id) {
fileId = response.data.id
response = callGoogleAPI(sessionGoogle, "PATCH",
"https://www.googleapis.com/drive/v3/files/" + fileId, null,
{name: "text.txt"}, "application/json");
} else {
}Define an Extended OAuth2 connection to G-Suite.
Property | Value | Description |
|---|---|---|
domain* | text, expression, variable | the name of the G-Suite domain |
credentialName* | text, expression, variable | OAuth2 credential for authentication to G-Suite |
scopes* | text, expression, variable | Array of Google OAuth2 scopes to enable |
impersonateUserId | text, expression, variable | Google User to impersonate |
options | expression, variable | Record or object holding additional options |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.GoogleDomain = "example.com"
Global.GoogleOAuthCredentialName = "MyGoogleExtendedCredential"
sessionGoogle = defineGoogleExtendedOAuthConnection(Global.GoogleDomain,
Global.MyGoogleExtendedCredential,
["https://www.googleapis.com/auth/drive"], currentUser.id)Define an OAuth2 connection to G-Suite.
Property | Value | Description |
|---|---|---|
domain* | text, expression, variable | the name of the G-Suite domain |
credentialName* | text, expression, variable | OAuth2 credential for authentication to G-Suite |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.GoogleDomain = "example.com"
Global.GoogleOAuthCredentialName = "MyGoogleCredential"
sessionGoogle = defineGoogleOAuthConnection(Global.GoogleDomain,
Global.GoogleOAuthCredentialName)Delete a G-Suite Calendar Resource record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Calendar Resource to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleCalendarResource(sessionGoogle, "projector-1")
Delete a trustee from a G-Suite Calendar.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
calendar* | text, expression, variable | the id (email) of the G-Suite Calendar |
trustee* | text, expression, variable | the id of the trustee |
domain | text, expression, variable | the domain of the G-Suite Calendar (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleCalendarTrustee(sessionGoogle, "jdoe@example.com",
"jsmith@example.com")Delete a G-Suite Custom Schema record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Custom Schema to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleCustomSchema(sessionGoogle, "my_schema")
Delete a G-Suite Group record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Group to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleGroup(sessionGoogle,
"test-group@example.com")Delete a G-Suite Alias from a Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
alias* | text, expression, variable | the Alias to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleGroupAlias(sessionGoogle, "test-group-alias@example.com")
Delete a member from a G-Suite Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
groupId* | text, expression, variable | the id of the group |
memberId* | text, expression, variable | the id of the object to delete from the Group |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleGroupMember(sessionGoogle, "test-group@example.com",
"joeuser@example.com")Delete a batch of members from a G-Suite Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
groupId* | text, expression, variable | the id of the group |
memberIds* | text, expression, variable | array of ids to remove from the Group |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
members = createArray()
appendArrayItem(members, "joeuser@example.com")
appendArrayItem(members, "freduser@example.com")
appendArrayItem(members, "tomuser@example.com")
result = deleteGoogleGroupMembers(sessionGoogle, "test-group@example.com",
members)Delete a batch of G-Suite Group record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
ids* | text, expression, variable | array of the G-Suite User ids to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groups = createArray() appendArrayItem(groups, "test-group1@example.com") appendArrayItem(groups, "test-group2@example.com") appendArrayItem(groups, "test-group3@example.com") result = deleteGoogleGroups(sessionGoogle, groups)
Delete a G-Suite OrgUnit record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite OrgUnit to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleteGoogleOrgUnit(sessionGoogle, "jim-test/jim-test-sub")
Delete a G-Suite Shared Contact record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Shared Contact to delete |
domain | text, expression, variable | the domain of the G-Suite Shared Contact to delete (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleSharedContact(sessionGoogle, "9f0e6b60fa1d04c")
Delete a G-Suite Shared Contact Photo by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite User |
domain | text, expression, variable | the domain of the G-Suite Shared Contact (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleSharedContactPhoto(sessionGoogle, "9f0e6b60fa1d04c")
Delete a G-Suite User record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite User to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleUser(sessionGoogle, "joeuser@example.com")
Delete a G-Suite Alias from a User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
alias* | text, expression, variable | the Alias to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleUserAlias(sessionGoogle, "joeuser@students.example.com")
Delete a G-Suite User Photo by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = deleteGoogleUserPhoto(sessionGoogle, "joeuser@example.com")
Delete batch of G-Suite Users by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
ids* | expression, variable | array of the G-Suite User ids to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
users = createArray() appendArrayItem(users, "joeuser@example.com") appendArrayItem(users, "freduser@example.com") appendArrayItem(users, "tomuser@example.com") result = deleteGoogleUsers(sessionGoogle, users)
Delete a Send-as Alias for a Google Apps user.
Property | Value | Description |
|---|---|---|
returnVariable | expression, variable | name of the variable to be assigned to the return value |
connection* | expression, variable | the G-Suite connection definition |
userid* | text, expression, variable | The UserID with the assigned alias (email) |
sendAsId | text, expression, variable | The SendAs Alias address to be delted |
Example
deleteGoogleUserSendAsAlias(sessionGoogle, "ddeers@idautodemo.com", "ccooper@idautodemo.com")
Get a G-Suite Calendar Resource record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Calendar Resource to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
resource = getGoogleCalendarResource(sessionGoogle,
"testresource_1393275428627")Get G-Suite Calendar Resource records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
resources = getGoogleCalendarResources(sessionGoogle)
Get a trustee of G-Suite Calendar.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
calendar* | text, expression, variable | the id (email) of the G-Suite Calendar |
trustee* | text, expression, variable | the id of the trustee |
domain | text, expression, variable | the domain of the G-Suite Calendar (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
trustee = getGoogleCalendarTrustee(sessionGoogle, "jdoe@example.com",
"example.com")Get G-Suite Calendar trustees.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
calendar* | text, expression, variable | the id (email) of the G-Suite Calendar |
domain | text, expression, variable | the domain of the G-Suite Calendar (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
trustees = getGoogleCalendarTrustees(sessionGoogle, "jdoe@example.com")
Get a G-Suite CustomSchema record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Custom Schema to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
my_schema = getGoogleCustomSchema(sessionGoogle, "my_schema")
Get G-Suite Custom Schema records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
schemas = getGoogleCustomSchemas(sessionGoogle)
Get a G-Suite Group record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Group to get |
minimal | boolean, expression, variable | don't get member, owner, and manager (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupIds = createArray() getGoogleGroup(groupIds, "group1@example.com") getGoogleGroup(groupIds, "group2@example.com") getGoogleGroup(groupIds, "group3@example.com") groups = getGoogleGroupsById(sessionGoogle, groupIds)
Get G-Suite Group records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
domain | text, expression, variable | the domain of the groups to get (default: the domain specified in the connection; * = all domains associated with the account) |
minimal | boolean, expression, variable | don't get member, owner, and manager (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groups = getGoogleGroups(sessionGoogle)
Get batch of G-Suite Group records by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
ids* | text, expression, variable | array of the G-Suite User ids to get |
minimal | boolean, expression, variable | don't get member, owner, and manager (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
group = getGoogleGroupsById(sessionGoogle,
"testgroup_1332876583247@example.com")Get a G-Suite Group Settings record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Group |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupSettings = getGoogleGroupSettings(sessionGoogle,
"testgroup_1332876583247@example.com")Get a G-Suite OrgUnit record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite OrgUnit to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
orgUnit = getGoogleOrgUnit(sessionGoogle, "jim-test")
Get G-Suite OrgUnit records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
parentId | text, expression, variable | the id of the parent G-Suite OrgUnit to get the children of (default: all OrgUnits) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
orgUnits = getGoogleOrgUnits(sessionGoogle)
Get a G-Suite Shared Contact record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Shared Contact to get |
domain | text, expression, variable | the domain of the G-Suite Shared Contact to get (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
contact = getGoogleSharedContact(sessionGoogle, "7154f278887c0b81")
Get a G-Suite Shared Contact Photo by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite Shared Contact |
domain | text, expression, variable | the domain of the G-Suite Shared Contact (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
photo = getGoogleSharedContactPhoto(sessionGoogle, "7154f278887c0b81")
Get G-Suite Shared Contact records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
domain | text, expression, variable | the domain of the G-Suite Shared Contacts to get (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
contacts = getGoogleSharedContacts(sessionGoogle)
Get a G-Suite User record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite User to get |
minimal | boolean, expression, variable | don't get user.emailLists, user.nicknames, and orgUnitPath (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
user = getGoogleUser(sessionGoogle, "jdoe@example.com")
Get a G-Suite User Photo by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
photo = getGoogleUserPhoto(sessionGoogle, "jdoe@example.com")
Get G-Suite User records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
parentId | text, expression, variable | the id of the parent G-Suite OrgUnit to get the children of (default: all OrgUnits) |
domain | text, expression, variable | the domain of the users to get (default: the domain specified in the connection; * = all domains associated with the account) |
filter | text, expression, variable | filter to limit the users returned (default: none) For filter syntax, see https://developers.google.com/admin-sdk/directory/v1/guides/search-users |
minimal | boolean, expression, variable | don't get user.emailLists, user.nicknames, and orgUnitPath (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
users = getGoogleUsers(sessionGoogle)
Get batch of G-Suite User records by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
ids* | expression, variable | array of the G-Suite User ids to get |
minimal | boolean, expression, variable | don't get user.emailLists, user.nicknames, and orgUnitPath (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userIds = createArray() appendArrayElement(userIds, "user1@example.com") appendArrayElement(userIds, "user2@example.com") appendArrayElement(userIds, "user3@example.com") users = getGoogleUsersById(sessionGoogle, userIds)
Get the specific Send-As Alias for a Google User.
Property | Value | Description |
|---|---|---|
returnVariable | expression, variable | name of the variable to be assigned to the return value |
connection* | expression, variable | the G-Suite connection definition |
userId* | text, expression, variable | the id of the G-Suite User |
sendAsId* | text, expression | the id of the SendAs alias |
Example
getGoogleUserSendAsAlias(sessionGoogle, "ddeers@idautodemo.com", "derrickdeers@idautodemo.com"
Get the Send-as Aliases for a G-Suite User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
userId* | text, expression, variable | the id of the G-Suite User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
sendAsAliases = getGoogleUserSendAsAliases(sessionGoogle, "jdoe")
Open G-Suite Calendar Resource Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
iterator = openGoogleCalendarResourceIterator(conn, true)
forEach(next, iterator) {
log("next:" + next);
}
close(iterator)Open G-Suite Group Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
domain | text, expression, variable | the domain of the users to get (default: the domain specified in the connection; * = all domains associated with the account) |
minimal | boolean, expression, variable | don't get user.emailLists, user.nicknames, and orgUnitPath (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
iterator = openGoogleGroupIterator(conn, true)
forEach(next, iterator) {
log("next:" + next);
}
close(iterator)Open G-Suite OrgUnit Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
parentId | text, expression, variable | the id of the parent G-Suite OrgUnit to get the children of (default: all OrgUnits) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
iterator = openGoogleOrgUnitIterator(conn, true)
forEach(next, iterator) {
log("next:" + next);
}
close(iterator)Open G-Suite Shared Contact Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
domain | text, expression, variable | the domain of the G-Suite Shared Contacts to iterate (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
iterator = openGoogleSharedContactIterator(conn, true)
forEach(next, iterator) {
log("next:" + next);
}
close(iterator)Open G-Suite User Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
parentId | text, expression, variable | the id of the parent G-Suite OrgUnit to get the children of (default: all OrgUnits) |
domain | text, expression, variable | the domain of the users to get (default: the domain specified in the connection; * = all domains associated with the account) |
filter | text, expression, variable | filter to limit the users returned (default: none) For filter syntax, see https://developers.google.com/admin-sdk/directory/v1/guides/search-users |
minimal | boolean, expression, variable | don't get user.emailLists, user.nicknames, and orgUnitPath (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
iterator = openGoogleUserIterator(conn, true)
forEach(next, iterator) {
log("next:" + next);
}
close(iterator)Update a G-Suite Calendar Resource record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
resource = createRecord(false)
setRecordFieldValue(resource, "resourceId", "projector-1")
setRecordFieldValue(resource, "resourceDescription",
"Dell model 1021 projector - Sales")
setRecordFieldValue(resource, "resourceName", "projector-sales")
result = saveGoogleCalendarResource(sessionGoogle, resource)Create/Update a G-Suite Custom Schema record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
schemaTemplate = createRecordFromObject({
schemaName: "my_schema",
fields: [
{
fieldName: "isManager",
fieldType: "BOOL",
indexed: false,
multiValued: false,
readAccessType: "ALL_DOMAIN_USERS"
},
{
fieldName: "directReports",
fieldType: "EMAIL",
indexed: true,
multiValued: true,
readAccessType: "ALL_DOMAIN_USERS"
},
]
})
my_schema = saveGoogleCustomSchema(conn, schemaTemplate)Create/Update a G-Suite Group record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
group = createRecord(false) setRecordFieldValue(group, "groupId", "test-group@example.com") setRecordFieldValue(group, "groupName", "test-group") setRecordFieldValue(group, "description", "A test group") result = saveGoogleGroup(sessionGoogle, group)
Create/Update a batch of G-Suite Group records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
records* | expression, variable | array of records to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groups = createArray()
i = 0
while(i++ < 5) {
group = createRecord(false)
setRecordFieldValue(group, "groupId", "test-group-" + i + "@example.com")
setRecordFieldValue(group, "groupName", "test-group-" + i);
setRecordFieldValue(group, "description", "A test group")
appendArrayItem(groups, group)
}
result = saveGoogleGroups(sessionGoogle, groups)Update a G-Suite Group Settings record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupSettings = createRecord(false)
setRecordFieldValue(groupSettings, "id", "test-group@example.com")
setRecordFieldValue(groupSettings, "whoCanPostMessage",
"ALL_MEMBERS_CAN_POST")
result = saveGoogleGroupSettings(sessionGoogle, groupSettings)Create/Update a G-Suite OrgUnit record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
orgUnit = createRecord(true) addRecordFieldValue(orgUnit, "name", "jim-test", false) addRecordFieldValue(orgUnit, "description", "Jim's test org unit", false) addRecordFieldValue(orgUnit, "parentOrgUnitPath", "/", false) saveGoogleOrgUnit(sessionGoogle, orgUnit) orgUnit2 = createRecord(false) addRecordFieldValue(orgUnit2, "name", "jim-test-sub", false) addRecordFieldValue(orgUnit2, "parentOrgUnitPath", "jim-test", false) addRecordFieldValue(orgUnit2, "description", "Jim's test sub ou", false) addRecordFieldValue(orgUnit2, "blockInheritance", "true", false) saveGoogleOrgUnit(sessionGoogle, orgUnit2)
Update a G-Suite Shared Contact record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
phone = createRecord(true) addRecordFieldValue(phone, "number", "2812200021", false) addRecordFieldValue(phone, "rel", "work", false) addRecordFieldValue(phone, "primary", "true", false) contact = createRecord(false) addRecordFieldValue(contact, "fullName", "Identity Automation", false) addRecordFieldValue(contact, "phoneNumber", phone, false) result = saveGoogleSharedContact(sessionGoogle, contact)
Create/Update a G-Suite User record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
user = createRecord(true) addRecordFieldValue(user, "primaryEmail", "joeuser@example.com", false) addRecordFieldValue(user, "password", "Ch@ng3m3", false) addRecordFieldValue(user, "familyName", "User", false) addRecordFieldValue(user, "givenName", "Joe", false) addRecordFieldValue(user, "orgUnitPath", "jim-test", false) phone = createRecord(true) addRecordFieldValue(phone, "number", "2812200021", false) addRecordFieldValue(phone, "rel", "work", false) addRecordFieldValue(phone, "primary", "true", false) addRecordFieldValue(user, "phones", phone) result = saveGoogleUser(sessionGoogle, user)
Create/Update a batch of G-Suite User records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
records* | expression, variable | array of records to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
users = createArray()
i = 0
while(i++ < 5) {
user = createRecord(true)
addRecordFieldValue(user, "primaryEmail", "joeuser_" + i +
"@example.com", false)
addRecordFieldValue(user, "password", "Ch@ng3m3", false)
addRecordFieldValue(user, "familyName", "User", false)
addRecordFieldValue(user, "givenName", "Joe", false)
addRecordFieldValue(user, "orgUnitPath", "jim-test", false)
appendArrayItem(users, group)
}
result = saveGoogleUsers(sessionGoogle, users)saveGoogleUserSendAsAlias
Add a Send-as Alias for a Google User.
Property | Value | Description |
|---|---|---|
returnVariable | expression, variable | name of the variable to be assigned to the return value |
connection* | expression, variable | the G-Suite connection definition |
record* | expression, variable | array of records to save |
Example
{
doesContain = stringContains(exists['emails'], recordAD['mail'], true)
if (!doesContain) {
# Add Google Apps Alias
{
result = addGoogleUserAlias(sessionGoogle, recordAD['mail'], record['userName'])
}
if (result) {
{
alias = createRecord()
setRecordFieldValue(alias, "userId", record['userName'])
setRecordFieldValue(alias, "address", recordAD['mail'])
setRecordFieldValue(alias, "name", recordAD['displayName'])
setRecordFieldValue(alias, "replyTo", recordAD['mail'])
setRecordFieldValue(alias, "makeDefault", true)
result = saveGoogleUserSendAsAlias(sessionGoogle, alias)
}
} else {
}
} else {
}
Add/Update a trustee of a G-Suite Calendar.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
calendar* | text, expression, variable | the id (email) of the G-Suite Calendar |
trustee* | text, expression, variable | the id of the trustee |
role* | choice (none, freebusy, read, owner), text, expression, variable | the trustee role |
domain | text, expression, variable | the domain of the G-Suite Calendar (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = setGoogleCalendarTrustee(sessionGoogle, "jdoe@example.com",
"jsmith@example.com", "read")Update a G-Suite Shared Contact Photo.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite User |
type* | text, expression, variable | the MIME media type of the photo |
photo* | expression, variable | the photo (as a byte array or Base64 encoded string) |
domain | text, expression, variable | the domain of the G-Suite Shared Contact (default: the domain specified in the connection) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
photo = loadFileAsBytes("/photos/test.jpg")
result = setGoogleSharedContactPhoto(sessionGoogle, "7154f278887c0b81",
"image/jpeg", photo)Update a G-Suite User Photo.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the G-Suite connection definition |
id* | text, expression, variable | the id of the G-Suite User |
type* | text, expression, variable | the MIME media type of the photo |
photo* | expression, variable | the photo (as a byte array or Base64 encoded string) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
photo = loadFileAsBytes("/photos/jdoe.jpg")
result = setGoogleUserPhoto(sessionGoogle, "jdoe@example.com",
"image/jpeg", photo)G-Suite Adapter Record Fields Reference
Field | Read-Only | Description |
|---|---|---|
id | Y | the primaryEmail of the user to be updated (exclude on create) |
primaryEmail (required for create) | N | The User's primary email address |
password (required for create) | N | Stores the password for the user account |
hashFunctionName | N | when setting password, the hash function that has already been applied to the password. Legal values are “SHA-1”, “MD5”, and “CRYPT” or leave unspecified if password in clear text |
givenName (required for create) | N | the User's first name |
familyName (required for create) | N | the User's last name |
fullName | Y | the User's full name |
admin | N | indicates if the User has super admininistrator privileges |
suspended | N | indicates if the User is suspended |
suspensionReason | Y | indicates the reason the User was suspended: “ADMIN”, “UNDER13”, “WEB_LOGIN_REQUIRED”, “ABUSE” |
changePasswordAtNextLogin | N | indicates if the User is forced to change their password at next login |
ipWhitelisted | N | indicates if the User's IP address is white listed |
includeInGlobalAddressList | N | indicates if the User's profile is visible in the G-Suite global address list when the contact sharing feature is enabled for the domain |
ims | N | the User's User IM Record Fields |
emails | N | the User's User Email Record Fields |
externalIds | N | the User's User External ID Record Fields |
relations | N | the User's User Relationship Record Fields |
addresses | N | the User's User Address Record Fields |
organizations | N | the User's User Organization Record Fields |
phones | N | the User's User Phone Number Record Fields |
etag | Y | eTag of the resource |
isDelegatedAdmin | Y | Indicates if the User is a delegated administrator |
lastLoginTime | Y | the last time the User logged into the User's account (Date object) |
creationTime | Y | the time the User User's account was created (Date object) |
deletionTime | Y | the time the User User's account was deleted (Date object) |
customerId | Y | the customer ID of the User |
isMailboxSetup | Y | indicates if the user's Google mailbox is created |
thumbnailPhotoUrl | Y | photo Url of the user |
uniqueid | Y | the unique ID for the user |
aliases | Y | the User's alias email addresses |
nonEditableAliases | Y | the user's non-editable alias email addresses - typically outside the account's primary domain or sub-domain |
memberOf | Y | all groups for which a user or group has a membership |
customSchemas | N | the User's Custom Schema Record Fields |
userName | N | the user name of the User (DEPRECATED - use primaryEmail) |
user.emailLists | Y | list of Groups the User belongs to (DEPRECATED - use memberOf) |
user.nicknames | Y | the Nicknames of the User (DEPRECATED - use aliases) |
Field | Read-Only | Description |
|---|---|---|
id | Y | the id of the Group to be updated (exclude on create) |
groupId (required for create) | N | the email address of the Group |
groupName (required for create) | N | the name of the Group |
description | Y | the description of the Group |
member | Y | list of members of the Group |
etag | Y | eTag of the resource |
whoCanAdd | N | the members that can add members to the Group. can be set to all members, managers, or none |
whoCanJoin | N | the members that can join the Group. can be set to members in any domain, by request, or invitation |
whoCanViewGroup | N | the members that can view to the Group. can be set to members in the domain, managers, members, or anyone |
whoCanLeaveGroup | N | the members that can leave the Group. can be set to all members, managers, or none |
whoCanContactOwner | N | the members that can contact the Group owner. can be set to all in the domain, members, managers, or anyone |
Field | Read-Only | Description |
|---|---|---|
id | Y | the id of the Alias (exclude on create) |
alias | Y | the Alias email address |
primaryEmail | Y | The aliased User's/Group's primary email address |
etag | Y | eTag of the resource |
Field | Read-Only | Description |
|---|---|---|
id | Y | the id of the OrgUnit (exclude on create) |
name | N | the simple name of the OrgUnit |
parentOrgUnitPath | N | the full path name of the OrgUnit parent |
description | N | the description of the OrgUnit |
blockInheritance | N | block policy inheritance from OrgUnits higher in the OrgUnit tree (“true”/“false”) |
orgUnitPath | Y | the full pathname of the OrgUnit |
etag | Y | eTag of the resource |
Field | Read-Only | Description |
|---|---|---|
id | Y | the id of the Contact (exclude on create) |
namePrefix | N | Honorific prefix of the Contact, e.g. 'Mr' or 'Mrs' |
givenName | N | given name of the Contact |
additionalName | N | additional name of the Contact, eg. middle name |
familyName | N | family name of the Contact |
nameSuffix | N | Honorific suffix of the Contact, e.g. 'Jr' or 'MD' |
fullName | N | Unstructured representation of the name of the Contact |
content | N | notes about the Contact |
N | Contact Email Record Fields | |
im | N | Contact IM Record Fields |
organization | N | Contact Organization Record Fields |
phoneNumber | N | Contact Phone Number Record Fields |
structuredPostalAddress | N | Contact Postal Address Record Fields |
where | N | place associated with the Contact |
extendedProperty | N | Contact Extended Property Record Fields |
title | Y | the title of the Contact |
updated | Y | the date the Contact record was last updated |
Field | Read-Only | Description |
|---|---|---|
id | Y | the id of the Resource (exclude on create) |
resourceId (required for create) | N | the unique name of the Resource |
resourceName | N | the name of the Resource |
resourceDescription | N | the description of the Resource |
resourceEmail | Y | the email address of the Resource and the id of the associated associated Calendar) |
resourceType | N | the type of the Resource |
resourceCommonName | N | the display name of the Resource (DEPRECATED - use resourceName) |
Field | Read-Only | Description |
|---|---|---|
userId | N | the id of the User the Send-As Alias will apply to |
name | N | the name associated with the Send-As Alias |
address | N | the email address of the Send-As Alias |
replyTo | N | optional reply-to address of Send-As Alias |
makeDefault | N | the make the Send-As Alias the default for the User |
isDefault | Y | indicates whether or not the Send-As Alias is currently default for the User |
verified | Y | indicates if the ownership of the email address's domain has been verified. This field must be true (verified), before the Send-As alias address can work. |
Field | Read-Only | Description |
|---|---|---|
id | Y | The id of the schema |
schemaName | N | The name of the custom schema |
schemaId | Y | The unique identifier of the schema |
fields | N | 1 or more Custom Field Definition Records |
Field | Read-Only | Description |
|---|---|---|
fieldName | N | The name of the custom field |
fieldId | Y | The unique identifier of the field |
fieldType | N | The type of the field:
|
indexed | N | true if field is to be indexed (default: true) |
multiValued | N | true if field is multivalued (default: false) |
readAccessType | N | Who can view values of this field:
|
numericIndexingSpec | N | Indexing spec for a numeric field. By default, only exact match queries will be supported for numeric fields. Setting this field allows range queries to be supported. |
numericIndexingSpec.maxValue | N | Maximum value of this field. This is meant to be indicative rather than enforced. Values outside this range will still be indexed, but search may not be as performant. |
numericIndexingSpec.maxValue | N | Minimum value of this field. This is meant to be indicative rather than enforced. Values outside this range will still be indexed, but search may not be as performant. |
Field | Description |
|---|---|
address (required) | the email address |
displayName | the display name of the entity the email address belongs to |
label | name for the email address, e.g. Work, Personal, Preferred, etc. |
rel | the type of email: one of home, work, or other |
primary | boolean indicating this is the primary email address |
Field | Description |
|---|---|
address (required) | the instant messaging address |
label | name for the email address, e.g. Work, Personal, Preferred, etc. |
rel | the type of IM: one of home, netmeeting, work, or other |
protocol | the IM protocol: one of AIM, MSN, YAHOO, SKYPE, QQ, GOOGLE_TALK, ICQ, JABBER |
primary | boolean indicating this is the primary im address |
Field | Description |
|---|---|
orgDepartment | the department within the organization |
orgName | the name of the organization |
orgSymbol | the symbol of the organization |
orgTitle | the title of the person of the organization |
orgJobDescription | the job description of the person within the organization |
label | label for the organization, e.g. Work, Volunteer, etc. |
rel | the type of organization: one of work, or other |
primary | boolean indicating this is the primary organization for the person |
where | a place associated with the organization, e.g. office location |
Field | Description |
|---|---|
number (required) | the phone number |
label | name for the phone number, e.g. Work, Personal, Preferred, etc. |
rel | the type of phone number: one of assistant, callback, car, company_main, fax, home, home_fax, isdn, main, mobile, pager, radio, telex, tty_tdd, work, work_fax, work_mobile, work_pager, other_fax, or other |
uri | URI of phone number for VOIP access |
primary | boolean indicating this is the primary phone number |
Field | Description |
|---|---|
street | the street address |
pobox | the post office box |
neighborhood | the neighborhood |
city | the city |
region | state, province, etc |
postcode | postal code |
country | name of the country |
countryCode | |
formattedAddress | the full, unstructured postal address |
label | name of the address, e.g. Work, Personal, Preferred, etc. |
rel | the type of address: one of work, home, or other |
primary | boolean indicating this is the primary phone number |
Field | Description |
|---|---|
name | the name of the extended property |
realm | the realm of the extended property |
value | the value of the extended property |
Field | Description |
|---|---|
address | the email address |
primary | indicates if this is the user's primary email |
type | the type of the email account: “home”, “work”, “other”, “custom” |
customType | if the value of type is custom, this field contains the custom type string |
Field | Description |
|---|---|
im | the user's IM network ID |
primary | indicates this is the user's primary IM |
protocol | the IM protocol: “aim”, “gtalk”, “icq”, “jabber”, “msn”, “net_meeting”, “qq”, “skype”, “yahoo”, “custom_protocol” |
customProtocol | if the protocol value is custom_protocol, this field holds the custom protocol's string |
type | the type of the IM account: “home”, “work”, “other”, “custom” |
customType | if the IM type is custom, this field holds the custom type string |
Field | Description |
|---|---|
costCenter | the cost center of the organization |
department | the department within the organization |
description | the description of the organization |
domain | the domain the organization belongs to |
location | the physical location of the organization |
name | the name of the organization |
primary | indicates if this is the user's primary organization |
symbol | text string symbol of the organization |
title | the user's title within the organization |
type | the type of organization: “unknown”, “school”, “work”, “domain_only”, “custom” |
customType | if the value of type is custom, this field contains the custom type |
Field | Description |
|---|---|
value | a human-readable phone number |
primary | indicates if this is the user's primary phone number |
type | the type of phone number: “assistant”, “callback”, “car”, “company_main”, “grand_central”, “home”, “home_fax”, “isdn”, “main”, “mobile”, “other”, “other_fax”, “pager”, “radio”, “telex”, “tty_tdd”, “work”, “work_fax”, “work_mobile”, “work_pager”, “custom” |
customType | if the value of type is custom, this field contains the custom type |
Field | Description |
|---|---|
country | the country |
countryCode | the country code |
extendedAddress | for extended addresses, such as an address that includes a sub-region |
formatted | a full and unstructured postal address |
locality | the town or city of the address |
poBox | the post office box |
postalCode | the ZIP or postal code |
primary | indicates if this is the user's primary address |
region | the abbreviated province or state |
sourceIsStructured | indicates if the user-supplied address was formatted |
streetAddress | the street address |
type | the address type: “home”, “other”, “work”, “custom” |
customType | if the address type is custom, this field contains the custom value |
Field | Description |
|---|---|
value | the value of the ID |
type | the type of the ID. Allowed values are: “account”, “custom”, “customer”, “network”, “organization” |
customType | if the external ID type is custom, this field holds the custom type |
Field | Description |
|---|---|
value | the name of the person the user is related to |
type | the type of relation: “assistant”, “brother”, “child”, “domestic_partner”, “father”, “friend”, “manager”, “mother”, “parent”, “partner”, “referred_by”, “relative”, “sister”, “spouse”, “custom” |
customType | if the value of type is custom, this field contains the custom type |
Field | Description |
|---|---|
<schema_name> | Record containing the custom schema fields for the schema with name schema_name |
<schema_name>.<field_name> | For single valued fields, the value of the field For multi-valued fields, 0 or more User Custom Schema Multivalued Value Record |
Field | Description |
|---|---|
value | The value of the field item |
type | Optional type of the value
|
customType | The name of the custom type if type=custom |
G-Suite API Quotas
Google basically has two classes of API’s: billable and non-billable. Billable API’s have a courtesy daily transaction limit and if you need to exceed that limit you have to enter billing information and then you are billed for transactions in excess of the courtesy limit. Non-billable API’s also have a courtesy daily transaction limit and if you need to exceed that limit you can make a request to have the limit raised and it will be considered on a case-by-case basis.
The APIs the G-Suite Adapter uses are primarily part of the Admin SDK, which is NOT a billable API. It has a courtesy limit of 150,000 transactions per day per Project (as defined in Google Developers Console). That limit should be sufficient for organizations up to about 50,000 people, but may not be sufficient for larger organizations, at least not for the initial on-boarding process and start/end of term for large educational institutions.Google will usually grant requests for an increased quota as long as you can reasonably justify it, but it’s hard to say how high they would actually raise it. Since quotas are associated with a Developer Console Project, an alternative to requesting an increased quota is to create and use multiple projects (and consequently multiple OAuth2 credentials) and using each project credential in a round-robin fashion to decrease the amount of quota used by any individual project. There are also per/user rate limits (transactions per second), with user really defined primarily as the ip address of the API client. In the case of the G-Suite adapters a user would actually be a single DSS appliance or possibly (if behind NAT) multiple appliances. The per/user rate limits can be raised in the Developer console to pretty much anything want them to be since the purpose of the per user limits is keep a single user from using up too much of your daily quota in a scenario such as a large web site using a single Project acting on behalf of millions of users. The default rate limit is 15 requests per second. Depending on your usage this may be insufficient and will result in occasional throttling messages showing up in your Action Set logs. If these messages happen on a regular basis, you will probably want to increase the per user limit for Admin SDK. Follow these steps to obtain the quota settings for a project.
Log into Google using credentials that you want to own the Client ID and Client Secret.
Browse to Google Cloud Console (i.e. Google Developers Console).
Open the project.
Navigate to APIs & Auth | API’s.
For each API that has been enabled for the project, there is a Quota column that will show how much of the daily quota has been used, and if you hover over that field will show you the actual quota.
If you click on the Admin SDK, and then Quota link you’ll go to a page allows you to adjust the per user limits and request additional quota.
For more information, visit the Google Cloud Platform Console Help Center.
Configure OAuth for G-Suite Adapter
As of version 4.1, the G-Suite Adapter supports two different forms of OAuth2 authentication. The original form (credential type GOOGLE, used with defineGoogleOAuthCredential()) is based on the Installed Applications scenario. For most uses, this form is the easiest to configure and use, and is sufficient for most usages of the G-Suite Adapter. The new form ((credential type GOOGLE_EXTENDED, used with defineGoogleExtendedOAuthCredential())) is based on the Service Account scenario. While more difficult to configure and use, this form provides some additional flexibility to impersonate any user within the domain without needing explicit approval from each user, which, in conjunction with the new callGoogleAPI() action, allows you to do things such a manage Calendars and Google Drive files for individual users, which an admin account would not normally be able to do.The User Interface for the Google Cloud Platform Console changes from time to time so the exact steps may be different than what is listed below.
Both GOOGLE and GOOGLE_EXTENDED credentials require the creation of a Google Cloud Platform project. A single project can be used for multiple credentials of either type, with the limitation that the credentials within the same project will all share the same G-Suite API Quotas.
Log into Google using credentials that you want to own the Client ID and Client Secret.
Browse to Google Cloud Platform Console aka Google Developers Console and select the project created above.
Click the Create Project button and name the project something appropriate like “Connect Google Adapter for MyCompany”.
If not already selected, click on the newly created project to select it.
Click on the menu button at the top left of the page, and select API Manager.
Select Dashboard in the left sidebar.
Click the ENABLE API link and enable the following APIs:
Admin SDK (required)
Calendar API (optional - only needed if provisioning calendar resources or trustees)
Contacts API (optional - only needed if provisioning shared contacts)
Group Settings API (optional - only needed if using Google Groups for Business/Education and want control group settings)
Google Classroom API (optional - only needed if you will be using the Google Classroom Adapter)
There will be several other APIs that were enabled by default: you may disable them if desired.
Note that you may come back at any time and enable/disable APIs.
A Client ID and Client Secret are needed to create a standard GOOGLE OAuth2 Credential.
Navigate to Google Cloud Platform Console and select the project created above.
Click on the menu button at the top left of the page, and select API Manager.
In the sidebar on the left, select Credentials.
Select OAuth consent screen tab
The consent screen settings control what is presented when creating the OAuth2 Credential in Connect.
Select an email address if not already selected.
Set the product name to RapidIdentity.
(Optional) Set the Homepage URL to http://www.identityautomation.com/
(Optional) Set the product Logo to http://downloads.identitymgmt.net/icons/IA_icon_120_inverse.png
Click the Save button.
Select Create Credentials tab.
Click the Create credentials button and select OAuth client ID.
Select the Other radio button and enter RapidIdentity in the Name field.
Click the Create button and then OK.
Click the Download JSON button to save an offline copy of the Client ID and Client Secret. Make sure it is stored somewhere secure.
A Client ID and Client Secret are needed to create a standard GOOGLE OAuth2 Credential.
Navigate to Google Cloud Platform Console and select the project created above.
Click on the menu button at the top left of the page, and select API Manager.
In the sidebar on the left, select Credentials.
Select Create Credentials tab.
Click the Create credentials button and select Service account key.
In the Service Account drop-down, select New service account.
Enter an appropriate Service account name.
Select the Project -> Service Account Actor role (or if actor role does not exist then 'owner' will work too)
Leave the Service account ID default value
Make sure JSON is selected as the Key type.
Click the Create button and then OK.
A JSON file will be downloaded containing the account information. Make sure it is stored somewhere secure.
Press the close button.
Click the Manage service accounts link.
Click the More actions button in the row corresponding to your newly created service account and select Edit. If that button is not visible you may need to scroll to the right.
Select the Enable G-Suite Domain-wide Delegation checkbox, and press Save.
To authorize the Service Account Key to access a Google domain:
Login to Google Admin Console as a User with Super Admin role.
Click on Security.
Click on Show more.
Click on Advanced settings.
Click on Manage API client access
Open the JSON file that was downloaded when you created the Service Account Key. Copy the value of the client_id field (without the enclosing quotes) and paste into the Client Name field in the browser.
Enter the scopes you want to grant access to, separated by commas, in the One or More API scopes field and press the Authorize button. A list of available scopes is available at: https://developers.google.com/identity/protocols/googlescopes
Additional scopes may be added later by repeating the previous two steps.
You will need an account with Administrator privileges in the domain you want to manage. While you can use the default administrative account, it is usually a good idea to create a separate User and grant the necessary administrative privileges.
Navigate to Connect > OAuth2 Credentials.
Select the project you want the credential associated with or select * to create a credential that may be used by all projects.
Click the Add… button and select GOOGLE.
Give the credential a name (must be unique within the project.)
Enter the Client ID and Client Secret created above in the corresponding fields.
Enter the email address of G-Suite administrator account you wish to use in the Username field.
Review the permissions that will be requested. The default selection represents the permissions that are required for the G-Suite adapter to be fully functional, but if you don't need all the capabilities you may wish to adjust the requested permissions.
Click the Request OAuth Credential button.
Press OK to redirect to Google to authorize the credential.
If necessary, log in to the G-Suite administrator account you entered above.
Review the requested permissions. All the permissions used by the G-Suite adapter are selected by default, but those used by other auxiliary adapters (such as Google Classroom) are not.
You may also add additional desired scopes for use with callGoogleAPI() by pressing the Add Custom... button.
Press the Accept button. You will be sent to a new browser window or tab that may ask you to log in and authorize the credential request.
Select and copy the code from the resulting page.
Switch back to the Connect tab or window, paste the code, and press the OK button.
Navigate to Connect > OAuth2 Credentials.
Select the project you want the credential associated with or select * to create a credential that may be used by all projects.
Click the Add… button and select GOOGLE_EXTENDED.
Give the credential a name (must be unique within the project.)
Open the JSON file you received when you created the Service Account Key and copy and the paste the contents into the Google Service Account JSON field.
Press the Create button.
Insert the defineGoogleOAuthConnection() action.
Enter the domain.
After selecting the credentialName field, select OAuth2 Credential… in the combo box.
Select the desired credential in the dialog and press OK.
Insert the defineGoogleExtendedOAuthConnection() action.
Enter the domain.
After selecting the credentialName field, select OAuth2 Credential… in the combo box.
Select the desired credential in the dialog and press OK.
Enter the Google User ID of the account you wish to use in the impersonateUserId field
Enter an array of scopes to authorize for the connection. The set of scopes must be a subset of those that were authorized for use by the Service Account Key for the domain.
Navigate to Connect > OAuth2 Credentials. Select the credential and press the Delete… button.
KeepnTrack Adapter Actions
Define a connection to a KeepnTrack server.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url of the KeepnTrack REST service |
db* | text, expression, variable | the name of the KeepnTrack database |
username | text, expression, variable | username for authentication to the KeepnTrack REST service |
password | password, string, expression, variable | password for authentication to the KeepnTrack REST service |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
conn = defineKeepnTrackConnection("https://customername.keepntrack.com/
knt.cgi", "customernamedb", "adminuser@customername.net", <Password>)Delete a KeepnTrack Facility Record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
id* | text, expression, variable | the id of the KeepnTrack Facility to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deletedFacility = deleteKeepnTrackFacility(conn, facilityId)
Delete a KeepnTrack Person Record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
id* | text, expression, variable | the id of the KeepnTrack Person to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deletedPerson = deleteKeepnTrackPerson(conn, specificUserID)
Get KeepnTrack Activity Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
filter | text, expression, variable | Example Record or SQL WHERE clause used to filter the Records |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
allActivities = getKeepnTrackActivities(conn)
Get a KeepnTrack Activity Record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
id* | text, expression, variable | the id of the KeepnTrack Activity to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
singleActivity = getKeepnTrackActivity(conn, activityId)
Get KeepnTrack Facility Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
filter | text, expression, variable | Example Record or SQL WHERE clause used to filter the Records |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
allFacilities = getKeepnTrackFacilities(conn)
Get a KeepnTrack Facility Record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
id* | text, expression, variable | the id of the KeepnTrack Facility to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
singleFacility = getKeepnTrackFacility(conn, facilityId)
Get a KeepnTrack Person Record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
id* | text, expression, variable | the id of the KeepnTrack Person to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
personByID = getKeepnTrackPerson(conn, personID)
Get KeepnTrack Person Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
filter | text, expression, variable | example Record or SQL WHERE clause used to filter the Records |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
persons = getKeepnTrackPersons(conn, \'Name_Last="Simpson"\')
Create/Update a KeepnTrack Facility Record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
record* | expression, variable | the Record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
facilityTemplate = createRecord(true)
addRecordFieldValue(facilityTemplate, "FacilityId", "MYFACILITY",
false)
addRecordFieldValue(facilityTemplate, "Name", "Springfield
Elementary School", false)
newfacility = saveKeepnTrackFacility(conn, facilityTemplate)Create/Update a KeepnTrack Person Record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the KeepnTrack connection definition |
record* | expression, variable | the Record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# student personTemplate = createRecord(true) addRecordFieldValue(personTemplate, "Name_First", "Homer", false) addRecordFieldValue(personTemplate, "Name_Last", "Simpson") addRecordFieldValue(personTemplate, "IsStudent", "Y", false) newPerson = saveKeepnTrackPerson(conn, personTemplate) # staff personTemplate = createRecord(true) addRecordFieldValue(personTemplate, "Name_Prefix", "Mr.") addRecordFieldValue(personTemplate, "Name_Suffix", "I", false) addRecordFieldValue(personTemplate, "id", newPerson.id) addRecordFieldValue(personTemplate, "IsStaff", "Y", true) addRecordFieldValue(personTemplate, "Facilities", "1", true) addRecordFieldValue(personTemplate, "Facilities", "3", true) newPerson = saveKeepnTrackPerson(conn, personTemplate)
Required Fields on create: Name_First, Name_Last, and at least one of IsVisitor, IsVolunteer, IsStudent, IsStaff, or IsVendor must be set to 'Y'.
Field | Read-Only | Type | Description |
|---|---|---|---|
Inactive | N | Logical(Y/N) | Whether this record is active or not. Missing means active. |
EffectiveDate | N | Date(yyyy?mm?dd) | The date on which this record takes effect. Missing means “far distant past. |
ExpirationDate | N | Date(yyyy?mm?dd) | The date on which this record expires. Missing means no expiration. |
OnlineAppRecord | Y | Logical(Y/N) | Indicates if this Person record was created as an online application, which are filtered from Person lookup. |
IsVisitor | N | Logical(Y/N) | Specifies whether this person is a visitor. |
IsVolunteer | N | Logical(Y/N) | Specifies whether this person is a volunteer. |
IsStudent | N | Logical(Y/N) | Specifies whether this person is a student. |
IsStaff | N | Logical(Y/N) | Specifies whether this person is a staff member. |
IsVendor | N | Logical(Y/N) | Specifies whether this person is a vendor. |
PersonId | N | Text(24) | Account-assigned, unique identification number. Used for external interfaces. If empty on creation, the server assigns a unique value. |
SignedInCount | Y | Unsigned | The number of times the person is currently signed in. Typically zero (not signed in) or one (signed in). Unimplemented. |
Name_Prefix | N | Text(24) | Prefix to the person’s name. Examples include Ms., Dr., etc. |
Name_First | N | Text(32) | The person’s given name. |
Name_Last | N | Text(32) | The person’s surname name. |
Name_Suffix | N | Text(24) | Suffix to the person’s name. Includes degrees, certifications, and affiliations. |
Address_Organization | N | Text(64) | The name of the organization. |
Address_Line1 | N | Text(64) | The first line of the address. |
Address_Line2 | N | Text(64) | The second line of the address. |
Address_City | N | Text(64) | The address’s city name. |
Address_Region | N | Text(2) | Two-character state or province code. Link to the ‘Region’table. |
Address_Postal_Code | N | Text | The address’s postal code. Not a link. |
Address_Country | N | Text(2) | Two-character country code. Link to the ‘Country’table. |
Address_Residence | N | Logical(Y/N) | Whether this is a resdential mailing address or not. |
Address_Delivery_Instructions | N | Text | Instructions that may be passed along to the delivery person for this address. |
Address_USPS_Validation | N | Logical(Y/N) | Whether USPS address validation has been attempted. |
Address_UPS_Validation | N | Logical(Y/N) | Whether UPS address validation has been attempted. |
Address_USPS_Validated_Address | N | Text(200) | The raw text returned by the USPS validation method. Missing if not validated. |
Address_UPS_Validated_Address | N | Text(200) | The raw text returned by the USPS validation method. Missing if not validated. |
HomePhone | N | Phone Number | The person’s home phone number. |
WorkPhone | N | Phone Number | The person’s work phone number. |
MobilePhone | N | Phone Number | The person’s mobile phone number. |
FaxNumber | N | Phone Number | The person’s fax number. |
EmailAddress | N | Email Recipient List | The person’s email address. |
ConfirmationEmail | N | Email Recipient List | The email address that receives record update confirmation email messages. |
Gender | N | Text(F/M) | The person’s gender. |
Ethnicity | N | Text(16) | The person’s ethnicity. List of values determined from a preference. |
BirthDate | N | Date(yyyy?mm?dd) | The person’s birth date. |
SocialSecurityNumber | N | Text(9) | The person’s social security number. |
PictureURL | Y | URL | The URL of this person's picture, if any. |
CriminalConviction | N | Logical(Y/N) | Has this person been convicted of a crime? |
MedicalReleaseonFile | N | Logical(Y/N) | Does this person have a medical release on file? |
MedicalConditions | N | Text(200) | The known medical conditions for this person. |
EmergencyContact | N | Text(100) | Free-text field containing emergency contact information. |
Notes | N | Text(2500) | Free-text notes for this person. |
CustomField1 | N | Text(200) | A field that may be used for each customer’s specific needs. |
CustomField2 | N | Text(200) | A field that may be used for each customer’s specific needs. |
CustomField3 | N | Text(200) | A field that may be used for each customer’s specific needs. |
CustomField4 | N | Text(200) | A field that may be used for each customer’s specific needs. |
CustomField5 | N | Text(200) | A field that may be used for each customer’s specific needs. |
CustomField6 | N | Text(200) | A field that may be used for each customer’s specific needs. |
CustomField7 | N | Text(200) | A field that may be used for each customer’s specific needs. |
CustomField8 | N | Text(200) | A field that may be used for each customer’s specific needs. |
DriverLicenseState | N | Text(2) | The two-letter postal code for the state issuing this person’s driver license. |
DriverLicenseNumber | N | Text(24) | The person’s driver license number. |
VehicleRegistrationState | N | Text(2) | The two-letter postal code for the state issuing this person’s vehicle registration. |
VehicleRegistration Number | N | Text(12) | This person’s license plate number. |
VehicleMake | N | Text(12) | The make of this person’s vehicle. |
VehicleColor | N | Text(12) | The color of this person’s vehicle. |
VolunteerId | N | Text(24) | For volunteers. Used to store a unique external id for this volunteer. |
VolunteerType | N | Text(32) | For volunteers. The type of this volunteer. List determined from a preference. |
VolunteerHours | Y | Minutes | For volunteers. The total number of volunteer minutes for this person. |
FavoriteActivities | N | Text(1000) | For volunteers. Unused. |
CheckoutAllowed | N | Logical(Y/N) | For students. Is this student permitted to be checked out? |
Grade | N | Text(2) | For students. The grade this student is in. |
Teacher | N | Text(32) | For students. The name of this student’s primary teacher. |
Bus1 | N | Text(12) | For students. This student’s bus number. |
Bus2 | N | Text(12) | For students. This student’s bus number. |
StudentId | N | Text(24) | For students. A value used to link this student to the SIS. |
Family Id | N | Text(24) | For students. A place to store information provided by the SIS. |
StudentHours | Y | Minutes | For students. The number of minutes this person has been checked in as a student. |
Homeroom | N | Text(12) | For students. The homeroom for this student. |
AuthorizedToCheckout | N | Text(1000) | For students. The list of people who are authorized to checkout this student. |
OnStaffDate | N | Date(yyyy?mm?dd) | For staff. The date this person joined the staff. |
StaffId | N | Text(24) | For staff. A place to store information provided by the SIS. |
StaffPosition | N | Text(32) | For staff. Text for the type of position this person holds. List determined from a preference. |
StaffHours | Y | Minutes | For staff. The number of minutes this person has been checked in as staff. |
Employer | N | Text(32) | For vendors. This vendor’s employer contact information. |
VendorHours | Y | Minutes | For vendors. The number of minutes this vendor has been checked in. |
CheckInAllowed | N | Logical(Y/N) | Is this person permitted to check in? |
SecurityApproved | N | Logical(Y/N) | Has this person’s application been reviewed by an outside authority? |
BackgroundCheckDate | N | Date(yyyy?mm?dd) | Date of this person’s most current background check. This background check is performed outside of KeepnTrack. May be missing. |
SexOffenderCheckTime | Y | Time | The time this person was last checked against the sex offender database. |
SexOffenderScore | Y | Unsigned | The score from the most recent sex offender check. Zero if no matches were found. |
SexOffenderResults | Y | Text(1000) | Textual results from the most recent sex offender check. |
CBCOffenderCheckTime | Y | Time | The time this person was last checked against criminal database. Unused. |
CBCOffenderScore | Y | Unsigned | The score from the most recent criminal background check. Zero if no matches were found. Unused. |
CBCOffenderResults | Y | Text(1000) | Textual results from the most recent criminal background check. Unused. |
PrintBadge | N | Logical(Y/N) | Print a badge for this person on check in? |
PersonalMessage | N | Text(250) | Text message to be displayed for this person on check in. |
LoginId | N | Text(24) | An optional login id used by this person to access their information through a web interface. |
Password | N | Password | Paired with the login id. Password authorizing this person to access their information. |
Facilities | N | Id (Multi-value) | The ids of facilities to which this person is affiliated. |
Field | Read-Only | Type | Description |
|---|---|---|---|
FacilityId | N | Text(32) | A short character string identifying the facility. |
Name | N | Text(32) | The name of the facility. |
ContactPerson_Prefix | N | Text(24) | Prefix to the person’s name. Examples include Ms., Dr., etc. |
ContactPerson_First | N | Text(32) | The person’s given name. |
ContactPerson_Last | N | Text(32) | The person’s surname name. |
ContactPerson_Suffix | N | Text(24) | Suffix to the person’s name. Includes degrees, certifications, and affiliations. |
PhoneNumber | N | Phone Number | The main phone number for this facility. |
FaxNumber | N | Phone Number | The fax number for this facility. |
EmailAddress | N | Email Recipient List | The email address for the facility contact person. |
Address_Organization | N | Text(64) | The name of the organization. |
Address_Line1 | N | Text(64) | The first line of the address. |
Address_Line2 | N | Text(64) | The second line of the address. |
Address_City | N | Text(64) | The address’s city name. |
Address_Region | N | Text(2) | Two-character state or province code. Link to the ‘Region’ table. |
Address_PostalCode | N | Postal Code | The address’s postal code. Not a link. |
Address_Country | N | Text(2) | Two-character country code. Link to the ‘Country’ table. |
Address_Residence | N | Logical(Y/N) | Whether this is a resdential mailing address or not. |
Address_DeliveryInstructions | N | Text | Instructions that may be passed along to the delivery person for this address. |
Address_USPSValidation | N | Logical(Y/N) | Whether USPS address validation has been attempted. |
Address_UPSValidation | N | Logical(Y/N) | Whether UPS address validation has been attempted. |
Address_USPSValidatedAddress | N | Text(200) | The raw text returned by the USPS validation method. Nil if not validated. |
Address_UPSValidatedAddress | N | Text(200) | The raw text returned by the USPS validation method. Nil if not validated. |
TimeZone | N | Text(64) | The time zone in which this facility is located. |
ScreenLogoURL | Y | URL | The URL of this accounts screen logo. |
BadgeLogoURL | Y | URL | The URL of this accounts badge logo. |
Field | Read-Only | Type | Description |
|---|---|---|---|
Facility | Y | ID | The facility to which this activity is associated. |
ActivityPerson | Y | ID | The person performing this activity. Applies only to activities for enrolled persons. |
Student | Y | ID | The student on whose behalf these hours should be credited. Not implemented. |
Parent | Y | ID | For a student being checked in or out, the parent who is doing the activity. Not implemented. |
Source | Y | Text(8) | The client from which this Activity originated. Currently either Admin or Kiosk. |
Classification | Y | Text(12) | The major classification for this Activity (e.g, Volunteer, Visitor, Student, Staff.) |
ActivityGroup | Y | Text(32) | Previously, for non-timed activities, the event that triggered this activity (e.g. Activity, Early Dismissal, Late Arrival.) Obsolete. |
ActivityType | Y | Text(32) | The type of activity this record represents. List determined from a preference. |
Destination | Y | Text(32) | Specific location or activity associated with Activity Type. |
TypeandDestination | Y | Text(64) | The text “Type (Destination)” for reporting and badges. |
TransactionType | Y | Text(8) | One of 'Timed', 'In', or 'Out' specifying whether the transaction is timed or untimed. |
StartTime | Y | Time | The time at which this activity started. |
EndTime | Y | Time | The time at which this activity concluded. |
Duration | Y | Minutes | The duration, in minutes, of this activity. |
CheckinStation | Y | ID | Station at which this person checked in. Present only for activities handled by the Kiosk. |
CheckinTime | Y | Time | Time at which this person checked out. Present only for activities handled by the Kiosk. |
CheckoutStation | Y | ID | Station at which this person checked out. Present only for activities handled by the Kiosk. |
CheckoutTime | Y | Time | Time at which this person checked out. Present only for activities handled by the Kiosk. |
Login | Y | ID | For manually entered records, the administrator creating the record. |
PersonId | Y | Text(24) | The Person Id of this Volunteer, Student, or Staff person. Used for sign out lookups. Applies only to enrolled persons. |
PersonName_Prefix | Y | Text(24) | Prefix to the person’s name. Examples include Ms., Dr., etc. |
PersonName_First | Y | Text(32) | The person’s given name. |
PersonName_Last | Y | Text(32) | The person’s surname name. |
PersonName_Suffix | Y | Text(24) | Suffix to the person’s name. Includes degrees, certifications, and affiliations. |
VisitorId | Y | Text(32) | For visitors. The visitor's driver license number or other form of id. |
VehicleMake | Y | Text(24) | For visitors. The visitor's vehicle make and color. |
VehicleRegistration | Y | Text(16) | For visitors. The visitor's vehicle registration number. |
BadgeNumber | Y | Text(8) | A unique number printed on the badge if a badge was printed at sign in. |
JobNumber | Y | Text(32) | For staff. The government-required job number. |
Donation | Y | Currency | The amount of a monetary donation. |
Description | Y | Text(2500) | A textual description of this activity for manually entered records. |
PictureURL | Y | URL | The URL of this person's picture, if any. |
Notes | Y | Text(2500) | Notes, if any, associated with this activity. |
FacilityName | Y | Text | The name of the facility where this activity took place. |
LDAP Adapter Actions
Compare a Record field on the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | expression, variable | the DN of the Record |
fieldName | text, expression, variable | name of the field to be compared |
fieldValue | text, expression, variable | value of the field to be compared |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
mail = "testuser@test.local"
isEqual = compareLDAPField(conn, dn, "mail", mail)
if(isEqual == true) {
log("mail = " + mail)
} else {
log("mail <> " + mail)
}Delete Record from the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | text, expression, variable | the DN of the Record |
recursive | boolean, expression, variable | recursively delete subtree rooted at dn (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
queryExample = createRecord()
setRecordValue(queryExample,"loginDisabled","TRUE")
inactiveRecords = getLDAPRecords(conn,"ou=people,o=data","sub",
"(loginDisabled=TRUE)")
forEach(inactive,inactiveRecords) {
delStatus = deleteLDAPRecord(conn,inactive["@dn"])
if(Boolean(delStatus)) {
log("Deletion Successful!")
} else {
log("Deletion Failed!")
}
}Get changed Records from an Active Directory server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
filter* | text, expression, variable | the search filter expression or an example Record |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
cookie | expression, variable | cookie returned from previous invocation (default: none, which will return all objects) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
cookieFile = "/cookie/studentsAD.cookie"
fileExists = isFile(cookieFile)
if(!fileExists) {
saveToFile(cookieFile, "")
} else {
}
varCookie = loadFileAsBytes(cookieFile)
# getRecords
moreResults = 1
while(moreResults != 0) {
recordChanges = getLDAPADChanges(conn, "OU=People,DC=test,DC=local",
"sub", "(employeeType=Student)", "cn,sn,givenName", varCookie)
moreResults = 0
if(recordChanges) {
log("Count: " + recordChanges.length)
} else {
}
# foreach
forEach(recordChange, recordChanges) {
if(recordChange.objectClass == "cookie") {
saveToFile(cookieFile, recordChange.cookie)
moreResults = Number(recordChange.moreResults)
} else {
record = getLDAPRecord(conn, recordChange['@dn'], "*")
# transformations
if(!record) {
continue()
} else {
log("Name information has changed: " + record.sn + "
" + record.givenName)
}
}
}
}Gets password stored by RapidIdentity password filter from a Record in Active Directory.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | text, expression, variable | the DN of the Record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
password = "password1"
dn = "CN=Test User,OU=People,DC=test,DC=local"
userPwd = getLDAPADPassword(conn, dn)
if(userPwd && userPwd == password) {
log("User has not changed their default password!")
} else {
log("Password has been changed from default.")
}
Get a Record from the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | expression, variable | the DN of the Record |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
resultRecord = getLDAPRecord(conn,"cn=jdoe,ou=people,o=data","givenName")
Get Records from the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
filter* | text, expression, variable | the search filter expression or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: the server maximum) |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
inactiveRecords = getLDAPRecords(conn,"o=data","sub",
"(&(objectclass=inetOrgPerson)(loginDisabled=TRUE))")
log("There are " + inactiveRecords.length + " inactive records.")
Returns the hostname or IP address of the LDAP server being used as the metadirectory.
Property | Value | Description |
|---|---|---|
returnVariable | expression, variable | Name of the variable to be assigned to the return value. |
Example
LDAP = getCurrentLDAPServerAddress() log(LDAP)
Gets universal password from a Record on a Novell eDirectory LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | text, expression, variable | the DN of the Record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
up = getLDAPUniversalPassword(conn, "cn=user1,ou=people,o=data")
log("The password is " + up + ".")Get changed Records from an OpenLDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
logDN* | text, expression, variable | the dn of the accesslog |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
classes | text, expression, variable | comma separated list of classes to return (default: none) |
attributes | text, expression, variable | comma separated list of attributes to check/return (default: all) |
cookie | expression, variable | cookie returned from previous invocation (default: none, which will return all objects) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
cookieFile = "/cookie/studentsOpenLDAP.cookie"
fileExists = isFile(cookieFile)
if(!fileExists) {
saveToFile(cookieFile, "")
} else {
}
varCookie = loadFileAsString(cookieFile)
# getRecords
moreResults = 1
while(moreResults != 0) {
recordChanges = getOpenLDAPChanges(conn, "o=changelog",
"ou=people,ou=data,o=meta", "sub", "inetOrgPerson",
"cn,sn,givenName", varCookie)
moreResults = 0
if(recordChanges) {
log("Count: " + recordChanges.length)
} else {
}
# foreach
forEach(recordChange, recordChanges) {
if(recordChange.objectClass == "cookie") {
saveToFile(cookieFile, recordChange.cookie)
varCookie = recordChange.cookie
moreResults = recordChange.moreResults
} else {
record = getLDAPRecord(conn, recordChange['@dn'], "*")
# transformations
if(!record || record['employeeType'] != "Student") {
continue()
} else {
log("Student record has changed: " + record['@dn'])
log(" Change type: " + recordChange.changeType)
log(" Added attribute values: " + recordChange.added)
log(" Deleted attribute values: " + recordChange.deleted)
}
}
}
}Gets password stored by RapidIdentity password filter from a Record in OpenLDAP.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | text, expression, variable | the DN of the Record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
password = "password1"
dn = "CN=Test User,OU=People,DC=test,DC=local"
userPwd = getOpenLDAPPassword(conn, dn)
if(userPwd && userPwd == password) {
log("User has not changed their default password!")
} else {
log("Password has been changed from default.")
}Get changed Records from an UnboundID-DS server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
classes | text, expression, variable | comma separated list of classes to return (default: none) |
attributes | text, expression, variable | comma separated list of attributes to check/return (default: all) |
cookie | expression, variable | cookie returned from previous invocation (default: none, which will return all objects) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
cookieFile = "/cookie/studentsUnboundId.cookie"
fileExists = isFile(cookieFile)
if(!fileExists) {
saveToFile(cookieFile, "")
} else {
}
varCookie = loadFileAsBytes(cookieFile)
# getRecords
moreResults = 1
while(moreResults != 0) {
recordChanges = getUnboundIDDSChanges(conn,
"ou=people,ou=Accounts,dc=meta", "sub", "inetOrgPerson",
"cn,sn,givenName", varCookie)
moreResults = 0
if(recordChanges) {
log("Count: " + recordChanges.length)
} else {
}
# foreach
forEach(recordChange, recordChanges) {
if(recordChange.objectClass == "cookie") {
saveToFile(cookieFile, recordChange.cookie)
varCookie = recordChange.cookie
moreResults = recordChange.moreResults
} else {
record = getLDAPRecord(conn, recordChange['@dn'], "*")
# transformations
if(!record || record['employeeType'] != "Student") {
continue()
} else {
log("Student record has changed: " + record['@dn'])
log(" Change type: " + recordChange.changeType)
log(" Added attribute values: " + recordChange.added)
log(" Deleted attribute values: " + recordChange.deleted)
}
}
}
}Gets password stored by RapidIdentity password filter from a Record in UnboundIDDS.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | text, expression, variable | the DN of the Record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
password = "password1"
dn = "CN=Test User,OU=People,DC=test,DC=local"
userPwd = getUnboundIDDSPassword(conn, dn)
if(userPwd && userPwd == password) {
log("User has not changed their default password!")
} else {
log("Password has been changed from default.")
}Modify a Record on the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | expression, variable | the DN of the Record |
removeRecord | expression, variable | a Record containing attributes/values to be removed |
addRecord | expression, variable | a Record containing attribute values to be added |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
addRecord = createRecord()
removeRecord = createRecord()
setRecordFieldValue(addRecord, "objectClass", "customObjectClass")
addRecordField(removeRecord, "telephoneNumber")
dn = "cn=Test User,ou=People,o=test"
result = modifyLDAPRecord(conn, dn, removeRecord, addRecord)
if(result) {
log("Record modified - Added " + addRecord)
log("Record modified - Removed " + removeRecord)
} else {
log("Record not modified - " + dn)
Open a connection to an LDAP server.
Property | Value | Description |
|---|---|---|
ldapHost* | text, expression, variable | the host name or IP address of the LDAP server |
ldapPort | expression, variable | the TCP port of the LDAP server (default: 636 if using SSL, 389 otherwise.) |
useSSL | boolean, expression, variable | use SSL/TLS (default: false.) |
userDn | text, expression, variable | the user DN for authenticating to the LDAP server |
password | password, string, expression, variable | the user password for authenticating to the LDAP server |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
extraProperties | expression, variable | Defined below as applicable |
Property | Description |
|---|---|
abandonOnTimeout | Indicates whether the LDAP SDK should attempt to abandon any request for which no response is received in the maximum response timeout period |
captureConnectStackTrace | Indicates whether the LDAP SDK should capture a thread stack trace for each attempt made to establish a connection |
useKeepAlive | Indicates whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections |
useTCPNoDelay | Indicates whether to use the TCP_NODELAY option for the underlying sockets used by associated connections |
followReferrals | Indicates whether associated connections should attempt to follow any referrals that they encounter |
usePassiveSSLSocketVerifier | If true, corresponds to RapidIdentity setting a |
Property | Description |
|---|---|
connectTimeoutMillis | The maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up |
useLinger | The SO_LINGER timeout for the underlying sockets used by associated connections |
referralHopLimit | The maximum number of hops that a connection should take when trying to follow a referral |
responseTimeoutMillis | The maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server |
Example
conn = openLDAPConnection("server1.company.com","636",true,
"cn=admin,o=company","password")
if(outputLDAP) {
log("LDAP connection successful!")
} else {
log("LDAP connection failed!")
}Open a connection to the MetaDirectory LDAP in scenarios where a Cloud Tenant's SharedGlobals.properties file is not populated in RapidIdentity Cloud versions 2021.4.9 or higher
Property | Value | Description |
|---|---|---|
Assign To | Expression | Choose the variable type to assign the action to |
Example
Input Parameters:
{
sessionMeta = openMetadirLDAPConnection()
if (sessionMeta) {
log("Connection to MetaDirectory was successful: " + sessionMeta, "DEBUG")
} else {
log("Connection to Metadirectory failed: " + sessionMeta, "ERROR")
}
if (sessionMeta) {
close(sessionMeta)
} else {
}
}Open Change Iterator for OpenLDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
logDN* | text, expression, variable | the dn of the accesslog |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
classes | text, expression, variable | comma separated list of classes to return (default: none) |
attributes | text, expression, variable | comma separated list of attributes to check/return (default: all) |
cookieFile* | text, expression, variable | path to file to load/save cookie |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
cookieFile = "/cookie/studentsOpenLDAP.cookie"
recordChanges = openOpenLDAPChangeIterator(conn,
"o=changelog", "ou=people,ou=data,o=meta", "sub",
"inetOrgPerson", "cn,sn,givenName", cookieFile)
forEach(recordChange, recordChanges) {
record = getLDAPRecord(conn, recordChange['@dn'], "*")
# transformations
if(!record || record['employeeType'] != "Student") {
continue()
} else {
log("Student record has changed: " + record['@dn'])
log(" Change type: " + recordChange.changeType)
log(" Added attribute values: " + recordChange.added)
log(" Deleted attribute values: " + recordChange.deleted)
}
}Open Record Iterator for OpenLDAP server to sort large sets of records.
Property | Value | Description |
|---|---|---|
filter* | text, expression, password, variable | the search filter expression or an example record |
pageSize | expression, variable | the preferred number of records to fetch at a time from LDAP server. (default: 100) |
attributes | text, expression, password, variable | comma-separated list of attributes to check/return (default: none) |
sortKey | text, expression, password, variable | comma-separated list of attributes to use as sort keys, with optional +/- to indicate sort direction. (default: unsorted) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
sessionLDAP = openLDAPConnection("10.100.70.28", "636", true,
"cn=doc-admin,ou=users,ou=system,o=meta",<Password>)
# Record Iterator
i = 0
recordChanges = openLDAPRecordIterator(sessionLDAP,
"ou=students,ou=people,ou=data,o=meta", "sub",
"(employeeType=Student)","cn")
recordIterator: forEach(recordChange, recordChanges) {
log(recordChanges)
i = i + 1
if(i >= 30) {
break(recordIterator)
} else {
}
}
# Close
close(sessionLDAP)Open Change Iterator for an UnboundID-DS server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
baseDn* | text, expression, variable | the search base dn |
scope* | choice (sub, one, base), text, expression, variable | the search scope |
classes | text, expression, variable | comma separated list of classes to return (default: none) |
attributes | text, expression, variable | comma separated list of attributes to check/return (default: all) |
cookieFile* | text, expression, variable | path to file to load/save cookie |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
cookieFile = "/cookie/studentsUnboundId.cookie"
recordChanges = openUnboundIDDSChangeIterator(conn,
"ou=people,ou=data,o=meta", "sub", "inetOrgPerson",
"cn,sn,givenName", cookieFile)
forEach(recordChange, recordChanges) {
record = getLDAPRecord(conn, recordChange['@dn'], "*")
# transformations
if(!record || record['employeeType'] != "Student") {
continue()
} else {
log("Student record has changed: " + record['@dn'])
log(" Change type: " + recordChange.changeType)
log(" Added attribute values: " + recordChange.added)
log(" Deleted attribute values: " + recordChange.deleted)
}
}Rename and/or move object on the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
oldDn* | text, expression, variable | the original DN of the object |
newDn* | text, expression, variable | the new DN of the object |
keepOldRdn* | boolean, expression, variable | preserve that attribute values used by the old dn (default: false.) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
oldDN = "cn=jdoe,ou=people,o=data"
newDN = "cn=xjdoe,ou=inactive,ou=people,o=data"
renameResult = renameLDAPRecord(conn, oldDN,newDN,false)
if(renameResult) {
log(LDAP object rename successful!)
} else {
log(LDAP object rename failed!)
}
Save a Record to the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
record* | expression, variable | the Record to save - must contain the dn in the @dn field |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
myRecord = createRecord()
setRecordFieldValue(myRecord,"@dn", "cn=jdoe,ou=people,o=data")
setRecordFieldValue(myRecord,"objectclass", "inetOrgPerson")
setRecordFieldValue(myRecord,"givenName", "John")
setRecordFieldValue(myRecord,"sn", "Doe")
saveResult = saveLDAPRecord(conn, myRecord)
if(Boolean(saveResult)) {
log("Save Successful!")
} else {
log("Save Failed!")
}Sets password on a Record on the LDAP server.
Property | Value | Description |
|---|---|---|
ldapConnection* | expression, variable | the LDAP connection |
dn* | text, expression, variable | the DN of the Record |
password* | password, string, expression, variable | the password |
oldPassword | password, string, expression, variable | the old password (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = setLDAPPassword(conn, "cn=user1,cn=Users,dc=acme,dc=org",
<password>)# Input from text file
textInput = openDelimitedTextInput("/root/senators.csv",
"LastName,FirstName,Title,Email,Phone,Description")
# Open LDAP connection (SSL)
outputLDAP = openLDAPConnection("ldap.company.com",true,"cn=admin,o=company",
"P@ssw0rD")
# Loop through input records
forEach(inputRecord,textInput) {
# Schema mapping
renameRecordFields(inputRecord, "LastName, FirstName, Title, Email, Phone",
"sn, givenName, title, mail, telephoneNumber")
cn = inputRecord['givenName'].substr(0,1) + inputRecord['sn']
setRecordValue(inputRecord,"@dn","cn=" + cn + ",ou=people,o=data")
# Check for existance in target
queryRecord = createRecord()
setRecordFieldValue(queryRecord,"cn",cn)
matchingRecords = getLDAPRecords(outputLDAP,"ou=people,o=data","sub",queryRecord)
if(matchingRecords.length == 1) {
# Match found. Add DN to current record from source.
matchingKeyValue = getRecordFieldValue(matchingRecords[0],"@dn")
setRecordFieldValue(inputRecord,"@dn",matchingKeyValue)
} else {
# No match found. Add new object.
setRecordValue(inputRecord,"objectclass","inetorgperson")
setRecordValue(inputRecord,"userPassword",inputRecord['sn'])
}
# Write (add/modify) record to LDAP
saveLDAPRecord(outputLDAP,inputRecord)
}
# Close LDAP and file connections
close(outputLDAP)
close(textInput)MackinVIA Adapter Actions
Define a connection to a MackinVIA Server.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the Base URL of the MackinVIA REST service |
apiUsername* | text, expression, variable | API userName for authentication to the MackinVIA REST service |
apiKey* | password, string, expression, variable | Secret key for authentication to the MackinVIA REST service |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.MackinURL = "https://dss.mackinvia.com/"
Global.MackinApiUser = "MyMackinAdmin"
Global.MackinApiKey = <password>
conn = defineMackinVIAConnection(Global.MackinURL,
Global.MackinApiUser, Global.MackinApiKey)Delete a given MackinVIA User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the MackinVIA connection definition |
accountID* | text, expression, variable | The accountID of the User |
userName* | text, expression, variable | The userName of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteMackinVIAUser(conn, Global.MackinAccountId, username)
Get a given MackinVIA User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the MackinVIA connection definition |
accountID* | text, expression, variable | The accountID of the User |
userName* | text, expression, variable | The userName of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userRecord = getMackinVIAUser(conn, Global.MackinAccountId, username)
Get MackinVIA Users.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the MackinVIA connection definition |
accountID* | text, expression, variable | The accountID of the s |
lastNamePrefix | text, expression, variable | Lastname prefix of Users |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userRecords = getMackinVIAUsers(conn, Global.MackinAccountId, "Jones")
Move a given MackinVIA User to a different Account.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the MackinVIA connection definition |
accountID* | text, expression, variable | The original accountID of the User |
userName* | text, expression, variable | The userName of the User |
newAccountID* | text, expression, variable | The new accountID of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
moved = moveMackinVIAUser(conn, Global.MackinAccountId, username,
Global.OtherMackinAccountId)Rename a given MackinVIA User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the MackinVIA connection definition |
accountID* | text, expression, variable | The accountID of the User |
userName* | text, expression, variable | The original userName of the User |
newUserName* | text, expression, variable | The new userName of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
renamed = renameMackinVIAUser(conn, Global.MackinAccountId,
username, newUsername)Create or update a given MackinVIA User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the MackinVIA connection definition |
record* | expression, variable | the User record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userTemplate = createRecord(false) setRecordFieldValue(userTemplate, "accountID", Global.MackinAccountId) setRecordFieldValue(userTemplate, "userName", username) setRecordFieldValue(userTemplate, "password",<Password>) created = saveMackinVIAUser(conn, userTemplate)
Supported MackinVIA User Record Fields
Field | Read-Only | Description |
|---|---|---|
accountID | Y | the account id of the school or organization the user is associated with |
userName | N | the user name of the User (required for create) |
password | N | the User password (required for create / write-only) |
lastName | N | the last name of the User |
firstName | N | the first name of the User |
middleName | N | the middle name of the User |
active | N | “True” if the User is active, “False” otherwise |
emailAddress | N | the email address of the User |
Notes Adapter Actions
Enter a request in the Administration Requests database to delete a Notes Group.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
name* | text, expression, variable | the name of the Group to delete |
immediate | boolean, expression, variable | delete Group from Domino Directory immediately (default: false) |
deleteWindowsGroup | boolean, expression, variable | also delete the corresponding Windows Group (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = adminpDeleteNotesGroup(sessionNotes, "cn=server1/o=org",
"MyGroup", true)Enter a request in the Administration Requests database to delete a Notes User.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
name* | text, expression, variable | the full hierarchical name of the Notes User to delete |
immediate | boolean, expression, variable | delete Notes User from Domino Directory immediately (default: false) |
mailFileAction* | choice (DELETE_ALL, DELETE_HOME, DELETE_NONE), text, expression, variable | disposition of the Notes User's mail file |
denyGroup | text, expression, variable | name of an existing deny access group to which the name of the Notes User is added (default: none) |
deleteWindowsUser | boolean, expression, variable | also delete the corresponding Windows User (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = adminpDeleteNotesUser(sessionNotes, "cn=server1/o=org",
"John Doe", true, "DELETE_HOME", false)Enter a request in the Administration Requests database to move a Notes User's mail file.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | the full hierarchical name of the Notes User to be moved |
newHomeServer* | text, expression, variable | the name of the new home mail server |
newHomeServerMailPath* | text, expression, variable | the path of the mail file on the new home mail server |
useSCOS | boolean, expression, variable | the new mail file makes use of the shared mail feature (default: false) |
newClusterReplicas | expression, variable | array of cluster replica server names and paths (e.g. [server1, server1Path, ....]) |
deleteOldClusterReplicas | boolean, expression, variable | delete old cluster replicas (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = adminpMoveNotesMailUser(sessionNotes, "cn=server1/o=org",
"John Doe", "cn=server2/o=org", "/local/notesdata/jdoe.id",
false, false, false)Enter a request in the Administration Requests database to move a Notes User's roaming files to another server.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | the full hierarchical name of the Notes User to be moved |
newServer* | text, expression, variable | the new roaming server |
newServerSubdir* | text, expression, variable | the new path on the roaming server |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpMoveNotesRoamingUser(sessionNotes,
"cn=server1/o=org", "John Doe", "cn=server2/o=org",
"/local/notesdata/roaming/jdoe")Enter requests in the Administration Requests database to move and optionally rename a Notes User's name in the hierarchy.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | the current full hierarchical name of the Notes User to be moved |
oldCertifier* | expression, variable | the current Certifier (defined with defineNotesCertifier) |
newCertifier* | expression, variable | the new Certifier (defined with defineNotesCertifier) |
newLastName | text, expression, variable | the new last name if Notes User is also to be renamed (default: no change) |
newFirstName | text, expression, variable | the new first name if Notes User is also to be renamed (default: no change) |
newMiddleInitial | text, expression, variable | the new middle initial if Notes User is also to be renamed (default: no change) |
newOrgUnit | text, expression, variable | the new org unit if Notes User is also to be renamed (default: no change) |
newAltCommonName | text, expression, variable | the new alternate common name if Notes User is also to be renamed (default: no change) |
newAltOrgUnit | text, expression, variable | the new alternate org unit if Notes User is also to be renamed (default: no change) |
newAltLanguage | text, expression, variable | the new alternate language if Notes User is also to be renamed (default: no change) |
renameWindowsUser | boolean, expression, variable | also rename the corresponding Windows Notes User (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpMoveNotesUserInHierarchy(sessionNotes,
"cn=server1/o=org", "John Doe", cert1, cert2, "movetest")Enter a request in the Administration Requests database to recertify a Notes User.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | the full hierarchical name of the Notes User to be recertified |
certifier* | expression, variable | the Certifier (defined with defineNotesCertifier) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpRecertifyNotesUser(sessionNotes, "cn=server1/o=org",
"John Doe", cert1)Enter a request in the Administration Requests database to rename a Notes Group.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
oldName* | text, expression, variable | the current Notes Group name |
newName* | text, expression, variable | the new Notes Group name |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpRenameNotesGroup(sessionNotes, "cn=server1/o=org",
"MyGroup, "YourGroup")Enter a request in the Administration Requests database to rename a Notes User.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | the current full hierarchical name of the Notes User to be renamed |
certifier* | expression, variable | the Certifier (defined with defineNotesCertifier) |
newLastName | text, expression, variable | the new last name (default: no change) |
newFirstName | text, expression, variable | the new first name (default: no change) |
newMiddleInitial | text, expression, variable | the new middle initial (default: no change) |
newOrgUnit | text, expression, variable | the new org unit (default: no change) |
newAltCommonName | text, expression, variable | the new alternate common name (default: no change) |
newAltOrgUnit | text, expression, variable | the new alternate org unit (default: no change) |
newAltLanguage | text, expression, variable | the new alternate language (default: no change) |
renameWindowsUser | boolean, expression, variable | also rename corresponding Windows User (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpRenameNotesUser(sessionNotes, "cn=server1/o=org",
"John Doe", cert1, "Doh", "Jack")Enter a request in the Administration Requests database to rename a Notes Web User.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | the current full hierarchical name of the Notes User to be renamed |
newFullName | text, expression, variable | the new full hierarchical name (default: no change) |
newLastName | text, expression, variable | the new last name (default: no change) |
newFirstName | text, expression, variable | the new first name (default: no change) |
newMiddleInitial | text, expression, variable | the new middle initial (default: no change) |
newShortName | text, expression, variable | the new short name (default: no change) |
newInternetAddress | text, expression, variable | the new internet address (default: no change) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpRenameNotesWebUser(sessionNotes, "cn=server1/o=org",
"John Doe", "Jack Doh", "Doh", "Jack")Enter a request in the Administration Requests database to change the password management settings of a Notes User.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | the full hierarchical name of the Notes User to be renamed |
notesPasswordCheckSetting | choice(CHECK,DONTCHECK,LOCKOUT), text, expression, variable | the check password setting (default: no change) |
notesPasswordChangeInterval | expression, variable | the password change required interval (default: no change) |
notesPasswordGracePeriod | expression, variable | the password change grace period (default: no change) |
internetPasswordForceChange | boolean, expression, variable | force the user to change the password on next login (default: no change) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpSetNotesUserPasswordSettings(sessionNotes,
"cn=server1/o=org", "John Doe", ""LOCKOUT")Enter a request in the Administration Requests database to upgrade a Notes User from a flat ID to a hierarchical ID.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
adminpServer | text, expression, variable | the name of the server hosting the AdminP process (default: the agent server) |
username* | text, expression, variable | current username |
certifier* | expression, variable | the Certifier (defined with defineNotesCertifier) |
newOrgUnit | text, expression, variable | the new org unit |
newAltCommonName | text, expression, variable | the new alternate common name |
newAltOrgUnit | text, expression, variable | the new alternate org unit |
newAltLanguage | text, expression, variable | the new alternate language |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = adminpUpgradeNotesUserToHierarchical(sessionNotes,
"cn=server1/o=org", "John Doe", cert1)Build a notes FullName.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
certifier* | expression, variable | the Certifier (defined with defineNotesCertifier) |
lastName* | text, expression, variable | the last name |
firstName | text, expression, variable | the first name |
middleInitial | text, expression, variable | the middle initial |
ou | text, expression, variable | additional OU beyond the certifier |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Note
fullName = buildNotesFullName(sessionNotes, cert1, "Doe", "John")
Compare the HTTPPassword field for a Notes Record.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
db* | text, expression, variable | the database name |
unid* | text, expression, variable | the UNID of the record |
password* | password, string, expression, variable | the password |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
passwordsEqual = compareNotesHTTPPassword(sessionNotes, "names",
userRecord['@UNID'], <Password>)Define a connection to a Notes Agent.
Property | Value | Description |
|---|---|---|
host* | text, expression, variable | the host name or ip address of the Domino server hosting the RapidIdentity Notes Agent |
port | expression, variable | the https port of the Domino server hosting the RapidIdentity Notes Agent (default: 443) |
adminUser* | text, expression, variable | the login name of Notes administrative User |
password* | password, string, expression, variable | the password for adminUser |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.notesAgentServer = "mynotesserver"
Global.notesAdminUser = "administrator"
Global.notesAdminPwd = <Password>
sessionNotes = defineNotesAgentConnection(Global.notesAgentServer,
Global.notesAdminUser,<Password>)
Define Notes certifier.
Property | Value | Description |
|---|---|---|
certifierName* | text, expression, variable | the name of the notes certifier (e.g. o=myorg) |
certifierIDFile | text, expression, variable | the full path on the agent server of idfile for the notes certifier (default: none, use Certificate Authority instead) |
certifierPassword | password, string, expression, variable | the password for certifierIDFile (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
cert0 = defineNotesCertifier("o=org", "/local/notesdata/org.id",
<Password>)
cert1 = defineNotesCertifier("ou=orgunit1/o=org",
"/local/notesdata/orgunit1.id",<Password>)
cert2 = defineNotesCertifier("ou=orgunit2/o=org",
"/local/notesdata/orgunit2.id",<Password>)
Delete an existing Notes Record.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
db* | text, expression, variable | the database name |
unid* | text, expression, variable | the UNID of the record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
status = deleteNotesRecord(sessionNotes, "mytestdb", record['@UNID'])
Get an existing Notes Record.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
db* | text, expression, variable | the database name |
unid* | text, expression, variable | the UNID of the record |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
group = getNotesRecord(sessionNotes, "names", record['@UNID'], "+")
Get Notes Records.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
db* | text, expression, variable | the database name |
filter | text, expression, variable | the search filter formula (default: all records) |
maxResults | expression, variable | maximum number of Records to return (default: the server maximum) |
attributes | text, expression, variable | comma separated list of attributes to return (default: none) |
since | expression, variable | Date object - return only records created or modified since (default: none) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
people = getNotesRecords(sessionNotes, "names", 'Type="Person"', 5)
Parse a Notes name.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
name* | text, expression, variable | the name to parse |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
parsedUsernameRecord = parseNotesName(sessionNotes, username)
Registers a new Notes User.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
record* | expression, variable | Record containing the registration properties |
certifier* | expression, variable | the Certifier (defined with defineNotesCertifier) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userTemplate = createRecord() setRecordFieldValue(userTemplate, "FirstName", "John") setRecordFieldValue(userTemplate, "LastName", "Doe") setRecordFieldValue(userTemplate, "IdFile", "/local/notesdata/JohnDoe.id") setRecordFieldValue(userTemplate, "Password",<Password>) setRecordFieldValue(userTemplate, "MailServer", "cn=server1/o=org") setRecordFieldValue(userTemplate, "MailDBPath", "mail/JohnDoe") setRecordFieldValue(userTemplate, "MailSystem", 1) user1 = registerNewNotesUser(sessionNotes, userTemplate, cert1)
Create or update a Notes Record.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
db* | text, expression, variable | the database name |
record* | expression, variable | the Record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupTemplate = createRecord() setRecordFieldValue(groupTemplate, "ListName", "Group1") setRecordFieldValue(groupTemplate, "Type", "Group") setRecordFieldValue(groupTemplate, "Form", "Group") setRecordFieldValue(groupTemplate, "LocalAdmin", "LocalDomainAdmins") setRecordFieldValue(groupTemplate, "Members", username1) addRecordFieldValue(groupTemplate, "Members", username2, true) group = saveNotesRecord(sessionNotes, "names", groupTemplate)
Send a console command to a Domino server.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
server | text, expression, variable | the name of the target server |
cmd* | text, expression, variable | the console command |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
sent = sendNotesConsoleCommand(sessionNotes, "tell adminp process all")
Set the HTTPPassword field for a Notes Record.
Property | Value | Description |
|---|---|---|
notesConnection* | expression, variable | the Notes Agent connection |
db* | text, expression, variable | the database name |
unid* | text, expression, variable | the UNID of the record |
password* | password, string, expression, variable | the password |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
passwordSet = setNotesHTTPPassword(sessionNotes, "names",
userRecord['@UNID'],<Password>)Notes databases do not have a fixed schema, but rather any record can have pretty much any field that conforms to the field naming restrictions imposed by Notes. Fields that start with $ are usually considered reserved or system fields and the adapter currently treats them as read-only. Each record also has metadata that is not stored as a field in the database and are available as read-only on any record. This metadata is represented in the adapter as fields that start with @.
Name | Type | Description |
|---|---|---|
@UNID | String | The Universal ID of the record |
@CREATED | Date | The creation timestamp |
@MODIFIED | Date | The modification timestamp |
@AUTHORS | String(s) | Names of those who have edited the record |
The @UNID field will be included in all records returned by getNotesRecord() and getNotesRecords(). The other @ fields will only be returned if explicitly specified the attribute list or the attribute list is “+”. When calling saveNotesRecord(), a record that contains @UNID will be considered to be an update, whereas one without @UNID will create a new record in the database.
When searching using getNotesRecords(), you may specify a filter expression using Notes Formula Language which is similar to the expressions used in Lotus 1-2-3 spreadsheets and provides very powerful selection capabilities.
While any record can have pretty much any field, the Form field associates the record with a Notes form definition which includes a predefined set of fields and rules for what can or must in each defined field. A database can also have a default form that applies to records that don't have an explicitly specified Form. Whenever the adapter saves a record, it asks Notes to apply any applicable form validation before it saves the record. In this respect a form definition can be thought of a kind of schema. As part of that validation, Notes may add fields, changes fields, or reject the save altogether if any validation requirements are not met. The easiest way to get a list of the fields that a form supports is to open a record that uses the given form in Notes or Domino Administrator, right click on the record, select Document Properties, and then select the second tab of the little dialog that pops up. Another way would be to use getNotesRecords() with filter = 'Form = “xxx”' and maxResults = 1 and log the results.
In Notes, Users and Groups live in what is known both as the Domino Directory and the Public Address Book, which is a database usually called “names”.
A User is associated with the Person form and has an associate ID file, and usually an associated mail file. While it a possible to create a Person record directly using saveNotesRecord(), in order to create a User (as opposed to e.g. a contact), you must use registerNewNotesUser(), which can also create and certify the User's ID file, and optionally create the User's mail file. There are also several operations on Users, such as rename, move, delete, etc., that must be performed via the adminpXXX() family of actions. Failure to do so will result in inconsistencies in Notes.
A Group is associated with the Group form. Unlike Users, Groups are created directly using saveNotesRecord(), but like Users, renaming and deleting groups must be performed via the adminpXXX() family of actions. Failure to do so will result in inconsistencies in Notes.
Name | Type | Description |
|---|---|---|
AltFullName | String | (default: none) An alternate User name |
AltFullNameLanguage | String | (default: none) The language for the alternate User name |
AltOrgUnit | String(s) | (default: none) Alternate name(s) for the organizational unit to use when creating ID files |
AltOrgUnitLang | String(s) | (default: none) Languages associated with the alternate name(s) for the organizational unit to use when creating ID files |
CreateMailDBInBackground | Boolean | (default: false) Create mail database in the background (via AdminP) |
EnforceUniqueShortName | Boolean | (default: true) Indicates whether a short name must be unique |
Expiration | Date | (default: system default) The expiration date to use when creating ID file |
FirstName | String | (default: blank) A first name for the User |
ForeignDN | String | (default: none) A foreign DN for the User |
ForwardDomain | String | (default: none) The forwarding domain for the user's mail file |
FullName | String | (default: calculated from other fields) |
GroupList | String(s) | (default: none) The Groups(s) to which the User is assigned during registration |
IDType | Number | (default: 173) The type of ID file to create 171 → FLAT, 172 → HIERARCHICAL, 173 → SAME AS CERTIFIER |
IdFile | String | (default: none) The ID file to be created; specify the complete path, for example, c:\notes\data\user.id |
LastName | String | (default: blank) A last name for the User to be registered |
Location | String | (default: none) A value for the location field in the Domino Directory record |
MailACLManager | String | (default: none) A name that is assigned Manager access in the mail database ACL |
MailCreateFTIndex | Boolean | (default: false) Indicates the creation of a full-text index for the mail database |
MailDBPath | String | (default: none) The path of the User's mail file relative to the data directory, e.g. “mail\jones.nsf” |
MailInternetAddress | String | (default: blank) The user's Internet name for sending and receiving mail |
MailOwnerAccess | Number | (default: 0) The mail database ACL setting for the owner 0 → Manager, 1 → Designer, 2 → Editor |
MailQuotaSizeLimit | Number | (default: no limit) The maximum size of the user's mail database, in megabytes. |
MailQuotaWarningThreshold | Number | (default: no limit) The size, in megabytes, at which the user's mail database issues a warning that it is getting too large |
MailReplicaServers | String(s) | (default: none) The names of servers to which the mail database will replicate. |
MailServer | String | (default: none) The canonical name of the server containing the User's mail file |
MailSystem | String | (default: 0) The user's mail system 0 → Notes, 1 → POP, 2 → IMAP, 3 → INotes, 4→ Internet, 5 → Other, 6 → None |
MailTemplateName | String | (default: system default) The name of the template for the design of the mail file |
MiddleInitial | String | (default: blank) A middle initial for the User |
MinPasswordLength | Number | (default: system default) The strength assigned to a password in an ID file |
NorthAmerican | Boolean | (default: system default) Indicates whether an ID file is North American |
OrgUnit | String | (default: none) The organizational unit to use when creating ID file |
Password | String | (default: none) Password for the user ID file |
PolicyName | String | (default: none) The name of an explicit policy |
PublicKeySize | Number | (default: system default) Size of the public key when creating ID file 630, 1024, 2048 |
RegistrationLog | String | (default: “certlog.nsf”) The log file to use when creating ID |
RegistrationServer | String | (default: the agent server) The server to use when creating ID and performing other registration functions |
RoamingCleanupPeriod | Number | (default: none) The interval in days for cleaning up data on Notes clients set up for roaming users - only needed when RoamingCleanupSetting == 1 |
RoamingCleanupSetting | String | (default: 0) Indicates the clean-up process for data on Notes clients set up for roaming users 0 → NEVER, 1 → EVERY_NDAYS, 2 → AT_SHUTDOWN, 3 → PROMPT |
RoamingServer | String | (default: none) The server on which the user's roaming data is stored |
RoamingSubdir | String | (default: none) The subdirectory that contains the user's roaming data |
RoamingUser | Boolean | (default: false) Indicates whether a user is a roaming user |
ShortName | String | (default: calculated from other fields) The short name when creating user ID |
StoreIDInAddressBook | Boolean | (default: true) Indicates whether the ID file is stored in the Address Boook |
StoreIDInMailFile | Boolean | (default: false) Indicates whether the ID file is stored in the user's mail file |
SynchInternetPassword | Boolean | (default: true) Synchronizes the user's Internet password with the password for the Notes client ID. |
UpdateAddressBook | Boolean | (default: true) Indicates whether an ID document in the Domino Directory is created when the ID file is created |
The Administration Process (AdminP) is a facility that runs on the Domino Server and handles complex tasks that involve possibly many steps, such as moving, renaming, or deleting Users and Groups. These tasks are considered complex because them may involve fixing up or removing references to the User or Group across the Notes infrastructure as well as performing tasks outside of the database such as deleting or moving other files. You make requests to AdminP via one of the actions prefixed with adminP.
Unlike direct Record access, requests to AdminP expect Users and Groups to be identified by name rather than by @UNID. The name for a User can be found as the first value of the FullName field and the name for a Group can be found as the first value of the ListName field.
Requests to AdminP are processed asynchronously after the action returns, so subsequent operations on the User or Group usually will need to be delayed until AdminP has finished processing the request. AdminP normally only wakes up periodically to process its queue of requests, but you can use a console command to tell AdminP to process new requests immediately:
sendNotesConsoleCommand("tell adminp process new")Note that many requests happen in multiple phases so waking up AdminP may only start the first step of the process, with each subsequent step happening one at a time each time adminp runs through its queue.
Office 365 Adapter Actions
The list of filterable attributes can be found here.
Add a member to an Office 365 DistributionGroup
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
groupIdentity* | text, expression, variable | the identity of the DistributionGroup |
memberIdentity* | text, expression, variable | the identity of the object to add to the DistributionGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
added = addOffice365DistributionGroupMember(session, "testgroup",
"johndoe@example.com")Add a member to an Office 365 MsolGroup
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
groupIdentity* | text, expression, variable | the identity of the MsolGroup |
memberIdentity* | text, expression, variable | the identity of the object to add to the MsolGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
added = addOffice365MsolGroupMember(session, "testgroup@example.com",
"johndoe@example.com")Add a member to an Office 365 MsolRole
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
groupIdentity* | text, expression, variable | the identity of the MsolRole |
memberIdentity* | text, expression, variable | the identity of the object to add to the MsolRole |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord()
setRecordFieldValue(filter, "RoleName" "User Account Administrator")
roles = getOffice365MsolRoles(session, filter, 1)
added = addOffice365MsolGroupMember(session, roles[0].ObjectId,
"johndoe@example.com")Add a member to an Office 365 SharePoint Online Site Group
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
site* | text, expression, variable | the url of the SharePoint Online Site |
groupIdentity* | text, expression, variable | the name of the SPOSiteGroup |
memberIdentity* | text, expression, variable | the login name of the object to add to the SPOSiteGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
added = addOffice365SPOSiteGroupMember(session,
"https://example.sharepoint.com/", "MySiteGroup",
"JohnDoe@example.com")Delete an Office 365 DistributionGroup record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 DistributionGroup to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365DistributionGroup(session, "testgroup")
Delete a member from an Office 365 DistributionGroup.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
groupIdentity* | text, expression, variable | the identity of the DistributionGroup |
memberIdentity* | text, expression, variable | the identity of the object to delete from the DistributionGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
removed = deleteOffice365DistributionGroupMember(session,
"testgroup@example.com", "jdoe@example.com")Delete an Office 365 Mailbox record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 Mailbox to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365Mailbox(session, "jdoe@example.com")
Delete an Office 365 MailContact record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MailContact to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365MailContact(session, "testContact")
Delete an Office 365 MailUser record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MailUser to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365MailUser(session, "testMailUser@example.com")
Delete an Office 365 MsolGroup record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MsolGroup to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365MsolGroup(session, "testgroup@example.com")
Delete a member from an Office 365 MsolGroup.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
groupIdentity* | text, expression, variable | the identity of the MsolGroup |
memberIdentity* | text, expression, variable | the identity of the object to delete from the MsolGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365MsolGroupMember(session,
"testgroup@example.com", "jdoe@example.com")Delete a member from an Office 365 MsolRole.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
groupIdentity* | text, expression, variable | the identity of the MsolRole |
memberIdentity* | text, expression, variable | the identity of the object to delete from the MsolRole |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord()
setRecordFieldValue(filter, "RoleName" "User Account Administrator")
roles = getOffice365MsolRoles(session, filter, 1)
deleted = deleteOffice365MsolGroupMember(session, roles[0].ObjectId,
"jdoe@example.com")Delete an Office 365 MsolUser record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MsolUser to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365MsolUser(session, "jdoe@example.com")
Delete an Office 365 SharePoint Online Site Group record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
site* | text, expression, variable | the url of the SharePoint Online Site |
identity* | text, expression, variable | the name of the Office 365 SharePoint Online Site Group to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365SPOSiteGroup(session,
"https://example.sharepoint.com/", "MySiteGroup")Delete a member from an Office 365 SharePoint Online Site Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
site* | text, expression, variable | the url of the SharePoint Online Site |
groupIdentity* | text, expression, variable | the name of the SPOSiteGroup |
memberIdentity* | text, expression, variable | the login name of the object to delete from the SPOSiteGroup |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteOffice365SPOSiteGroupMember(session,
"https://example.sharepoint.com/", "MySiteGroup",
"jdoe@example.com")Get an Office 365 DistributionGroup record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 DistributionGroup to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
distGroup = getOffice365DistributionGroup(session, "testgroup")
Get Office 365 DistributionGroup records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "GroupType", "SecurityEnabled") mailboxes = getOffice365DistributionGroups(session, filter, 50)
Get an Office 365 Mailbox record by Identity.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 Mailbox to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
mailbox = getOffice365Mailbox(session, "jdoe@example.com")
Get Office 365 Mailbox records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "LastName", "Doe") setRecordFieldValue(filter, "FirstName", "John") mailboxes = getOffice365Mailboxes(session, filter, 2)
Get an Office 365 MailContact record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MailContact to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
contact = getOffice365MailContact(session, "testContact")
Get Office 365 MailContact records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "LastName", "Doe") setRecordFieldValue(filter, "FirstName", "John") mailboxes = getOffice365MailContacts(session, filter, 2)
Get an Office 365 MailUser record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MailUser to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
mailUser = getOffice365MailUser(session, "testMailUser")
Get Office 365 MailUser records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
filter | text, expression, variable | an OPath filter or an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "LastName", "Doe") setRecordFieldValue(filter, "FirstName", "John") mailboxes = getOffice365MailUsers(session, filter, 2)
Get an Office 365 MsolGroup record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MsolGroup to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Note
filter = createRecord() setRecordFieldValue(filter, "GroupType",
"Security") mailboxes = getOffice365MsolGroups(session,
filter, 50)Get Office 365 MsolGroup records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
filter | text, expression, variable | an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "GroupType", "Security") mailboxes = getOffice365MsolGroups(session, filter, 50)
Get an Office 365 MsolRole record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MsolRole to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
role = getOffice365MsolRole(session, "fe930be7-5e62-47db-91af-98c3a49a38b1")
Get Office 365 MsolRole records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
filter | text, expression, variable | an example Record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "RoleName" "User Account Administrator") roles = getOffice365MsolRoles(session, filter, 1)
Get an Office 365 MsolUser record by Identity.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
identity* | text, expression, variable | the identity of the Office 365 MsolUser to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
user = getOffice365MsolUser(session, "jdoe@example.com")
Get Office 365 MsolUser records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
filter | text, expression, variable | an example Record |
maxResults | expression, variable | maximum number of Records to return (default: 1000) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "Department", "Sales") setRecordFieldValue(filter, "State", "CA") users = getOffice365MsolUsers(session, filter, 200)
Get an Office 365 SharePoint Online Site Group record by Id.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
site* | text, expression, variable | the url of the SharePoint Online Site |
identity* | text, expression, variable | the name of the Office 365 SharePoint Online Site Group to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
siteGroup = getOffice365SPOSiteGroup(session,
"https://example.sharepoint.com/", "MySiteGroup")Get Office 365 SharePoint Online Site Group records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
site* | text, expression, variable | the url of the SharePoint Online Site |
maxResults | expression, variable | maximum number of Records to return (default: 200) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
siteGroups = getOffice365SPOSiteGroups(session,
"https://example.sharepoint.com/", 50)Open a connection to Office 365.
Property | Value | Description |
|---|---|---|
office365AgentURL* | text, expression, variable | the URL of the Exchange Administrative Web Service agent (e.g. https://hostname:port/idautoExchangeAdminWS) |
noExchange | boolean, expression, variable | set to true for domains that don't support Exchange Online (default: false) |
spoAdminURL | text, expression, variable | the URL of the SharePoint Online Administration Center (e.g. https://mycompany-admin.sharepoint.com) |
username* | text, expression, variable | username for authentication to Office 365 |
password* | password, string, expression, variable | password for authentication to Office 365 |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.office365URL = "https://10.10.10.10/idautoExchangeAdminWS"
Global.office365User = "office365admin@example.net"\nGlobal.office365Pwd
= <Password>
session = openOffice365Connection(Global.office365URL,Global.office365User,
Global.office365Pwd)Purge deleted users from Office 365 Recycle Bin.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
purgeOffice365UserRecycleBin(session)
Create/Update an Office 365 DistributionGroup record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupTemplate = createRecord(, ) setRecordFieldValue(groupTemplate, "Name", "testgroup") saveOffice365DistributionGroup(session, groupTemplate)
Create/Update an Office 365 Mailbox record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
mailboxTemplate = createRecord()
setRecordFieldValue(mailboxTemplate, "Name", "JDoe")
setRecordFieldValue(mailboxTemplate, "Password",Password>)
setRecordFieldValue(mailboxTemplate, "MicrosoftOnlineServicesID",
johndoe@example.com")
mailbox = saveOffice365Mailbox(session, mailboxTemplate)Create/Update an Office 365 MailContact record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
contactTemplate = createRecord()
setRecordFieldValue(contactTemplate, "Name", "testContact")
setRecordFieldValue(contactTemplate, "ExternalEmailAddress",
"testContact@example.com")
contact = saveOffice365MailContact(session, contactTemplate)Create/Update an Office 365 MailUser record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
mailUserTemplate = createRecord()
setRecordFieldValue(
setRecordFieldValue(mailUserTemplate, "EmailAddresses",
"testMailUser@example.org")
mailUser = saveOffice365MailUser(session, mailUserTemplate)Create/Update an Office 365 MsolGroup record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupTemplate = createRecord() setRecordFieldValue(groupTemplate, "DisplayName", "testGroup") group = saveOffice365MsolGroup(session, groupTemplate)
Create/Update an Office 365 MsolUser record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userTemplate = createRecord()
setRecordFieldValue(userTemplate, "DisplayName", testId)
setRecordFieldValue(userTemplate, "Password",<//Password//>)
setRecordFieldValue(userTemplate, "UserPrincipleName", testId +
"@" + testDomain)
setRecordFieldValue(userTemplate, "UsageLocation", "US")
setRecordFieldValue(userTemplate, "LicenseAssignment",
"mydomain:ENTERPRISEPACK")
msolUser = saveOffice365MsolUser(session, userTemplate)Create/Update an Office 365 SharePoint Online Site Group record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Office 365 connection |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Fields supported for creating/updating on Office 365 objects are documented as parameters to the New-* and Set-* , Exchange Cmdlets, Azure AD Cmdlets, and SharePoint Online Cmdlets. Because many objects are polymorphic, there are different cmdlets that can be applied to the same object and the set of supported attributes is based on all the applicable cmdlets, e.g. a Mailbox is also a User, a Recipient, a CASMailbox, and a MailboxRegionalConfiguration, so the set of supported attributes is the union of the Cmdlets for those 5 object types. Note that some of the fields documented for Exchange are not available in Office 365, though the specifics of which fields is not documented.
For all Record types, the Identity field serves as the identifier for the corresponding Office 365 object. On save, a Record that has the Identity field will be treated as an update, whereas any Record without the Identity field will be treated as a create. Records returned from the Office 365 will always have the Identity field populated, though for purposes of getting or updating the object, any of the following can be used interchangeably as the Identity: ADObjectID, ,Alias, Distinguished name (DN), Domain\Account, GUID, LegacyExchangeDN, SmtpAddress, User principal name (UPN), Windows Live ID.
For search filters, only one Office 365 object type is supported for each Record type, which means that searches cannot be performed across all the attributes that are supported for create/update on each Record type. The list of attributes supported in search filters can be found here: http://technet.microsoft.com/en-us/library/bb738155.aspx.The syntax for searching is called OPath and is documented here: http://technet.microsoft.com/en-us/library/bb124268.aspx#OPATH. Filters should NOT be enclosed in braces { } because the adapter automatically takes care of that. Note that the filter could also be an example record.
For Msol* object types, OPath filters are not supported, and an example record filter will be used as additional parameters on the Get-Msol* cmdlet, many of which can be used to filter the result set.
Record type | New Cmdlet | Set Cmdlet(s) | Supported Attributes | Search Filter Object Type |
|---|---|---|---|---|
MsolUser | AlternateEmailAddresses, BlockCredential, City, Country, Department, DisplayName, Fax, FirstName, ImmutableId, LastName, LicenseAssignment, LicenseOptions, MobilePhone, Office, Password, PasswordNeverExpires, PhoneNumber, PostalCode, PreferredLanguage, State, StreetAddress, StrongPasswordRequired, TenantId, Title, UsageLocation, UserPrincipalName, NewPassword, AddLicenses, RemoveLicenses, NewUserPrincipalName, ForceChangePassword | MsolUser | ||
MsolGroup | New-MsolGroup | Set-MsolGroup | Description, DisplayName, ManagedBy, TenantId | MsolGroup |
Mailbox | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, ActiveSyncAllowedDeviceIDs, ActiveSyncBlockedDeviceIDs, ActiveSyncDebugLogging, ActiveSyncEnabled, ActiveSyncMailboxPolicy, Alias, ApplyMandatoryProperties, AssistantName, BypassModerationFromSendersOrMembers, CalendarRepairDisabled, CalendarVersionStoreDisabled, City, Company, CountryOrRegion, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, DeliverToMailboxAndForward, Department, Discovery, DisplayName, EmailAddresses, EvictLiveId, ExternalOofOptions, Fax, FederatedIdentity, FirstName, Force, ForwardingAddress, GrantSendOnBehalfTo, HiddenFromAddressListsEnabled, HomePhone, Identity, ImapEnabled, ImapMessagesRetrievalMimeFormat, ImapUseProtocolDefaults, ImmutableId, ImportLiveId, Initials, Languages, LastName, MAPIEnabled, MailTip, MailTipTranslations, MailboxPlan, Manager, MessageTrackingReadStatusEnabled, MobilePhone, ModeratedBy, ModerationEnabled, Name, Notes, OWAEnabled, Office, OrganizationalUnit, OtherFax, OtherHomePhone, OtherTelephone, Pager, Password, Phone, PopEnabled, PopMessagesRetrievalMimeFormat, PopUseProtocolDefaults, PostOfficeBox, PostalCode, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, RemotePowerShellEnabled, RemovedMailbox, RequireSenderAuthenticationEnabled, ResetPasswordOnNextLogon, ResourceCapacity, ResourceCustom, SecondaryAddress, SendModerationNotifications, SimpleDisplayName, StateOrProvince, StreetAddress, Title, Type, UseExistingLiveId, UserCertificate, UserSMimeCertificate, WebPage, WindowsEmailAddress, MicrosoftOnlineServicesID, DateFormat, Language, LocalizeDefaultFolderName, TimeFormat, TimeZone, PictureData | Recipient | ||
DistributionGroup | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, Alias, BypassModerationFromSendersOrMembers, BypassNestedModerationEnabled, CopyOwnerToMember, CreateDTMFMap, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, DisplayName, EmailAddresses, GrantSendOnBehalfTo, HiddenFromAddressListsEnabled, Identity, MailTip, MailTipTranslations, ManagedBy, MemberDepartRestriction, MemberJoinRestriction, Members, ModeratedBy, ModerationEnabled, Name, Notes, OrganizationalUnit, PhoneticDisplayName, PrimarySmtpAddress, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, ReportToManagerEnabled, ReportToOriginatorEnabled, RequireSenderAuthenticationEnabled, RoomList, SendModerationNotifications, SendOofMessageToOriginatorEnabled, SimpleDisplayName, Type, Universal, WindowsEmailAddress | Recipient | ||
MailContact | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, Alias, AllowUMCallsFromNonUsers, AssistantName, BypassModerationFromSendersOrMembers, City, Company, CountryOrRegion, CreateDTMFMap, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, Department, DisplayName, EmailAddresses, ExternalEmailAddress, Fax, FirstName, GrantSendOnBehalfTo, HiddenFromAddressListsEnabled, HomePhone, Identity, Initials, LastName, MacAttachmentFormat, MailTip, MailTipTranslations, Manager, MessageBodyFormat, MessageFormat, MobilePhone, ModeratedBy, ModerationEnabled, Name, Notes, Office, OrganizationalUnit, OtherFax, OtherHomePhone, OtherTelephone, Pager, Phone, PhoneticDisplayName, PostOfficeBox, PostalCode, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, RequireSenderAuthenticationEnabled, SecondaryAddress, SecondaryDialPlan, SendModerationNotifications, SimpleDisplayName, StateOrProvince, StreetAddress, TelephoneAssistant, Title, UMCallingLineIds, UMDialPlan, UseMapiRichTextFormat, UsePreferMessageFormat, WebPage, WindowsEmailAddress | Recipient | ||
MailUser | AcceptMessagesOnlyFrom, AcceptMessagesOnlyFromDLMembers, AcceptMessagesOnlyFromSendersOrMembers, Alias, AllowUMCallsFromNonUsers, AssistantName, BypassModerationFromSendersOrMembers, City, Company, CountryOrRegion, CreateDTMFMap, CustomAttribute1, CustomAttribute2, CustomAttribute3, CustomAttribute4, CustomAttribute5, CustomAttribute6, CustomAttribute7, CustomAttribute8, CustomAttribute9, CustomAttribute10, CustomAttribute11, CustomAttribute12, CustomAttribute13, CustomAttribute14, CustomAttribute15, Department, DisplayName, EmailAddresses, ExternalEmailAddress, Fax, FirstName, GrantSendOnBehalfTo, HiddenFromAddressListsEnabled, HomePhone, Identity, Initials, LastName, MacAttachmentFormat, MailTip, MailTipTranslations, Manager, MessageBodyFormat, MessageFormat, MobilePhone, ModeratedBy, ModerationEnabled, Name, Notes, Office, OrganizationalUnit, OtherFax, OtherHomePhone, OtherTelephone, Pager, Phone, PhoneticDisplayName, PostOfficeBox, PostalCode, RejectMessagesFrom, RejectMessagesFromDLMembers, RejectMessagesFromSendersOrMembers, RequireSenderAuthenticationEnabled, SecondaryAddress, SecondaryDialPlan, SendModerationNotifications, SimpleDisplayName, StateOrProvince, StreetAddress, TelephoneAssistant, Title, UMCallingLineIds, UMDialPlan, UseMapiRichTextFormat, UsePreferMessageFormat, WebPage, WindowsEmailAddress | Recipient | ||
SPOSiteGroup | Name, Owner, OwnerTitle, PermissionLevels, PermissionLevelsToAdd, PermissionLevelsToRemove, Site, Title, Users | N/A |
Important Notes
Office 365 supports a new higher level management object, MsolUser, that should be preferred to managing users via the Mailbox object.
While a Mailbox can still be created directly, the corresponding MsolUser must be assigned a license or the Mailbox will be disabled after a grace period.
The corresponding MsolUser is not available immediately (probably due to AD replication latency) so immediately trying to add a license after creating a Mailbox directly will usually fail.
Creating a Mailbox directly requires the field MicrosoftOnlineServicesID as opposed to WindowsLiveID (Live@EDU) or UserPrincipalName (Exchange).
After an MsolUser is created and assigned an appropriate license, a Mailbox will be automatically created after some delay.
While initial password can still be set when creating a Mailbox, subsequent password changes can only be made to the MsolUser.
Setting the initial password on an MsolUser uses the Password field, but subsequent password changes can use either the Password or NewPassword field.
Licenses can be added on the initial creation of MsolUser using the LicenseAssignment field. Subsequent addition or removal of licenses use the AddLicenses or RemoveLicense field. In either case the assigning a license will fail of the UsageLocation field has not been set.
The licenses available for assignment for a particular domain can be determined by going to the server hosting the Exchange agent and opening the “Microsoft Online Services Module for Windows PowerShell” from the desktop. Then running the following commands:
Connect-MsolService -Credential ( Get-Credential ) (Get-MsolAccountSku).AccountSkuid
You can disable specific applications that would normally be enabled by a license usin the LicenseOptions field. The LicenseOptions field is a record that has two fields: AccountSkuID, which is the name of the license; and DisabledPlans, which is an array of the names of specific modules to be disabled for the user. The names of the modules that are available within a given license can be determined by going to the server hosting the Exchange agent and opening the “Microsoft Online Services Module for Windows PowerShell” from the desktop. Then running the following commands:
Connect-MsolService -Credential ( Get-Credential ) forEach ( $sku in Get-MsolAccountSku) { echo $sku; forEach ( $service in $sku.ServiceStatus) { echo $service.ServicePlan.ServiceName} }
Creating an MsolGroup will create a security group (as opposed to a distribution group), after initial creation, MsolGroup can be used for listing or adding/removing members from both security and distribution groups.
There is a timing issue with user creation on the Office 365 backend. We are recommending that you not set Location, Time Zone or Language at user creation time. If you wish to set these attributes you should update them in a later action.
Org Adapter Actions
Department Actions
Retrieves a Department.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Department |
Example
department = saveDepartment({"name": "Math", "code": "765", "description": "Math Department"})
department = getDepartment(department.id)Retrieves all Departments.
Note
If there is no department ID yet in the system, RapidIdentity will create one using a createDepartment Action.
Property | Value | Description |
|---|---|---|
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
saveDepartment({"name": "Math", "code": "765", "description": "Math Department"})
departments = getAllDepartments()Updates a Department.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Department |
Example
saveDepartment({"name": "Math", "code": "765", "description": "Math Department"})Retrieves just one Department Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Department Relationship |
Example
department = saveDepartment({"name": "Math", "code": "765", "description": "Math Department"})
departmentRelationship = saveDepartmentRelationship({"departmentId": department.id, "userId":<some user's id>, "role": "ADMINISTRATOR"})
departmentRel = getDepartmentRelationShip(departmentRelationship.id)Retrieves all Department Relationships. If no relationship IDs have yet been defined, RapidIdentity will create one using a createDepartmentRelationship Action Set.
Property | Value | Description |
|---|---|---|
departmentId | string | The department ID for which to fetch department relationships |
userId | string | The user ID for which to fetch department relationships |
role | string | The role for which to fetch department relationships |
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
department = saveDepartment({"name": "Math", "code": "765", "description": "Math Department"})
saveDepartmentRelationship({"departmentId": department.id, "userId":<some user's id>, "role": "ADMINISTRATOR"})
departments = getAllDepartmentRelationships()Updates a Department Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Department Relationship |
Example
department = saveDepartment({"name": "Math", "code": "765", "description": "Math Department"})
saveDepartmentRelationship({"departmentId": department.id, "userId":<some user's id>, "role": "ADMINISTRATOR"})Deletes a Department Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Department Relationship |
Process
Delete by Department Relationship id.
Deletes a department.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the department to be deleted |
Process
Delete by Department id.
District Actions
Retrieves just one District.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the District |
Example
district = saveDistrict({"name": "District 1", "code": "123456", "ncesID": "123456", "stated": stateId})
district = getDistrict(district.id }Retrieves all Districts.
Property | Value | Description |
|---|---|---|
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
districts = getAllDistricts()
districtId = " "
if (districts.length <1) {
district = saveDistrict({"name": "District 1", "code": "123456", "ncesID": "123456", "stated": stateId})
districtID = districtid
} else {
districtId = districts[0].id
district = getDistrict(districtId)
}Updates a District.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the District |
Example
districtRec = createRecord() addRecordFieldValue(districtRec, 'name', districtName, false) addRecordFieldValue(districtRec, "code", districtCode, false) addRecordFieldValue(districtRec, "ncesId", ncesId, false) addRecordFieldValue(districtRec, "stateId", stateId, false) district = saveDistrict(districtRec) return district
Retrieves just one District Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the District Relationship |
Example
district = saveDistrict({"name": "District 1", "code": "123456", "ncesID": "123456", "stated": stateId})
districtRel = saveDistrictRelationship({"districtId": districtId, "userId": user_id, "role": "ADMINISTRATOR"})
districtRel = getDistrictRelationship(districtRelId)Retrieves all District Relationships.
Property | Value | Description |
|---|---|---|
districtId | string | The dID for which to fetch district relationships |
userId | string | The user ID for which to fetch district relationships |
role | string | The role for which to fetch district relationships |
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
districtRels = getDistrictRelationships(districtId, user_id)
districtRelId = " "
if (districtRels.length < 1) {
districtRel = saveDistrictRelationship({"districtId": districtId, "userId": user_id, "role": "ADMINISTRATOR"})
districtRelId = districtRel.id
} else {
districtRelId = districtRels[0].id
districtRel = getDistrictRelationship(districtRelId)Updates a District Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the District Relationship |
Example
district = saveDistrict({"name": "District 1", "code": "123456", "ncesID": "123456", "stated": stateId})
districtRel = saveDistrictRelationship({"districtId": districtId, "userId": user_id, "role": "ADMINISTRATOR"})Deletes a District Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the District Relationship |
Process
Delete by District Relationship id.
Deletes a District.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the District |
Process
Delete by District id.
Job Actions
Retrieves just one Job.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Job |
Example
saveJob({"name": "math123", "code": "456", "title": "Best Math Teacher"})Retrieves all Jobs.
Property | Value | Description |
|---|---|---|
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
saveJob({"name": "math123", "code": "456", "title": "Best Math Teacher"})
getAllJobs()Updates a Job.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Job |
Example
job = saveJob({"name": "math123", "code": "456", "title": "Best Math Teacher"})
job = getJob(job.id)Retrieves just one Job Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Job Relationship |
Example
job = saveJob({"name": "math123", "code": "456", "title": "Best Math Teacher"})
jobRel = saveJobRel({{"jobId": job.id, "userId":"user_id", "role": "ADMINISTRATOR"}
jobRel = getJobRelationship(jobRel.id)Retrieves all Jobs Relationships.
Property | Value | Description |
|---|---|---|
jobId | string | The job ID for which to fetch job relationships |
userId | string | The user ID for which to fetch job relationships |
role | string | The role for which to fetch job relationships |
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
job = saveJob({"name": "math123", "code": "456", "title": "Best Math Teacher"})
jobRel = saveJobRel({{"jobId": job.id, "userId":"user_id", "role": "ADMINISTRATOR"}
jobRels = getAllJobRelationships()saveJob
Updates a job.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Job |
Example
job = saveJob({"name": "math123", "code": "456", "title": "Best Math Teacher"})
job = getJob(job.id)Updates a Job Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Job Relationship |
Example
job = saveJob({"name": "math123", "code": "456", "title": "Best Math Teacher"})
jobRel = saveJobRel({{"jobId": job.id, "userId":"user_id", "role": "ADMINISTRATOR"}Deletes a Job Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Job Relationship |
Process
Delete by Job Relationship id.
Deletes a Job.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Job |
Process
Delete by Job id.
Location Actions
Retrieves just one Location.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Location |
Example
location = saveLocation({"name": "Houston", "code": "111"})
location = getLocation(location.id)Retrieves all Locations.
Property | Value | Description |
|---|---|---|
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
saveLocation({"name": "Houston", "code": "111"})
locations = getAllLocations()Updates a Location.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Location |
Example
saveLocation({"name": "Houston", "code": "111"})Retrieves just one Location relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Location relationship |
Example
location = saveLocation({"name": "Houston", "code": "111"})
locationRel = saveLocationRelationship({"locationId": location.id, "userId":"user_id", "role": "ADMINISTRATOR"})
locationRel = getLocationRelationship(locationRel.id)Retrieves all Location Relationships.
Property | Value | Description |
|---|---|---|
locationId | string | The location ID for which to fetch location relationships |
userId | string | The user ID for which to fetch location relationships |
role | string | The role for which to fetch location relationships |
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
location = saveLocation({"name": "Houston", "code": "111"})
locationRel = saveLocationRelationship({"locationId": location.id, "userId":"user_id", "role": "ADMINISTRATOR"})
locationRels = getAllLocationRelationships()Updates a Location Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Location Relationship |
Example
location = saveLocation({"name": "Houston", "code": "111"})
saveLocationRelationship({"locationId": location.id, "userId":"user_id", "role": "ADMINISTRATOR"})Deletes a Location Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Location Relationship |
Process
Delete by Location Relationship id.
Deletes a Location.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the Location |
Process
Delete by Location id.
School Actions
Retrieves just one School.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the School |
Example
school = saveSchool({"name": "The School", "code": "234", "ncesId": 123451234512, "districtId": district.id})
school = getSchool(school.id)Retrieves all Schools.
Property | Value | Description |
|---|---|---|
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
schools = getAllSchools()
SchoolId = " "
if (schools.length <1) {
school = saveSchool({"name": "School 1", "code": "321654", "ncesId": "123456789123", "districtId": districtId})
} else {
schoolId = schools[0].id
school = getSchool(schoolId)
}Updates a School.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the School |
Example
schoolRec = createRecord() addRecordFieldValue(schoolRec, 'name', schoolName, false) addRecordFieldValue(schoolRec, "code", schoolCode, false) addRecordFieldValue(schoolRec, "ncesId, ncesId, false) addRecordFieldValue(schoolRec, "districtId", districtId, false) school = saveSchool(schoolRec) return school
Retrieves just one School relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the School relationship |
Example
school = saveSchool({{"name": "The School", "code": "234", "ncesId": 123451234512, "districtId": district.id})
schoolRel = saveSchoolRelationship ("schoolId": schoolId, "userId": user_id, "role": ADMINISTRATOR})
schoolRel = getSchoolRelationships(schoolRel.id)Retrieves all School Relationships.
Property | Value | Description |
|---|---|---|
schoolId | string | The school ID for which to fetch school relationships |
userId | string | The user ID for which to fetch school relationships |
role | string | The role for which to fetch school relationships |
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
schoolRels = getSchoolRelationship(schoolId, user_id)
schoolRelId = " "
if (schoolRels.length <1) {
schoolRel = saveSchoolRelationship ("schoolId": schoolId, "userId": user_id, "role": ADMINISTRATOR})
schoolRelID = schoolRel.id
} else {
schoolRelID = schoolRels[0].id
schoolRel = getSchoolRelationships(schoolRelId)
}Updates a School relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the School relationship |
Example
id = "cc913124-c1d6-4716-9462-42e5577c730f"
schoolId = "aef284b-9c6fe-4ad1-8e12-8cd7ee0b7c4f"
conn = openMetadirLDAPConnection()
schoolRel = saveSchoolRelationship({"userId": id, "schoolId": schoolID, "role": "ADMINISTRATOR"})
log('Adding User with Email: "' + email + '" as an Administrator for School with ID: "' + schoolID + '"')
close(conn)
return id Deletes a School Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the School Relationship |
Process
Delete by School Relationship id.
Deletes a School.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the School |
Process
Delete by School id.
Deletes a School Type.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the School Type |
Process
Delete by School Type id.
State Actions
Retrieves just one State.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the State |
Example
state = saveState({"name": "State 1", "code": 123456
state = getState(state.id)Retrieves all States. If there are no existing states in the system, RapidIdentity will create one using a createState action set.
Property | Value | Description |
|---|---|---|
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
states = getAllStates()
stateId = " "
if (states.length) < 1) {
state = saveState({"name": "State 1", "code": 123456
stateID = state.id
} else {
stateId = states[0].id
state = getState(stateID)Updates a State.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the State |
Example
idautoStateRec = createRecord(false) addRecordFieldValue(idautoStateRec, 'name', stateName, false) addRecordFieldValue(idautoStateRec, "code", stateCode, false) idautoState = saveState(idautoStateRec) return idautoState
Retrieves just one State relationship.
Property | Value | Description |
|---|---|---|
stateid* | string | The state ID of the State relationship |
user_id | expression | The user ID for the state relationships to retrieve |
role | string | The role of the state relationships to retrieve |
Example
stateRel = getStateRelationship(stateId, user_id)
stateRelId = " "
if stateRel.length < 1) {
stateRel = savestateRelationship({"stateId": state.id, "userId": user_id, "role": ADMINISTRATOR
} else {
stateRelID = stateRel[0].id
stateRel = getStateRelationship(stateRelId)
}Retrieves all State Relationships. If there are no state relationships currently in the system, RapidIdentity will create one using a createStateRelationship action set.
Property | Value | Description |
|---|---|---|
stateId | string | The ID for which to fetch state relationships |
userId | string | The user ID for which to fetch state relationships |
role | string | The role for which to fetch state relationships |
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
stateRels = getStateRelationships(stateId, user_id)
stateRelId = " "
if stateRels.length < 1) {
stateRel = savestateRelationship({"stateId": state.id, "userId": user_id, "role": ADMINISTRATOR
} else {
stateRelID = stateRel[0].id
stateRel = getStateRelationship(stateRelId)
}Updates a State Relationship.
Property | Value | Description |
|---|---|---|
stateId | string | The ID for which to fetch state relationships |
userId | string | The user ID for which to fetch state relationships |
role | string | The role for which to fetch state relationships |
pageSize | integer | The page size (required for a paging request) |
pageNum | integer | The page number (defaults to 1 for a paging request) |
Example
state = saveState({"name": "State 1", "code": 123456
stateRel = savestateRelationship({"stateId": state.id, "userId": user_id, "role": ADMINISTRATOR
stateRel = getStateRelationship(stateRel.id)Deletes a State Relationship.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the State Relationship |
Process
Delete by State Relationship id.
Deletes a State.
Property | Value | Description |
|---|---|---|
id* | string | The ID of the State |
Process
Delete by State id.
Portal Adapter Actions
Core Actions
Define a connection to a Portal server and optionally login for a token.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | The url of the Portal server. |
username | text, expression, variable | The username for authentication to the Portal server. |
password | password, string, expression, variable | The password for authentication to the Portal server. |
login | boolean, expression, variable | Determines whether or not to login for an authentication token. If false, each Portal action will perform a full authentication. Set this to true if you are invoking 2 or more actions within this session. |
remoteDebug | choice ('OFF', 'DEBUG', 'DEBUG_ALL'), text, expression, variable | Remote Portal request debug logging options. DEBUG: standard debug logging. DEBUG_ALL: extended debug logging (not recommended). |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | The name of the variable to be assigned to the return value |
Example
connection = definePortalConnection("http://server.company.com",
"testuser1", <Password>, true)
connection = definePortalConnection("http://server.company.com",
"testuser1", <Password>, true, \'DEBUG\')Creates/Retrieves the IdautoID value for a particular Role in LDAP
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
roleDN* | text, expression, variable | the DN of the Group in question |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
idautoID = getPortalIdautoIDForGroup(connection,
"CN=My Group,OU=groups,DC=example,DC=com")Creates/Retrieves the IdautoID value for a particular User in LDAP
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
userDN* | text, expression, variable | the DN of the User in question |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
idautoID = getPortalIdautoIDForUser(connection,
"CN=Homer Simpson,OU=people,DC=example,DC=com")Profiles Actions
Retrieve the Challenge Set information for a target DN
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
targetDN* | text, expression, variable | the DN of the target to query |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
The returned object is a record which will have the following fields:
Field | Description |
|---|---|
“challengePolicyId” | The ID of the ARMS Challenge Policy associated with the target |
“adminQuestions” | The Admin questions required by the Challenge Policy (if any) |
“numUserQuestions” | The number of User questions required by the Challenge Policy (may be 0) |
Example
targetDN = "CN=user,OU=people,DC=example,DC=com"
challengeSetupDefn = getPortalChallengeSetPolicy(connection,
targetDN)
challengePolicyId = getRecordFieldValue(challengeSetupDefn,
"challengePolicyId")
adminQuestions = getRecordFieldValues(challengeSetupDefn,
"adminQuestions")
numUserQuestions = getRecordFieldValue(challengeSetupDefn,
"numUserQuestions")Determines if the provided password is valid for the specified User's current Portal Password Policy.
Property | Value | Description |
|---|---|---|
returnVariable | expression, variable | name of the variable to be assigned to the return value |
connection* | expression, variable | the Portal connection object obtained from invoking |
password* | text | the password to check for validity |
userDNOrId | text, expression, variable | the ID or DN or the user to check password validity for |
Example
portalConn = definePortalConnection("https://localhost:8443", "jdoe", <Password>, true)
isValid = isPasswordValidForPortalUser(portalConn, <Password>, "cn=jdoe,ou=employees,ou=people,o=idauto,dc=meta")
if (isValid)_ {
log("The password is valid", "INFO")
} else {
log("The password is invalid", "INFO")
}Set challenge questions and answers for a target DN
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
targetDN* | text, expression, variable | the DN of the target whose challenge questions will be updated |
challengePolicyId* | text, expression, variable | the ID of the Portal Challenge Policy for the target |
adminQAs | text, expression, variable | Record containing Admin questions and associated answers |
userQAs | text, expression, variable | Record containing User questions and associated answers |
helpdeskQAs | text, expression, variable | Record containing Helpdesk questions and associated answers |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
adminQAs = createRecord(false)
addRecordFieldValue(adminQAs, "Admin Question 1", "Admin Answer 1",
false)
addRecordFieldValue(adminQAs, "Admin Question 2", "Admin Answer 2",
false)
userQAs = createRecord(false)
addRecordFieldValue(userQAs, "User Question 1", "User Answer 1",
false)
addRecordFieldValue(userQAs, "User Question 2", "User Answer 2",
false)
# Example of creating a Record from an object literal
helpdeskQAs = createRecordFromObject({"Helpdesk Question 1":
"Helpdesk Answer 1"})
success = setPortalChallengeSetAnswers(connection, targetDN,
challengePolicyId, adminQAs, userQAs, helpdeskQAs)Retrieves the ID of the default Portal Password Policy.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
defaultPolicyId = getPortalDefaultPasswordPolicyID(connection)
Retrieves the ID of the Portal Password Policy associated with a particular user.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
userDNorID* | text, expression, variable | the DN or IdautoID of the target user |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
defaultPolicyId = getPortalPasswordPolicyID(connection)
Generates a random password for a user based on their current Portal Password Policy.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
userDNorID* | text, expression, variable | the DN or IdautoID of the target user |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
randomPassword = generatePortalPasswordForUser(connection,
"CN=John Simpson,OU=people,DC=example,DC=com")Generates a random password based on the specified Portal Password Policy ID.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
policyId* | text, expression, variable | the Portal Password Policy ID |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
policyId = getPortalDefaultPasswordPolicyID(connection) randomPassword = generatePortalPasswordForPolicy(connection, policyId)
Dashboard Actions
Increment the tally for a user-defined ROI Type
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
roiTypeId* | choice (dss.addDistributionListMember, dss.addGroupMember, dss.changePassword, dss.createAccount, dss.createDistributionList, dss.createGroup, dss.createMailbox, dss.deleteAccount, dss.deleteDistributionList, dss.deleteGroup, dss.deleteMailbox, dss.disableAccount, dss.disableMailbox, dss.enableAccount, dss.enableMailbox, dss.moveAccount, dss.moveDistributionList, dss.moveGroup, dss.removeDistributionListMember, dss.removeGroupMember, dss.renameAccount, dss.renameDistributionList, dss.renameGroup, dss.updateAccount, dss.updateDistributionList, dss.updateGroup, dss.updateMailbox) text, expression, variable | the ID of the ROI Type whose tally should be incremented |
count | expression, variable | the number of tallies to generate (must be > 0). The default value is 1 if no value is provided |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
roiTally = incrementROITally(connection, "TestROITally")
log("ROI incremented = " + roiTally, "green")Roles Actions
Deletes a Portal role.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
roleDNOrID* | text, expression, variable | the DN or IdautoID of the role to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deletePortalRole(connection,
"CN=My Role,OU=groups,DC=example,DC=com")Obtains the DN or IdAutoId of all members in the listed Role.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | The Identity Portal connection definition |
roleDNsORId* | text, expression, variable | The DN or the IdAutoID of the user |
returnVariable | expression, variable | Returns an array of Role DNs or IdAutoIDs |
Initiate import of a particular new Portal role.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
roleId* | text, expression, variable | the IdautoID of the role to import |
syncAfterImport* | boolean, expression, variable | whether the imported role should be synced after importing |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupId = getIdautoIDForGroup(connection,
"CN=My New Group,OU=groups,DC=example,DC=com")
success = importPortalRole(connection, groupId, true)Initiate import of new Portal roles.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
syncAfterImport* | boolean, expression, variable | whether imported roles should be synced after the import completes |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
success = importPortalRoles(connection, true)
Property | Value | Description |
|---|---|---|
connection* | expression, variable | The Identity Portal connection definition |
userDNorID* | text, expression, variable | The DN or the IdAutoID of the user |
roleDNsORIds* | expression, variable | An array of Role DNs or IdAutoIDs |
returnVariable | expression, variable | Returns true or false. |
Determines whether a listed user is a member of any of queried roles.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | The Identity Portal connection definition |
userDNorID* | text, expression, variable | The DN or the IdAutoID of the user |
roleDNsORIds* | expression, variable | An array of Role DNs or IdAutoIDs |
returnVariable | expression, variable | Returns true or false. |
Example
conn = definePortalConnection("https://localhost:8443", "username",
<Password>, true)
array = createArray(6)
insertArrayItem(array, 0, "CN=Role Managers,OU=managed,OU=groups,
DC=test,DC=local")
insertArrayItem(array, 1, "0b0ad0e1-2222-3333-ceds-44se4444")
insertArrayItem(array, 2, "0ed8092a-29dw-23ub-sw19-23sdf09u")
insertArrayItem(array, 3, "sedrofle-234n-32fs-2wld-sadf343d")
insertArrayItem(array, 4, "34ajedf2-a232-adv0-a34w-adf3ljww")
result = isPortalUserInAllRoles(conn,
"34dsaer2-2342-saef-adv9-e4sdv039", array)
log(result)
log(" ")
result = isPortalUserInAnyRoles(conn,
"34dsaer2-2342-saef-adv9-e4sdv039", array)
log(result)
close(conn)Opens an iterator over the members of a particular Portal Role.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | The Identity Portal connection definition |
roleDNsORId* | text, expression, variable | The DN or the IdAutoID of the user |
returnVariable | expression, variable | Returns an array of Role DNs or IdAutoIDs |
Example
conn = definePortalConnection("https://localhost:8443", "username",
<Password>, true)
result = getPortalRoleMembership(conn,
"CN=Role Managers,OU=managed,OU=groups,DC=test,DC=local")
log(result)
#
# With membership array in hand, add two new members to the role
in the Roles module of Identity Portal
#
# Use the iterator to obtain the two new role members
#
records = openPortalRoleMembershipIterator(conn,
"CN=Role Managers,OU=managed,OU=groups,DC=test,DC=local")
forEach(record, records) {
log(record)
}
close(conn)Initiate synchronization of a Portal role.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
roleDN* | text, expression, variable | the DN of the role |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
success = syncPortalRole(connection, "CN=testgroup1,OU=groups,
DC=test,DC=idauto,DC=lab")Sync membership among all Portal roles for a single user.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
userDNOrID* | text, expression, variable | the DN or IdautoID of the user to sync |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
syncResult = syncPortalMembership(connection, "CN=Test User,
OU=people,DC=example,DC=com")
if(hasRecordField(syncResult, "added") {
forEach(addedDN, getRecordFieldValues(syncResult, "added")) {
log( "The user was added to role " + addedDN )
}
} else {
log( "The user was added to no role" )
}
if (hasRecordField(syncResult, "removed")) {
forEach(removedDN, getRecordFieldValues(syncResult, "removed")) {
log("The user was removed from role " + removedDN)
}
} else {
log("The user was removed from no roles")
}
Workflow Actions
Get the ID of entitlement based on its name.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
entitlementName* | text, expression, variable | the name of the entitlement |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
nameOfEntitlement = "LabMonitor" entitlementID = getPortalEntitlementId(connection, nameOfEntitlement)
Start a Portal workflow, returning the workflow request ID.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Portal connection definition |
type* | choice (GRANT, REVOKE), text, expression, variable | the workflow type |
recipientId* | text, expression, variable | the idautoID of the workflow recipient |
entitlementId* | text, expression, variable | the ID of the workflow entitlement |
comments | text, expression, variable | optional workflow comments |
previousRequestId | text, expression, variable | the ID of the workflow request that granted the entitlement to be revoked (required for REVOKE of a multi-bound entitlement) |
formData | expression, variable | optional Record or object containing form data |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
nameOfEntitlement = "LabMonitor"
entitlementId = getPortalEntitlementID(connection,
nameOfEntitlement)
workFlowStarted = startPortalWorkflow(connection, "GRANT",
"cn=testuser1,OU=People,DC=test,DC=idauto,DC=lab", entitlementId,
"Start the LabMonitor Workflow")QuickSchools Adapter Actions
Define a connection to a QuickSchools Server.
Property | Value | Description |
|---|---|---|
apiKey* | password, string, expression, variable | Secret key for authentication to the QuickSchools REST service |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
conn = defineQuickSchoolsConnection(<Password>)
Get a QuickSchools record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | The connection to the QuickSchools Server |
type* | choice (class, parent, section, student, student sections, teacher), text, expression, variable | The type of record to retrieve |
id* | text, expression, variable | The ID of the record |
fields | text, expression, variable | A comma separated list of additional attributes to retrieve |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
record = getQuickSchoolsRecord(conn, "student", "415330")
Get QuickSchools Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | The connection to the QuickSchools Server |
type* | choice (classes, parents, school, schools, sections, students, student sections, teachers), text, expression, variable | The type of records to retrieve |
filter | expression, variable | A record to filter by |
fields | text, expression, variable | A comma separated list of additional attributes to retrieve |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
records = getQuickSchoolsRecords(conn, "students")
Open QuickSchools record iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | The connection to the QuickSchools Server |
type* | choice (parents, students, student sections, teachers), text, expression, variable | The type of record to retrieve |
filter | expression, variable | A record to filter by |
fields | text, expression, variable | A comma separated list of additional attributes to retrieve |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
it = openQuickSchoolsRecordIterator(conn, "students")
forEach(record, it) {
# process record
}Create or Update a QuickSchools record.
Property | Value | Description |
|---|---|---|
returnVariable | expression, variable | name of the variable to be assigned to the value |
connection* | expression, variable | The connection to the QuickSchools Server |
type* | choice (classes, parents, school, schools, sections, students, student sections, teachers), text, expression, variable | The type of records to save |
id | text, expression, variable | The ID of the record to update. This is required for resource types of parents, sections, or assignments |
record* | text, expression, variable | the QuickSchools record to save |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
age | integer | the age of the student | Yes | No | No |
classCode | string | the grade level abbreviation | Yes | No | No |
classId | integer | the identifier for the class | Yes | No | No |
className | string | the grade level of the student | Yes | No | No |
fullName | string | the full name of the student | Yes | No | No |
gender | string | the gender of the student | Yes | No | No |
id | integer | unique student identifier | Yes | No | No |
preferredName | string | the preferred name of the student | Yes | No | No |
Field | Type | Description |
|---|---|---|
homeroomId | integer | the unique identifier of the student's homeroom |
classId | integer | the unique identifier of the student's grade level |
parentId | integer | the unique identifier of the student's parent |
showHasLeft | boolean | if true, includes students who have graduated |
showDeleted | boolean | if true, includes deleted students |
studentNumbers | string | a student number, or a comma separated list of student numbers |
search | string,integer | the student's full name, the student's number, or class name |
firstName
middleName
familyName
suffix
studentNumber
enrollmentDate
parents
siblings
homeroomId
homeroomTeacher
multiLineResidentialAddress
country
zip
state
city
phone
cellPhone
fax
email
nationality
confidentialInformation
deleted
hasLeft
isExpelled
customFields
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
fullName | string | the full name of the teacher | Yes | No | No |
gender | string | the gender of the teacher | Yes | No | No |
id | integer | unique teacher identifier | Yes | No | No |
title | string | the title of the teacher | Yes | No | No |
Field | Type | Description |
|---|---|---|
employeeNumbers | string | an employee number, or a comma separated list of employee numbers |
search | string,integer | the teacher's full name or employee name |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
fullName | string | the full name of the parent | Yes | No | No |
id | integer | unique parent identifier | Yes | No | No |
students
country
zip
state
city
cellPhone
homePhone
email
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
abbreviation | string | the grade level abbreviation | Yes | No | No |
id | integer | unique class identifier | Yes | No | No |
name | string | the grade level | Yes | No | No |
sortOrder | integer | the key used for sorting classes | Yes | No | No |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
classId | integer | the identifier for the class | Yes | No | No |
className | string | the grade level of the section | Yes | No | No |
id | integer | unique section identifier | Yes | No | No |
sectionCode | string | the code of the section | Yes | No | No |
sectionName | string | the name of the section | Yes | No | No |
teachers | string | a list of section teachers and their details | Yes | No | No |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
address | string | the address of the school | Yes | No | No |
string | the email address of the school | Yes | No | No | |
id | integer | unique school identifier | Yes | No | No |
phone | string | the phone number of the school | Yes | No | No |
principalName | string | the name of the school principle | Yes | No | No |
schoolCode | string | the code of the school | Yes | No | No |
schoolName | string | the name of the school | Yes | No | No |
website | string | the website for the school | Yes | No | No |
Field | Type | Description |
|---|---|---|
subdomain | string | the subdomain for a school |
Field | Type | Description | Read | Create | Update |
|---|---|---|---|---|---|
fullName | string | the full name of the student | Yes | No | No |
id | integer | unique student identifier | Yes | No | No |
sections | string | a list of enrolled sections and their details | Yes | No | No |
Filter Example
record = createRecord(true)
setRecordFieldValue(record, "studentNumbers", "S-000003,S-000010,
S-000006")
records = getQuickSchoolsRecords(conn, "students", record)Search Example
record = createRecord(true) setRecordFieldValue(record, "search", "Amber Phillips") records = getQuickSchoolsRecords(conn, "students", record)
Additional Fields Example
records = getQuickSchoolsRecords(conn, "students", "city, state,
zip, country, cellPhone, parents") Documentation from QuickSchools
QuickSchools API Documentation.
To obtain an API Key for QuickSchools, click QuickSchools.
Schoology Adapter Actions
Define a connection to Schoology server.
Property | Value | Description |
|---|---|---|
consumerKey* | text, expression, variable | the consumer key |
secretKey* | password, string, expression, variable | the secret key |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
connection = defineSchoologyConnection("myConsumerKey",<myPassword>)Delete/Deactivate the specified Schoology User.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
id* | text, expression, variable | the user Schoology ID |
reason | text, expression, variable | comment on reason for deactiving |
keepEnrollments | boolean, expression, variable | keep history of user's grad and attendance data |
emailNotification | boolean, expression, variable | send email notification to user that the account was deactived. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deletedUser = deleteSchoologyUser(connection, "1234")
Gets a specified inactive Schoology User record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection definition |
id* | text, expression, variable | the user Schoology ID |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
inactive = getInactiveSchoologyUsers(connection)
Gets inactive Schoology User records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
inactive = getInactiveSchoologyUsers(connection)
Get the specified Schoology User record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
id* | text, expression, variable | the Schoology id of the User |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
user = getSchoologyUser(connection, "1234")
Gets Schoology User records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
filterRecord | expression, variable | a record containing filter parameters |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Filters can be defined by creating a record object and populating the record with the fields and values to filter by. The following are the fields that can be used as filters.
Field | Value | Description |
|---|---|---|
building_id | text, variable | Only return users for the given building. |
role_ids | text, variable | (Comma-separated list of IDs) Only return users who belong to the given role IDs |
parent_access_codes | boolean, variable | Add in parent access codes for each of the returned users (set to 1) |
school_uids | text, variable | A comma-separated list of school_uids within the school (up to 50 at one time) |
Example
#define the connection
connection = defineSchoologyConnection("myConsumerKey",<Password>)
# create record filter
{
fr = createRecord(false)
addRecordFieldValue(fr, "role_id", "Student")
}
list = getSchoologyUsers(connection, fr)Open Schoology inactive User Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
#define the connection
connection = defineSchoologyConnection("myConsumerKey",<Password>)
inactiveUser = openSchoologyInactiveUserIterator(connection)
forEach(inactiveUser, inactiveUser) {
...
}Get Schoology User records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
filterRecord | expression, variable | a record containing filter parameters |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
#define the connection
connection = defineSchoologyConnection("myConsumerKey",<Password>)
# create record filter
{
fr = createRecord(false)\n addRecordFieldValue(fr, "role_id", "Student")
}
users = openSchoologyUserIterator(connection, fr)
forEach(user, users) {
...
}Reactivates a specified list of Schoology Users.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
ids* | expression, variable | an array of Schoology ids to be reactivated |
reenroll* | boolean, expression, variable | Set to true in the request body to place the user back into their courses and groups. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
reactivateSchoologyUsers(connection,"1234",true)
Create/Update an Schoology User record. Note you cannot update inactive users.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
record* | expression, variable | the Schoology User record |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Field | Value | Description |
|---|---|---|
school_uid | text, expression, variable | The user's unique ID (e.g. student ID, SIS ID) |
name_first | text, expression, variable | The user's first name |
name_last | text, expression, variable | The user's last name |
role_id | text, expression, variable | The ID of the role to which you would like to assign the user |
username | text, expression, variable | The user's username (either a username or email address is required for each user) |
primary_email | text, expression, variable | The user's primary email address (either a username or email address is required for each user) |
To see additional optional fields go to the user api.
Example
connection = defineSchoologyConnection("myConsumerKey",<Password>)
# create the new user record
addTest = createRecord(false)
setRecordFieldValue(addTest, "school_uid", "testUser1234")
setRecordFieldValue(addTest, "name_first", "MrTest")
setRecordFieldValue(addTest, "name_last", "Tester")
setRecordFieldValue(addTest, "role_id", "296904")
setRecordFieldValue(addTest, "additional_buildings", "456")
setRecordFieldValue(addTest, "username", "TestMaster2")
# attempt the add
newUser = saveSchoologyUser(connection, addTest)
log(newUser)Creates multiple Schoology User records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the Schoology connection |
records* | expression, variable | the array of records to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
# create users
(true) {
# user 1 {
user1 = createRecord(false)
setRecordFieldValue(user1, "school_uid", "u1")
setRecordFieldValue(user1, "name_first", "Sara")
setRecordFieldValue(user1, "name_last", "Doe")
setRecordFieldValue(user1, "role_id", "296904")
setRecordFieldValue(user1, "additional_buildings", "456")
setRecordFieldValue(user1, "username", "user1")
}
# user 2 {
user2 = createRecord(false)
setRecordFieldValue(user2, "school_uid", "u2")
setRecordFieldValue(user2, "name_first", "Ryan")
setRecordFieldValue(user2, "name_last", "Jordan")
setRecordFieldValue(user2, "role_id", "296904")
setRecordFieldValue(user2, "additional_buildings", "456")
setRecordFieldValue(user2, "username", "jryan")
}
# user 3 {
user3 = createRecord(false)
setRecordFieldValue(user3, "school_uid", "u3")
setRecordFieldValue(user3, "name_first", "Austin")
setRecordFieldValue(user3, "name_last", "Powell")
# role ids can also be set using their title rather
than their id value
setRecordFieldValue(user3, "role_id", "Student")
setRecordFieldValue(user3, "additional_buildings", "456")
setRecordFieldValue(user3, "username", "paustin")
}
# create array of user records {
users = createArray()
appendArrayItem(users, user1) appendArrayItem(users, user2)
appendArrayItem(users, user3)
}
}
# connection
connection = defineSchoologyConnection("myConsumerKey", < Password > )
ret = saveSchoologyUsers(connection, users)Example
connection = defineSchoologyConnection("myConsumerKey", < Password > )
# create the new user record {
addTest = createRecord(false)
setRecordFieldValue(addTest, "school_uid", "testUser12345")
setRecordFieldValue(addTest, "name_first", "MrTest")
setRecordFieldValue(addTest, "name_last", "Tester")
setRecordFieldValue(addTest, "role_id", "296904")
setRecordFieldValue(addTest, "additional_buildings", "456")
setRecordFieldValue(addTest, "username", "TestMaster3")
}
# attempt the add
newUser = saveSchoologyUser(connection, addTest)
uid = getRecordFieldValue(newUser, "uid")
log(newUser)# get the user
user = getSchoologyUser(connection, uid)
log(user)# delete the user\ nret = deleteSchoologyUser(connection, uid)
log(ret)# reactivate the user
reactivateList = createArray()
appendArrayItem(reactivateList, uid)
user = reactivateSchoologyUsers(connection, reactivateList, false)
log(user)ServiceNow Adapter Actions
Define a connection to a ServiceNow Server.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the Base URL of the ServiceNow web service |
username* | text, expression, variable | Username for authentication to the ServiceNow web service |
password* | password, string, expression, variable | Password for authentication to the ServiceNow web service |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.snUrl = "https://sandbox.service-now.com"
Global.snUser = "admin"
Global.snPwd = "admin"
session = defineServiceNowConnection(Global.snUrl, Global.snUser,
Global.snPwd)Deletes the record in ServiceNow. Returns a success boolean.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ServiceNow connection definition |
objectType* | text, expression, variable | The ServiceNow object type |
id* | text, expression, variable | The sys_id of the ServiceNow record to delete. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
users = getServiceNowRecords(session, "sys_user", "user_name=joh.doe, 1)
if(users.length) {
result = deleteServiceNowRecord(session, "sys_user", users[0][\'sys_id\'])
}Gets a given ServiceNow Record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ServiceNow connection definition |
objectType* | text, expression, variable | The ServiceNow object type |
id* | text, expression, variable | The sys_id of the ServiceNow record. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
user = getServiceNowRecord(session, "02826bf03710200044e0bfc8bcbe5d55")
Get All ServiceNow Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ServiceNow connection definition |
objectType* | text, expression, variable | The ServiceNow object type |
filter | text, expression, variable | The filter used to limit results. Can either be an encoded query as specified by ServiceNow, or a Record example object. |
limit | expression, variable | The maximum number of records to return. Defaults to all objects. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
users = getServiceNowRecords(sessionServiceNow, "sys_user",
"user_name=john.doe", 1)
Open a ServiceNow Record Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ServiceNow connection definition |
objectType* | text, expression, variable | The ServiceNow object type |
filter | text, expression, variable | The filter used to limit results. Can either be an encoded query as specified by ServiceNow, or a Record example object. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
it = openServiceNowRecordIterator(sessionServiceNow, "sys_user")
forEach(user, it) {
# do something with user
}
close(it)Creates or updates the record in ServiceNow. Returns the id of the object.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the ServiceNow connection definition |
objectType* | text, expression, variable | The ServiceNow object type |
record* | text, expression, variable | A Record object containing the fields you want to save. If 'sys_id' is set, an update will be performed, otherwise a create will be performed. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userTemplate = createRecord(true) setRecordFieldValue(userTemplate, "user_name", "john.doe") setRecordFieldValue(userTemplate, "first_name", "John") setRecordFieldValue(userTemplate, "user_name", "john.doe") setRecordFieldValue(userTemplate, "user_name", "john.doe") user = saveServiceNowRecord(sessionServiceNow, "sys_user", userTemplate)
SharePoint Adapter Actions
Add a member to a SharePoint Group
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
groupName* | text, expression, variable | the name of the Group |
userLoginName* | text, expression, variable | the login name of the User to add to the Group |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
memberAdded = addSharePointGroupMember(session,
"testGroup", "Test\\\\testuser")Define a connection to SharePoint.
Property | Value | Description |
|---|---|---|
siteUrl* | text, expression, variable | URL of the SharePoint site |
username | text, expression, variable | username for authentication to SharePoint |
password | password, string, expression, variable | password for authentication to SharePoint |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.spHost = "sharepoint.test.local"
Global.spUser = "Test\\\\Administrator"
Global.spPwd = <Password>
session = defineSharePointConnection("http://" + Global.spHost,
Global.spUser,<Password>)Delete a SharePoint Group record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
groupName* | text, expression, variable | the name of the SharePoint Group to delete |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
deleted = deleteSharePointGroup(session, "testGroup")
Delete a member from a SharePoint Group.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
groupName* | text, expression, variable | the id of the group |
userLoginName* | text, expression, variable | the id of the object to delete from the Group |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
memberDeleted = deleteSharePointGroupMember(session, "testGroup",
"Test\\\\testuser")Get a SharePoint Group record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
groupName* | text, expression, variable | the name of the SharePoint Group to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
group = getSharePointGroup(session, "testGroup")
Get SharePoint Group records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groups = getSharePointGroups(session)
Get a SharePoint User record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
loginName* | text, expression, variable | the loginName of the SharePoint User to get |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
user = getSharePointUser(session, "Test\\\\testuser")
Get SharePoint User records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
users = getSharePointUsers(session)
Rename a SharePoint Group record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
groupName* | text, expression, variable | the name of the SharePoint Group to rename |
newName* | text, expression, variable | the new name |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
renamed = renameSharePointGroup(session, "testGroup", "testGroup1")
Create/Update a SharePoint Group record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
groupTemplate = createRecord() setRecordField(groupTemplate, "Name", "testGroup") created = saveSharePointGroup(session, groupTemplate)
Create/Update a SharePoint User record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the SharePoint connection definition |
record* | expression, variable | the record to save |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
userTemplate = createRecord() setRecordField(userTemplate, "LoginName", "Test\\\\testUser") setRecordField(userTemplate, "Name", "testUser") created = saveSharePointUser(session, userTemplate)
Field | Read-Only | Description |
|---|---|---|
LoginName (required) | Y | User login name (from the Authentication Provider, usually AD - must exist in the provider before can be created in SharePoint) |
Name | N | Display Name |
N | User e-mail address | |
Notes | N | Descriptive notes about User |
Groups | Y | List of Groups that the User is a member of |
ID | Y | Internal SharePoint ID |
IsDomainGroup | Y | Domain group flag |
IsSiteAdmin | Y | Site administrator flag |
SID | Y | Security ID |
Field | Read-Only | Description |
|---|---|---|
Name (required) | Y | Name of Group |
Description | N | Description of Group |
OwnerIdentifier | N | Name of Group or LoginName of User that owns this group |
OwnerType | N | The type of the OwnerIdentitifier: “user” or “group” |
Users | Y | List of Users that are members of Group |
ID | Y | Internal SharePoint ID |
OwnerID | Y | Internal SharePoint ID of Owner |
OwnerIsUser | Y | Owner type flag flag |
Text Adapter Actions
Open a Delimited Text file for reading.
Property | Value | Description |
|---|---|---|
filesystem | expression, variable | the filesystem definition to use (default: dss server managed files) |
fileName* | text, expression, variable | the name of the Delimited Text input file |
charSet | text, expression, variable | the character encoding of the file (default: ISO-8859-1) |
fieldNames | text, expression, variable | comma separated string containing the names of the fields in each Record |
firstRecordHandling | choice (Normal, Field Names, Skip), text, expression, variable | how to handle the first Record of the file |
fieldSeparator | text, expression, variable | the field separator character (default: ',') |
quoteCharacter | text, expression, variable | the quote character (default: '"') |
escapeCharacter | text, expression, variable | the quote character (default: the quoteCharacter) |
strictQuoteHandling | boolean, expression, variable | true if strict quote handling should be enforced (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
csvInput = openDelimitedTextInput("input.csv", "utf-8",
"fname,lname,dept,loc,job,status,type", "Skip", ",", "\\"",
"\\"", false)Open a Delimited Text file for writing.
Property | Value | Description |
|---|---|---|
filesystem | expression, variable | the filesystem definition to use (default: dss server managed files) |
fileName* | text, expression, variable | the name of the Delimited Text output file |
appendToFile | boolean, expression, variable | true if the file should be appended to (default: false) |
charSet | text, expression, variable | the character encoding of the file (default: ISO-8859-1) |
fieldNames* | text, expression, variable | comma separated string containing the names of the fields in each Record |
outputHeaderRecord | boolean, expression, variable | true if a header Record should be output containing the field names (default: false) |
fieldSeparator | text, expression, variable | the field separator character (default: ',') |
quoteCharacter | text, expression, variable | the quote character (default: '"') |
escapeCharacter | text, expression, variable | the quote character (default: the quoteCharacter) |
eol | expression, variable | the character(s) to use as end-of-line (default: '\n') |
quoteAllFields | boolean, expression, variable | quote all fields (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
csvOutput = openDelimitedTextOutput("output.csv", "utf-8",
"fname,lname,dept,loc,job,status,type", true, ",", "\\"",
"\\"", false) Open an LDIF file for writing.
Property | Value | Description |
|---|---|---|
filesystem | expression, variable | the filesystem definition to use (default: dss server managed files) |
fileName* | text, expression, variable | the name of the LDIF output file |
appendToFile | boolean, expression, variable | true if the file should be appended to (default: false) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
ldifOutput = openLDIFOutput("output.ldif", false) Open a Text file for reading.
Property | Value | Description |
|---|---|---|
filesystem | expression, variable | the filesystem definition to use (default: dss server managed files) |
fileName* | text, expression, variable | the name of the Delimited Text input file |
charSet | text, expression, variable | the character encoding of the file (default: ISO-8859-1) |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
textInput = openTextInput("input.txt", "utf-8", false) Open a Text file for writing.
Property | Value | Description |
|---|---|---|
filesystem | expression, variable | the filesystem definition to use (default: dss server managed files) |
fileName* | text, expression, variable | the name of the Delimited Text output file |
appendToFile | boolean, expression, variable | true if the file should be appended to (default: false) |
charSet | text, expression, variable | the character encoding of the file (default: ISO-8859-1) |
eol | expression, variable | the character(s) to use as end-of-line (default: '\n') |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
textOutput = openTextOutput("output.txt", false, "utf-8", false,
"\\r\\n")Put a line to a Text Output.
Property | Value | Description |
|---|---|---|
textOutput* | expression, variable | the Text Output |
line* | expression, variable | the output line |
Example
putTextOutputLine(textOutput, "The quick brown fox jumped over
the lazy dog.") Put a Record to a Text Output.
Property | Value | Description |
|---|---|---|
textOutput* | expression, variable | the Text Output |
record* | expression, variable | the output Record |
Example
record = createRecord(, ) setRecordFieldValue(record, "fname", "John") setRecordFieldValue(record, "lname", "Doe") setRecordFieldValue(record, "dept", "Sales") setRecordFieldValue(record, "loc", "CA") setRecordFieldValue(record, "job", "Manager") setRecordFieldValue(record, "status", "Active") setRecordFieldValue(record, "type", "Full-Time") putTextOutputRecord(textOutput, record)
Rewind Text Input back to the beginning.
Property | Value | Description |
|---|---|---|
textInput* | expression, variable | the Text Input |
Example
rewindTextInput(csvInput)
Example
# open csv input file using first line as field names
csvInput = openDelimitedTextInput("input.csv", "utf-8", 1, \',\\'
"\\'"\false)
# open csv output file using specified field names, don't write
header, append if existing file
csvOutput = openDelimitedTextOutput("input.csv", false, "utf-8",
"sn,givenName,gender,species", true, \'\\n\')
# open ldif output file
ldifOutput = openLDIFOutput("output.ldif")
# loop through input records
forEach(record, csvInput) {
# write record to output csv
putTextOutputRecord(output, record)
}
# add dn and also write to output ldif
setRecordFieldValue(record, record[\'@dn\'] , "cn=" +
record[\'givenName\'] + " " + record[\'sn\'] +
"OU=Staff,OU=Internal,DC=test,DC=local")
putTextOutputRecord(output, ldifOutput)
close(csvInput)
close(csvOutput)
close(ldifOutput)Example
# read lines from input file, transform to uppercase, and write to
output file
lineInput = openTextInput("input.txt", "utf-8")
lineOutput = openTextOutput("output.txt", "utf-8", "\\n")
forEach(line, lineInput) {
line = stringToUpper(line)\n putTextOutputLine(lineOutput, line)
}
close(lineOutput)
close(lineInput)TIES Adapter Actions
Define a connection to a TIES Server.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the Base URL of the TIES REST service, not including page number |
apiKey* | text, expression, variable | API key for authentication to the TIES REST service |
secretKey* | password, string, expression, variable | Secret key for authentication to the TIES REST service |
districtNumber* | text, expression, variable | The District Number for use with the TIES REST service |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
Global.tiesURL = "https://api.tiescloud.net"
Global.tiesApiKey = "feeddeadbeef"
Global.tiesSecretKey = <Password>
Global.tiesDistrictNumber = 4200000000
session = defineTIESConnection(Globale.tiesURL, Global.tiesApiKey,
Global.tiesSecretKey, Global.tiesDistrictNumber)Get All TIES Family Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
filter | text, expression, variable | Any additional parameters to pass to the TIES REST service |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "StudentIds", student.StudentId) families = getTIESFamilies(session, filter)
Get a given TIES Family Record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
id* | text, expression, variable | The ID of the family |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
family = getTIESFamily(session, "1234")
Gets a given TIES Staff Member Record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
id* | text, expression, variable | The ID of the Staff Member |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
staffMember = getTIESStaffMember(session, "1234")
Get All TIES Staff Member Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
filter | text, expression, variable | Any additional parameters to pass to the TIES REST service |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
teachers = getTIESStaffMembers(session)
Gets a given TIES Student Record.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
id* | text, expression, variable | The ID of the student |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
student = getTIESStudent(session, "4567")
Get All TIES Student Records.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
filter | text, expression, variable | Any additional parameters to pass to the TIES REST service |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "SchoolYear", "2015") setRecordFieldValue(filter, "Grade", "12") students = getTIESStudents(session, filter)
Open TIES Family Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
filter | text, expression, variable | Any additional parameters to pass to the TIES REST service |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "StudentIds", student.StudentId) it = openTIESFamilyIterator(session, filter)
Open TIES Staff Member Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
filter | text, expression, variable | Any additional parameters to pass to the TIES REST service |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
it = openTIESStaffMemberIterator(session)
Open TIES Student Iterator.
Property | Value | Description |
|---|---|---|
connection* | expression, variable | the TIES connection definition |
filter | text, expression, variable | Any additional parameters to pass to the TIES REST service |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
filter = createRecord() setRecordFieldValue(filter, "SchoolYear", "2015") setRecordFieldValue(filter, "Grade", "12") it = openTIESStudentIterator(session, filter)
Student
Family
StaffMember
Filter Fields (not currently documented)
Web Services Adapter Actions
All HTTP actions return a record with the following fields:
Field | Description |
|---|---|
statusCode | the HTTP status code returned from the server |
statusReason | the descriptive name of the HTTP status code returned from the server |
headers | a Record containing the HTTP header fields returned from the server |
data | the data returned from the server. Will be E4X XML object if the data is detected to be XML, an ECMAScript object if detected to be JSON, a String if detected to be any other kind of text, and a byte array if anything else |
All HTTP actions may also return undefined in the event of any error that doesn't result in at least an HTTP status.
Perform an HTTP DELETE operation.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url |
headers | expression, variable | Record or Object containing HTTP header fields |
username | text, expression, variable | username for authentication to the url |
password | password, string, expression, variable | password for authentication to the url |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = httpDELETE("http://httpbin.org/delete")
log(result ? result.statusCode + " " + result.statusReason + "\n"
+ toJSON(result.data, true) : "Missing Result")Perform an HTTP GET operation.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url |
headers | expression, variable | a Record or Object containing HTTP header fields |
username | text, expression, variable | username for authentication to the url |
password | password, string, expression, variable | password for authentication to the url |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = httpGET("http://httpbin.org/get")
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")Perform an HTTP HEAD operation.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url |
headers | expression, variable | Record or Object containing HTTP header fields |
username | text, expression, variable | username for authentication to the url |
password | password, string, expression, variable | password for authentication to the url |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = httpHEAD("http://httpbin.org/get")
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.headers, true) : "Missing Result")Perform an HTTP OPTIONS operation.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url |
headers | expression, variable | Record or Object containing HTTP header fields |
username | text, expression, variable | username for authentication to the url |
password | password, string, expression, variable | password for authentication to the url |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
result = httpOPTIONS("http://httpbin.org/get")
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.headers, true) : "Missing Result")Perform an HTTP PATCH operation.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url |
headers | expression, variable | Record or Object containing HTTP header fields |
data | expression, variable | Data to post |
username | text, expression, variable | username for authentication to the url |
password | password, string, expression, variable | password for authentication to the url |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
jsonRestMessage = toJSON({surname: "Jon", givenName: "Doe"})
result = httpPATCH("http://httpbin.org/patch", {"Content-Type": "application/json"}, jsonRestMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")Perform an HTTP POST operation.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url |
headers | expression, variable | Record or Object containing HTTP header fields |
data | expression, variable | Data to post |
username | text, expression, variable | username for authentication to the url |
password | password, string, expression, variable | password for authentication to the url |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
soapMessage =
<Envelope>
<Body>
<thankYou xmlns="urn:idauto:dss:samples:thankYouServer"/>
</Body>
</Envelope>
result = httpPOST("http://httpbin.org/post", {"Content-Type": "application/xml", SOAPAction: "thankYou"}, soapMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")Perform an HTTP PUT operation.
Property | Value | Description |
|---|---|---|
url* | text, expression, variable | the url |
headers | expression, variable | Record or Object containing HTTP header fields |
data | expression, variable | Data to post |
username | text, expression, variable | username for authentication to the url |
password | password, string, expression, variable | password for authentication to the url |
options | expression, variable | A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout. |
returnVariable | expression, variable | name of the variable to be assigned to the return value |
Example
formMessage = "surname=Doe&givenName=John"
result = httpPUT("http://httpbin.org/put", {"Content-Type": "application/x-www-form-urlencoded"}, formMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")Usually for HTTP Basic Authentication, the client makes a request without the credentials and the server responds with a challenge telling the client what kind of authentication it needs to perform the operation. The client then reissues the request with the provided credentials. For some web services, the server does not issue the challenge, but rather expects the client to send any the credentials without being asked for them. Usually this is the case when some requests can be processed without any authentication, but will provide a different answer based on being authenticated as a known user who has more rights. This is known as unsolicited authentication. The Web Service Adapter will perform unsolicited authentication if you provide the X-UnsolicitedBaseAuth header with a non-null value.
Example
formMessage = "surname=Doe&givenName=John"
result = httpPUT("http://httpbin.org/put", {"Content-Type": "application/x-www-form-urlencoded", "X-UnsolicitedBaseAuth": "1"}, formMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")The Web Service Adapter supports implementing SOAP endpoints using an Action Set.
The Action Set MUST define at least one input parameter. Any additional input parameters must be defined as optional. When invoked as an endpoint, the first input parameter will contain an E4X XML object that represents the SOAP message and is guaranteed to be a valid SOAP Envelope. Any additional input parameters will have the value undefined.
The Action Set MUST return a valid SOAP Envelope (either as a String or as an XML object). Failure to do so will result in a SOAP Fault message being returned to the client. The SOAP version of the returned Envelope SHOULD match the SOAP Version of the Envelope provided as the first input parameter.
Other than the above requirements, the Action Set MAY exercise any/all DSS capabilities for which the server is licensed.
An Action Set is invoked as a SOAP endpoint by POSTing a valid SOAP 1.1 or SOAP 1.2 Envelope to a URL of the form:
http[s]:server[:port]/dss/services/soap/<action-set-name> * Clients that cannot gracefully handle an HTTP return code of 500 Internal Server Error (e.g. Flash/Flex) , should post to the alternate URL which will return 200 OK even when there is a SOAP Fault: * http[s]:server[:port]/dss/ws/dss/soap/<action-set-name>
Invoking an Action Set as SOAP endpoint MUST provide valid credentials of a User that is authorized to run the Action Set (e.g. have role Administrator or Operator) using one of the following methods.
HTTP Basic Authentication; OR
Providing the credentials as query parameters on the URL:
?authUser=<user>&authPassword=<password>
An Action Set invoked as a SOAP endpoint will write its execution log to a file on the DSS server exactly as it would if it were invoked manually using the runAsync or runForValue REST resource endpoints. The log will contain detailed trace information if and only if the URL has the trace=true query paramter appended.
An Action Set that implements a SOAP endpoint MAY still be invoked/called like any other Action Set provided that the required first parameter is supplied. Calling the SOAP endpoint Action Set from a wrapper Action Set is usually the simplest way to test/debug the Action Set.
Example
# define the soepenv and thanks namespaces so we can use them in e4x expressions
# (since differing namespaces for different versions of SOAP, respond with the same SOAP version as the request)
soapenv = message.namespace()
thanks = "urn:idauto:dss:samples:thankYouServer"
# Start off with a mostly empty response
response = <Envelope xmlns={soapenv}> <Body/> </Envelope>
responseBody = response.soapenv::Body
# Check that request body has a thanks::thankYou element
thankYou = message.soapenv::Body.thanks::thankYou[0]
if(!thankYou) {
# Fault structure is different in SOAP 1.2 than SOAP 1.1
if(soapenv == "http://www.w3.org/2001/06/soap-envelope") {
# SOAP 1.2
fault = <Fault xmlns={soapenv} xmlns:soapenv={soapenv}> <Code> <Value>soapenv:Sender</Value> </Code> <Reason> <Text>Missing thankYou element</Text> </Reason> </Fault>
} else {
# Check that request body has a thanks::thankYou element
# Fault structure is different in SOAP 1.2 than SOAP 1.1
fault = <Fault xmlns={soapenv} xmlns:soapenv={soapenv}> <faultcode>soapenv:Client</faultcode> <faultstring>Missing thankYou element</faultstring> </Fault>
}
dummy = responseBody.appendChild(fault)
} else {
youreWelcome = <youreWelcome xmlns={thanks}/>
dummy = responseBody.appendChild(youreWelcome)
}
# return the response
return response.toXMLString()Workday Adapter Actions
Workday adapter actions are deprecated - these functions are now performed by a Web Service adapter to access the current API directly.
Documentation from Workday
Useful information on the Workday API.
RapidIdentity Developer Guides
RapidIdentity Agent Guides
In RapidIdentity, agents act as an intermediary between RapidIdentity and an application or service provider to facilitate extract, transform, and load (ETL) operations.
The agents are only used when the APIs provided by the application or service provider and are not directly accessible by the RapidIdentity Linux appliance.
Credential Provider Install Guide
The RapidIdentity Credential Provider can be installed in three different pathways.
A single workstation prompted dialog using an msi file.
An unprompted command line installation.
Active Directory Group Policy Object.
System Requirements
Prior to installing the Credential Provider, ensure the environment meets the following requirements.
Workstation with:
Intel/AMD x86 or x86-64 processor
Microsoft Windows 7 or later
Administrator access
Browser access to RapidIdentity 2017.x.x or higher with the Portal Capability is enabled.
Single Workstation Installation
Installing the RapidIdentity Credential Provider to a single workstation requires running the .msi installation file, which will provide a normal, prompted installation.
These files can be downloaded through the RapidIdentity Appliance downloads.
Standard (unprompted) Workstation Installation
Standard (unprompted) workstation installation of the RapidIdentity Credential Provider Module is accomplished from a command-line execution and requires Administrator or System privileges.
Follow these three steps to install the credential provider through the command line.
Right mouse click the shortcut for Command Prompt , select Run as , and choose Administrator.
Run the command listed below using the syntax provided:
msiexec /passive /i <UNC path of .msi file to install> ARMSURL=https://<RapidIdentity Portal Address> ALLUSERS=1
After successful installation of the RapidIdentity Credential Provider Module and upon next user login to the workstation, the option to Switch User will have an additional user entry named Forgot My Password displays. The Identity Automation logo is displayed as its user picture.
If the RapidIdentity server URL needs to be modified after completing the installation, it is best to uninstall the Credential Provider and then reinstall the Credential Provider with the revised URL.
Active Directory Group Policy Object (GPO) Installation
A GPO created for “Software installation” will set up the RapidIdentity Credential Provider Module, but without command-line options, and there is no simple way to configure the standard Software Install, to add the command line options.
The workaround to add the command line options is to create a batch file (example: InstallRapidIdentityCentralProvider.cmd contents, below in the Notes section) containing the proper command-line for install, as noted in the “Standard Workstation Installation” above.
Then, setup a GPO, associated to Domain Computers, and configure as follows:
Run Command Prompt as an Administrator on a domain controller and enter
gpme.msc.Select the default Domain Policy (or other policy as applicable) and press OK.
In the left panel, navigate to and select Computer Configuration > Policies > Windows Settings > Scripts.
In the right panel, double-click Startup.
In the Script Name field, enter the UNC path of the script and click OK.
Click OK.
At the next user login, assuming the machine is associated with the Active Directory domain and that it has been rebooted, the machine will run the script / batch file in the background, and install the Credential Provider with proper rights to make the registry changes.
The next time a user logs out and selects to change user, the Credential Provider user will be accessible to allow for a password change.
Notes - Credential Provider Install Guide
The RapidIdentity Credential Provider requires a trusted certificate, as described above.
Example InstallRapidIdentityCentralProvider.cmd
:CheckOSIF EXIST "%PROGRAMFILES(X86)%"
(GOTO 64BIT)
ELSE
(GOTO 32BIT)
:64BIT msiexec /passive /i \\<address of shared software server>\
<shared software directory ARMSURL=https://<portal server ip>/portal
GOTO END
:32BIT msiexec /passive /i \\<address of shared software server>\
<shared software directory
GOTO END
:ENDCredential Provider User's Guide
The RapidIdentity Credential Provider is a self-service feature to enable users to reset a forgotten domain password.
The domain password can be reset without contacting the HelpDesk, provided the user can confirm their identity by answering their configured challenge-response questions correctly.
Change a Forgotten Password
Follow these steps to access the Credential Provider and reset a forgotten password.
Click on the Switch User button on the login screen and then click the Forgot My Password user.
Click Reset Password.
Enter the domain username and click Next.
Answer your challenge questions to validate your identity and click Next.
Enter a new password to match the policy description and click Next.
Finally, click either of the two links to proceed.
Exchange/Office 365 Agent Guides
The following guides provide detailed information on installing Exchange 2007, Exchange 2010/2013, and Office 365 Agent:
Exchange Agent Install Guide for Exchange 2010/2013
System Requirements
System Hosting Exchange
Exchange 2013+
Windows PowerShell and winRM 3.0 or higher
Note
The Agent may be deployed on the same server hosting Exchange (if it meets the OS requirements) or a different server in the same domain.
System Hosting Agent
Windows Server 2012 or newer
Note
The server on which the agent is running must have Windows Management Framework (WMF) 5.1.
Windows PowerShell and WinRM 3.0 or higher
Internet Information Services (IIS) 7 or higher
.NET Framework 4.x
Must have access to:
Package Provider: NuGet
Up-to-date modules:
PowerShellGet
MSOnline
Note
The RapidIdentity Exchange Administrative Web Service Agent exposes the Powershell based Exchange ManagementAPI as a web service for consumption by the Exchange and Office 365 adapters.
Installing/Configuring the Prerequisites
Both Systems
Make sure .NET Framework 4.0 or newer is installed.
Make sure Windows Management Framework (Windows PowerShell 3.0 and WinRM 3.0) or newer is installed.
Configure WinRM listener using 'winrm qc'.
System Hosting Exchange
In Internet Information Services (IIS) Manager:
Make sure Powershell virtual directory is configured to allow Windows Authentication.
System Hosting Agent
In Server Manager:
Under Roles, make sure Web Server (IIS) Role is installed, and the ASP.NET and IIS 6 Management Compatibility Role Services have been added to it.
In Internet Information Services (IIS) Manager:
Configure the IIS site that will host the service (can use the default website). It is strongly recommended that the site is configured to support or even require HTTPS connections.
Ensure ASP.NET is registered with IIS by running
%WINDIR%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis -i
Installing the Agent
If your environment is running RapidIdentity Connect 4.0 or later with Exchange 2013 or higher, download the most current version of the agent which will be listed at the top of the directory with a name format ending in yyyy.m.d.msi. In this example, the most current agent is idautoExchangeAdminWSInstaller-2018.3.1.msi.
Run idautoExchangeAdminWSInstaller.msi
When prompted, select the IIS Site.
Verifying Your Installation in Exchange 2013 or Newer
You can verify that the RapidIdentity Exchange Administrative Web Service Agent is working correctly by accessing the agent through a web browser using a URL of the form:
http[s]://<hostname>[:<port>]/idautoExchangeAdminWS/test
where <hostname>[:<port>] is the hostname and port of the IIS site hosting the Agent
In the resulting page, select Exchange 2013 or newer, and enter the Exchange server name, and username/password for the administrative user, and press Test.
Office 365 Agent Install Guide
Microsoft Awareness
Microsoft periodically updates its requirements, links, and nomenclature without prior notice.
Thus, some downloads and installations may not exactly correspond to a particular environment, or the Microsoft links may break due to a Microsoft content reorganization. If any of these events occur please contact Support to initiate the troubleshooting and updating processes.
System Requirements
Windows 2012R2 Server (or higher)
Note
The server on which the agent is running must have Windows Management Framework (WMF) 5.1.
Windows PowerShell and WinRM 3.0 or newer
Internet Information Services (IIS) 7 or newer
.NET Framework 4.x or higher
Microsoft Online Services Sign-In Assistant
MSOnline PowerShell for Azure Active Directory
SharePoint Online Management Shell (Only required for SharePoint Online support)
Must have access to:
Package Provider: NuGet
Up-to-date modules:
PowerShellGet
MSOnline
Note
The RapidIdentity Connect Exchange Administrative Web Service Agent exposes the Powershell based Exchange ManagementAPI as a web service for consumption by the Exchange and Office 365 adapters.
MSOnline PowerShell for Azure Active Directory Requirement
MSOnline PowerShell for Azure Active Directory currently requires the PowerShellGet module and should be installed prior to starting the process linked to MSOnline PowerShell for Azure Active Directory.
Installing/Configuring the Prerequisites
If running a version of Windows Server 2008R2:
Download and install .NET Framework 4.0 or higher.
Download and install Windows Management Framework (Windows PowerShell 3.0 and WinRM 3.0) or newer is installed.
Download and install both Microsoft Online Services Sign-In Assistant and MSOnline PowerShell for Azure Active Directory.
If Sharepoint Online support is desired, download and install Sharepoint Online Management Shell.
In Server Manager (2008R2):
Under Roles, make sure Web Server (IIS) Role is installed, and ASP.NET have been added to it.
Under Role Services, make sure IIS 6 Management Compatibility has been added
In Server Manager (2012):
Under Roles, select Web Server (IIS)
Under Features, make sure the all the .NET Framework 4.5 features are installed.
Under Role Services, make sure IIS 6 Management Compatibility has been added
In Internet Information Services (IIS) Manager:
Configure the IIS site that will host the service (can use the default website). It is strongly recommended that the site is configured to support or even require HTTPS connections.
Ensure ASP.NET is registered with IIS by running ”%WINDIR%\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis -i”
In the Office 365 admin panel, validate that the account being used by the agent holds the Global Administrator role (required to retrieve/submit information through remote power shell calls)
Installing the Agent
Exchange 2007 / 2010 is known to have incompatibilities with PowerShell 3 and .NET4, and a given .NET executable cannot be built to support both PowerShell 3 and .NET4
Run idautoExchangeAdminWSInstaller.msi.
When prompted, select the IIS Site you configured above.
Verifying Your Installation in Office 365
You can verify that the RapidIdentity Connect Exchange Administrative Web Service Agent is working correctly by accessing the agent through a web browser using a URL of the form:
http[s]://<hostname>[:<port>]/idautoExchangeAdminWS/test
where <hostname>[:<port>] is the hostname and port of the IIS site hosting the Agent
In the resulting page, select Exchange 2010 or higher, and enter the Exchange server name, and username/password for the administrative user, and press Test.
Notes Agent Install Guide
System Requirements
IBM Domino Server 8.0.x or higher.
Preparing the Domino Server
The agent should be installed on a Domino server that holds a replica of the databases that will be managed by DSS (usually names.nsf).
The Domino server must be configured to run the HTTP task with the SSL port enabled.
How to enable SSL in Lotus Domino (Self-signed only)
Installing the Agent
Download idautoAgent.nsf and place it in the Domino data folder.
On Unix/Linux systems, make sure that that idautoAgent.nsf is owned by the Domino user (usually notes) and has a permissions mask of 0644.
In the Files tab in Domino Administrator or Domino Web Administrator, select idautoAgent.nsf and:
Tools | Database | Manage ACL
Make sure entries for LocalDomainAdmins and LocalDomainServers exist and are set to allow Manager access.
Make sure the -Default- and OtherDomainServers entries exist and are set to No Access.
Delete any other entries.
Tools | Database | Sign
Sign design documents with the server id.
Restart the HTTP task.
Verifying Your Installation in Notes
You can verify that the DSS Notes Agent is working correctly by accessing the agent through a web browser using a URL of the form:
https://<hostname>[:<port]/idautoAgent.nsf/ws
If working correctly, you be prompted for username and password: Enter the username and password of a member of the localdominoadministrator group. After successfully authenticating, you should see a bullet list like:
NotesAgent(wsdl)
getVersion
RapidIdentity API Guides
All RapidIdentity APIs are defined by Swagger, and the URL that returns the Swagger-defined APIs reflect the RapidIdentity APIs with respect to the Rolling or Long Term Support Release installed.
RapidIdentity Authentication API Guides
There are three main API calls involved in the Modular Authentication API.
Endpoint | Description |
|---|---|
GET /idp/ws/rest/authn/krb | Attempt to initialize the process with Kerberos SSO. See Kerberos. |
GET /idp/ws/rest/authn | Initialize the authentication process and receive the initial authentication step. See Initialization. |
POST /idp/ws/rest/authn | Submit an authentication step and receive the next step. |
Each response from the server and associated request from the client is a JSON object which has at the very minimum a type and id field.
In a response from the server, the type field indicates the next authentication method required to proceed.
The id field is an opaque value which has no meaning in-and-of-itself. All requests from the client should contain the same id value which was previously included in the response from the server.
During the authentication process, the server currently maintains session data using the Java HttpSession mechanism and this is bound to a particular client using a HTTP Cookie. This implies that the client must support cookies in order to use RapidFederation Modular Authentication.
The Authentication API Consumer allows access to all of the API endpoints listed in the table below.
Authentication Method API | Details |
|---|---|
Username | This API should be used to identify a user by "username" and receive the idautoID of that user. |
QR Code | This API should be used to identify a user by QR code and receive the idautoID of that user. |
OTP | This API should be used to authenticate a user by OTP code. |
Pictograph | This API should be used to authenticate a user by Pictograph code. Pictograph authentication requires the client to first request a "challenge set" from the server. The response contains various inner and outer arrays. The inner arrays include objects that represent a set of images to be used to challenge the user, along with the valid choice for the user. The outer array contains "n" inner arrays where "n" is also the number of choices the user must answer correctly. ImportantWhen the client requests the Pictograph challenge for a particular user, the response will include a "cookie" string. This value must be included in the next request that includes the list of selected image IDs to successfully complete a Pictograph authentication. |
PingMe | This API should be used to authenticate a user by PingMe code. PingMe authentication is performed by first requesting the server send a PingMe notification to all of the target user's registered devices and then polling for the response. |
Proximity Card | This API should be used to identify a user by proximity card (contactless smart card) and receive the idautoID of that user. |
Exchange | The Exchange API may be used by the client to exchange claims previously received on behalf of an authenticating user. |
Available Authentication Methods
Failure
If an un-recoverable failure occurs during the authentication process the server will send a response with the type property value fail and generally some kind of error object that in some way explains what went wrong. The only reasonable thing for the UI to do in this situation is to display the error message and allow the user to start over.
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "fail",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"error": {
"type": "simple",
"message": "Unable to complete the authentication process. Please try again later"
}
}Completion
When the authentication process has completed successfully, the server will send a response with the type property value complete.
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "complete",
"id": "931c4a40-2dc9-11e6-937b-005056c00008"
}In order to finalize the SAML authentication process, the browser should then issue a POST to /idp/authn/idauto with a parameter complete and a value of 1. This will indicate to the IdP's SAML engine that the user has authenticated successfully and the user should then be forwarded on to their destination application with a valid SAML Assertion.
FIDO Authentication
Here is an example response from the server indicating that FIDO Authentication is required as the next step:
Note
Displayed values have been truncated here for formatting purposes, but the strings listed here should represent actual, usable values when generated in a production environment.
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"step": {
"appId": "https://rapidIdentity.example.com:8443/FIDO/appId",
"challenge": "g9WMWOFyFef8x9nNwt4zfZnJhaLHoSyKEprXT_EGPxU",
"devices": [
{
"name": "FIDO Device - (ID: a28af5qa-f4r2-4271-a926-7d09537f869c)",
"deviceId": "a24af5ca-f4f2-4171-a936-7d01567f869c",
"keyHandle": "jwCS9L5WAxN4PjZFjIOgv-D9FE0Fze_[...]_CsCSUQtI__[...]"
}
],
"type": "authenticate",
"userId": "8e123420-00e4-11r6-c668-005056r00008",
"version": "U2F_V2"
},
"type": "fido"
}Note that the value of the type property is fido and the step.type property is authenticate.
When responding to the FIDO Authenticate response, a value for the clientData and signatureData properties are required. These values should be generated between the FIDO device and client.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"step": {
"clientData": "eyJvcmlnaW4iOiJodHRwczovL2xvY2FsaG9zdDoyNTE0OCIsImNpZF9wdWJrZ[...]",
"signatureData": "AQEBAQEiYycLYY0_EHePpkSt22mTwjZJ2HMCIF9IE_gT0jmxaknCyM4cbp[...]",
"defer": false,
"type": "authenticate"
},
"type": "fido"
}Here is an example response from the server indicating that FIDO Registration is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"step": {
"appId": "https://rapidIdentity.example.com:8443/FIDO/appId",
"challenge": "g9WMWOFyFef8x9nNwt4zfZnJhaLHoSyKEprXT_EGPxU",
"passwordRequired": true,
"name": "FIDO Device - (ID: a28af5ca-f4f2-4271-a946-7d09567f869c)",
"deviceId": "a28af5ca-f4f2-4271-a946-7d09567f869c",
"type": "register",
"userId": "8e193920-00e4-11e6-a668-005056c00008",
"version": "U2F_V2"
},
"type": "fido"
}Note that the value of the type property is fido and the step.type property is register.
When responding to the FIDO Register response, a value for the clientData and registrationData properties are required. These values should be generated between the FIDO device and client. The password property is only required if the user has yet to enter a password or authenticate using a Pre-Auth authentication type.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"id": "e230e2e0-25re-11s5-8da9-0050b6c32ffc",
"step": {
"clientData": "eyJvcmlnaW4iOiJodHRwczovL2xvY2FsaG9zdDoyNTE0OCIsImNpZF9wdWJrZXki[...]",
"registrationData": "BQQtRU22R6qjdGYw3d1JWg5dxy7W2Y8_YXxbYLyn_NzXV6SNhabfaoSzkDwsoheJ[...]",
"password": "p@$$w0rd",
"type": "register"
},
"type": "fido"
}Initialization
If Kerberos authentication was not successful, then the way to proceed is to issue the following request:
GET /idp/ws/rest/authn HTTP/1.1 Accept: application/json
The response from the server will always be of type username, username+password or policyChoice and will contain other pieces of information needed to construct the initial authentication page:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"availableRealms": [
{
"id": "internal",
"name": "Internal"
},
{
"id": "11541860-161f-11e6-aec5-005056c00008",
"name": "Realm 1"
},
{
"id": "233d3570-161f-11e6-aec5-005056c00008",
"name": "Realm 2"
}
],
"allowQRCodeScan": false,
"allowKerberos": false,
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
]
}Let's ignore the type for now, it will be discussed later.
The id property is a value that must be included in the subsequent request
The availableRealms property is an array of authentication realms to which the user may authenticate. This is only included if RapidFederation is currently configured for realms other than the default which has the id value of internal.
The allowQRCodeScan property is a boolean indicating that the user may initiate the authentication process by scanning a QR code
The allowKerberos property is a boolean indicating that the user may initiate the authentication process by attempting Manual Kerberos Authentication.
The claimAccountLink object contains the link location (href) as well as the text to display on the button (displayName) which allows a user to claim their account. This object will only be included in the response if the link should be displayed.
The helpLinks property is an array of objects describing help links and their display names which should be available to the user when they click the "Need help?" button on the login page. If no help links are configured, this property will not be included.
Username/Password
This initial authentication step is required if the type property in the initial response has the value username+password. It indicates that
There are no enabled Authentication Policies defined for RapidFederation OR
All enabled Authentication Policies require Password as the initial authentication method
A valid username and password combination is required to proceed to the next authentication step:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser",
"password": "mysecurepassword"
}Additionally, if authenticating against a realm other than internal is desired, the realm property may be included in the request body:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"realm": "233d3570-161f-11e6-aec5-005056c00008",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser",
"password": "mysecurepassword"
}Here is an example of a response from the server if the username/password combination sent in the request is incorrect:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"availableRealms": [
{
"id": "internal",
"name": "Internal"
},
{
"id": "11541860-161f-11e6-aec5-005056c00008",
"name": "Realm 1"
},
{
"id": "233d3570-161f-11e6-aec5-005056c00008",
"name": "Realm 2"
}
],
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
],
"error": {
"type": "simple",
"message": "Incorrect Username and/or Password"
}
}Notice the error property in the response. It has a type value of simple which means that the associated message should be displayed to the user.
Here is an example of the response from the server if the username & password combination were correct but the user is required to update their password before continuing:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "username+password",
"id": "cd4f0ab0-2dc7-11e6-937b-005056c00008",
"availableRealms": [
{
"id": "internal",
"name": "Internal"
},
{
"id": "11541860-161f-11e6-aec5-005056c00008",
"name": "Realm 1"
},
{
"id": "233d3570-161f-11e6-aec5-005056c00008",
"name": "Realm 2"
}
],
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
],
"error": {
"type": "password-expired",
"message": "Your password is expired and must be updated before continuing",
"expiredPasswordText": "CLICK HERE to change your password.",
"targetUrl": "/arms/expired-password",
"username": "8kb+8GQVM2HUGJQtMRxKjNFfUNuboOhcdtBw8VtIlZU=",
"password": "78EV3jkq6IYu/8S2rC4M54NQYwTQRPRaUEaFuNdRx6w="
}
}Notice the error property in the response. It has a type value of password-expired which indicates that the user must change their password and the associated message should be displayed to the user to let them know. The expiredPasswordText, targetUrl, username and password property values are used to construct a link which, when clicked, submits a form in a new window which POSTs the obfuscated username and password to the targetUrl.
Username
This initial authentication step is required if the type property in the initial response has the value username. It indicates that
There is at least one enabled Authentication Policies defined for RapidFederation AND
At least one of the enabled Authentication Policies requires an initial authentication method other than Password.
A valid username is required to proceed to the next step:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser"
}Additionally, if authenticating against a realm other than internal is desired, the realm property may be included in the request body:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "username+password",
"realm": "233d3570-161f-11e6-aec5-005056c00008",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"username": "someuser"
}
If a username which does not successfully map to a valid account is provided in the username request, it will kick off a "Bogus" authentication flow which will always fail.
PolicyChoice
This authentication step allows users to select which authentication policy they want to use to authenticate, and is only present if:
There are multiple authentication policies which are applicable to a user
Authentication Policy Options have been "opted-in" to
Here is an example of the response from the server if either username or username+password has been completed successfully and authentication policy options are enabled:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "policyChoice",
"id": "2f875a60-dbfc-11e6-8449-005056c00008",
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
],
"policies": [
{
"id": "5fda6a30-d1ee-11e6-8629-005056c00008",
"methods": [
{
"type": "password"
}
]
},
{
"id": "4101afb0-d1ee-11e6-8629-005056c00008",
"methods": [
{
"type": "password"
},
{
"type": "rapidPortalChallenge"
}
]
}
]
}Next, the user returns a request with the policy ID that they would like to authenticate with:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"id": "65a22d80-d9c9-11e6-9ed6-005056c00008",
"type": "policyChoice",
"policyId": "5fda6a30-d1ee-11e6-8629-005056c00008"
}Kerberos
If the API is being invoked from a browser, the first step in the process should be attempting Kerberos SSO. The following request should be issued:
GET /idp/ws/rest/authn/krb HTTP/1.1 Accept: application/json
If Kerberos authentication is successful, the server will return a status of 200 and the JSON data for the next authentication step to perform will be included in the response. In the event that Kerberos is the only authentication method required for the user, the next step will of type compete which indicates that no further authentication steps are required.
If Kerberos authentication is successful it means that the username of the user is known and a username prompt is not required to initiate the RapidFederation authentication process.
If any other status besides 200 is returned, then it means that Kerberos authentication failed and the authentication process should proceed with the Initialization step.
Manual Authentication
An internal engineering ticket was opened to address an issue with automatic Kerberos processing and, as such, we've had to slightly adjust how Kerberos works. Specifically, there is a new option in the Kerberos Configuration which allows an admin to toggle "Automatic Kerberos Processing". From the server's point of view if automatic processing is turned off, this means that all Kerberos requests made at the very beginning of the process will automatically fail, however the response from the normal init call at /idp/ws/rest/authn/ will have a new allowKerberos flag set to true. This indicates to the client that manual Kerberos authentication is enabled and the user should be given the option to do so if they wish. A manual Kerberos request is exactly the same as the automatic one except that a request parameter requested must be present with the value true.
GET /idp/ws/rest/authn/krb?requested=true HTTP/1.1 Accept: application/json
Everything else about the response will be the same as with automatic processing.
As an Authentication Method
If the Kerberos authentication method is enabled for a given policy, it means that Kerberos authentication is required to have completed successfully or authentication will automatically fail.
As an Authentication Policy Criteria
If Kerberos criteria is enabled for a given policy, it means that only users who have successfully completed Kerberos authentication will be eligible for that policy.
Example Javascript
This example demonstrates how to attempt Kerberos authentication against RapidFederation using JQuery
< script >
$.ajax({
type: 'GET',
url: '/idp/ws/rest/authn/krb',
cache: false,
async: true,
xhrFields: {
withCredentials: true
}
}).done(function(data) { //data should contain a JSON object }).fail(function() {
//kerberos failed, go ahead and call /idp/ws/rest/authn to get the first step
});
</script>Password Authentication Method
Here is an example response from the server indicating that password authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "password",
"id": "931c4a40-2dc9-11e6-937b-005056c00008"
}Note that the value of the type property is password.
In addition to sending the standard id and type properties with the next request, the only other thing required is a valid password:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "password",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"password": "mysecurepassword"
}If the password provided is correct, then the next authentication step will be returned by the server. If not a password type will be returned with an error property.
Here is an example of a response from the server if the password sent in the request is incorrect:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "password",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"error": {
"type": "simple",
"message": "Incorrect Username and/or Password"
}
}Notice the type of the error is simple. This indicates that the associated message should be displayed to the user and they should be prompted again for a valid password.
Here is an example of the response from the server if the password was correct but the user is required to update their password before continuing:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "password",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"error": {
"type": "password-expired",
"expiredPasswordUrl": "https://customer.rapididentity.com/",
}
}Notice the type of the error is password-expired. This indicates that the user must change their password. If expiredPasswordUrl is not included in the response, it indicates that the Expired Password Flow should be executed against the current server URL. If the property is included in the response, the Expired Password Flow should be executed against the server whose URL is provided.
If RapidIdentity detects that a user's password is expired during a login attempt, here are the new APIs to facilitate a successful password change.
Once the user's password is detected as expired, here is the new update password init request:
POST /expiredPassword/init HTTP/1.1
Content-Type: application/json
{
"userId": "321g4a40-2dd4-11e6-937b-005056c24006",
"currentPassword": "mysecurepassword"
}If the request is successful, the server will respond with the following response, containing a token and the password policy associated with the user:
HTTP/1.1 200 OK
Content-Type: application/json
{
"token":"wsJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.bEkmBEgjf7PivEbXkJjg5PYABZ8DooSUO1jAWTBfY4ZfNWvtxjss1l2k_00WV8Kfuc9XQGVWDgbJe6nYZE5kY95SZ144ioDdS0a7aCeMKS2azFI142iBx5P1vNakYRoVhV7dwCYN7oLHXQBe7fqaYHDbUStCrGzm1rOe4jFTfOHrNIve6x4aLdW3N4M7inTdZK7v3t2_FeCbG9g06A09N75jmJ26uwcQXh7eez9nEnBrzeh7JnGA18UJsYHhpaoqftdMV52NDNIw6os7zM9352R3xEzZErK-mD0Cw42G1zr9zk_dfd0z0RyF5pr9yFVYbY9mga6_vVmBOhTsnFzPIA.4XSwi4xokumtM-w7.3sBpe1XM34pG2CkKl9XUvSLd9y2C7A4I3Nz5PNNw1ZLzGecverVYkh5HKpjH9EI-6Qv4rfovzpqh_rt-JbaBNhqU5jZgA0v4HEQJwJaY8oJ7Q8TI3oiLtqvi-r6kmXKDixSj7BbwQ5kQ2o4S9Wx13O60MtzCH7dvFryRxHYvyblvSUpSXoqKGy5Zljf7nWPLFjq2RYRG6vUHkOE1CfYO2BqoEkTILe7Eqg4sD7BiTilz2u90uGIRafxdC0PUThMfNY6zlGH0LsT9YUDmU4O2pWGz5yzHYNXKRAHRUu-Oz3KQI0FVNXdKEiQl6CWeErOxM8Efin67TKZUVx745ddL-BZGqoyaEmktu71mfRMHXX6sDBQwvQdXeZG3VpHdbqvU9ycavjsEJhnEVFBaTrpu5G-nTiX0yZKRMeIKyIr1PsoGRgqNTfL7W1lGCb68n45UNXIr2sq3eGS8arCIAPzYPszPGDkWzXNy4EF8dMY4py9ml29GLm2QTTW4rEL6d2VU-rebf5JstINVg5s-We-ugyEyBVE-03VjpZRMFkA3jMNbm_kK5UTU0bi7BYb2912wA6Mcc0wCPK_3F1pW2Zljgto1isBOk9--iR5MIuVt91rxfUs7Fzv2-wFrni2aaW1dxgIjmb_rnBlM_mH4USFtC2ueNv-Vz-QQBOm37W0I-KSXBuiDl_qUMRBDE0DKDsgyuAJ2a9dmVF9F5Oqw5wvQEtQttbJfh0RhhB8WX42kK5cNIp96da4kSxvLplPpAh33kv2WGLcjMoxnWGEdjo2e2Riz2IxWg3mMOoAoRM3uCIJUi6Z83SdmmfpCcl2uV_1ztgplmiayLpj6Pa68AxkM7wt7tASH9GcVN92zvFWgKco033RE6jRGWPNXtOhVvgQPaEUI0E4te3_CXhGB2WPmKKPIsBiBWDZFA34cVMQbUSUTfM-PwYBPdAf-.pK1LGDsQ0W12JJZLz_sD3x",
"passwordPolicy": {
"id": "c61e98ee-204b-405f-a271-d351a8ecf784",
"name": "Default Password Policy",
"description": "[Add a description]",
"minLength": 3,
"maxLength": 255,
"charSets": [
{
"id": "charset.lower",
"type": "LOWER",
"min": 1,
"max": 0
},
{
"id": "charset.digits",
"type": "DIGITS",
"min": 1,
"max": 0
},
{
"id": "charset.symbols",
"type": "SYMBOLS",
"min": 1,
"max": 0
},
{
"id": "charset.upper",
"type": "UPPER",
"min": 1,
"max": 0
}
],
"requiredCharSets": 0,
"allowRandomPassword": false,
"matchingAttributesCaseSensitive": false,
"matchingAttributesMatchEntire": false,
"blackListed": [],
"blackListCaseSensitive": false,
"blackListMatchEntire": false,
"blackListRegexes": [],
"defaultForceUserPasswordChange": true
}
}The next step will be to test the user's new password against the password policy. An example of that request would be:
POST /expiredPassword/test HTTP/1.1
Content-Type: application/json
{
"token":"wsJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.bEkmBEgjf7PivEbXkJjg5PYABZ8DooSUO1jAWTBfY4ZfNWvtxjss1l2k_00WV8Kfuc9XQGVWDgbJe6nYZE5kY95SZ144ioDdS0a7aCeMKS2azFI142iBx5P1vNakYRoVhV7dwCYN7oLHXQBe7fqaYHDbUStCrGzm1rOe4jFTfOHrNIve6x4aLdW3N4M7inTdZK7v3t2_FeCbG9g06A09N75jmJ26uwcQXh7eez9nEnBrzeh7JnGA18UJsYHhpaoqftdMV52NDNIw6os7zM9352R3xEzZErK-mD0Cw42G1zr9zk_dfd0z0RyF5pr9yFVYbY9mga6_vVmBOhTsnFzPIA.4XSwi4xokumtM-w7.3sBpe1XM34pG2CkKl9XUvSLd9y2C7A4I3Nz5PNNw1ZLzGecverVYkh5HKpjH9EI-6Qv4rfovzpqh_rt-JbaBNhqU5jZgA0v4HEQJwJaY8oJ7Q8TI3oiLtqvi-r6kmXKDixSj7BbwQ5kQ2o4S9Wx13O60MtzCH7dvFryRxHYvyblvSUpSXoqKGy5Zljf7nWPLFjq2RYRG6vUHkOE1CfYO2BqoEkTILe7Eqg4sD7BiTilz2u90uGIRafxdC0PUThMfNY6zlGH0LsT9YUDmU4O2pWGz5yzHYNXKRAHRUu-Oz3KQI0FVNXdKEiQl6CWeErOxM8Efin67TKZUVx745ddL-BZGqoyaEmktu71mfRMHXX6sDBQwvQdXeZG3VpHdbqvU9ycavjsEJhnEVFBaTrpu5G-nTiX0yZKRMeIKyIr1PsoGRgqNTfL7W1lGCb68n45UNXIr2sq3eGS8arCIAPzYPszPGDkWzXNy4EF8dMY4py9ml29GLm2QTTW4rEL6d2VU-rebf5JstINVg5s-We-ugyEyBVE-03VjpZRMFkA3jMNbm_kK5UTU0bi7BYb2912wA6Mcc0wCPK_3F1pW2Zljgto1isBOk9--iR5MIuVt91rxfUs7Fzv2-wFrni2aaW1dxgIjmb_rnBlM_mH4USFtC2ueNv-Vz-QQBOm37W0I-KSXBuiDl_qUMRBDE0DKDsgyuAJ2a9dmVF9F5Oqw5wvQEtQttbJfh0RhhB8WX42kK5cNIp96da4kSxvLplPpAh33kv2WGLcjMoxnWGEdjo2e2Riz2IxWg3mMOoAoRM3uCIJUi6Z83SdmmfpCcl2uV_1ztgplmiayLpj6Pa68AxkM7wt7tASH9GcVN92zvFWgKco033RE6jRGWPNXtOhVvgQPaEUI0E4te3_CXhGB2WPmKKPIsBiBWDZFA34cVMQbUSUTfM-PwYBPdAf-.pK1LGDsQ0W12JJZLz_sD3x",
"newPassword": "mynewsecurepassword"
}If the request is successful, then the server will respond with the following:
HTTP/1.1 200 OK
Content-Type: application/json
{
"result": true
}If an error occurs during the request, there will be a similar response with an added message property that looks like this:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"httpStatusCode": 400,
"message": "Error message details",
}The final API is the request to update the user's password. The request body is the exact same as the request to test the user's new password; however, the URL is different.
POST /expiredPassword/updatePassword HTTP/1.1
Content-Type: application/json
{
"token":"wsJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.bEkmBEgjf7PivEbXkJjg5PYABZ8DooSUO1jAWTBfY4ZfNWvtxjss1l2k_00WV8Kfuc9XQGVWDgbJe6nYZE5kY95SZ144ioDdS0a7aCeMKS2azFI142iBx5P1vNakYRoVhV7dwCYN7oLHXQBe7fqaYHDbUStCrGzm1rOe4jFTfOHrNIve6x4aLdW3N4M7inTdZK7v3t2_FeCbG9g06A09N75jmJ26uwcQXh7eez9nEnBrzeh7JnGA18UJsYHhpaoqftdMV52NDNIw6os7zM9352R3xEzZErK-mD0Cw42G1zr9zk_dfd0z0RyF5pr9yFVYbY9mga6_vVmBOhTsnFzPIA.4XSwi4xokumtM-w7.3sBpe1XM34pG2CkKl9XUvSLd9y2C7A4I3Nz5PNNw1ZLzGecverVYkh5HKpjH9EI-6Qv4rfovzpqh_rt-JbaBNhqU5jZgA0v4HEQJwJaY8oJ7Q8TI3oiLtqvi-r6kmXKDixSj7BbwQ5kQ2o4S9Wx13O60MtzCH7dvFryRxHYvyblvSUpSXoqKGy5Zljf7nWPLFjq2RYRG6vUHkOE1CfYO2BqoEkTILe7Eqg4sD7BiTilz2u90uGIRafxdC0PUThMfNY6zlGH0LsT9YUDmU4O2pWGz5yzHYNXKRAHRUu-Oz3KQI0FVNXdKEiQl6CWeErOxM8Efin67TKZUVx745ddL-BZGqoyaEmktu71mfRMHXX6sDBQwvQdXeZG3VpHdbqvU9ycavjsEJhnEVFBaTrpu5G-nTiX0yZKRMeIKyIr1PsoGRgqNTfL7W1lGCb68n45UNXIr2sq3eGS8arCIAPzYPszPGDkWzXNy4EF8dMY4py9ml29GLm2QTTW4rEL6d2VU-rebf5JstINVg5s-We-ugyEyBVE-03VjpZRMFkA3jMNbm_kK5UTU0bi7BYb2912wA6Mcc0wCPK_3F1pW2Zljgto1isBOk9--iR5MIuVt91rxfUs7Fzv2-wFrni2aaW1dxgIjmb_rnBlM_mH4USFtC2ueNv-Vz-QQBOm37W0I-KSXBuiDl_qUMRBDE0DKDsgyuAJ2a9dmVF9F5Oqw5wvQEtQttbJfh0RhhB8WX42kK5cNIp96da4kSxvLplPpAh33kv2WGLcjMoxnWGEdjo2e2Riz2IxWg3mMOoAoRM3uCIJUi6Z83SdmmfpCcl2uV_1ztgplmiayLpj6Pa68AxkM7wt7tASH9GcVN92zvFWgKco033RE6jRGWPNXtOhVvgQPaEUI0E4te3_CXhGB2WPmKKPIsBiBWDZFA34cVMQbUSUTfM-PwYBPdAf-.pK1LGDsQ0W12JJZLz_sD3x",
"newPassword": "mynewsecurepassword"
}A successful request can have different responses depending on the result of the request. If an alternate action is not enabled, then the response will look like the following:
HTTP/1.1 200 OK
Content-Type: application/json
{
"result": true,
}If there is an alternate action enabled, there will be a message field populated in the response, such as the following:
HTTP/1.1 200 OK
Content-Type: application/json
{
"result": true,
"message": "My alternate action message",
}If there is an error during the update password request or the alternate action fails, the request will be similar to the following. The message property will be different based on the type of error being thrown on the server.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"httpStatusCode": 400,
"message": "Error message",
}Pictograph Authentication Method
Here is an example response from the server indicating that Pictograph authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "pictograph",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "challenge",
"numToChoose": 1,
"images": [
{
"id": "_social-016_apple-64.png",
"url":"https://rapidIdentity.example.com:8443/idp/ws/icons/
_social-016_apple-64.png"
},
{
"id": "_social-010_html5-64.png",
"url": "https://rapidIdentity.example.com:8443/idp/ws/icons/
_social-010_html5-64.png"
},
{
"id": "_social-036_android-64.png",
"url": "https://rapidIdentity.example.com:8443/idp/ws/icons/
_social-036_android-64.png"
},
{
"id": "_thin-0037_smiley_happy_like_face-48.png",
"url": "https://localhost:8443/idp/ws/icons/
_thin-0037_smiley_happy_like_face-48.png"
},
{
"id": "_thin-0038_smiley_neutral_face-48.png",
"url": "https://localhost:8443/idp/ws/icons/
_thin-0038_smiley_neutral_face-48.png"
}
]
}
}Note the value of the type property is pictograph and the step object has a type property value of challenge.
The numToChoose property indicates how many of the provided images the user must identify.
The images array contains a randomized subset of the total image set available to the method as defined in the Authentication Policy. It will always contain at least numToChoose images which the user previously selected during their setup step.
To successfully complete the Pictograph authentication step, the user must identify the image(s) they chose during the setup phase. The IDs of those images need to be sent to the server in the subsequent request:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "pictograph",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "challenge",
"imageIds": [
"_social-016_apple-64.png"
]
}
}Setup
If a user needs to choose their pictures for a future challenge, the server will respond with a setup step. It will look similar to the following:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "pictograph",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "setup",
"numToChoose": 1,
"images": [
{
"id": "_social-016_apple-64.png",
"url": "https://rapidIdentity.example.com:8443/idp/ws/icons/
_social-016_apple-64.png"
},
{
"id": "_social-010_html5-64.png",
"url": "https://rapidIdentity.example.com:8443/idp/ws/icons/
_social-010_html5-64.png"
},
{
"id": "_social-036_android-64.png",
"url": "https://rapidIdentity.example.com:8443/idp/ws/icons/
_social-036_android-64.png"
},
{
"id": "_thin-0037_smiley_happy_like_face-48.png",
"url": "https://rapidIdentity.example.com:8443/idp/ws/icons/
_thin-0037_smiley_happy_like_face-48.png"
},
{
"id": "_thin-0038_smiley_neutral_face-48.png",
"url": "https://rapidIdentity.example.com:8443/idp/ws/icons/
_thin-0038_smiley_neutral_face-48.png"
}
],
"passwordRequired": true
}
}The numToChoose property indicates how many images the user must choose for future challenges.
The images array contains all of the possible images the user may choose. Each image has an id and a url.
The passwordRequired property indicates whether or not a valid password is required to complete the setup process. This will be true if there have been no previous authentication steps which have validated the user is who they claim to be. In other words requiring a password for setup ensures that someone cannot setup Pictograph authentication for someone else by simply supplying a valid username at the beginning of the process.
To successfully complete the setup step the proper number of images must be chosen and their IDs should be passed to the server.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "pictograph",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "setup",
"imageIds": [
"_social-016_apple-64.png"
],
"password": "idAuto#123"
}
}PingMe Authentication
Here is an example response from the server indicating that PingME authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "pingMe",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "chooseIdentity",
"identities": [
{
"username": "username1",
"domain": "DOMAIN1"
},
{
"username": "username2",
"domain": "DOMAIN2"
}
]
}
}Note the value of the type property is pingMe and the step object has a type property value of chooseIdentity.
The identities array will contain one or more identities associated with this user which they can choose to use for this authentication step. An identity object consists of two properties: username and domain. The username property will always be present but the domain property might not. When displaying the identity choice to the user, if a domain value is present, it should be displayed in standard Windows format: domain\username.
Currently, the first step for PingME authentication will always be chooseIdentity even if the authenticating user can use a single identity. We could go a few different ways with this.
The UI could just immediately begin the authentication process by sending a chooseIdentity request to the server with the single identity without user interaction
The UI could present a button that the user should click when they are ready for RapidFederation to send the authentication request to their device
The server could be changed to skip the initial chooseIdentity step and automatically send the authentication request (perhaps this could be a configurable setting in the policy).
To begin authentication, the user must choose an identity to use and the following request should be issued:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "pingMe",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "chooseIdentity",
"identity": {
"username": "username1",
"domain": "DOMAIN1"
}
}
}If everything is good so far, the server sends back a response indicating that authentication is underway:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "pingMe",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "authenticating"
}
}At this point, the user should receive the push notification on their device and they can Approve or Deny the request. However, while that's happening, the UI should display a spinner and poll the server in the background every few seconds to find out if the authentication has succeeded or failed.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "pingMe",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"step": {
"type": "pollAuthentication"
}
}RapidFederation will continue to respond to pollAuthentication requests with authenticating responses until the 2FA ONE server sends back a response or 120 seconds has elapsed.
I have been told that the 2FA ONE server will always return a response within a minute, but we give it up to two minutes
If the user approved the push request on their device and RapidFederation successfully receives that response, then the authentication flow will continue to the next step.
Authentication Failure
If authentication fails because the user denied the push request on their device or the request times out without a response from the user, then authentication has failed. In this case the response from the server will resemble the following:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "pingMe",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"error": {
"type": "simple",
"message": "2FA ONE PingME Authentication Failed"
},
"step": {
"type": "chooseIdentity",
"authenticationRetries": 2,
"identities": [
{
"username": "username1",
"domain": "DOMAIN1"
},
{
"username": "username2",
"domain": "DOMAIN2"
}
]
}
}Please note that the response contains a standard simple type error object with a message with should be displayed to the user. Additionally, the chooseIdentity step contains a new property authenticationRetries which indicates how many more PingME authentication attempts may be made before authentication fails altogether.
Since this response step type is chooseIdentity, this gives the user the opportunity to use a different identity for the next authentication attempt.
Useful WSDLs for the RapidIdentity MFA server:
Portal Challenge Authentication Method
If Federation calls out to retrieve the challenge set from Portal and challenge questions are either out of date or not setup, Federation will initiate the Portal challenge authentication setup.
Here is an example setup response from the server indicating that Portal challenge authentication setup is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "portalChallenge",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"step": {
"type": "setup",
"challengeSetup": {
"targetId": "",
"challengePolicy": {
"id": "",
"name": "",
"noChallenge": false,
"adminQuestions": [
{
"required": true,
"question": "What is your favorite color"
},
{
"required": true,
"question": "What is your mother's maiden name"
}
],
"minAdminQuestionPoolSize": 2,
"allowUserDefinedQuestions": true,
"minUserQuestionPoolSize": 0,
"maxUserQuestionPoolSize": 255,
"minQuestionLength": 3,
"maxQuestionLength": 255,
"minAnswerLength": 3,
"maxAnswerLength": 255,
"numAdminAnswersForAuth": 2,
"numUserAnswersForAuth": 0,
"numHelpdeskQuestions": 0,
"restrictWordsFromQuestion": false,
"canSkipSetup": false,
"enforceUniqueAnswers": true
},
"adminQuestions": [
{
"required": true,
"question": "What is your favorite color"
}
],
"userQuestions": [],
"helpdeskQuestions": []
},
"passwordRequired": false
}
}Note that the value of the type property is portalChallenge and the step type is setup.
In addition to sending the standard id, type, and step properties with the next request, answers must be provided for all values in the challengeQuestions array from the server response:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "portalChallenge",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"step": {
"type": "setup",
"adminQuestions": [
{
"question": "What is your favorite color",
"answer": "cyan"
},
{
"question": "What is your mother's maiden name",
"answer": "smith"
}
],
"userQuestions": [],
"helpdeskQuestions": []
}
}Challenge:
If Federation calls out to retrieve the challenge set from Portal and challenge questions valid, Federation will initiate the Portal challenge authentication setup.
Here is an example challenge response from the server indicating that Portal challenge authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "portalChallenge",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"step": {
"type": "challenge",
"challengeQuestions": [
"What is your favorite color",
"What is your mother's maiden name"
]
}
}Note that the value of the type property is portalChallenge and the step type is challenge.
In addition to sending the standard id, type, and step properties with the next request, a correct answer must be provided for all values in the challengeQuestions array from the server response:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "portalChallenge",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"step": {
"type": "challenge",
"questionsAndAnswers": [
{
"question": "What is your favorite color",
"answer": "cyan"
},
{
"question": "What is your mother's maiden name",
"answer": "smith"
}
]
}
}Errors
If Federation calls out to retrieve the challenge set from Portal and that request fails, either because Portal could not be contacted or the user's password could not be retrieved from the directory, the authentication process will immediately fail. It will look something like this:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "fail",
"id": "931c4a40-2dc9-11e6-937b-005056c00008",
"error": {
"type": "simple",
"message": "Failed to retrieve a Portal challenge"
}
}QR Code Authentication Method
The QR Code authentication method is a bit different from the other methods so far because it can be used to initiate the authentication process as well as provide another factor after authentication has been initiated via standard Initialization schemes.
As Initialization
At the API level, you know that a QR code may be used to initialize the authentication process if the response from the initialization request contains the property allowQRCodeScan with a value of true.
Currently, there are to ways for this to happen:
If there is at least one enabled Authentication Policy whose first enabled method is QR Code
If there is at least one enabled Authentication Policy whose insecureQRIdEnabled flag is set to true
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "username+password",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"allowQRCodeScan": true,
"claimAccountLink": {
"href": "/arms/claim/",
"displayName": "Claim My Account"
},
"helpLinks": [
{
"href": "/arms/forgotmyusername",
"displayName": "Forgot My Username"
},
{
"href": "/arms/forgotmypassword?redirect_to=/arms",
"displayName": "Forgot My Password"
}
]
}To successfully initialize the authentication process with a QR code, the client must send a request containing the value encoded by the QR Code as read by a scanner:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "qrCode",
"id": "35bf1450-2dbe-11e6-8a8b-005056c00008",
"value": "gobbledygookgibbersih"
}As an Authentication Step
Here is an example response from the server indicating that QR Code authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "qrCode",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008"
}To successfully complete the QR code authentication step, the client must send a request containing the value encoded by the QR Code as read by a scanner:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "qrCode",
"id": "e89afb10-2e6e-11e6-b6f0-005056c00008",
"value": "gobbledygookgibbersih"
}SMS Authentication Method
Here is an example response from the server indicating that SMS authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "sms",
"id": "beaa50c0-4a9a-11e5-ae5f-0050b6c32ffc"
}This indicates that RapidFederation was able to successfully call out to the SMS provider to send a One-Time Password (OTP) to the user's mobile device.
In addition to sending the standard id and type properties with the next request, the otpCode should be included with the value the user received on their device.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "sms",
"id": "beaa50c0-4a9a-11e5-ae5f-0050b6c32ffc",
"otpCode": "123456"
}Re-sending the OTP
Please note that this will negate the original code and in the event that the user receives both codes, the latest one is the only one which will work.
If the user wishes for RapidFederation to re-send the OTP code to their device the following request can be made:
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "sms",
"id": "beaa50c0-4a9a-11e5-ae5f-0050b6c32ffc",
"forceNewAuthz": true
}Social Authentication Method
Setup
Log in to https://developers.facebook.com
My Apps -> Add a New App -> Website
Give it a meaningful name like "RapidFederation Test" -> Create New Facebook App ID
Settings -> Advanced -> Valid OAuth redirect URIs
https://<RF_HOST>:<RF_PORT>/idp/socialCallback?n=facebook
Settings -> Advanced -> Require App Secret
Set to "No"
Enter App ID and App Secret in the Social configuration for your Authentication Policy
Log into Log into https://console.developers.google.com
Create a new Project and give it a meaningful name like "RapidFederation Test"
Choose "Use Google APIs"
Search for and enable Identity Toolkit API
Choose the "Credentials" item on the left
Add credentials
OAuth 2.0 client ID
Configure consent screen -> Save
Application Type: Web Application
Authorized redirect URIs
https://<RF_HOST>:<RF_PORT>/idp/socialCallback?n=googleplus
Create
Enter client ID and client secret in the Social configuration for your Authentication Policy
Log into https://apps.twitter.com/
Create New App
Give it a meaningful name like "RapidFederation Test"
Fill in the rest of the required fields
Callback URL
https://<RF_HOST>:<RF_PORT>/idp/socialCallback/twitter
If testing with localhost, just put in another hostname. It will be OK
Permissions -> Read only
Enter Consumer Key and Consumer Secret in the Social configuration for your Authentication Policy
Create Application
Give it a meaningful name like "RapidFederation Test"
Fill in the rest of the required fields
Keep Default Application Permission of r_basicprofile
OAuth 2.0 Authorized Redirect URLs
https://<RF_HOST>:<RF_PORT>/idp/socialCallback?n=linkedin
Enter Client ID and Client Secret in the Social configuration for your Authentication Policy
API
Initial Response
Below is an example of an initial response:
{
"type": "social",
"id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
"step": {
"type": "choose",
"providers": [
{
"id": "facebook",
"iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
social/facebook.svg",
"authenticationUrl": "...."
},
{
"id": "googleplus",
"iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
social/googleplus.svg",
"authenticationUrl": "...."
},
{
"id": "linkedin",
"iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
social/linkedin.svg",
"authenticationUrl": "...."
},
{
"id": "twitter",
"iconUrl": "https://rapidIdentity.example.com:8443/idp/assets/img/
social/twitter.svg",
"authenticationUrl": "...."
}
]
}
}This is an example of a "type" = "social" response from the server. Notice the "step" object whose type is "choose". This object contains information about all of the choices the user has for social authentication – in other words, which providers (social networks) are allowed for authentication. Each provider has an "id", an "iconUrl" and an "authenticationUrl". The choose screen should render each option as a clickable button with the specified iconUrl as the button's image.
When the user clicks on one of them, a new tab should be opened to the associated "authenticationUrl". This will redirect the user to that social platform for authentication and once authenticated, back into RapidFederation at the "callback URL" of .../idp/socialCallback?n=<network>.
Auth Step
As soon as the user clicks the button to open the new tab, the RapidFederation page should switch to a view that is ready to submit the "auth" step.
Below is an example auth request:
{
"type": "social",
"id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
"step": {
"type": "auth"
}
}kThe "auth" step is intended to be submitted after authentication at the social site has completed. If it is submitted before that takes place, the "choose" step will be returned again.
If the user authenticates to the social platform with an identity which has already been paired, then at this point life is good and RapidFederation will move on to the next step. If the user authenticates with a new identity (i.e. one which they have not previously paired), then we move on to the "pair" step which begins with a "pair" response from the server.
Pair Step
Below is an example pair response:
{
"type": "social",
"id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
"step": {
"type": "pair",
"provider": {
"id": "facebook",
"iconUrl": "https://localhost:8443/idp/assets/img/social/googleplus.svg"
},
"profile": {
"name": "John ",
"email": "jdoe@example.com",
"imageUrl": ""
},
"pairRequiresPassword": true
}
}The "pair" begins with the server responding with some basic information about the social identity used for authentication and should be considered as the server confirming that the user wants to pair that social identity with their RapidFederation identity. Note that there is information about the provider and some basic profile information.
In my testing with our currently supported social networks, I was able to get at least "name" and "imageUrl" to be returned. Realize that the information we get back from each provider is dependent on what information the user has given to that provider as well as what OAuth permissions the app on that platform has been given.
One more request is required to complete the pair process and that is the confirmation from the user that they want to pair with that social identity:
Pair Request
Below is an example pair request:
{
"type": "social",
"id": "c2e109d0-8d7b-11e5-8c0d-0050b6c32ffc",
"step": {
"type": "pair",
"password": "P@$$w0rD"
}
}If "pairRequiresPassword" is true in the previous Pair Response, then of course the user will need to provide their password to complete the pair. Otherwise it can be omitted. Once complete RapidFederation moves on to the next authentication step.
TOTP Authentication Method
Here is an example response from the server indicating that TOTP authentication is required as the next step:
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"allowDeferral": true
}Note that the value of the type property is totp.
When responding to the TOTP challenge a value for the otpCode property is required. This should contain the current value as displayed on the TOTP device. Additionally, if the response from the server contains a true value for the allowDeferral property, as above, the user may opt to defer being challenged for 30 days.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"otpCode": "123456",
"defer": true
}Deferral
If deferral is allowed and opted-into by the user, if the otpCode was valid then the next response from the server will contain a Set-Coolie header which should be handled automatically by the browser if cookies are enabled. The cookie contains information linking a particular user to a particular deferral.
Since the deferral is managed with a cookie, it is only good for a single browser on a single device. If a different browser or device is used in the future, the user will be challenged again and may opt-in to deferral for that device/browser combination.
Multiple users may have active deferrals on the same device & browser.
Setup
The first time a user is challenged for TOTP authentication they need to go through a setup phase where they register their TOTP key with a device. In this case, the server will respond with a setup object which will contain all of the information required.
Note
Displayed values have been truncated here for formatting purposes, but the strings listed here should represent actual, usable values when generated in a production environment.
HTTP/1.1 200 OK
Content-Type: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"setup": {
"setupInstructions": "You need to set this up now!",
"base64QrCode": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRB[...]",
"secret": "KDXUAAZNFCYVUEVXPXPT3BHRX4S5KXFO",
"passwordRequired": false
},
"allowDeferral": true
}The setupInstructions property contains instructions which should be displayed to the user
The base64QrCode property contains a Base64-encoded PNG image of the QR code which should be displayed. Many TOTP devices allow registration by scanning a QR code.
The secret roperty contains the TOTP secret key which can be used to perform manual registration on a device
The passwordRequired property indicates whether or not a valid password is required to complete the setup process. This will be true if there have been no previous authentication steps which have validated the user is who they claim to be. In other words requiring a password for setup ensures that someone cannot setup TOTP authentication for someone else by simply supplying a valid username at the beginning of the process.
To To successfully complete the setup step a valid otpCode must be provided. This ensures that the user has successfully setup their TOTP device.
POST /idp/ws/rest/authn HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"type": "totp",
"id": "e230e2e0-25ae-11e5-8dc9-0050b6c32ffc",
"otpCode": "123456",
"defer": true,
"password": "mysupersecretpassword"
}Swagger API Documentation
For anyone with the API Developer Role, the Swagger-defined APIs can be accessed by following these three steps.
Open a browser tab and type this address: https://<hostname or IP address>/api.
Click the Swagger link, which will be in this format: https://<hostname or IP address>/api/rest/api-docs?url=/api/rest/swagger.json.
Note
This URL can be bookmarked for convenience.
The Swagger-defined APIs may take a moment to load. This behavior is normal and expected. Once loaded, the APIs appear as shown.
Integrating and Applying RapidIdentity APIs
RapidIdentity APIs enable developers and other information technology profiles to access and employ identity information that is otherwise not available in the user interface.
Depending on the specific use case and its solution implementation, technology professionals can leverage the APIs to help automate self-service actions, provisioning, auditing, and even integrate the underlying RapidIdentity technology into a custom environment independent of the RapidIdentity user interface.
API-derived solutions, whether the APIs are specific to RapidIdentity or integrate service provider APIs (e.g. Google), are representative of a snapshot-in-time since APIs adapt and evolve relative to the software roadmap. As software increases in functionality and obsoletes older technology and features, APIs adapt and evolve accordingly. If an API is not available when required or if additional functionality is necessary beyond the currently available API, a RapidIdentity Connect RESTPoint can bridge this gap.
Moreover, the manner in which RapidIdentity can be leveraged to address a use case and implement a solution is dependent on the RapidIdentity licensing, the organization's environment (e.g. systems, software, necessary regulations), and how the customer chooses to address the use case.
To address this context, the following scenario is intended to provide a conceptual overview to how RapidIdentity's technology and APIs can address key identity and access management scenarios, which can then inspire technology professionals to leverage this technology to develop unique solutions for their own environment.
Self Service with Organization Front-End Environment
RapidIdentity Self-Service Profiles Actions (e.g. Update Challenge Responses, Claim Account) allow users to perform administrative actions on their own accounts without the need of an information technology professional to grant or moderate access and authorization. The advantages of this delegation to users include relieving IT staff of relatively mundane tasks and empowering users to take immediate ownership of their account.
Challenge Questions/Answers Overview
The objective is to provide users with a mechanism to update specific Challenge Question Answers selected by an organization (e.g. one or two question/answers in a challenge set of six questions) in a custom, organization-specific front-end environment without requiring users to use the RapidIdentity Challenge Question dialog. These challenge questions are presented on the front end through a drop-down box for each question and users are forbidden from answering the same question more than once. Users can also input three of their own question and make only one of them required.
This use case is an example of how RapidIdentity technology can operate in the background and is relatively common since many organizations have their own portal-type environment in which users are required to authenticate to gain access to their secure organization network and applications and prefer to use their own, company-branded interface to avoid user confusion as new technology is integrated.
Before launching into the order-of-operations to address this use case conceptually, it is important to consider what is likely to be necessary to address this use case first. The following eight items compose a nonexhaustive list of key issues to consider.
User Authentication Process
RapidIdentity Challenge Response APIs
Organization APIs
Filtering Challenge Set Questions
Data format (JSON or XML)
Authoritative Source Synchronization (e.g. Directory Service, Database)
Audit Logs
Regulatory Concerns
Not all of these eight issues will be addressed in the solution approach because that is beyond the scope of this topic and the intention is to provide a conceptual overview.
Admins trigger Challenge Question Answer updates through RapidIdentity Portal.
Challenge Set Questions are obtained by API, filtered by the organization, and the updated user responses are returned to RapidIdentity in JSON format using API.
Only one Challenge Set Policy Exists.
Updates are sent to the directory service.
Audit logs are updated through RapidIdentity.
Regulatory concerns are not addressed.
With these six assumptions in hand, the simplified order of operations to address this use case is as follows.
Administrator navigates to RapidIdentity Portal | Configuration | Profiles | Extended | Challenge Policy Manager | General and click Set to Now.
Administrators must have the RapidIdentity Portal Profiles Admin role.
User authenticates.
User challenge questions are obtained through API call to RapidIdentity.
GET /arms/ws/rest/actm/actions/challenge/setup
RESPONSE 200 OK:
{ "targetId":"0dbe1c00-7056-11e6-aa1d-0e37b9aa2711", "challengePolicy":{ "id":"397b0e20-6ee9-11e6-a4b4-0e37b9aa2711", "name":"Default Challenge Policy", "noChallenge":false, "adminQuestions":[ { "required":true, "question":"What is your favorite color" } ], "minAdminQuestionPoolSize":1, "allowUserDefinedQuestions":true, "minUserQuestionPoolSize":0, "maxUserQuestionPoolSize":255, "minQuestionLength":3, "maxQuestionLength":255, "minAnswerLength":3, "maxAnswerLength":255, "numAdminAnswersForAuth":1, "numUserAnswersForAuth":0, "numHelpdeskQuestions":0, "restrictWordsFromQuestion":false, "canSkipSetup":false, "enforceUniqueAnswers":true }, "adminQuestions":[ { "required":true, "question":"What is your favorite color" } ], "userQuestions":[ { "question":"What is my dog's favorite toy" }, { "question":"What is my favorite song" }, { "question":"Who was my first college roommate" } ] }Admin parses JSON to extract questions. Admin determines whether user questions are allowed and then pushes all questions to the user interface.
User answers questions and clicks Submit.
Admin creates pre-request JSON and makes POST API call to RapidIdentity.
POST /arms/ws/rest/actm/actions/challenge/setup
{ "targetId": "0dbe1c00-7056-11e6-aa1d-0e37b9aa2711", "challengePolicy": { "id": "397b0e20-6ee9-11e6-a4b4-0e37b9aa2711", "version": 1, "name": "Default Challenge Policy", "priority": 1, "enabled": true, "noChallenge": false, "default": true, "groupAclsEnabled": false, "groupAcls": [ {} ], "filterAclEnabled": false, "filterAcl": "", "adminQuestions": [ { "required": true, "question": "What is your favorite color" } ], "minAdminQuestionPoolSize": 1, "allowUserDefinedQuestions": true, "minUserQuestionPoolSize": 1, "maxUserQuestionPoolSize": 3, "minQuestionLength": 3, "maxQuestionLength": 255, "minAnswerLength": 3, "maxAnswerLength": 255, "numAdminAnswersForAuth": 1, "numUserAnswersForAuth": 1, "numHelpdeskQuestions": 0, "restrictWordsFromQuestion": false, "canSkipSetup": false, "enforceUniqueAnswers": true, "oldestAllowedResponseTimestamp": 20170622 }, "adminQuestions": [ { "required": true, "question": "What is your favorite color", "answer": "Orange" } ], "userQuestions": [ { "required": true, "question": "What is my dog's favorite toy", "answer": "Squirrel" }, { "required": false, "question": "What is my favorite song", "answer": "Cheeseburger in Paradise" }, { "required": false, "question": "Who was my first college roommate", "answer": "Luke" } ] }RESPONSE 200 OK:
{ "target": "0dbe1c00-7056-11e6-aa1d-0e37b9aa2711", "targetName": "Doc Admin", "success": true }
While this use case focuses on specific challenge questions and their answers in a set, this use case solution approach could easily be adapted to password self-service, account claiming, or any other delegated administration action.
To develop solutions for additional RapidIdentity self-service use cases (e.g. Password, Account Claim) by adopting the above approach, it is necessary to substitute the corresponding APIs specific to your use case and constructing the POST pre-request JSON script to match the API.
OAuth 2.0 User Guide
RapidIdentity currently supports the Authorization Code Grant as defined by the OAuth 2.0 Specification.
Authorization Request
Issue a GET to /idp/profile/oauth2/auth with the following parameters:
Type: String
Required: True
Description: The default value is "code."
Type: String
Required: True
Description: The Client ID.
Type: String
Required: True
The registered callback URL.
Type: String
Required: False
Space-delimited API scopes to request. The default value is "basic."
Type: String
Required: False
An opaque value used by your application to maintain state between the request and callback.
Note
If the authenticating user does not already have an authenticated Federation session, they will be redirected to the login page.
After successful authentication or validation of the user's current session, the browser will be redirected to the callback URL with a "code" parameter and a "state" parameter (if one was supplied in the initial request).
The "code" must be exchanged for an access token in the next step.
RapidIdentity currently supports a single scope of "basic" which gives read-only access to the authenticated user's profile.
Access Token Refresh
Issue a POST to /idp/profile/oauth2/token with the following parameters:
Parameter | Type | Description |
|---|---|---|
grant_type | String required | " |
refresh_token | String required | The refresh token value received in the Access Token Response. |
scope | String optional | Space-delimited API scopes, defaults to whatever scope was originally granted. |
client_id | String optional | Your Client ID. This is required if HTTP Basic Authentication is not used. |
client_secret | String optional | Your Client Secret. This is required if HTTP Basic Authentication is not used. |
As shown in the parameter table, HTTP Basic Authentication may be used instead of providing client_id and client_secret as request parameters.
In that case, the Client ID should be used as the username and the Client Secret should be used as the password.
If possible, the use of HTTP Basic Authentication is preferred.
Assuming the request is valid, the Authorization Server generates a new access token and refresh token pair and returns a response in the same format as the Access Token Response.
Access Token Response
Assuming the Access Token Request is valid, the Authorization Server will return a response like this:
Below is an example response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 7200,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
"scope": "basic"
}Note
Once an Authorization Code has been exchanged for an Access Token, that Authorization Code may not be used again in the future.
Access Token Request
Issue a POST to /idp/profile/oauth2/token using the application/x-www-form-urlencoded format with a character encoding of UTF-8 and the following parameters in the request body:
Parameter | Type | Description |
|---|---|---|
grant_type | String required | " |
code | string required | The value of the "code" parameter from the previous response. |
redirect_uri | string required | Your registered callback URL. Must match exactly the value used in the previous request |
client_id | string optional | Your Client ID. This is required if HTTP Basic Authentication is not used. |
client_secret | string optional | Your Client Secret. This is required if HTTP Basic Authentication is not used. |
As shown in the parameter table, HTTP Basic Authentication may be used instead of providing client_id and client_secret as request parameters.
In that case, the Client ID should be used as the username and the Client Secret should be used as the password.
If possible, the use of HTTP Basic Authentication is preferred.
My User Profile Request
Required Scopes: basic
When requesting a user profile, the system will return a JSON object containing the information your RapidIdentity Administrator selected to be returned to the OAuth 2.0 Client you are using.
For example, if you submitted this example request:
GET /idp/profile/oauth2/me Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
You should get a response that looks like this:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": "f1ca0d92-f42c-4499-a77a-4a733fc841b2",
"firstName": "Homer",
"lastName": "Simpson",
"email": "homer.j.simpson@simpsons.com"
}The response you receive may be different, depending on your system's configuration.
WS-Federation Usage Guide
RapidIdentity supports the WS-Federation 1.2 Web Passive Requestor Protocol as defined by Oasis.
At this time, RapidIdentity only supports the generation of security tokens containing a SAML 1.1 assertion. SAML 2.0 assertions may be supported in the future.
An Identity Provider must be created in the RapidIdentity cluster before WS-Federation will work.
Sign-On Request
Issue a GET to /idp/profile/wsfed with the following parameters.
Parameter | Type | Description |
|---|---|---|
wa | String required | "wsignin1.0". |
wtrealm | String required | The "Realm ID" of the Relying Party. |
wctx | String optional | A opaque value used by the Relying Party to maintain state between the request and callback. |
wfresh | Integer optional | The desired maximum age of authentication in minutes. A value of 0 (zero) indicates that the Identity Provider should force the user to re-authenticate before issuing a token. A value &gt; 0 indicates that the Identity Provider should force the user to re-authenticate if they have not authenticated in that many minutes. If not specified, then the Identity Provider will make its own determination on whether the user needs to be re-authenticated based on the global SSO session timeout. |
wreply | String optional | The URL to which the Identity Provider should POST the security token. By default the Identity Provider will POST the security token response back to the "Realm ID" of the Relying Party if it is a valid URL. However, multiple response URLs can be registered for any Relying Party and if one of those is specified by this parameter, the Identity Provider will POST the token there. The Identity Provider will never POST to a response URL which has not been pre-registered. |
Upon issuing a security token, the Identity Provider generates an HTML form populated with the following values and POSTs the form to the response URL.
Parameter | Type | Description |
|---|---|---|
wa | String | "wsignin1.0". |
wctx | String | The wctx value which was passed in to the original Sign-On request (if any). |
wresult | String | The security token itself. |
Sign-Out Request
RapidIdentity does not currently support "Federated" or "Single Sign-Out". Upon receiving a WS-Federation Sign-Out request, only the SSO session at the Identity Provider is destroyed.
Issue a GET to /idp/profile/wsfed with the following parameters.
Parameter | Type | Description |
|---|---|---|
wa | String required | "wsignout1.0" |
Relying Party Management
The REST endpoint for managing WS-Federation Relying Parties is /api/rest/admin/wsfed/relyingParties. The standard GET, POST, PUT and DELETE verbs are supported for CRUD operations.
A Relying Party is required to have a unique realmId and name. The realmId must be a valid URI.
A Relying Party may be configured to allow release of various attributes in the SAML 1.1 assertion included in the security token response.
WS-Federation Metadata
The WS-Federation metadata document is available from the RapidIdentity server at these two locations.
/FederationMetadata/2007-06/FederationMetadata.xml
/idp/wsfed/metadata
By default the metadata is signed with the Identity Provider's signing credential. If this is not desired, include the URL parameter ?sign=false to disable the signature.
RapidIdentity API Reference
RapidIdentity Rolling & LTS Release Versions
New RapidIdentity Versioning Scheme
Beginning in May 2020, RapidIdentity's versioning scheme is changing to Year.MajorRelease.MinorRelease-BuildID. The first RapidIdentity version for this new versioning scheme is 2020.0.0-<BuildID>.
 |
Yearis the year of the release.MajorReleaseindicates which major release for the year. Major starts at 0 for each new year.MinorReleaseindicates a maintenance release or hotfix for a major release and starts at 0 for each new major.BuildIDis provided by the build system.
The first release in 2020 would be 2020.0.0-<BuildID>
The second major release in 2020 would be 2020.1.0-<BuildID>
A maintenance release or hotfix for the first 2020 release would be 2020.0.1-<BuildID>
Previously, updates to the RapidIdentity product and all of its components occurred through a versioning sequence based on date with a format of YYYY.MM.DD that occurred in two different version classifications: Rolling and Long Term Support (LTS). These and all subsequent versions are detailed further in the RapidIdentity Release Notes.
RapidIdentity Cloud Versioning Scheme
The RapidIdentity Cloud Versioning scheme is different from the LTS versioning scheme, as Cloud tenants are updated automatically by Identity Automation. This consists of the date the build was cut as well as the BuildID.
 |
Previously, updates to the RapidIdentity product and all of its components occurred through a versioning sequence based on date with a format of YYYY.MM.DD that occurred in two different version classifications: Rolling and Long Term Support (LTS). These, Cloud versions, and all subsequent versions are detailed further in the RapidIdentity Release Notes.
Rolling Release Versions
The purpose of the Rolling Release is to make new updates to the RapidIdentity product available to customers and partners faster. These updates can include, but are not limited to, bug fixes, improvements, new features, and security updates.
The Rolling Release frequency intends to be faster than past release versions, which was approximated monthly for bug fixes and quarterly for minor versions to include to new features (e.g. 4.2.4.2.0 to 4.3.4.3.0).
It is possible for Rolling Releases to occur daily, however, daily releases would likely indicate bug fixes, which may not affect the environment based on RapidIdentity licensing.
Rolling Releases are visible in RapidIdentity Appliance and available for upgrade if the current RapidIdentity License matches software included in the Rolling Release.
Note
Rolling Releases have been deprecated and are no longer offered by Identity Automation.
Long Term Support (LTS) Release Versions
A RapidIdentity Long Term Support (LTS) Release is a RapidIdentity Version that is available for support for up to 12 months. LTS Release Versions occur approximately every 6 months.
There are two primary differences between a Rolling Release and an LTS Release: LTS Releases includes bug fixes and security updates only and the versioning date number includes a trailing digit.
The LTS versioning sequence is formatted as YYYY.MM.DD.N, where "N" is an integer. For example, a future LTS version could be designated as 2018.3.15.0, where the trailing-zero indicates the first LTS version.
A subsequent LTS version that includes bug fixes or security updates but no new features since this date would be 2018.3.15.1.
Overall Sequence
The outline below is intended to show how Rolling and LTS Releases are related.
2017.7.22 # First Version of RapidIdentity in this versioning sequence. 2017.9.02 # Rolling Release, bug fix2017.9.08 # Rolling Release, new feature 2017.9.20 # Rolling Release, enhancement 2017.9.23 # Rolling Release, bug fix. 2017.9.23.0LTS # Includes all Rolling Release versions to this date. 2017.9.30 # Rolling Release, bug fix. 2017.10.04 # Rolling Release, bug fix. 2017.10.09 # Rolling Release, new feature. 2017.10.18 # Rolling Release, new feature. 2017.9.23.1 LTS # Includes bug fixes only (2017.9.30 and 2017.10.04). 2017.10.23 # Rolling Release, bug fix. 2018.3.15 # Rolling Release, new feature. 2018.3.15.0 LTS # Includes all Rolling Releases since 2017.09.23
SSH Management
The RapidIdentity Command Line Interface allows for selected management and configuration of RapidIdentity Appliance settings. Some of these settings overlap with settings found through links on the RapidIdentity Appliance homepage, while other settings are unique to the CLI interface.
The layout with the look and feel of the current CLI menu is different compared to the CLI menu from the RapidIdentity versions 4.3 and earlier. Notably, the interface contains a blue background and there are eight main menu options. There are currently eight Main Menu options.
Updating Configurations
Installing RapidIdentity automatically configures settings that are sensible based on how the RapidIdentity software works. Care should be exercised before attempting to modify any of the settings available through the RapidIdentity CLI Interface.
Main Menu
The Main Menu interface is the top-level of the RapidIdentity Command Line interface and provides access to 9 interfaces:
RapidIdentity
System
Logs
Local Database
Local LDAP Server
Local File Server
Tools
Shutdown/Reboot
About
RapidIdentity
The RapidIdentity Interface provides 7 additional interfaces:
 |
Status
The RapidIdentity Status interface provides the option to Stop, Start, or Restart RapidIdentity at the process level.
 |
The Restart option can be used after making changes to configuration options in the CLI or through the RapidIdentity Appliance Home page.
The Stop option is helpful when making changes that affect RapidIdentity globally, such as an uninstall-reinstall of the Local Database or LDAP Server.
The Start option is helpful in the event the service was stopped.
Main Database
The Main Database menu item lists the currently configured database. Selecting this option opens a submenu with 7 additional items.
Type
Host
Port
Database/Schema
Username
Password
Advanced
 |
Selecting options 2-6 opens a prompt for administrators to change the values for each of those fields. The Advanced menu item directs to the rapididentity.properties configuration file.
Selecting the Type menu option allows administrators to change the main RapidIdentity Database. The currently supported databases types are MySQL, PostgreSQL, and MSSQL.
 |
If the Main Database is changed, it is necessary to Restart RapidIdentity for the change to take effect.
MySQL Driver
The MySQL driver can be installed after the initial RapidIdentity installation.
Audit Database
The Audit Database interface allows administrators to determine whether a specific database should be used for audit.
 |
The default setting is False, which means that the local database is used for audit.
If the Audit Database is changed, it is necessary to Restart RapidIdentity for the change to take effect.
Start-At-Boot
The Start-At-Boot configuration allows RapidIdentity to start when the operating system is started.
For example, if RapidIdentity is hosted on an AWS EC2 Instance and Start-At-Boot is enabled, once the instance has passed its start up checks RapidIdentity will start and subsequently be available to access from a browser after a few minutes; RapidIdentity is available immediately from the command line after the instance passes its start up checks.
The default setting is enabled. To disable this configuration, select and confirm to disable.
 |
Capabilities
The Capabilities menu item allows administrators to define the currently available capabilities. Selecting this option opens a prompt to edit Capabilities, which control the various functionalities that should be exposed by the RapidIdentity server.
The advantage of this functionality in a unified RapidIdentity is that RapidIdentity back end processes are not dedicated to a component that isn't applicable. Therefore, RapidIdentity can run more efficiently.
 |
The end result is that the rapididentity.propertiescapabilities value is updated.
 |
Capabilities can be configured to inclusive or exclusive by adding prefixes of "+" or "-", respectively.
Each component in the table matches to a RapidIdentity Component, except for "admin" which refers to RapidIdentity Configuration components. The API is critical for any .ui or .jobs components.
Component | UI | Jobs |
|---|---|---|
admin | admin.ui | admin.jobs |
connect | connect.ui | connect.jobs |
federation | federation.ui | federation.jobs |
folders | folders.ui | folders.jobs |
portal | portal.ui | portal.jobs |
studio NoteStudio is only available in IDaaS environments | studio.ui | studio.jobs |
If the Cluster metadirectory is not pointing to Active Directory, the folders capabilities will continue running even with no tasks since RapidIdentity Folders is specific for Windows-based home or group shared folders.
Note
Best practice is to exclude or not enable any capabilities that are not licensed.
The wildcard "all" can be used as a prefix in three possible ways with either an inclusion or exclusion.
all: includes or excludes every UI and Job capability
all.ui: includes or excludes every UI capability
all.jobs: includes or excludes every Job capability
Inclusions and exclusions are processed in the order they occur and result in adding or removing from the set of capabilities.
If the list is empty, then all capability group is used.
If the list starts with an exclusion, then the initial set is the all capability group.
If the first item in the list is an inclusion, the initial set starts as empty.
Including or excluding a top level capability also includes or excludes all its subordinates (e.g. connect includes connect, connect.ui and connect.jobs).
Including a subordinate implies inclusion of its superior (e.g. federation.ui includes Federation).
Excluding a subordinate does not imply exclusion of its superior.
Including or excluding a group is equivalent to including or excluding each of the individual members of the group.
Capability | Description |
|---|---|
capabilities= | Includes all capabilities |
capabilities=all | Includes all capabilities |
capabilities=admin,connect | Includes admin, admin.ui, admin.jobs, connect, connect.ui, and connect.jobs. |
capabilities=-folders | Includes all capabilities except folders. |
capabilities=portal,-portal.jobs,federation | Includes portal, portal.ui, federation, federation.ui, and federation.jobs. |
Specialty Configurations
Occasionally, you will need capabilities configurations to support customized actions for RapidIdentity. Listed below are a few typical options.
Expose Connect RESTPoints without exposing the UI or jobs on that server:
capabilities=connect,-connect.jobs,-connect.uiNote
This will allow a cluster member to accept and respond to RESTPoints built in a Connect project, but prevent UI access from that instance and prevent scheduled Connect jobs from running on that instance.
Configure a Connect instance to not run background jobs:
capabilities=connect,-connect.jobs
Configure a Studio instance to not run background jobs:
Note
Studio is only available in IDaaS environments
capabilities=studio,-studio.jobs
SSL/TLS Profile
The SSL/TLS Profile menu item defines which SSL Profile should be used with RapidIdentity. Selecting this option opens a prompt to edit the profile.
The end result is that the rapididentity.properties tomcat.sslProfile value is updated.
Beginning in RapidIdentity version 2020.1.0, the following changes will apply to the Tomcat properties in rapididentity.properties:
tomcat.sslCipherBlacklist has been deprecated.
tomcat.sslProtocols can now include TLSv1.2, and TLSv1.1 ONLY.
By default, RapidIdentity will use the list TLSv1.2 for version 2020.1.0. In order to use TLSv1.1 with 2020.1, you will need to provide your own cipher suites.
tomcat.sslCipherWhitelist has been added. This allows you to specify a list of TLS cipher suites to enable. If this list is provided, it will override the default list.
Note
The whitelist will be a comma-separated list, just like the blacklist was. Examples:
tomcat.sslProtocols=TLSv1.2tomcat.sslCipherWhitelist=TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384RapidIdentity will use a secure set of cipher suites by default, including:
For TLSv1.2:
Note
ONLY included if TLSv1.2 is enabled and there is no whitelist - default behavior
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
For TLSv1.1:
Note
ONLY if TLSv1.1 is enabled and there is no whitelist - default behavior, and ONLY included in later builds of 2019.12.15.x and 2020.x.
TLSv1.1 is not recommended.
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
Advanced
The Advanced menu item directs administrators to the rapididentity.properties configuration file.
System
The System menu allows administrators to update five configurations.
 |
Network
From the RapidIdentity Systems Menu, navigate to the Network menu to adjust network and firewall settings.
 |
The Network submenus allow administrators to configure network parameters in Network Settings, define a proxy URL if necessary, update Firewall Settings, pl;access Network Diagnostics, and choose to restart the Networking or Firewall.
 |
Network Settings
The Network Settings submenu provides four menu items.
IP Address, Gateway and DHCP
Hostname
DNS Servers
Hosts File
HTTP Proxy URL
Selecting the HTTP Proxy URL allow administrators to enter a proxy URL.
Firewall Settings
Firewall Settings opens the configuration file and those settings can be modified and saved. Even if no changes are made to the firewall file, the firewall is restarted every time the file is closed.
 |
Choosing to restart the Network or Firewall results in an automatic restart.
Diagnostics
Network Diagnostics provides seven options to troubleshoot network issues pertaining to RapidIdentity.
Devices
Connections
Routing Table
ARP Table
Ping
TraceRoute
NSLookup
Devices lists networked devices associated to RapidIdentity. If there are no networked devices associated to RapidIdentity then the table will be blank.
Connections opens a table describing Active Internet Connections.
 |
The Routing Table lists the Kernel IP Routing Table.
 |
The ARP Table opens a table of existing IPv4 addresses in a given network. If there are no addresses then the table will be blank.
Ping, TraceRoute, and NSLookup all provide an input dialog to enter a Hostname or IP address to perform the action.
 |
Restart Networking or Firewall
These menu items, when chosen, will restart the selected item.
Time
The Time menu displays the current time and allows administrators to configure the timezone.
 |
The Timesync menu option opens a configuration describing how time synchronization works within RapidIdentity.
 |
SNMP
The SNMP provides access to the snmpd configuration file and its manual.
 |
The configuration file can be edited, and once that file is closed the SNMP service is restarted.
 |
The manual describes the snmpd agent.
 |
Security
The Security menu allows administrators to change the RapidIdentity Appliance user password along with choosing whether to enable SSH multifactor authentication and unlimited strength encryption.
 |
Unlimited Strength Encryption
Choosing whether to enable unlimited strength encryption requires administrators to familiarize themselves with legal restrictions.
It is recommended that administrators consult legal counsel prior to enabling this option to ensure compliance with all relevant laws.
SSH Multi-Factor
SSH Multi-Factor is an option available to Identity Automation administrators only. To enable fully, it is necessary to enter the idauto username and TOTP token from the mobile device.
 |
Updates
The Updates menu allows administrators to check or apply updates pertaining to security only or to the entire system.
 |
Selecting either of the options to check for updates initiates a script to determine whether security or or system updates are available.
 |
Selecting either of the options to apply updates initiates a script to determine whether existing packages can be updated. If updates are not available then administrators are prompted to press any key to continue.
 |
Logs
The Logs interface allows administrators to view log data from RapidIdentity, the configured Audit Database, the Local Database, and the Local LDAP Server.
 |
For example, selecting RapidIdentity opens up a view of the RapidIdentity logs and administrators can either scroll down or tail the logs to have feedback on demand.
 |
Local Database
The Local Database allows administrators to configure either PostgreSQL or MySQL.
 |
RapidIdentity searches for PostgreSQL by default. Both installed databases have the same menu when selected.
 |
Selecting Server Status allows administrators to stop, restart, or uninstall. Since PostgreSQL is not installed in this example, its interface only provides the potion to install.
 |
 |
The Start-At-Boot and Daily Backups interfaces allow administrators to disable the corresponding service.
 |
 |
Local LDAP Server
The Local LDAP Server menu allows administrators to configure the Server Status, whether to Start-At-Boot, and the Password sync key.
Selecting the Local LDAP Server Main Menu item displays the current Server Status.
 |
Selecting the current Server Status opens a submenu to configure the Server Status, whether to Start-At-Boot, and the Password sync key.
 |
The LDAP Server Status and Start-At-Boot options are identical to the Local Database.
The Password Sync Key is used by OpenLDAP to encrypt captured passwords and its functionality is analogous to the Active Directory Password Filter. Selecting this option enables the installation or update of the public key to encrypt captured passwords.
 |
 |
Password Sync Key Considerations
Depending on the environment and the directory service associated with RapidIdentity, it may be necessary to install or update the Password Sync Key when using OpenLDAP and RapidIdentity. Sometimes the Password Sync may not be installed or running, or the instance may be a standalone component whose sole purpose is to host the OpenLDAP server and the RapidIdentity Server(s) are hosted elsewhere. It is usually helpful to update the Password Sync Key when integrating OpenLDAP with RapidIdentity.
Local File Server
The Local File Server is available with all RapidIdentity Rolling and LTS Release versions beginning with Rolling Release version 2018.5.2.
The Local File Server interface allows administrators to install an SMB file system to serve as a Windows-environment cluster shared file system.
 |
Installing the Local File server is best used for on-premises configurations and test environments , and the Local File Server can be installed in either of 2 places:
A dedicated Windows File Share Server in the organization's environment.
On the RapidIdentity appliance server that contains the RapidIdentity database.
If the dedicated Windows File Share Server is available in the organization's environment, option 1 is best. Otherwise, option 2 is sufficient, however, it is advisable to ensure sufficient disk space exists to allow for both database and RapidIdentity Connect logs to store. If possible, SNMP monitoring of the disk space is also advisable.
Post-installation, RapidIdentity will only ever expose one shared idautocluster and it will only be accessible by 1 user of the same name, and the Local File Server is not visible in the Windows Explorer Network Folder. It is necessary to know the Local File Server UNC path to access it, which is available in the Connection Info menu after installation.
Once the Local File Server is installed and configured in the Command Line Environment, it can be subsequently administered in either of 2 places, depending on UI:
Install the Local File Server
Upon upgrading to a RapidIdentity Release Version that makes the Local File Server configuration available, the default configuration will be Not Installed. If the Local File Server is not necessary for the RapidIdentity implementation, the default configuration can remain as Not Installed.
To install the Local File Server, follow these steps:
Navigate to Main Menu | Option 6 and press Enter.
The Server Status displays not installed. Press Enter or Select to continue and the Enter or Select install the Local File Server.
Enter and confirm the Local File Server password.
A successful installation prompts users to click any key to continue and subsequently displays a Server Status value of running.
Server Status
The Server Status menu allows administrators to start, restart, or uninstall the Local File Server.
 |
 |
Change Password
Administrators can change the Local File Server password at any time to match their organization's File Server Password Policy requirements.
To change the Local File Server Password, navigate to Option 2 | Change Local File Server Password and press Enter.
 |
Enter and confirm the new password, and then press any key to continue.
 |
 |
 |
Connection Info
The Connection Info provides the UNC Path and the Username for the Local File Server.
 |
 |
Installing the Local File Server on a RapidIdentity Appliance makes the Local File Server available as a configuration option but does not automatically enable the Local File Server.
To enable the Local File Server, navigate to either of the two UI options described about and configure (i.e. add the UNC File Path, username, and password) the Local File Server as CIFS File Storage.
Tools
The Tools menu contains 7 menu items:
Top
Network
Processed
Disk Space
Large Files
Java Version
Groovy Version
VMWare Open VM Tools
 |
Top
The Top menu item opens a nonexhaustive dynamic process identification table detailing CPU and memory percentages amongst other values. The command for each running process is also listed in each row.
 |
To exit this table and return to the Tools menu, press the Q Key.
Processes
The Processes menu item opens an exhaustive process table similar to that detailed in the Top section described above.
 |
Disk Space
The Disk Space menu item opens a table detailing the Filesystem size, how much space is available and used, the use percentage, and the location on which the file system is mounted.
 |
Large Files
The Large Files menu item displays a table for file sizes of at least 1 million blocks, which is slightly less than 0.5 GB. If all existing file sizes are under this threshold the screen will be blank.
 |
Currently, the table only returns files stored in the logs file of the RapidIdentity Connect Main project.
 |
Java and Groovy Versions
The Java Version and Groovy Version menu items open an information window detailing the RapidIdentity installed versions of Java and Groovy.
 |
 |
VMWare Open VM Tools
VMWare Open VM Tools is open source software that can enhance the performance of VMWare products running RapidIdentity.
 |
 |
Once installed, this menu item should only display if RapidIdentity is running on VMWare.
Installing open-vm-tools
open-vm-tools is not included in the RapidIdentity ISO.
If open-vm-tools is desired, it is necessary to contact Identity Automation Support to install open-vm-tools.
Shutdown/Reboot
The Shutdown/Reboot interface allows users to either shutdown or reboot the operating system on which RapidIdentity is installed.
 |
Shutdown
Selecting Shutdown will automatically terminate RapidIdentity resulting in logging out of the CLI interface. If RapidIdentity is installed on a cloud server (e.g. AWS EC2 instance), that instance will be stopped.
Reboot
Selecting Reboot will trigger the operating system to restart. If RapidIdentity is installed on a cloud server (e.g. AWS EC2 instance), that instance will be restarted. Once that process is complete RapidIdentity will need to be restarted.
About
The About interface details the RapidIdentity Release version with information on the build and commit along with a copyright notice.
 |
Configure External Authentication Realms
Follow these steps to configure External Authentication Realms:
From the Module Selector, click Configuration. From the Security section, click Identity Providers.
Click External Auth Realms from the left menu items.
Click Create Realm.
Table 90. Create External Authentication RealmField
Value
Description
Type
Select LDAP from the drop-down menu
Required Field: complete to suit organizational needs
Name
Enter a name for the realm
Required Field: complete to suit organizational needs
Description
Enter a description for the realm
Complete to suit organizational needs
Enabled
True
Enables the new realm upon saving
Default
True
Sets the realm as the default
LDAP Server Set
Select a server set for the realm
Select the new LDAP server set that was created
Internal User Filter
Click Fix in LDAP Builder to enter the LDAP Filter
The copy icon can be used to copy the filter to the clipboard
Fix in LDAP Builder
Click to open the LDAP Filter search
Complete to suit organizational needs
Remote Search Base DN
Enter a distinguished name for search
Complete to suit organizational needs
Remote Username Attribute
This value is largely dependent on organizational preference and LDAP structure
This value is most often the value the end user will type during remote login. Common values include, but not limited to, cn, mail, sAMAccountName, userPrincipalName, and uid.
Remote User Filter
Complete to suit organizational needs
Click Fix in LDAP Builder to enter the LDAP Filter
To add external or internal attributes, under Attribute Map Items, click Add Item.
Enter the External and Internal Attributes. If two or more realms exist, check the default box to assign a default external authentication realm. Unless the Internal Realm Name is changed, it will display as "Internal."
Note
When at least one External Authentication Realm is enabled, users will see a drop-down on the login page that allows them to choose which realm to use for authentication.
When complete, click Save. The new realm now displays in the Current Realms box. At this point, configuring support for multiple LDAP servers is complete.
Trusted IdPs
In the Federation Authentication Method, RapidIdentity Federation acts as a SAML 2.0 Relying Party to a RapidIdentity Identity Provider or a third-party SAML Identity Provider.
When configuring the Federation Authentication Method for an Authentication Policy, you must choose a previously configured Trusted Identity Provider. Therefore, a Trusted Identity Provider contains all of the configuration necessary to facilitate SAML 2.0 SSO between RapidIdentity Federation and a third-party SAML 2.0 Identity Provider.
SAML 2.0 Trusted IdPs are configured similarly to RapidIdentity Trusted IdPs, but instead of having the fields host and port, they require the fields loginUrl and binding.
Note
If the Trusted IdP is in a domain different from RapidIdentity, you may need to add that domain as an Allowed Origin in the RapidIdentity CORS Security Configuration. The Allowed Origin value should take the form https://trusted_idp_domain.
To add a new IdP, click Add Trusted Identity Provider.
 |
A pop-out window will open with form fields. On the General tab, enter the information as provided by the identity provider.
 |
Field | Description |
|---|---|
Name | Required field - give the IdP a meaningful name |
Description | Optional description if desired |
Entity ID | The SAML 2.0 Entity ID of the third-party Identity Provider |
Type | The Identity Provider to be used when composing SAML responses. RapidIdentity makes it simple to point to an external RapidIdentity Identity Provider |
*Host | The hostname of the remote RapidIdentity Identity Provider |
*Port | The port the Identity Provider is to use with requests. This defaults to 443 |
Signing Certificate | Cut and paste the provider's certificate into this box |
At the bottom of this menu is an option to add Configuration Attribute Mappings. This option allows administrators to map attributes from the local Identity Provider to the remote Identity Provider. To match the same user in both systems, both systems must have a uniquely identifying attribute for each user. For example, if email address is the unique identifier, configure the Local field with the attribute name for email (e.g., "mail"), and the Remote field with the same attribute as it is named in the other system (e.g., "emailAddress").
Note
Attribute Mapping supports a special remote attribute value: @NameID. This indicates that the NameID attribute returned from the Remote Identity Provider should be mapped to the specified Local attribute.
 |