Connector reference
Installation and configuration reference for the connectors that are supported with ForgeRock® Identity Cloud software. This reference includes installation and configuration instructions for each connector, and examples that demonstrate how to use the connectors in a deployment.
Connectors let you connect to external resources such as LDAP, Active Directory, flat files, and others. This guide describes all the connectors supported with Identity Cloud, and how to configure them.
Built-in Connectors
Learn about the Identity Cloud built-in connectors.
RCS Bundled Connectors
Learn about the connectors bundled with RCS.
Additional Connectors
Learn about the additional connectors supported with Identity Cloud.
Connector Configuration
Learn how to configure connectors, and how to control what the connector synchronizes.
Remote Connector Configuration
Manage connectors on remote systems, with connector servers.
ICF Interfaces
Discover the ICF interfaces implemented by each connector.
Operation Options
Discover the operation options implemented by each connector.
Configurations shown in this guide are simplified to show essential aspects. Not all resources support all Identity Cloud operations; however, the resources shown here support most of the CRUD operations, reconciliation, and liveSync.
Resources
are external systems, databases, directory servers, and other sources of identity data, that are managed and audited by Identity Cloud. To connect to resources, Identity Cloud loads the ForgeRock Open Identity Connector Framework (ICF). ICF avoids the need to install agents to access resources, instead using the resources' native protocols. For example, ICF connects to database resources using the database’s Java connection libraries or JDBC driver, to directory servers over LDAP, and to UNIX systems over ssh
.
ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.
The ForgeRock Common REST API works across the platform to provide common ways to access web resources and collections of resources.
Identity Cloud built-in connectors
Identity Cloud provides these built-in connectors, for synchronization with the respective data stores:
Adobe Marketing Cloud ConnectorThe Adobe Marketing Cloud connector lets you manage profiles in an Adobe Campaign data store. |
Marketo ConnectorThe Marketo connector lets you synchronize between Identity Cloud user identities and a Marketo Lead Database. |
MS Graph API ConnectorThe Microsoft Graph API connector lets you manage users and groups in a Microsoft Azure tenant, and lets you synchronize users and groups between Identity Cloud and Azure. |
Salesforce ConnectorThe Salesforce connector enables provisioning, reconciliation, and synchronization between Salesforce and the Identity Cloud repository. |
ServiceNow ConnectorThe ServiceNow connector lets you manage objects in the ServiceNow platform, integrating with ServiceNow’s REST API. |
SuccessFactors ConnectorThe SAP SuccessFactors connector lets you synchronize user accounts between Identity Cloud and the SAP SuccessFactors HR system. |
Adobe Marketing Cloud connector
The Adobe Marketing Cloud connector lets you manage profiles in an Adobe Campaign data store. To use this connector, you need an Adobe ID. For information on the Adobe Marketing Cloud, see the Adobe documentation.
The connector supports a subset of the OpenICF operations, as listed in OpenICF Interfaces Implemented by the Adobe Marketing Cloud Connector.
Before you start
Configure a new integration on AdobeIO, as shown in the following steps. Note that these steps assume a specific version of the AdobeIO user interface. Please refer to the current Adobe documentation for configuring your AdobeIO integration.
The integration requires a public certificate and private key that will be used to sign the JWT token. |
-
Log in to https://console.adobe.io/.
-
Click Integrations > New Integration.
-
Click Access an API > Continue.
-
Under the Experience Cloud item, click Adobe Campaign > Continue, then click New integration > Continue.
-
Enter a name and short description for the new integration. For example,
IDM-managed
. -
Drag and drop your public certificate file into the Public keys certificates area. Alternatively, click Select a File, and browse to the file location.
-
Select a license, then click Create Integration.
-
Select Continue to integration details to obtain the Client Credentials required by the connector.
You will need these details for the connector configuration.
Configure the Adobe Marketing Cloud connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select Adobe Marketing Cloud Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
The following example shows an excerpt of the provisioner configuration. Enable the connector (set "enabled" : true
) then edit at least the configurationProperties
to match your Adobe IO setup:
"configurationProperties" : {
"endpoint" : "mc.adobe.io",
"imsHost" : "ims-na1.adobelogin.com",
"tenant" : "https://example.adobesandbox.com/",
"apiKey" : "",
"techAccId" : "example@techacct.adobe.com",
"orgId" : "example@AdobeOrg",
"clientSecret" : "CLIENT_SECRET",
"privateKey" : "PRIVATE_KEY"
},
...
endpoint
-
The Adobe IO endpoint for Marketing Cloud—
mc.adobe.io
by default. You should not have to change this value. imsHost
-
The Adobe Identity Management System (IMS) host—
ims-na1.adobelogin.com
by default. You should not have to change this value. tenant
-
Your AdobeIO tenant (organization) name or sandbox host. Do not specify the ID Cloud tenant details here.
apiKey
-
The API key (client ID) assigned to your API client account.
techAccId
-
Your Technical account ID, required to generate the JWT.
orgId
-
Your organization’s unique ID, for example
12345@AdobeOrg
. clientSecret
-
The client secret assigned to your API client account.
privateKey
-
The private key used to sign the JWT token, corresponds to the public key certificate that you attached to the integration.
For a list of all the configurable properties, see Adobe Marketing Cloud Connector Configuration.
Test the connector
When your connector is configured correctly, you can test its status by running the following command:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system?_action=test" [ { "name": "adobe", "enabled": true, "config": "config/provisioner.openicf/adobe", "connectorRef": { "bundleName": "org.forgerock.openicf.connectors.adobecm-connector", "connectorName": "org.forgerock.openicf.acm.ACMConnector", "bundleVersion": "[1.5.0.0,1.6.0.0)" }, "displayName": "Adobe Marketing Cloud Connector", "objectTypes": [ "__ALL__", "account" ], "ok": true } ]
A status of "ok": true
indicates that the connector can reach the configured
Adobe integration.
OpenICF Interfaces Implemented by the Adobe Marketing Cloud Connector
The Adobe Marketing Cloud Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Adobe Marketing Cloud Connector Configuration
The Adobe Marketing Cloud Connector has the following configurable properties:
Basic configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
The Adobe IO endpoint for Marketing Cloud. mc.adobe.io by default - you should not have to change this. |
||||
|
|
|
|
Yes |
Adobe Identity Management System (IMS) host. ims-na1.adobelogin.com by default - you should not have to change this. |
||||
|
|
|
|
Yes |
Your tenant (organization) name or sandbox host. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Adobe Integration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
Yes |
The API key (client ID) assigned to your API client account |
||||
|
|
|
|
Yes |
Your Technical account ID, required to generate the JWT |
||||
|
|
|
|
Yes |
Your organizations unique ID, for example 12345@AdobeOrg |
||||
|
|
|
Yes |
Yes |
The client secret assigned to your API client account |
||||
|
|
|
Yes |
Yes |
The private key used to sign the JWT token, corresponds to the public key certificate attached to the integration |
||||
|
|
|
Yes |
No |
The OAuth Access Token for the application |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Marketo connector
The Marketo connector lets you synchronize between Identity Cloud user identities and a Marketo leads database. You can synchronize any managed user to Marketo—those who have been added directly to the Identity Cloud repository, and those who have registered themselves through a Social Identity Provider.
The Marketo connector is an implementation of the Scripted Groovy Connector, and lets you interact with leads in a Marketo database.
To use the Marketo connector, you need the following:
-
A Marketo account
-
A client ID and client secret
-
The REST API URL for your Identity Cloud service
-
A custom list created in your Marketo leads database
To obtain these details from Marketo, see the Marketo documentation.
Configure the Marketo connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select Marketo Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
This sample connector configuration shows the mandatory properties:
Sample Marketo connector configuration
{
"displayName" : "MarketoConnector",
"description" : "Connector used to sync users to Marketo leads",
"author" : "ForgeRock",
"enabled" : true,
"connectorRef" : {
"bundleName" : "org.forgerock.openicf.connectors.marketo-connector",
"bundleVersion" : "[1.5.0.0,1.6.0.0)",
"connectorName" : "org.forgerock.openicf.connectors.marketo.MarketoConnector"
},
...
"configurationProperties" : {
"instance" : "<INSTANCE_FQDN>",
"clientId" : "<CLIENT_ID>",
"clientSecret" : "<CLIENT_SECRET>",
"leadFields" : null,
"partitionName" : null,
"listName" : "<LEAD_LIST_NAME>",
...
},
...
}
- instance
-
To locate the REST API endpoint URL in Marketo, select Admin > Web Services, scroll down to REST API, and find the endpoint. Use that REST endpoint as the value of the
instance
property in your connector configuration. Remove the protocol and/rest
from the URL. For example, if the endpoint ishttps://some-number.mktorest.com/rest
, the value of theinstance
property must besome-number.mktorest.com
. - clientId
-
Locate the client ID in the details of your Marketo service
LaunchPoint
. - clientSecret
-
Locate the client secret in the details of your Marketo service
LaunchPoint
. - listName
-
The name of the custom list created in your Marketo Leads database.
For details of all the configuration properties, see Marketo Connector Configuration.
When the connector is configured correctly, you can test its status by running the following command:
+
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system?_action=test" [ { "name": "marketo", "enabled": true, "config": "config/provisioner.openicf/marketo", "objectTypes": [ "__ALL__", "account" ], "connectorRef": { "bundleName": "org.forgerock.openicf.connectors.marketo-connector", "connectorName": "org.forgerock.openicf.connectors.marketo.MarketoConnector", "bundleVersion": "[1.5.0.0,1.6.0.0)" }, "displayName": "Marketo Connector", "ok": true } ]
A status of "ok": true
indicates that the connector can reach your Marketo database.
Implementation specifics
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The Marketo connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.
OpenICF Interfaces Implemented by the Marketo Connector
The Marketo Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Marketo Connector Configuration
The Marketo Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
Custom Sensitive Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
No |
Custom Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
Yes |
The Marketo-assigned FQDN for your instance |
||||
|
|
|
|
Yes |
Your OAuth2 client ID |
||||
|
|
|
Yes |
Yes |
Your OAuth2 client secret |
||||
|
|
|
|
No |
Comma-delimited list of lead fields to fetch; Leave empty for default set |
||||
|
|
|
|
No |
Name of the partition in which to create and update leads; May be left empty |
||||
|
|
|
|
Yes |
Name of the Marketo static list the connector will use to manage leads |
||||
|
|
|
|
Yes |
The access token for the application |
||||
|
|
|
|
Yes |
The expiration token for the application |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Operation Script Files
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
|
The name of the file used to perform the CREATE operation. |
||||
|
|
|
|
No |
The script used to customize some function of the connector. Read the documentation for more details. |
||||
|
|
|
|
|
The name of the file used to perform the AUTHENTICATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RUNSCRIPTONRESOURCE operation. |
||||
|
|
|
|
|
The name of the file used to perform the DELETE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RESOLVE_USERNAME operation. |
||||
|
|
|
|
|
The name of the file used to perform the SEARCH operation. |
||||
|
|
|
|
|
The name of the file used to perform the UPDATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the SCHEMA operation. |
||||
|
|
|
|
|
The name of the file used to perform the TEST operation. |
||||
|
|
|
|
|
The name of the file used to perform the SYNC operation. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Groovy Engine configuration
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
Directory into which to write classes. |
||||
|
|
|
|
No |
Warning Level of the compiler |
||||
|
|
|
|
No |
Gets the extensions used to find groovy files |
||||
|
|
|
|
No |
Sets the minimum of time after a script can be recompiled. |
||||
|
|
|
|
No |
Base class name for scripts (must derive from Script) |
||||
|
|
|
|
Yes |
The root folder to load the scripts from. If the value is null or empty the classpath value is used. |
||||
|
|
|
|
No |
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted. |
||||
|
|
|
|
No |
If true, debugging code should be activated |
||||
|
|
|
|
No |
Classpath for use during compilation. |
||||
|
|
|
|
No |
Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled. |
||||
|
|
|
|
No |
If true, the compiler should produce action information |
||||
|
|
|
|
No |
Encoding for source files |
||||
|
|
|
|
No |
If set to true recompilation is enabled |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Microsoft Graph API connector
The Microsoft Graph API connector is built in to the ID Cloud. When Microsoft Azure is the authoritative data source, this connector can read, search, and fetch data from, and provision data to, Microsoft Azure.
Before you start
Before you can use the connector, you must register an application with Azure. You need a Microsoft Azure subscription to complete this procedure:
-
Log in to the Microsoft Azure portal as an administrative user.
-
Under Azure services, select App registrations.
-
On the Register an application page, enter a name for the application; for example, FR-Connector.
-
Select the supported account types, and enter a Redirect URI.
The redirect URI is the Identity Cloud URI that Azure should redirect to after successful authentication; for example,
https://<id-cloud-tenant-name>./
. -
On the new registration page for your application, make a note of the Application (client) ID and the Directory (tenant) ID. You will need these to configure the connector:
-
Generate a client secret:
-
Select Certificates & secrets > New client secret.
-
Enter a description, select an expiration date, and click Add.
-
Copy the client secret Value:
You will not be able to retrieve the client secret in cleartext after you exit this screen. -
-
Set the API permissions:
-
Select API permissions, click Microsoft Graph, and then click Application permissions.
-
From the User item, select the following permissions:
-
User.Export.All
-
User.ManageIdentities.All
-
User.Read.All
-
User.ReadWrite.All
-
-
From the Group item, select the following permissions:
-
Group.Create
-
Group.Read.All
-
Group.ReadWrite.All
-
-
From the Directory item, select the following permissions:
-
Directory.Read.All
-
Directory.ReadWrite.All
-
-
Click Add permissions.
-
-
Grant admin consent for the API permissions:
On the Configured permissions page, Grant admin consent for org-name, then click Yes.
Configure the MS Graph API connector
You can configure the MS Graph API connector through the IDM admin UI or over REST.
To create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select MSGraphAPI Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
See this procedure to create a connector configuration over REST.
Test the MS Graph API connector
In your running Identity Cloud use these examples to test that the connector is configured correctly and operating as expected:
Check the Connector Configuration
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system?_action=test" { "name": "azuread", "enabled": true, "config": "config/provisioner.openicf/azuread", "connectorRef": { "bundleVersion": "[1.5.19.0,1.6.0.0]", "bundleName": "org.forgerock.openicf.connectors.msgraphapi-connector", "connectorName": "org.forgerock.openicf.connectors.msgraphapi.MSGraphAPIConnector" }, "displayName": "MSGraphAPI Connector", "objectTypes": [ "subscribedSku", "team", "user", "__ALL__", "group" ], "ok": true }
A status of "ok": true
indicates that the connector is configured correctly.
List User Entries
This command retrieves a list of users in your Azure tenant. You can also use any system-enabled filter, such as those described in Construct Queries:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user?_queryId=query-all-ids" { "result": [ { "_id": "c48be8cc-5846-4059-95e8-a7acbf6aec31" }, { "_id": "c7fe57e2-3159-45e1-b67a-435232fd88d9" }, { "_id": "9e714b5c-345a-430c-93f5-d8c6f9a2f225" }, ... ], ... }
Return a User Entry
This command retrieves a specific user entry from your Azure tenant:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user/c48be8cc-5846-4059-95e8-a7acbf6aec31" { "_id": "c48be8cc-5846-4059-95e8-a7acbf6aec31", "surname": "Jensen", "displayName": "Babs Jensen", "memberOf": [ "036f288c-6f71-41ae-9d09-6a68c8ba315b" ], "mail": "babs.jensen@example.onmicrosoft.com", "onPremisesExtensionAttributes": { ... }, "usageLocation": "FR", "userType": "Member", "identities": [ { "signInType": "userPrincipalName", "issuerAssignedId": "00991235@example.onmicrosoft.com", "issuer": "example.onmicrosoft.com" } ], "businessPhones": [], "createdDateTime": "2020-11-20T11:09:15Z", "accountEnabled": true, "userPrincipalName": "00991235@example.onmicrosoft.com", "proxyAddresses": [ "smtp:00991235@example.onmicrosoft.com", "SMTP:babs.jensen@example.onmicrosoft.com" ], "imAddresses": [], "passwordPolicies": "None", "mailNickname": "00991235", "givenName": "Babs", "__NAME__": "00991235@example.onmicrosoft.com" }
Create Users or Groups
This command creates a new user in your Azure tenant:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --header "content-type: application/json" \ --data '{ "surname": "Carter", "displayName": "Steve Carter", "givenName": "Steve", "userType": "Member", "accountEnabled": true, "mailNickname": "00654321", "userPrincipalName": "00654321@forgedemo.onmicrosoft.com", "__PASSWORD__": "MyPassw0rd" }' \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user?_action=create" { "_id": "9fa6c765-0872-45f6-8714-1dcd1ed94859", "surname": "Carter", "displayName": "Steve Carter", "memberOf": [], "onPremisesExtensionAttributes": { "extensionAttribute14": null, ... }, "userType": "Member", "identities": [ { "signInType": "userPrincipalName", "issuerAssignedId": "00654321@example.onmicrosoft.com", "issuer": "example.onmicrosoft.com" } ], "businessPhones": [], "createdDateTime": "2020-12-18T13:23:58Z", "accountEnabled": true, "userPrincipalName": "00654321@example.onmicrosoft.com", "proxyAddresses": [], "imAddresses": [], "mailNickname": "00654321", "givenName": "Steve", "__NAME__": "00654321@example.onmicrosoft.com" }
Update Entries
This command changes the password for the user created previously:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request PATCH \ --header "content-type: application/json" \ --data '[ { "operation": "replace", "field": "__PASSWORD__", "value": "MyNewPassw0rd" } ]' \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user/9fa6c765-0872-45f6-8714-1dcd1ed94859" { "_id": "9fa6c765-0872-45f6-8714-1dcd1ed94859", "surname": "Carter", "displayName": "Steve Carter", "memberOf": [], "onPremisesExtensionAttributes": { "extensionAttribute14": null, ... }, "userType": "Member", "identities": [ { "signInType": "userPrincipalName", "issuerAssignedId": "00654321@forgedemo.onmicrosoft.com", "issuer": "forgedemo.onmicrosoft.com" } ], "businessPhones": [], "createdDateTime": "2020-12-18T13:23:58Z", "accountEnabled": true, "userPrincipalName": "00654321@forgedemo.onmicrosoft.com", "proxyAddresses": [], "imAddresses": [], "mailNickname": "00654321", "givenName": "Steve", "__NAME__": "00654321@forgedemo.onmicrosoft.com" }
Delete Users and Groups
This command deletes the user created previously:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user/9fa6c765-0872-45f6-8714-1dcd1ed94859" { "_id": "9fa6c765-0872-45f6-8714-1dcd1ed94859", "surname": "Carter", "displayName": "Steve Carter", "memberOf": [], "onPremisesExtensionAttributes": { "extensionAttribute14": null, ... }, "userType": "Member", "identities": [ { "signInType": "userPrincipalName", "issuerAssignedId": "00654321@forgedemo.onmicrosoft.com", "issuer": "forgedemo.onmicrosoft.com" } ], "businessPhones": [], "createdDateTime": "2020-12-18T13:23:58Z", "accountEnabled": true, "userPrincipalName": "00654321@forgedemo.onmicrosoft.com", "proxyAddresses": [], "imAddresses": [], "mailNickname": "00654321", "givenName": "Steve", "__NAME__": "00654321@forgedemo.onmicrosoft.com" }
Manage User Licenses
The MicroSoft Graph API connector lets you list the available licenses in your Azure data source, and manage those licenses for specific users:
List Available Licenses in Azure
This command lists the values of the read-only subscribedSku
object. For more information about this object class, see the corresponding Microsoft
documentation:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/subscribedSku?_queryFilter=true" { "result": [ { "_id": "5ee8xxxx-xxxx-xxxx-xxxx-76dc2c2c30bc_f245ecc8-xxxx-xxxx-xxxx-xxxx114de5f3", "prepaidUnits": { "warning": 0, "enabled": 1, "suspended": 0 }, "skuId": "f245ecc8-xxxx-xxxx-xxxx-xxxx114de5f3", "skuPartNumber": "O365_BUSINESS_PREMIUM", "capabilityStatus": "Enabled", "appliesTo": "User", "consumedUnits": 1, "__NAME__": "O365_BUSINESS_PREMIUM", "servicePlans": [ { "servicePlanName": "RMS_S_BASIC", "provisioningStatus": "PendingProvisioning", "appliesTo": "Company", "servicePlanId": "31cxxxxxxxxxxxxxxxxxxxxxxxxxxx122" }, { "servicePlanName": "POWER_VIRTUAL_AGENTS_O365_P2", "provisioningStatus": "PendingProvisioning", "appliesTo": "User", "servicePlanId": "041xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxaee" }, { "servicePlanName": "CDS_O365_P2", "provisioningStatus": "PendingProvisioning", "appliesTo": "User", "servicePlanId": "95bxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx95a" }, ... ] } ], ... }
List a User’s Licenses
Each user object can include a read-only licenses
property that contains an
array of objects (maps).
This command lists a specific user’s licenses:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user/c48be8cc-5846-4059-95e8-a7acbf6aec31?_fields=licenses" { "_id": "c48be8cc-5846-4059-95e8-a7acbf6aec31", "licenses": [ { "skuPartNumber": "O365_BUSINESS_PREMIUM", "servicePlans": [ { "servicePlanName": "RMS_S_BASIC", "provisioningStatus": "PendingProvisioning", "appliesTo": "Company", "servicePlanId": "31cxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx122" }, { "servicePlanName": "POWER_VIRTUAL_AGENTS_O365_P2", "provisioningStatus": "PendingProvisioning", "appliesTo": "Company", "servicePlanId": "041xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxaee" }, { "servicePlanName": "CDS_O365_P2", "provisioningStatus": "PendingProvisioning", "appliesTo": "Company", "servicePlanId": "95bxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx95a" }, ... ], "id": "c8noxxxxsEqoxxxxLCwwxxxxRfKvxxxxth8nxxxx5fM", "skuId": "f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3" } ] }
Add and Remove a User’s Licenses
You cannot manipulate a user’s licenses
property directly, because it is
read-only. To add or remove licenses for a user, set the addLicenses
or
removeLicenses
properties when you create or update the user.
The connector does not currently support PATCH |
This command updates an existing user entry to add a license with the `skuId`f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3
:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --header "If-None-Match: *" \ --request PUT \ --data '{ "addLicenses": [ { "skuId": "f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3" } ] }' \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user/c48be8cc-5846-4059-95e8-a7acbf6aec31"
This command updates the user entry to remove the license with `skuId`f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3
:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --header "If-Match: *" \ --request PUT \ --data '{ "removeLicenses": "f24xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx5f3" }' \ "https://tenant-name.forgeblocks.com/openidm/system/azuread/user/c48be8cc-5846-4059-95e8-a7acbf6aec31"
Synchronize Accounts Between Identity Cloud and Azure
To use the MS Graph API connector to synchronize accounts between Identity Cloud and Azure, set up a mapping between the two data stores.
OpenICF Interfaces Implemented by the MSGraphAPI Connector
The MSGraphAPI Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
MSGraphAPI Connector Configuration
The MSGraphAPI Connector has the following configurable properties:
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
The Azure AD tenant name or id |
||||
|
|
|
|
Yes |
The clientID used by the connector during the OAuth flow |
||||
|
|
|
Yes |
No |
The client secret used by the connector during the OAuth flow |
||||
|
|
|
|
No |
The Http proxy host |
||||
|
|
|
|
No |
The Http proxy port |
||||
|
|
|
|
No |
The Http proxy user name |
||||
|
|
|
Yes |
No |
The Http proxy user password |
||||
|
|
|
|
No |
If set to true, the Azure object will be deleted permanently on delete operation. |
||||
|
|
|
|
No |
Define throttling for read operations either per seconds ("30/sec") or per minute ("100/min"). |
||||
|
|
|
|
No |
Define throttling for write operations (create/update/delete) either per second ("30/sec") or per minute ("100/min"). |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Microsoft Graph API remote connector
You can configure the Microsoft Graph API connector as a remote connector. As a Java connector, the MS Graph API connector functions like any standard Identity Cloud connector.
You can download the MS Graph API connector from here.
See Remote connector configuration for configuring the MS Graph API remote connector.
The Microsoft (MS) Graph API remote connector uses the MS Graph SDK for Java and the Authentication Providers for the MS Graph Java SDK.
Unlike the PowerShell connector for Azure, the MS Graph API connector is a Java connector, and does not need a .NET RCS to run.
Salesforce connector
The Salesforce connector lets you provision, reconcile, and synchronize users between Salesforce and the Identity Cloud managed user repository.
This chapter describes how to install and configure the Salesforce connector, and how to perform basic tests to ensure that it’s running correctly.
Before you configure the Salesforce connector
The instructions in this chapter assume that you have an existing Salesforce organization, a Salesforce administrative account, and a Connected App with OAuth enabled.
For instructions on setting up a Connected App, see the corresponding Salesforce documentation. When you have set up the Connected App, locate the Consumer Key and Consumer Secret. You will need these details to configure the connector.
The Salesforce connector is bundled with Identity Cloud and has no specific installation requirements.
Configure the Salesforce connector using the IDM admin UI
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select Salesforce Connector - 1.5.20.5.
-
Complete the Base Connector Details.
The Login URL is the OAuth endpoint used to make the OAuth authentication request to Salesforce.
When you create your connected app, you are instructed to wait 2-10 minutes for the settings to propagate across all the Salesforce data centers. If you are using a Salesforce test tenant, such as https://eu26.lightning.force.com
, you can specify a custom URL here and enter the FQDN of the test tenant. This lets you test the connector without waiting for the new app settings to be propagated. -
Click Save.
The connector attempts to access your Salesforce organization.
-
Enter your Salesforce login credentials.
-
On the permission request screen, click Allow to enable Identity Cloud to access your Salesforce Connected App.
When your connector is configured correctly, the connector displays as Active in the IDM admin UI.
Implementation specifics
-
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The Salesforce connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value. Salesforce does not support multi-valued attributes.
-
Attributes themselves cannot be removed from Salesforce. The connector therefore performs an update with
""
as the value of the attribute being removed. This sets the value of the removed attribute tonull
.Salesforce does not support application user DELETE requests. -
The Salesforce connector supports any Salesforce object that is available to the API. To check which objects are available, log in to Salesforce Workbench to access the API explorer. This URL points to Version 49 of the API. Adjust the URL for the latest API version.
Because the number of Salesforce objects is potentially very large, the Salesforce connector configuration includes a
supportedObjectTypes
property that lets you specify the objects you want to support. The connector checks the metadata in Salesforce for each of the objects you list in this property, and dynamically builds the required schema. The sample connector configuration file (provisioner.openicf-salesforce.json
) generates the schema only for the User object:{ ... "configurationProperties": { ... "supportedObjectTypes": [ "User" ] }, }
You can add any object to the list of
supportedObjectTypes
, and the connector will build the schema for that object. -
The Salesforce API restricts how query results can be paged. The default, and maximum page size is
2000
. The minimum page size is200
. The Salesforce API does not guarantee that the requested page size is the actual page size. Returned results might vary, to maximize performance.For example, the following query (with
"pageSize=1"
) might return more than one user if more than one user exists in Salesforce:https://tenant-name.forgeblocks.com/openidm/system/salesforce/user?_queryId=query-all-ids&_pageSize=1
For more information, see the Salesforce documentation.
OpenICF Interfaces Implemented by the Salesforce Connector
The Salesforce Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Salesforce Connector Configuration
The Salesforce Connector has the following configurable properties:
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
The client identifier |
||||
|
|
|
|
Yes |
The secure client secret for OAUTH |
||||
|
|
|
|
Yes |
The refresh token for the application |
||||
|
|
|
Yes |
|
The endpoint from which a new access token should be queried (https://login.salesforce.com/services/oauth2/token) |
||||
|
|
|
|
Yes |
The URL of the Salesforce instance (such as https://example-com.cs1.my.salesforce.com) |
||||
|
|
|
|
No |
The Salesforce API version |
||||
|
|
|
|
No |
The maximum connection timeout |
||||
|
|
|
|
No |
The hostname of an http proxy, used between the connector and the Salesforce service provider |
||||
|
|
|
|
No |
The proxy port number, if an HTTP proxy is used between the connector and the Salesforce service provider |
||||
|
|
|
|
No |
The maximum size of the HTTP connection pool |
||||
|
|
|
|
No |
Defines a list of Salesforce objects that will be used to dynamically build the provisioner schema |
||||
|
|
|
|
No |
The URI of an HTTP proxy that contains the scheme, host, and port number for that proxy |
||||
|
|
|
|
No |
The proxy username to use with a proxy that requires authentication |
||||
|
|
|
|
No |
The proxy user password to use with a proxy that requires authentication |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
ServiceNow connector
This connector lets you manage objects in the ServiceNow platform, integrating with ServiceNow’s REST API.
Before you start
The connector requires a ServiceNow instance with OAuth enabled. You might need to activate the OAuth plugin and set the OAuth activation property if OAuth is not yet enabled on your ServiceNow instance. For more information, see the ServiceNow documentation that corresponds to your ServiceNow version.
When Oauth is enabled, register an OAuth client application for the connection
to Identity Cloud. Take note of the client_id
and client_secret
of the
application, as you need these values when you configure the connector.
The connector configuration must include a ServiceNow user who has the following roles:
-
admin
-
rest_api_explorer
If you do not want to give complete admin
rights to this user, you can create
a new role that provides access to the following tables:
-
sys_user_has_role
-
sys_user_grmember
-
sys_user_delegate
-
sys_user_role
-
sys_user_group
-
core_company
-
cmn_department
-
cmn_cost_center
-
cmn_location
Configure the ServiceNow connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select ServiceNow Connector - 1.5.20.5.
-
Complete the Base Connector Details.
instance
(string)-
The ServiceNow instance URL; for example,
example.service-now.com/
. username
(string)-
The name of a ServiceNow user with the
admin
andrest_api_explorer
roles. password
(string)-
The password of the ServiceNow user.
clientID
(string)-
The ID of your OAuth application.
clientSecret
(string)-
The client secret of your OAuth application.
-
Click Save.
The following excerpt of connector configuration shows the required configurationProperties
:
"configurationProperties" : {
"instance" : "example.service-now.com/",
"username" : "admin",
"password" : {encrypted-password},
"clientID" : "4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxee",
"clientSecret" : {encrypted-client-secret},
"readSchema" : false
}
Identity Cloud encrypts the value of the password
and clientSecret
on startup.
Test the connector
When your connector is configured correctly, test its status by running the following command:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system?_action=test" [ { "name": "serviceNow", "enabled": true, "config": "config/provisioner.openicf/serviceNow", "connectorRef": { "bundleVersion": "[1.5.0.0,1.6.0.0)", "bundleName": "org.forgerock.openicf.connectors.servicenow-connector", "connectorName": "org.forgerock.openicf.connectors.servicenow.ServiceNowConnector" }, "displayName": "ServiceNow Connector", "objectTypes": [ "delegate", "role", "__ALL__", "costCenter", "location", "company", "userHasGroup", "department", "user", "userHasRole", "group" ], "ok": true } ]
A status of "ok": true
indicates that the ServiceNow connector can reach the configured resource provider.
Manage users with the ServiceNow connector
These examples show the basic CRUD operations using the ServiceNow connector.
Query all ServiceNow users
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/serviceNow/user?_queryId=query-all-ids" { "result": [ { "_id": "02826bf03710200044e0bfc8bcbe5d3f", "__NAME__": "lucius.bagnoli@example.com" }, { "_id": "02826bf03710200044e0bfc8bcbe5d55", "__NAME__": "jimmie.barninger@example.com" }, { "_id": "02826bf03710200044e0bfc8bcbe5d5e", "__NAME__": "melinda.carleton@example.com" }, ... ], "resultCount": 578, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 }
Query a single ServiceNow user
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/serviceNow/user/02826bf03710200044e0bfc8bcbe5d3f" { "_id": "02826bf03710200044e0bfc8bcbe5d3f", "internal_integration_user": false, "department": "5d7f17f03710200044e0bfc8bcbe5d43", "sys_mod_count": "5", "location": "0002c0a93790200044e0bfc8bcbe5df5", "web_service_access_only": false, "sys_updated_on": "2018-02-25 16:42:47", "sys_domain": "global", "notification": "2", "sys_created_by": "admin", "locked_out": "false", "__NAME__": "lucius.bagnoli@example.com", "company": "81fd65ecac1d55eb42a426568fc87a63", "sys_domain_path": "/", "password_needs_reset": "false", "active": "true", "gender": "Male", "sys_created_on": "2012-02-18 03:04:49", "sys_class_name": "sys_user", "calendar_integration": "1", "email": "lucius.bagnoli@example.com", "sys_id": "02826bf03710200044e0bfc8bcbe5d3f", "user_password": "md5230ls7L", "user_name": "lucius.bagnoli", "sys_updated_by": "developer.program@snc", "vip": "false", "last_name": "Bagnoli", "first_name": "Lucius" }
Create a ServiceNow user
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "__NAME__": "bjensen@example.com", "first_name": "Barbara", "last_name": "Jensen", "email": "bjensen@example.com", "phone": "555-123-1234" }' \ "https://tenant-name.forgeblocks.com/openidm/system/serviceNow/user?_action=create" { "_id": "4116e0690fa01300f6af65ba32050e7a", "sys_mod_count": "0", "password_needs_reset": "false", "notification": "2", "locked_out": "false", "phone": "555-123-1234", "sys_created_on": "2018-02-27 13:33:38", "first_name": "Barbara", "email": "bjensen@example.com", "active": "true", "sys_domain": "global", "calendar_integration": "1", "web_service_access_only": false, "vip": "false", "sys_id": "4116e0690fa01300f6af65ba32050e7a", "sys_updated_on": "2018-02-27 13:33:38", "sys_domain_path": "/", "sys_created_by": "admin", "sys_class_name": "sys_user", "last_name": "Jensen", "__NAME__": "bjensen@example.com", "sys_updated_by": "admin", "internal_integration_user": false }
Update a ServiceNow user
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --header "If-Match:*" \ --request PUT \ --data '{ "__NAME__": "bjensen@example.com", "first_name": "Barbara", "last_name": "Jensen", "email": "bjensen@example.com", "phone": "555-000-0000" }' \ "https://tenant-name.forgeblocks.com/openidm/system/serviceNow/user/4116e0690fa01300f6af65ba32050e7a" { "_id": "4116e0690fa01300f6af65ba32050e7a", "sys_mod_count": "1", "password_needs_reset": "false", "notification": "2", "locked_out": "false", "phone": "555-000-0000", "sys_created_on": "2018-02-27 13:33:38", "first_name": "Barbara", "email": "bjensen@example.com", "active": "true", "sys_domain": "global", "calendar_integration": "1", "web_service_access_only": false, "vip": "false", "sys_id": "4116e0690fa01300f6af65ba32050e7a", "sys_updated_on": "2018-02-27 13:35:32", "sys_domain_path": "/", "sys_created_by": "admin", "sys_class_name": "sys_user", "last_name": "Jensen", "__NAME__": "bjensen@example.com", "sys_updated_by": "admin", "internal_integration_user": false }
Delete a ServiceNow user
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "If-Match:*" \ --request DELETE \ "https://tenant-name.forgeblocks.com/openidm/system/serviceNow/user/4116e0690fa01300f6af65ba32050e7a" { "_id": "4116e0690fa01300f6af65ba32050e7a", "sys_mod_count": "1", "password_needs_reset": "false", "notification": "2", "locked_out": "false", "phone": "555-000-0000", "sys_created_on": "2018-02-27 13:33:38", "first_name": "Barbara", "email": "bjensen@example.com", "active": "true", "sys_domain": "global", "calendar_integration": "1", "web_service_access_only": false, "vip": "false", "sys_id": "4116e0690fa01300f6af65ba32050e7a", "sys_updated_on": "2018-02-27 13:35:32", "sys_domain_path": "/", "sys_created_by": "admin", "sys_class_name": "sys_user", "last_name": "Jensen", "__NAME__": "bjensen@example.com", "sys_updated_by": "admin", "internal_integration_user": false }
Synchronize ServiceNow users
The ServiceNow connector supports bidirectional reconciliation and liveSync. To set up user synchronization, create a mapping between user identities and ServiceNow users.
This example assumes that you have configured a mapping. The example runs a reconciliation operation from ServiceNow to the managed user repository:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/recon?_action=recon&mapping=systemServicenowUser_managedUser" { "_id": "19755e51-5c3b-4362-b316-601856cb282c-13624", "state": "ACTIVE" }
The following example runs a liveSync operation from ServiceNow to the managed user repository:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system/serviceNow/user?_action=liveSync" { "connectorData": { "nativeType": "string", "syncToken": "2018-02-275 11:29:15" }, "_rev": "0000000031285d9b", "_id": "SYSTEMSERVICENOWUSER" }
The ServiceNow connector does not support the |
Implementation specifics
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The ServiceNow connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.
OpenICF Interfaces Implemented by the ServiceNow Connector
The ServiceNow Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
ServiceNow Connector Configuration
The ServiceNow Connector has the following configurable properties:
Basic configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
URL of the ServiceNow instance, for example: dev00000.service-now.com |
||||
|
|
|
|
Yes |
An API user in ServiceNow that can consume the REST API |
||||
|
|
|
Yes |
Yes |
Password for the user |
||||
|
|
|
|
Yes |
Client ID of the OAuth application in ServiceNow |
||||
|
|
|
Yes |
Yes |
Client Secret for the preceding Client ID |
||||
|
|
|
|
No |
Default page size |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
SAP SuccessFactors connector
The SAP SuccessFactors connector lets you synchronize SAP SuccessFactors users with Identity Cloud user identities.
OpenICF Interfaces Implemented by the SuccessFactors
The SuccessFactors implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
SuccessFactors Configuration
The SuccessFactors has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
Hostname of the target |
||||
|
|
|
|
Yes |
The client identifier |
||||
|
|
|
|
Yes |
User Id for authentication |
||||
|
|
|
|
Yes |
The private key to be used for signing JWT |
||||
|
|
|
|
Yes |
Company ID as present in target application |
||||
|
|
|
|
No |
Page Size of Search |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Remote Connector Server (RCS) bundled connectors
The remote connectors are used for synchronization with data stores on premises, in a private cloud, or in a public cloud.
Based on their availability here are two types of remote connectors:
-
RCS bundled connectors: Remote connectors that are bundled with the ForgeRock remote connector server (RCS).
-
Additional connectors: Connectors that are available for download from the ForgeRock Download Center.
Remote Connector Server (RCS) bundled connectors
ForgeRock provides a number of connectors that are bundled with RCS:
CSV File ConnectorThe CSV file connector is useful when importing users, either for initial provisioning or for ongoing updates. When used continuously in production, a CSV file serves as a change log, often containing only user records that have changed. |
Database Table ConnectorThe Database Table connector enables provisioning to a single table in a JDBC database. |
Groovy ConnectorThe Groovy Connector Toolkit lets you run a Groovy script for any ICF operation, such as search, update, create, and others, on any external resource. |
Kerberos ConnectorThe Kerberos connector is an implementation of the SSH connector, and is based on Java Secure Channel (JSch) and the Java implementation of the Expect library (Expect4j). This connector lets you manage Kerberos user principals from Identity Cloud. |
LDAP ConnectorThe LDAP connector is based on JNDI, and can be used to connect to any LDAPv3-compliant directory server, such as ForgeRock Directory Services (DS), Active Directory, SunDS, Oracle Directory Server Enterprise Edition, IBM Security Directory Server, and OpenLDAP. |
SCIM ConnectorThe SCIM connector is based on the Simple Cloud Identity Management (SCIM) protocol, and lets you manage user and group accounts on any SCIM-compliant resource provider, such as Slack, Facebook, or SalesForce. |
Scripted REST ConnectorThe Scripted REST connector is an implementation of the Scripted Groovy Connector. This connector lets you interact with any REST API, using Groovy scripts for the ICF operations. |
Scripted SQL ConnectorThe Scripted SQL connector is an implementation of the Scripted Groovy Connector. This connector lets you interact with any SQL database, using Groovy scripts for the ICF operations. |
SSH ConnectorThe SSH connector is an implementation of the Scripted Groovy Connector, and is based on Java Secure Channel (JSch) and the Java implementation of the Expect library (Expect4j). This connector lets you interact with any SSH server, using Groovy scripts for the ICF operations. |
CSV file connector
The CSV file connector is useful when importing users, either for initial provisioning or for ongoing updates. When used continuously in production, a CSV file serves as a change log, often containing only user records that have changed.
This connector does not verify CSV data before attempting a synchronization. You must ensure that your CSV file is complete and properly formed before using the connector. Do not remove or replace CSV files that are the source or target of an active scheduled reconciliation or synchronization operation. |
Configure the CSV file connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select CSV File Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
The only required configuration property is the path to the csvFile
:
"configurationProperties" : {
"csvFile" : "&{idm.instance.dir}/data/csvConnectorData.csv"
}
For a list of all configuration properties for this connector, see Configuration Properties.
If you change the structure of the CSV file resource, by adding or removing columns, you must update the corresponding object |
OpenICF Interfaces Implemented by the CSV File Connector
The CSV File Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Batch
-
Execute a series of operations in a single request.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
CSV File Connector Configuration
The CSV File Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
The CSV header that maps to the password for each row. Use this property when password-based authentication is required. |
||||
|
|
|
|
No |
The character(s) used to replace spaces within column names. |
||||
|
|
|
|
Yes |
The full path to the CSV file that is the data source for this connector. |
||||
|
|
|
|
No |
The character string in the CSV file that is used to terminate each line. |
||||
|
|
|
|
No |
The CSV header that maps to the uid (or name) for each row. |
||||
|
|
|
|
No |
The character in the CSV file that is used to encapsulate strings. |
||||
|
|
|
|
No |
The character in the CSV file that is used to separate field values. |
||||
|
|
|
|
No |
The number of historical copies of the CSV file to retain when performing synchronization operations. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Database Table connector
The Database Table connector lets you provision to a single table in a JDBC database.
Configure the Database Table connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select Database Table Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
The following excerpt shows a sample Database Table connector configuration:
"configurationProperties" : {
"url" : "jdbc:mysql://localhost:3306/contractordb?serverTimezone=UTC",
"driverClassName" : "com.mysql.cj.jdbc.Driver",
"username" : "root",
"password" : "password",
"table" : "people",
"keyColumn" : "EMAIL",
"passwordColumn" : "",
"changeLogColumn" : "CHANGE_TIMESTAMP",
"disablePaging" : false,
"enableEmptyString" : false,
"quoting" : "",
"rethrowAllSQLExceptions" : true,
"nativeTimestamps" : false,
"allNative" : false,
"suppressPassword" : true,
"validationQueryTimeout" : -1,
"validationQuery" : "SELECT 1 FROM DUAL",
"validationInterval" : 3000,
"initialSize" : 10,
"maxIdle" : 100,
"minIdle" : 10,
"maxWait" : 30000,
"maxActive" : 100,
"maxAge" : 0,
"minEvictableIdleTimeMillis" : 60000,
"timeBetweenEvictionRunsMillis" : 5000,
"testWhileIdle" : false,
"testOnBorrow" : true
}
The mandatory configurable properties are as follows:
url
-
The JDBC database address that contains the table to which you are provisioning. The format of the url will change depending on the type of database, such as
jdbc:mysql://localhost:3306/contractordb?serverTimezone=UTC
, orjdbc:oracle:thin:@//localhost:3306/contractordb
. Note that the address includes the name of the database you are connecting to. driverClassName
-
The class name of the driver you are using to connect to a database. The name varies depending on the type of database you are using, such as
oracle.jdbc.OracleDriver
, orcom.mysql.cj.jdbc.Driver
. table
-
The name of the table in the JDBC database that contains the user accounts.
keyColumn
-
The column value that is used as the unique identifier for rows in the table.
If you want to map NAME
orUID
to an attribute in Identity Cloud, change thekeyColumn
to a column in the SQL schema that does not match any of the target properties in your mapping; otherwise, a conflict occurs and Identity Cloud does not create the account. Previously, this column wasUNIQUE_ID
.
Unless the database is configured to not need authentication, username
and password
are also required.
Implementation specifics
-
To use this connector for liveSync, add a changelog type column to the database and provide the name of this column in the
changeLogColumn
property. Note that the Database Table connector supports liveSync for create and update operations only. To detect deletes in the database you must run a full reconciliation. -
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The Database Table connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.
-
The Database Table connector supports paged reconciliation queries only for the following databases:
-
MySQL
-
PostgreSQL
-
Oracle Database 12c and later versions
-
Microsoft SQL Server 2012 and later versions
Paging is enabled by default. If you are connecting to a database for which paging is not supported, you must disable it by setting "disablePaging" : true
in the connector configuration.
For more information about configuring paged reconciliation queries, see Paging Reconciliation Query Results.
-
-
If your database does not support precise (nanosecond) timestamps, you can use the
inclusiveSync
configuration property to ensure that modified entries are not missed in liveSync operations. IfinclusiveSync
is set totrue
, the connector synchronizes all entries whose change timestamp is greater than or equal to thesyncToken
. Be aware that if you set this property totrue
, the activity log creates a new entry every time liveSync occurs, even if entries are changed. This can lead to rapid growth of the activity audit log.
OpenICF Interfaces Implemented by the Database Table Connector
The Database Table Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Database Table Connector Configuration
The Database Table Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
The connection properties that will be sent to our JDBC driver when establishing new connections. Format of the string must be [propertyName=property;]* NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here. The default value is null. |
||||
|
|
|
|
No |
Set this to true to propagate the interrupt state for a thread that has been interrupted (not clearing the interrupt state). Default value is false for backwards compatibility. |
||||
|
|
|
|
No |
Set this to true if you wish to put a facade on your connection so that it cannot be reused after it has been closed. This prevents a thread holding on to a reference of a connection it has already called closed on, to execute queries on it. |
||||
|
|
|
|
No |
The default catalog of connections created by this pool. |
||||
|
|
|
|
No |
To avoid excess validation, run validation at most at this frequency (in milliseconds). If a connection is due for validation, but was validated within this interval, it will not be validated again. The default value is 3000 (3 seconds). |
||||
|
|
|
|
No |
Flag whether ignore error of connection creation while initializing the pool. Set to true if you want to ignore error of connection creation while initializing the pool. Set to false if you want to fail the initialization of the pool by throwing exception. |
||||
|
|
|
|
No |
Register the pool with JMX or not. The default value is true. |
||||
|
|
|
|
No |
If autoCommit==false then the pool can complete the transaction by calling commit on the connection as it is returned to the pool If rollbackOnReturn==true then this attribute is ignored. Default value is false. |
||||
|
|
|
|
No |
Flag to log stack traces for application code which abandoned a Connection. Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. The default value is false. |
||||
|
|
|
|
No |
The maximum number of connections that should be kept in the pool at all times. Idle connections are checked periodically (if enabled) and connections that have been idle for longer than minEvictableIdleTimeMillis are released. The default value is derived from maxActive:100. (Also see testWhileIdle.) |
||||
|
|
|
|
No |
The indication of whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false and this property has to be set in order for the pool cleaner/test thread is to run (also see timeBetweenEvictionRunsMillis) |
||||
|
|
|
|
No |
Flag to remove abandoned connections if they exceed the removeAbandonedTimeout. If set to true a connection is considered abandoned and eligible for removal if it has been in use longer than the removeAbandonedTimeout Setting this to true can recover db connections from applications that fail to close a connection. See also logAbandoned The default value is false. |
||||
|
|
|
|
No |
Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that connections are eligible for closure as soon as removeAbandonedTimeout has been reached. |
||||
|
|
|
|
No |
The minimum number of established connections that should be kept in the pool at all times. The connection pool can shrink below this number if validation queries fail. The default value is derived from initialSize:10. (Also see testWhileIdle.) |
||||
|
|
|
|
No |
The default read-only state of connections created by this pool. If not set then the setReadOnly method will not be called. (Some drivers dont support read only mode, ex: Informix) |
||||
|
|
|
|
No |
The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. Default value is 30000 (30 seconds) |
||||
|
|
|
|
No |
Set this to true to log errors during the validation phase to the log file. If set to true, errors will be logged as SEVERE. Default value is false for backwards compatibility. |
||||
|
|
|
|
No |
The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar |
||||
|
|
|
|
No |
Returns the name of the connection pool. By default a JVM unique random name is assigned. |
||||
|
|
|
|
No |
Returns true if this connection pool is configured to wrap statements in order to enable equals() and hashCode() methods to be called on the closed statements if any statement proxy is set. |
||||
|
|
|
|
No |
A custom query to be run when a connection is first created. The default value is null. |
||||
|
|
|
|
No |
The timeout in seconds before a connection validation queries fail. This works by calling java.test_sample.Statement.setQueryTimeout(seconds) on the statement that executes the validationQuery. The pool itself doesnt timeout the query, it is still up to the JDBC driver to enforce query timeouts. A value less than or equal to zero will disable this feature. The default value is -1. |
||||
|
|
|
|
No |
The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query does not have to return any data, it just cant throw a SQLException. The default value is null. Example values are SELECT 1(mysql), select 1 from dual(oracle), SELECT 1(MS Sql Server) |
||||
|
|
|
|
No |
If autoCommit==false then the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool Default value is false. |
||||
|
|
|
|
No |
By default, the jdbc-pool will ignore the DataSource.getConnection(username,password) call, and simply return a previously pooled connection under the globally configured properties username and password, for performance reasons. The pool can however be configured to allow use of different credentials each time a connection is requested. To enable the functionality described in the DataSource.getConnection(username,password) call, simply set the property alternateUsernameAllowed to true. Should you request a connection with the credentials user1/password1 and the connection was previously connected using different user2/password2, the connection will be closed, and reopened with the requested credentials. This way, the pool size is still managed on a global level, and not on a per schema level. |
||||
|
|
|
|
No |
The name of a class which implements the org.apache.tomcat.jdbc.pool.Validator interface and provides a no-arg constructor (may be implicit). If specified, the class will be used to create a Validator instance which is then used instead of any validation query to validate connections. The default value is null. An example value is com.mycompany.project.SimpleValidator. |
||||
|
|
|
|
No |
Timeout value in seconds. Similar to to the removeAbandonedTimeout value but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning if logAbandoned is set to true. If this value is equal or less than 0, no suspect checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets logged and a JMX notification gets sent once. |
||||
|
|
|
|
No |
Set to true if you wish the ProxyConnection class to use String.equals and set to false when you wish to use == when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value is true. |
||||
|
|
|
|
No |
Timeout in seconds before an abandoned(in use) connection can be removed. The default value is 60 (60 seconds). The value should be set to the longest running query your applications might have. |
||||
|
|
|
|
No |
The default auto-commit state of connections created by this pool. If not set, default is JDBC driver default (If not set then the setAutoCommit method will not be called.) |
||||
|
|
|
|
No |
Returns true if we should run the validation query when connecting to the database for the first time on a connection. Normally this is always set to false, unless one wants to use the validationQuery as an init query. |
||||
|
|
|
|
No |
A semicolon separated list of classnames extending org.apache.tomcat.jdbc.pool.JdbcInterceptor class. See Configuring JDBC interceptors below for more detailed description of syntaz and examples. These interceptors will be inserted as an interceptor into the chain of operations on a java.test_sample.Connection object. The default value is null. |
||||
|
|
|
|
No |
The initial number of connections that are created when the pool is started. Default value is 10 |
||||
|
|
|
|
No |
The default TransactionIsolation state of connections created by this pool. One of the following: NONE, READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ, SERIALIZABLE If not set, the method will not be called and it defaults to the JDBC driver. |
||||
|
|
|
|
No |
Property not used in tomcat-jdbc-pool. |
||||
|
|
|
|
No |
The URL used to connect to the database. |
||||
|
|
|
|
No |
The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. In order to have a more efficient validation, see validationInterval. Default value is false |
||||
|
|
|
|
No |
Set to true if you wish that calls to getConnection should be treated fairly in a true FIFO fashion. This uses the org.apache.tomcat.jdbc.pool.FairBlockingQueue implementation for the list of the idle connections. The default value is true. This flag is required when you want to use asynchronous connection retrieval. Setting this flag ensures that threads receive connections in the order they arrive. During performance tests, there is a very large difference in how locks and lock waiting is implemented. When fairQueue=true there is a decision making process based on what operating system the system is running. If the system is running on Linux (property os.name=Linux. To disable this Linux specific behavior and still use the fair queue, simply add the property org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true to your system properties before the connection pool classes are loaded. |
||||
|
|
|
|
No |
Property not used. Access can be achieved by calling unwrap on the pooled connection. see javax.test_sample.DataSource interface, or call getConnection through reflection or cast the object as javax.test_sample.PooledConnection |
||||
|
|
|
|
No |
Time in milliseconds to keep this connection. When a connection is returned to the pool, the pool will check to see if the now - time-when-connected > maxAge has been reached, and if so, it closes the connection rather than returning it to the pool. The default value is 0, which implies that connections will be left open and no age check will be done upon returning the connection to the pool. |
||||
|
|
|
|
No |
The minimum amount of time an object may sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds). |
||||
|
|
|
|
No |
The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread. This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often we validate idle connections. The default value is 5000 (5 seconds). |
||||
|
|
|
|
No |
The indication of whether objects will be validated before being returned to the pool. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false. |
||||
|
|
|
|
No |
Return true if a lock should be used when operations are performed on the connection object. Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting. |
||||
|
|
|
|
No |
The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100 |
||||
|
|
|
|
No |
The connection username to be passed to our JDBC driver to establish a connection. Note that method DataSource.getConnection(username,password) by default will not use credentials passed into the method, but will use the ones configured here. See alternateUsernameAllowed property for more details. |
||||
|
|
|
|
Yes |
Enter the name of the table in the database that contains the accounts. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Basic Configuration
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
Yes |
The connection password to be passed to the JDBC driver to establish a connection. Note that method DataSource.getConnection(username,password) by default will not use credentials passed into the method, but will use the ones configured here. See alternateUsernameAllowed property for more details. |
||||
|
|
|
|
No |
Select whether database column names for this resource should be quoted, and the quoting characters. By default, database column names are not quoted (None). For other selections (Single, Double, Back, or Brackets), column names will appear between single quotes, double quotes, back quotes, or brackets in the SQL generated to access the database. |
||||
|
|
|
|
Yes |
This mandatory column value will be used as the unique identifier for rows in the table. |
||||
|
|
|
|
No |
Enter the name of the column in the table that will hold the password values. If empty, no validation is done on resources and passwords. |
||||
|
|
|
|
Yes |
If true, optional paging in a query will be ignored by the connector. Defaults to false. |
||||
|
|
|
|
No |
Select to enable support for writing an empty string, instead of a NULL value, in character based columns defined as not-null in the table schema. This option does not influence the way strings are written for Oracle based tables. By default empty strings are written as a NULL value. |
||||
|
|
|
|
No |
If this is not checked, SQL statements which throw SQLExceptions with a 0 ErrorCode will be have the exception caught and suppressed. Check it to have exceptions with 0 ErrorCodes rethrown. |
||||
|
|
|
|
No |
Select to retrieve Timestamp data type of the columns in java.sql.Timestamp format from the database table. |
||||
|
|
|
|
No |
Select to retrieve all data types of columns in native format from the database table. |
||||
|
|
|
|
|
The change log column stores the latest change time. Providing this value the Sync capabilities are activated. |
||||
|
|
|
|
No |
If set to true then the password will not be returned. Never. Even though it is explicitly requested. If set to false then the password will be returned if it is explicitly requested. |
||||
|
|
|
|
No |
If true, the SyncOp will query for ChangeLogColumn >= syncToken. One record will always be returned from the database in this case and be handled by the connector. If set to false, the SyncOp will query for ChangeLogColumn > syncToken. Defaults to false. |
||||
|
|
|
|
No |
Return Generated Keys |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Groovy Connector Toolkit
The generic Groovy Connector Toolkit runs a Groovy script for any ICF operation, such as search, update, create, and others, on any external resource.
The Groovy Connector Toolkit is not a complete connector in the traditional sense. Rather, it is a framework within which you must write your own Groovy scripts to address the requirements of your implementation.
Configure scripted Groovy connectors
You cannot configure a scripted Groovy connector through the UI. Configure the connector over REST, as described in Configure Connectors Over REST.
Validate pooled connections
The scripted SQL connector uses the Tomcat JDBC Connection Pool to managed its connections. Occasionally, a JDBC resource that is accessed by the scripted SQL connector might become unavailable for a period. When the resource comes back online, Identity Cloud is generally able to recover automatically and resume operations. However, the connector might not be able to refresh its connection pool and might then pass a closed connection to its scripts. This can affect operations until Identity Cloud is restarted.
To avoid this situation, you can configure connection validation, where connections are validated before being borrowed from the connection pool.
To configure connection validation, add the following properties to the configurationProperties
object in your connector configuration:
testOnBorrow
-
Validates the connection object before it is borrowed from the pool. If the object fails to validate, it is dropped from the pool and the connector attempts to borrow another object.
For this property to have an effect, you must set
validationQuery
to a non-null string. validationQuery
-
The SQL query used to validate connections from the pool before returning them to the caller.
The precise query will differ, depending on the database that you are accessing. The following list provides sample queries for common databases:
- HyperSQL DataBase (HSQLDB)
-
select 1 from INFORMATION_SCHEMA.SYSTEM_USERS
- Oracle DB
-
select 1 from dual
- DB2
-
select 1 from sysibm.sysdummy1
- MySQL
-
select 1
- Microsoft SQL
-
select 1
- PostgreSQL
-
select 1
- Ingres Database
-
select 1
- Apache Derby
-
values 1
- H2 Database
-
select 1
- Firebird SQL
-
select 1 from rdb$database
validationInterval
-
Specifies the maximum frequency (in milliseconds) at which validation is run. If a connection is due for validation but was previously validated within this interval, it is not validated again.
The larger the value, the better the connector performance. However, with a large value you increase the chance of a stale connection being presented to the connector.
Connection validation can have an impact on performance and should not be done too frequently. With the following configuration, connections are validated no more than every 34 seconds:
{
...
"configurationProperties" : {
...
"testOnBorrow" : true,
"validationQuery" : "select 1 from dual",
"validationInterval" : 34000,
...
},
...
}
Use Custom properties in scripts
The customConfiguration
and customSensitiveConfiguration
properties enable you to inject custom properties into your scripts. Properties listed in customSensitiveConfiguration
are encrypted.
For example, the following excerpt of the scripted Kerberos provisioner file shows how these properties inject the Kerberos user and encrypted password into the scripts, using the kadmin
command.
"customConfiguration" : "kadmin { cmd = '/usr/sbin/kadmin.local'; user='<KADMIN USERNAME>'; default_realm='<REALM>' }",
"customSensitiveConfiguration" : "kadmin { password = '<KADMIN PASSWORD>'}",
Debug Groovy scripts
When you call a Groovy script from the Groovy connector, you can use the SLF4J logging facility to obtain debug information.
For instructions on how to use this facility, see the KnowledgeBase article How do I add logging to Groovy scripts in IDM.
Script compilation and caching
The first time a script is read, it is compiled (from Groovy script to Java bytecode) and cached in memory. Each time the script is called, the Groovy script engine checks the last modified of the script file to see if it has changed. If it has not changed, the cached bytecode is executed. If it has changed, the script is reloaded, compiled and cached.
Implemented interfaces
The following tables list the ICF interfaces that are implemented for non-poolable and poolable connector implementations:
OpenICF Interfaces Implemented by the Scripted Groovy Connector
The Scripted Groovy Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
OpenICF Interfaces Implemented by the Scripted Poolable Groovy Connector
The Scripted Poolable Groovy Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Configuration properties
The following tables list the configuration properties for non-poolable and poolable connector implementations:
Scripted Groovy Connector Configuration
The Scripted Groovy Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
Custom Sensitive Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
No |
Custom Configuration script for Groovy ConfigSlurper |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Operation Script Files
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
|
The name of the file used to perform the CREATE operation. |
||||
|
|
|
|
No |
The script used to customize some function of the connector. Read the documentation for more details. |
||||
|
|
|
|
|
The name of the file used to perform the AUTHENTICATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RUNSCRIPTONRESOURCE operation. |
||||
|
|
|
|
|
The name of the file used to perform the DELETE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RESOLVE_USERNAME operation. |
||||
|
|
|
|
|
The name of the file used to perform the SEARCH operation. |
||||
|
|
|
|
|
The name of the file used to perform the UPDATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the SCHEMA operation. |
||||
|
|
|
|
|
The name of the file used to perform the TEST operation. |
||||
|
|
|
|
|
The name of the file used to perform the SYNC operation. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Groovy Engine configuration
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
Directory into which to write classes. |
||||
|
|
|
|
No |
Warning Level of the compiler |
||||
|
|
|
|
No |
Gets the extensions used to find groovy files |
||||
|
|
|
|
No |
Sets the minimum of time after a script can be recompiled. |
||||
|
|
|
|
No |
Base class name for scripts (must derive from Script) |
||||
|
|
|
|
Yes |
The root folder to load the scripts from. If the value is null or empty the classpath value is used. |
||||
|
|
|
|
No |
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted. |
||||
|
|
|
|
No |
If true, debugging code should be activated |
||||
|
|
|
|
No |
Classpath for use during compilation. |
||||
|
|
|
|
No |
Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled. |
||||
|
|
|
|
No |
If true, the compiler should produce action information |
||||
|
|
|
|
No |
Encoding for source files |
||||
|
|
|
|
No |
If set to true recompilation is enabled |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Scripted Poolable Groovy Connector Configuration
The Scripted Poolable Groovy Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
Custom Sensitive Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
No |
Custom Configuration script for Groovy ConfigSlurper |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Operation Script Files
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
|
The name of the file used to perform the CREATE operation. |
||||
|
|
|
|
No |
The script used to customize some function of the connector. Read the documentation for more details. |
||||
|
|
|
|
|
The name of the file used to perform the AUTHENTICATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RUNSCRIPTONRESOURCE operation. |
||||
|
|
|
|
|
The name of the file used to perform the DELETE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RESOLVE_USERNAME operation. |
||||
|
|
|
|
|
The name of the file used to perform the SEARCH operation. |
||||
|
|
|
|
|
The name of the file used to perform the UPDATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the SCHEMA operation. |
||||
|
|
|
|
|
The name of the file used to perform the TEST operation. |
||||
|
|
|
|
|
The name of the file used to perform the SYNC operation. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Groovy Engine configuration
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
Directory into which to write classes. |
||||
|
|
|
|
No |
Warning Level of the compiler |
||||
|
|
|
|
No |
Gets the extensions used to find groovy files |
||||
|
|
|
|
No |
Sets the minimum of time after a script can be recompiled. |
||||
|
|
|
|
No |
Base class name for scripts (must derive from Script) |
||||
|
|
|
|
Yes |
The root folder to load the scripts from. If the value is null or empty the classpath value is used. |
||||
|
|
|
|
No |
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted. |
||||
|
|
|
|
No |
If true, debugging code should be activated |
||||
|
|
|
|
No |
Classpath for use during compilation. |
||||
|
|
|
|
No |
Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled. |
||||
|
|
|
|
No |
If true, the compiler should produce action information |
||||
|
|
|
|
No |
Encoding for source files |
||||
|
|
|
|
No |
If set to true recompilation is enabled |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Kerberos connector
The Kerberos connector is an implementation of the SSH connector, and is based on Java Secure Channel (JSch) and the Java implementation of the Expect library (Expect4j).
The Kerberos connector lets you manage Kerberos user principals from Identity Cloud. The connector bundles a number of Groovy scripts, to interact with a Kerberos admin server. You should not edit the bundled Groovy scripts. The scripts use the kadmin
utility to communicate with the Kerberos server.
The Kerberos connector lets you perform the following operations on Kerberos user principals:
-
List the existing principals.
-
Display the details of a principal.
-
Add a user principal.
-
Change the password of a user principal and unlock the principal.
-
Delete a user principal.
Kerberos connector schema
The Kerberos connector can only be used to manage the Kerberos principal
object type (which maps to the ICF __ACCOUNT__
object). The following attributes are supported in the schema:
-
principal
- (maps to__NAME__
and__UID__
) -
__PASSWORD__
- updatable, required when an object is created -
__LOCK_OUT__
- updatable only; unlock an account by setting this attribute tofalse
-
policy
- the password policy used by the principal -
expirationDate
- the date that the user principal expires -
passwordExpiration
- the date that the password expires -
maximumTicketLife
- the maximum ticket life for the principal. At the end of the ticket lifetime, the ticket can no longer be used. However, if the renewable lifetime (maximumRenewableLife
) is longer than the ticket lifetime, the ticket holder can present the ticket to the KDC and request a new ticket. -
maximumRenewableLife
- the period during which the ticket can be renewed. A renewed ticket usually has a new ticket lifetime, dating from the time that it was renewed, that is constrained by the renewable ticket lifetime.
In addition, the following read-only attributes are supported:
-
lastPasswordChange
-
lastModified
-
lastSuccessfulAuthentication
-
lastFailedAuthentication
-
failedPasswordAttempts
Configure the Kerberos connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select Kerberos Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
-
Set the authentication properties, as described in Configure Authentication to the SSH Server. In addition, set at least the following properties:
customConfiguration
-
Specify the details of the user principal and the default realm here. The sample connector configuration is as follows:
"customConfiguration" : "kadmin {
cmd = '/usr/sbin/kadmin.local';
user = '<KADMIN USERNAME>';
default_realm = '<REALM, e.g. EXAMPLE.COM>'
}"
A complete custom configuration will look something like this:
"customConfiguration" : "kadmin {
cmd = '/usr/sbin/kadmin.local';
user = 'openidm/admin';
default_realm = 'EXAMPLE.COM'
}"
customSensitiveConfiguration
-
Set the password for the user principal here. The sample connector configuration is as follows:
"customSensitiveConfiguration" : "kadmin {password = '<KADMIN PASSWORD>'}"
Change this to reflect your user principal password, for example:
"customSensitiveConfiguration" : "kadmin {password = 'Passw0rd'}"
Basic Kerberos Connector Configuration
This list describes the basic Kerberos connector configuration properties. For a complete list, see Configuration Properties:
host
-
The host name or IP address of the SSH server on which the
kadmin
command is run. port
-
The port number on which the SSH server listens.
Default:
22
(the default SSH port) user
-
The username of the account that is used to connect to the SSH server.
This is not the same as your Kerberos user principal. This account must be able to
ssh
into the server on which Kerberos is running, with the password provided in the next parameter.If you use the
root
user, thesudo
command in the Test script will never get the'pass::'
prompt. Instead of using theroot
user, create a regular user and add that user to the group that hassudo
privileges. Alternatively, modify the Test script so that it does not usesudo
. password
-
The password of the account that is used to connect to the SSH server.
prompt
-
A string representing the remote SSH session prompt. This must be the exact prompt string, in the format
username@target:
, for exampleroot@localhost:~$
.If the prompt includes a trailing space, you must include the space in the value of this property.
Consider customizing your Linux prompt with the
PS1
andPS2
variables, to set a safe prompt. For information about customizing prompts, see this article. sudoCommand
-
A string that shows the full path to the
sudo
command; for example/usr/bin/sudo
. echoOff
-
If set to
true
(the default), the input command echo is disabled. If set tofalse
, every character that is sent to the server is sent back to the client in theexpect()
call. terminalType
-
Sets the terminal type to use for the session. The list of supported types is determined by your Linux/UNIX system. For more information, see the
terminfo
manual page (man terminfo
).Default:
vt102
setLocale
-
If set to
true
, indicates that the default environment locale should be changed to the value of thelocale
property.Default:
false
locale
-
Sets the locale for LC_ALL, LANG, and LANGUAGE environment variables, if
setLocale
is set totrue
.Default:
en_US.utf8
connectionTimeout
-
Specifies the connection timeout to the remote server, in milliseconds.
Default:
5000
expectTimeout
-
Specifies the timeout used by the
expect()
calls in scripts, in milliseconds.Default:
5000
authenticationType
-
Sets the authentication type, either
PASSWORD
orPUBKEY
. For more information, see connector-reference:ssh.adoc#ssh-authentication.Default:
PASSWORD
throwOperationTimeoutException
-
If
true
, the connector throws an exception when the timeout is reached for an operation. Otherwise, the operation fails silently.Default:
true
scriptRoots
-
The path to the Groovy scripts that will perform the ICF operations, relative to your installation directory. For the Kerberos connector, the scripts are bundled up in the connector .jar file, so this path is set to
jar:file:connectors/kerberos-connector-1.5.20.5.jar!/script/kerberos/
in the sample connector configuration. classpath
-
The directory in which the compiler should look for compiled classes. The default classpath, if not is specified, is
install-dir/lib
. ScriptFileName
-
The script that is used for each ICF operation. Do not change these script names in the bundled Kerberos connector.
OpenICF Interfaces Implemented by the Kerberos Connector
The Kerberos Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Kerberos Connector Configuration
The Kerberos Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
Yes |
No |
Description is not available |
||||
|
|
|
Yes |
No |
Description is not available |
||||
|
|
|
Yes |
No |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
`root@localhost:# ` |
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
LDAP connector
The LDAP connector is based on the Java Naming and Directory Interface (JNDI), and can connect to any LDAPv3-compliant directory server, such as ForgeRock Directory Services (DS), Active Directory, SunDS, Oracle Directory Server Enterprise Edition, IBM Security Directory Server, and OpenLDAP.
Because it is based on JNDI, the LDAP connector is restricted to the attribute types that are supported by JNDI. JNDI supports only strings and an array of bytes. If you attempt to use different attribute value types, the connector throws a malformed attribute value exception. For more information, see the corresponding JNDI documentation.
Configure the LDAP connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select LDAP Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
Sample LDAP Connector Configuration
This configuration shows the properties for an LDAP connector connecting to DS. For more information about the properties that affect synchronization, see connector-reference:ldap.adoc#ldap-connector-sync-controls. For a complete list of the configuration properties for the LDAP connector, see LDAP Connector Configuration:
"configurationProperties" : {
"host" : "localhost",
"port" : 1389,
"ssl" : false,
"startTLS" : false,
"privateKeyAlias" : null,
"alternateKeyStore" : null,
"alternateKeyStoreType" : null,
"alternateKeyStorePassword" : null,
"principal" : "uid=admin",
"credentials" : "password",
"baseContexts" : [
"dc=example,dc=com"
],
"baseContextsToSynchronize" : [
"dc=example,dc=com"
],
"accountSearchFilter" : null,
"accountSynchronizationFilter" : null,
"groupSearchFilter" : null,
"groupSynchronizationFilter" : null,
"removeLogEntryObjectClassFromFilter" : true,
"modifiersNamesToFilterOut" : [ ],
"changeLogBlockSize" : 100,
"attributesToSynchronize" : [ ],
"changeNumberAttribute" : "changeNumber",
"filterWithOrInsteadOfAnd" : false,
"objectClassesToSynchronize" : [
"inetOrgPerson"
],
"vlvSortAttribute" : "uid",
"passwordAttribute" : "userPassword",
"useBlocks" : false,
"maintainPosixGroupMembership" : false,
"failover" : [ ],
"readSchema" : true,
"accountObjectClasses" : [
"top",
"person",
"organizationalPerson",
"inetOrgPerson"
],
"accountUserNameAttributes" : [
"uid"
],
"groupMemberAttribute" : "uniqueMember",
"passwordHashAlgorithm" : null,
"usePagedResultControl" : true,
"blockSize" : 100,
"uidAttribute" : "entryUUID",
"maintainLdapGroupMembership" : false,
"respectResourcePasswordPolicyChangeAfterReset" : false
},
host
-
The host name or IP address of the server on which the LDAP instance is running.
port
-
The port on which the LDAP server listens for LDAP requests. The sample configuration specifies a default port of 1389.
ssl
-
If
true
, the specified port listens for LDAPS connections.For instructions on using the LDAP connector over SSL, see Configure the LDAP Connector to Use SSL and StartTLS.
startTLS
-
Specifies whether to use the startTLS operation to initiate a TLS/SSL session. To use startTLS, set
"startTLS":true,
and"ssl":false
. Your connection should use the insecure LDAP port (typically389
or1389
for a DS server).Specify the certificates that should be used for authentication, as described in Configure the LDAP Connector to Use SSL and StartTLS.
principal
-
The bind DN that is used to connect to the LDAP server.
credentials
-
The password of the
principal
that is used to connect to the LDAP server. baseContexts
-
One or more starting points in the LDAP tree that will be used when searching the tree. Searches are performed when discovering users from the LDAP server or when looking for the groups of which a user is a member. During reconciliation operations, Identity Cloud searches through the base contexts listed in this property for changes. For more information, see Control What the LDAP Connector Synchronizes.
baseContextsToSynchronize
-
One or more starting points in the LDAP tree that will be used to determine if a change should be synchronized. During liveSync operations, Identity Cloud searches through the base contexts listed in this property for changes. If no value is specified here, the values in listed in the
baseContexts
property are used. For more information, see Control What the LDAP Connector Synchronizes. accountSynchronizationFilter
-
Used during synchronization actions to filter out LDAP accounts. For more information, see Control What the LDAP Connector Synchronizes.
accountObjectClasses
-
This property lists all the object classes that represent an account. If this property has multiple values, an
AND
filter is used to determine the affected entries. For example, if the value of this property is["organizationalPerson", "inetOrgPerson"]
, any entry with the object classorganizationalPerson
AND the object classinetOrgPerson
is considered as an account entry. You can override the value of this property by specifying the user object classes during the create operation.If no object class is specified when you create a user, this property is used as the default list of object classes for the new entry.
accountSearchFilter
-
Search filter that user accounts must match. For more information, see Control What the LDAP Connector Synchronizes.
accountUserNameAttributes
-
Attributes holding the account’s user name. Used during authentication to find the LDAP entry matching the user name.
attributesToSynchronize
-
List of attributes used during object synchronization. Identity Cloud ignores change log updates that do not include any of the specified attributes. If empty, Identity Cloud considers all changes. For more information, see Control What the LDAP Connector Synchronizes.
blockSize
-
Block size for simple paged results and VLV index searches, reflecting the maximum number of entries retrieved at any one time.
changeLogBlockSize
-
Block size used when fetching change log entries.
changeNumberAttribute
-
Change log attribute containing the last change number.
failover
-
LDAP URLs specifying alternative LDAP servers to connect to if Identity Cloud cannot connect to the primary LDAP server specified in the
host
andport
properties. filterWithOrInsteadOfAnd
-
In most cases, the filter to fetch change log entries is AND-based. If this property is set, the filter ORs the required change numbers instead.
groupMemberAttribute
-
LDAP attribute holding members for non-POSIX static groups.
groupSearchFilter
-
Search filter that group entries must match.
maintainLdapGroupMembership
-
If
true
, Identity Cloud modifies group membership when entries are renamed or deleted.Does not apply to Active Directory.
In the sample LDAP connector configuration, this property is set to
false
. This means that LDAP group membership is not modified when entries are renamed or deleted in Identity Cloud. To ensure that entries are removed from LDAP groups when the entries are deleted, set this property totrue
or enable referential integrity on the LDAP server. For information about configuring referential integrity in DS, see Referential Integrity in the Configuration Guide for ForgeRock Directory Services. maintainPosixGroupMembership
-
If
true
, Identity Cloud modifies POSIX group membership when entries are renamed or deleted. modifiersNamesToFilterOut
-
Use this property to avoid loops caused by changes made to managed user objects being synchronized. For more information, see Control What the LDAP Connector Synchronizes.
objectClassesToSynchronize
-
Identity Cloud synchronizes only entries that have these object classes. For more information, see Control What the LDAP Connector Synchronizes.
passwordAttribute
-
Attribute to which Identity Cloud writes the predefined
PASSWORD
attribute. passwordHashAlgorithm
-
Hash password values with the specified algorithm, if the LDAP server stores them in clear text. The hash algorithm can be one of the following:
NONE
Cleartext.
WIN-AD
Used for password changes to Active Directory.
SHA
Secure Hash Algorithm.
SHA-1
A 160-bit hash algorithm that resembles the MD5 algorithm.
SSHA
Salted SHA.
MD5
A 128-bit message-digest algorithm.
SMD5
Salted MD5 .
readSchema
-
If
true
, read the schema from the LDAP server.This property is used only during the connector setup, to generate the object types.
If this property is
false
, the LDAP connector provides a basic default schema that can manage LDAP users and groups. The default schema mapsinetOrgPerson
to the OpenICF__ACCOUNT__
property, andgroupOfUniqueNames
to the OpenICF__GROUP__
property. The following LDAP object classes are also included in the default schema:-
organization
-
organizationalUnit
-
person
-
organizationalPerson
-
account
-
groupOfNames
-
removeLogEntryObjectClassFromFilter
-
If
true
, the filter to fetch change log entries does not contain thechangeLogEntry
object class, and Identity Cloud expects no entries with other object types in the change log. The default setting istrue
. respectResourcePasswordPolicyChangeAfterReset
-
If
true
, bind with the Password Expired and Password Policy controls, and throwPasswordExpiredException
and other exceptions appropriately. uidAttribute
-
Specifies the LDAP attribute that should be used as the immutable ID for the entry. You can use a DN (or any unique attribute) for the
id
. As a best practice, you _should use an attribute that is both unique and immutable, such as theentryUUID
. For a DS resource, you must use theentryUUID
as theuidAttribute
, otherwise you might encounter problems with synchronizing delete operations. useBlocks
-
If
useBlocks
isfalse
, no pagination is used. IfuseBlocks
istrue
, the connector uses block-based LDAP controls, either the simple paged results control, or the virtual list view control, depending on the setting of theusePagedResultControl
property. usePagedResultControl
-
Taken into account only if
useBlocks
istrue
. IfusePagedResultControl
isfalse
, the connector uses the virtual list view (VLV) control, if it is available. IfusePagedResultControl
istrue
, the connector uses the simple paged results control for search operations. useTimestampsForSync
-
If
true
, use timestamps for liveSync operations, instead of the change log.By default, the LDAP connector has a change log strategy for LDAP servers that support a change log, such as ForgeRock Directory Services (DS) and Oracle Directory Server Enterprise Edition. If the LDAP server does not support a change log, or if the change log is disabled, liveSync for create and modify operations can still occur, based on the timestamps of modifications.
Regardless of the
useTimestampsForSync
value, the connector uses a timestamp strategy for liveSync for the following LDAP server types:-
MS Active Directory Global Catalog
-
OpenLDAP
-
Unknown
An LDAP server type is marked unknown if it is anything other than IBM, Novell, UnboundIDD, RedHat/Fedora 389, CA LDAP, OpenDS, ForgeRock OpenDJ / DS, Sun DSEE Directory, Microsoft Active Directory, Microsoft Active Directory Lightweight Directory Services (LDS), Microsoft Active Directory Global Catalog, or OpenLDAP.
-
vlvSortAttribute
-
Attribute used as the sort key for virtual list view.
sendCAUDTxId
-
If
true
, propagate the Common Audit Transaction ID to a DS server.
Configure the LDAP connector to use SSL and StartTLS
To use the LDAP connector over SSL, update your connector configuration as follows:
-
For a connection over SSL, set the
ssl
property totrue
and set theport
to a secure port, for example,636
.To initiate a connection using startTLS, set
"startTLS":true,
and"ssl":false
. Set theport
to an insecure LDAP port, for example,389
. -
If you are using a CA-signed server certificate, add that certificate to the RCS truststore, for example:
keytool \ -importcert \ -alias server-cert \ -keystore /path/to/openicf/security/truststore \ -storepass changeit \ -file /path/to/server-cert.crt
-
Specify the certificate that the LDAP connector will use to authenticate to the remote LDAP server. You have two options:
-
Set the
privateKeyAlias
to the alias of a certificate in the RCS keystore. The alias name is case-sensitive.If you set
privateKeyAlias
tonull
, no private key is sent during the SSL handshake, so only the server certificate is used. You must import the server certificate into the RCS truststore, as shown in the previous step.If
privateKeyAlias
is set to an alias within the RCS keystore, the connector uses that private key for SSL mutual authentication. -
Specify a different keystore for the connector.
If you do not want to use the default RCS keystore, set the following properties:
-
alternateKeyStore
- specifies the full path to an alternate keystore. -
alternateKeyStoreType
- specifies alternate keystore type. Valid values areJKS
,JCEKS
andPKCS12
. -
alternateKeyStorePassword
- specifies password for the alternate keystore.
-
-
-
Enable hostname verification to prevent a third party from manipulating DNS entries or spoofing the LDAP Server IP.
When hostname verification is enabled, the connector compares the hostname in the certificate
subject
andsubjectAltName
with a simple hostname pattern defined in thehostNameVerification
property.To enable hostname verification, set
"hostNameVerification" : true
and set thehostNameVerification
property to the hostname you want to match. If the pattern matches, the connector is initialized successfully. If the pattern does not match, connector initialization throws an error. ThehostNameVerification
property supports wild card matching.Assume, for example, a server certificate principal hostname of
server1.example.com
. With the following connector configuration, Identity Cloud starts up and the connector is initialized:"configurationProperties" : { ... "hostNameVerification" : true, "hostNameVerifierPattern" : "server1.example.com", ... }
Similarly, with the following connector configuration, Identity Cloud starts up and the connector is initialized:
"configurationProperties" : { ... "hostNameVerification" : true, "hostNameVerifierPattern" : "*.example.com", ... }
With the following connector configuration, Identity Cloud starts up but connector initialization throws an error:
"configurationProperties" : { ... "hostNameVerification" : true, "hostNameVerifierPattern" : "server2.example.com", ... }
The error returned is similar to the following:
The host name from the server certificate'CN=server1.example.com' does not match the provided pattern 'server2.example.com'
Control what the LDAP connector synchronizes
To control the set of LDAP entries that are affected by reconciliation and automatic synchronization operations, set the following properties in the provisioner configuration. Automatic synchronization includes liveSync (synchronization of changes from the LDAP server to Identity Cloud) and implicit sync (synchronization from Identity Cloud to the LDAP server). For more information, see Synchronization types.
accountSearchFilter
-
Only user accounts that match this filter are searched, and therefore affected by reconciliation and synchronization operations. If you do not set this property, all accounts within the base contexts specified previously are searched.
accountSynchronizationFilter
-
This property is used during reconciliation and automatic synchronization operations, and filters out any LDAP accounts that you specifically want to exclude from these operations.
attributesToSynchronize
-
During automatic synchronization operations, only the attributes listed here are considered for changes. Objects that include these attributes are synchronized. Objects that do not include these attributes are ignored. If this property is not set, Identity Cloud considers changes to all attributes specified in the mapping.
This attribute works only with LDAP servers that log changes in a change log, not with servers (such as Active Directory) that use other mechanisms to track changes.
baseContexts
-
The starting points in the LDAP tree that are used when searching the directory tree; for example,
dc=example,dc=com
. These base contexts must include the set of users and the set of groups that must be searched during reconciliation operations. baseContextsToSynchronize
-
The starting points in the LDAP tree that are used to determine if a change should be synchronized. This property is used only for automatic synchronization operations. Only entries that fall under these base contexts are considered during synchronization operations.
modifiersNamesToFilterOut
-
This property lets you define a list of DNs. During synchronization operations, the connector ignores changes made by these DNs.
When a managed user object is updated, and that change is synchronized to the LDAP server, the change made on the LDAP server is recorded in the change log. A liveSync operation picks up the change, and attempts to replay the change on the managed user object, effectively resulting in a loop of updates.
To avoid this situation, you can specify a unique user in your LDAP directory, that will be used only for the LDAP connector. The unique user must be something other than
uid=admin
; for example,cn=idmuser
. You can then include that user DN as the value ofmodifiersNamesToFilterOut
. When a change is made through the LDAP connector, and that change is recorded in the change log, the modifier’s name (cn=idmuser
) is flagged, and Identity Cloud does not attempt to replay the change back to the managed user repository. So, you are effectively indicating that Identity Cloud should not synchronize changes back to managed user that originated from managed user, thus preventing the update loop.This attribute works only with LDAP servers that log changes in a change log, not with servers (such as Active Directory) that use other mechanisms to track changes.
objectClassesToSynchronize
-
During automatic synchronization operations, only the object classes listed here are considered for changes. Identity Cloud ignores change log updates (or changes to managed objects) which do not have any of the object classes listed here.
Use the LDAP Connector With Active Directory
The LDAP connector provides functionality specifically for managing Active Directory users and groups. The connector can handle the following operational attributes to manage Active Directory accounts:
__ENABLE__
-
Uses the
userAccountControl
attribute to get or set the account status of an object.The LDAP connector reads the
userAccountControl
to determine if an account is enabled or disabled. The connector modifies the value of theuserAccountControl
attribute if Identity Cloud changes the value of__ENABLE__
. __ACCOUNT_EXPIRES__
-
Sets the
accountExpires
attribute of an Active Directory object to reset an expired account, or to set a future expiration date.To set an account that never expires, set
"__ACCOUNT_EXPIRES__": "0"
.To set an expiration date, set
"__ACCOUNT_EXPIRES__": "date"
, wheredate
is in ISO8601 format. For example:curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "__ACCOUNT_EXPIRES__": "2020-12-31T00:00:00Z" }' \ "https://tenant-name.forgeblocks.com/openidm/system/AD/account/e1418d64-096c-4cb0-b903-ebb66562d99d" { "sn": "jensen", "__LOCK_OUT__": false, "__ENABLE__": true, "objectGUID": "e1418d64-096c-4cb0-b903-ebb66562d99d", "dn": "CN=bjensen,OU=create,DC=example,DC=com", "accountExpires": "2020-12-31T00:00:00Z" }
__LOCK_OUT__
-
Uses the
msDS-User-Account-Control-Computed
system attribute to check if a user account has been locked.If Identity Cloud sets
__LOCK_OUT__
toFALSE
, the LDAP connector sets the Active DirectorylockoutTime
to0
to unlock the account.If Identity Cloud sets
__LOCK_OUT__
toTRUE
, the LDAP connector ignores the change and logs a message. __PASSWORD_EXPIRED__
-
Uses the
msDS-User-Account-Control-Computed
system attribute to check if a user password has expired.To force password expiration (that is, to force a user to change their password when they next log in), set
pwdLastSet
to0
. The LDAP connector setspwdLastSet
to0
, if Identity Cloud sets__PASSWORD_EXPIRED__
toTRUE
.To remove password expiration, set
pwdLastSet
to0
and then to-1
. This sets the value ofpwdLastSet
to the current time. The LDAP connector setspwdLastSet
to-1
if Identity Cloud sets__PASSWORD_EXPIRED__
toFALSE
.Active Directory does not allow you to create an enabled account with an expired password. If you are using __PASSWORD_EXPIRED__
to force a new user to change their password when they next log in, you can create the user account as disabled initially (__ENABLE__=false
). You can then patch the new user account to enable it. You can use the same workaround for synchronization operations, creating new user accounts as disabled, then issuing anopenidm.patch
call in apostCreate
script to enable the account. __CURRENT_PASSWORD__
-
For a password change request, the connector supplies the
__CURRENT_PASSWORD__
, along with the new password. The connector can also do a password reset where only the new password is supplied.
Manage Active Directory Users With the LDAP Connector
If you create or update users in Active Directory, and those user entries include passwords, you must use the LDAP connector over SSL. You cannot create or update an Active Directory user password in clear text. To use the connector over SSL, follow the instructions in Configure the LDAP Connector to Use SSL and StartTLS.
The following command adds an Active Directory user. The output shows the operational attributes described in the previous section:
curl \ --header "Content-Type: application/json" \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "dn": "CN=Brian Smith,CN=Users,DC=example,DC=com", "cn": "Brian Smith", "sAMAccountName": "bsmith", "userPrincipalName": "bsmith@example.com", "userAccountControl": "512", "givenName": "Brian", "mail": "bsmith@example.com", "__PASSWORD__": "Passw0rd" }' \ https://tenant-name.forgeblocks.com/openidm/system/ad/account?_action=create { "_id": "e1418d64-096c-4cb0-b903-ebb66562d99d", "mobile": null, "postalCode": null, "st": null, "employeeType": [], "objectGUID": "e1418d64-096c-4cb0-b903-ebb66562d99d", "cn": "Brian Smith", "department": null, "l": null, "description": null, "info": null, "manager": null, "sAMAccountName": "bsmith", "sn": null, "whenChanged": "20151217131254.0Z", "userPrincipalName": "bsmith@example.com", "userAccountControl": "512", "__ENABLE__": true, "displayName": null, "givenName": "Brian", "middleName": null, "facsimileTelephoneNumber": null, "lastLogon": "0", "countryCode": "0", "employeeID": null, "co": null, "physicalDeliveryOfficeName": null, "pwdLastSet": "2015-12-17T13:12:54Z", "streetAddress": null, "homePhone": null, "__PASSWORD_NOTREQD__": false, "telephoneNumber": null, "dn": "CN=Brian Smith,CN=Users,DC=example,DC=com", "title": null, "mail": "bsmith@example.com", "postOfficeBox": null, "__SMARTCARD_REQUIRED__": false, "uSNChanged": "86144", "__PASSWORD_EXPIRED__": false, "initials": null, "__LOCK_OUT__": false, "company": null, "employeeNumber": null, "accountExpires": "0", "c": null, "whenCreated": "20151217131254.0Z", "uSNCreated": "86142", "division": null, "groups": [], "__DONT_EXPIRE_PASSWORD__": false, "otherHomePhone": [] }
|
Note that the command sets the userAccountControl
to 512
, which is an enabled
account. The value of the userAccountControl
determines the account policy. The following list describes the common values for the userAccountControl
.
512
-
Enabled account.
514
-
Disabled account.
544
-
Enabled account, password not required.
546
-
Disabled account, password not required.
66048
-
Enabled account, password does not expire.
66050
-
Disabled account, password does not expire.
66080
-
Enabled account, password does not expire and is not required.
66082
-
Disabled account, password does not expire and is not required.
262656
-
Enabled account, smartcard required.
262658
-
Disabled account, smartcard required.
262688
-
Enabled account, smartcard required, password not required.
262690
-
Disabled account, smartcard required, password not required.
328192
-
Enabled account, smartcard required, password does not expire.
328192
-
Enabled account, smartcard required, password does not expire.
328194
-
Disabled account, smartcard required, password does not expire.
328224
-
Enabled account, smartcard required, password does not expire and is not required.
328226
-
Disabled account, smartcard required, password does not expire and is not required.
Manage Active Directory Groups With the LDAP Connector
The following command creates a basic Active Directory group with the LDAP connector:
curl \ --header "Content-Type: application/json" \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "dn": "CN=Employees,DC=example,DC=com" }' \ https://tenant-name.forgeblocks.com/openidm/system/ad/group?_action=create { "_id": "240da4e9-59d8-1547-ad86-29f5b2b5114d" }
The LDAP connector exposes two special attributes to handle Active Directory group scope and type: GROUP_SCOPE
and GROUP_TYPE
.
The GROUP_SCOPE
attribute is defined in the provisioner configuration as follows:
...
"__GROUP_SCOPE__" : {
"type" : "string",
"nativeName" : "__GROUP_SCOPE__",
"nativeType" : "string"
},
The value of the GROUP_SCOPE
attribute can be global
, domain
, or universal
. If no group scope is set when the group is created, the scope is global
by default. For more information about the different group scopes, see the corresponding Microsoft documentation.
The GROUP_TYPE
attribute is defined in the provisioner configuration as follows:
...
"__GROUP_TYPE__" : {
"type" : "string",
"nativeName" : "__GROUP_TYPE__",
"nativeType" : "string"
},
The value of the GROUP_TYPE
attribute can be security
or distribution
. If no group type is set when the group is created, the type is security
by default. For more information about the different group types, see the corresponding Microsoft documentation.
The following example creates a new distribution group, with universal scope:
curl \ --header "Content-Type: application/json" \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "dn": "CN=NewGroup,DC=example,DC=com", "__GROUP_SCOPE__": "universal", "__GROUP_TYPE__": "distribution" }' \ https://tenant-name.forgeblocks.com/openidm/system/ad/group?_action=create { "_id": "f189df8a-276f-9147-8ad5-055b1580cbcb" }
Handle Active Directory Dates
Most dates in Active Directory are represented as the number of 100-nanosecond intervals since January 1, 1601 (UTC). For example:
pwdLastSet: 130698687542272930
Identity Cloud generally represents dates as an ISO 8601-compliant string with yyyy-MM-dd’T’HH:mm:ssZ
format. For example:
2015-03-02T20:17:48Z
The generic LDAP connector therefore converts any dates from Active Directory to ISO 8601 format, for fields such as pwdLastSet
, accountExpires
, lockoutTime
, and lastLogon
.
Multiple Active Directory Domains
In a multi-domain Active Directory Domain Services (AD DS) forest, the global catalog (GC) provides a read-only (searchable) representation of every object in the forest. Each domain controller (DC) in the forest stores a writable replica of the objects in its domain. Therefore, a DC can locate only the objects in its domain.
If your Active Directory deployment has only one domain controller, you can configure the connector to connect to that single domain controller. If your deployment spans multiple domains, you must configure the connector to connect to the Global Catalog (GC) to have a comprehensive view of all the domains.
Using a GC as the authoritative data source has the following limitations:
-
Only a subset of attributes is replicated from other domains to the GC.
Certain attributes required by the LDAP connector might be missing. To avoid this problem, modify the Active Directory schema to ensure that the required attributes are replicated to the GC.
-
Delete operations are not detected immediately.
A liveSync operation will therefore not update Identity Cloud with the result of a delete operation. Delete operations are detected by a reconciliation operation, so data stores are only temporarily "out of sync" with regard to deletes.
-
Not all group types are supported.
Group membership information is replicated to the GC for universal groups only. You must therefore use universal groups if your directory service has more than one domain.
You can use the |
LDAP Search Filters
The LDAP connector constructs an LDAP search filter using a combination of filters, in the following order:
(& (native filter) (user filter) (object class filter) )
The filter components are as follows:
- Native Filter
-
The native filter is the query filter that has been translated to an LDAP query. For example,
uid+eq+"user123"
is translated touid=user123
.This part of the filter is processed first.
- User Filter
-
You can define a user filter with the properties
accountSearchFilter
andgroupSearchFilter
in the connector configuration.These properties enable you to construct a more granular or specific search filter. If a user filter is specified, the connector does not use the object class filter. If no user filter is specified, (
accountSearchFilter
andgroupSearchFilter
set tonull
or absent from the connector configuration), the connector uses the object class filter. - Object Class Filter
-
This part of the filter includes the object classes that the entry must have in order to be returned by the search.
The
__ACCOUNT__
and__GROUPS__
object classes are defined by the propertiesaccountObjectClasses
andgroupObjectClasses
in the connector configuration. For example, the following configuration indicates that theaccountObjectClasses
include the LDAP object classestop
,person
,organizationalPerson
, andinetOrgPerson
:"configurationProperties" : { ... "accountObjectClasses" : [ "top", "person", "organizationalPerson", "inetOrgPerson" ], ... }
With this configuration, the search filter for accounts is constructed as follows:
(&(objectClass=top)(objectClass=person)(objectClass=organizationalPerson)(objectClass=inetOrgPerson))
If no
accountObjectClasses
orgroupObjectClasses
are defined in the connector configuration, the connector uses the name of the ICF ObjectClass in the filter. For example, an object of typeorganizationUnit
will result in:(&(objectClass=organizationUnit)
OpenICF Interfaces Implemented by the LDAP Connector
The LDAP Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
LDAP Connector Configuration
The LDAP Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
|
Normally the filter used to fetch change log entries is an and-based filter retrieving an interval of change entries. If this property is set, the filter will or together the required change numbers instead. |
||||
|
|
|
|
|
The object classes to synchronize. The change log is for all objects; this filters updates to just the listed object classes. You should not list the superclasses of an object class unless you intend to synchronize objects with any of the superclass values. For example, if only "inetOrgPerson" objects should be synchronized, but the superclasses of "inetOrgPerson" ("person", "organizationalperson" and "top") should be filtered out, then list only "inetOrgPerson" here. All objects in LDAP are subclassed from "top". For this reason, you should never list "top", otherwise no object would be filtered. |
||||
|
|
|
|
|
One or more starting points in the LDAP tree that will be used to determine if a change should be synchronized. The base contexts attribute will be used to synchronize a change if this property is not set. |
||||
|
|
|
|
|
The names of the attributes to synchronize. This ignores updates from the change log if they do not update any of the named attributes. For example, if only "department" is listed, then only changes that affect "department" will be processed. All other updates are ignored. If blank (the default), then all changes are processed. |
||||
|
|
|
|
|
The name of the change number attribute in the change log entry. |
||||
|
|
|
|
|
The list of names (DNs) to filter from the changes. Changes with the attribute "modifiersName" that match entries in this list will be filtered out. The standard value is the administrator name used by this adapter, to prevent loops. Entries should be of the format "cn=Directory Manager". |
||||
|
|
|
Yes |
No |
Password for the principal. |
||||
|
|
|
|
|
The number of change log entries to fetch per query. |
||||
|
|
|
|
|
If true, the connector will use the createTimestamp and modifyTimestamp system attributes to detect changes (Create/Update) on the directory instead of native change detection mechanism (cn=changelog on OpenDJ or Update Sequence Number -USN- on Active Directory for instance). Default value is false. |
||||
|
|
|
|
|
An optional LDAP filter for the objects to synchronize. Because the change log is for all objects, this filter updates only objects that match the specified filter. If you specify a filter, an object will be synchronized only if it matches the filter and includes a synchronized object class. |
||||
|
|
|
|
|
If this property is set (the default), the filter used to fetch change log entries does not contain the "changeLogEntry" object class, expecting that there are no entries of other object types in the change log. |
||||
|
|
|
Yes |
No |
Password to use for the alternate keystore |
||||
|
|
|
|
|
An optional LDAP filter for the objects to synchronize. Because the change log is for all objects, this filter updates only objects that match the specified filter. If you specify a filter, an object will be synchronized only if it matches the filter and includes a synchronized object class. |
||||
|
|
|
|
No |
The name of the group attribute that will be updated with the distinguished name of the user when the user is added to the group. |
||||
|
|
|
|
No |
An optional LDAP filter to control which accounts are returned from the LDAP resource. If no filter is specified, only accounts that include all specified object classes are returned. |
||||
|
|
|
|
No |
Specifies the name of a private key alias from the keystore that should be used for SSL mutual authentication. If null, no private key is sent during SSL handshake so only server cert is used. This alias name is case sensitive. |
||||
|
|
|
|
No |
Select the check box to connect to the LDAP server using SSL. |
||||
|
|
|
|
No |
When enabled and a user is renamed or deleted, update any POSIX groups to which the user belongs to reflect the new name. Otherwise, the LDAP resource must maintain referential integrity with respect to group membership. |
||||
|
|
|
|
No |
The minimum interval (seconds) at which the target directory is polled when a connection is reused from the pool. Defaults to 60 seconds. |
||||
|
|
|
|
No |
An optional LDAP filter to control which groups are returned from the LDAP resource. If no filter is specified, only groups that include all specified object classes are returned. |
||||
|
|
|
|
No |
Defines how to handle LDAP referrals. Possible values can be follow, ignore or throw. |
||||
|
|
|
|
No |
The name or IP address of the host where the LDAP server is running. |
||||
|
|
|
|
No |
When enabled and a user is renamed or deleted, update any LDAP groups to which the user belongs to reflect the new name. Otherwise, the LDAP resource must maintain referential integrity with respect to group membership. |
||||
|
|
|
|
No |
Connector can reset the sync token if ever the value of the sync token is greater than the last change number in the directory changelog. Defaults to "never" (no reset). If set to "first" it will reset the sync token to the value of the firstChangeNumber changelog attribute. If set to "last" it will reset the sync token to the value of the lastChangeNumber changelog attribute. |
||||
|
|
|
|
No |
Specify the sort attribute to use for VLV indexes on the resource. |
||||
|
|
|
|
No |
Converts the Greenwich Time to ISO8601 format |
||||
|
|
|
|
No |
One or more starting points in the LDAP tree that will be used when searching the tree. Searches are performed when discovering users from the LDAP server or when looking for the groups of which a user is a member. |
||||
|
|
|
|
No |
If true, the connector will verify the hostname in the certificate (subject + alternative subject) against the defined hostNameVerifierPattern. |
||||
|
|
|
|
No |
The maximum number of entries that can be in a block when retrieving entries in blocks. |
||||
|
|
|
|
No |
The default list of object classes that will be used when creating new group objects in the LDAP tree. This can be overridden by specifying the group object classes during the Create operation. |
||||
|
|
|
|
No |
Attribute or attributes which holds the account’s user name. They will be used when authenticating to find the LDAP entry for the user name to authenticate. |
||||
|
|
|
|
No |
List all servers that should be used for failover in case the preferred server fails. If the preferred server fails, JNDI will connect to the next available server in the list. List all servers in the form of "ldap://ldap.example.com:389/", which follows the standard LDAP v3 URLs described in RFC 2255. Only the host and port parts of the URL are relevant in this setting. |
||||
|
|
|
|
No |
TCP/IP port number used to communicate with the LDAP server. |
||||
|
|
|
|
No |
Converts the AD Interval to ISO8601 |
||||
|
|
|
|
No |
A simple pattern used to match the hostname from the certificate. It can contains * character (server1.example.com, *.example.com) |
||||
|
|
|
|
No |
The name of the LDAP attribute that holds the password. When changing a users password, the new password is set to this attribute. |
||||
|
|
|
|
No |
If true, the connector will do a DNS query to find SRV records associated with the value set for host property ("_ldap._tcp.example.com" for example). Defaults to false. |
||||
|
|
|
|
No |
Specifies whether to add an extra _memberId attribute to get the group members UID. CAUTION: Setting this property to true can incur a large performance cost on group handling. |
||||
|
|
|
|
No |
The last time the connector was checked to see if it was alive |
||||
|
|
|
|
No |
Specifies whether to use the startTLS operation to initiate a TLS/SSL session. |
||||
|
|
|
|
No |
Connector can delete an entry (node) with leaf entry if this value is set to true (defaults to false). The LDAP control LDAP_SERVER_TREE_DELETE_OID (1.2.840.113556.1.4.805) is used. |
||||
|
|
|
|
No |
When this resource is specified in a Login Module (i.e., this resource is a pass-through authentication target) and the resource’s password policy is configured for change-after-reset, a user whose resource account password has been administratively reset will be required to change that password after successfully authenticating. |
||||
|
|
|
|
No |
The name of the LDAP attribute that is mapped to the OpenICF UID attribute. |
||||
|
|
|
|
No |
The distinguished name with which to authenticate to the LDAP server. |
||||
|
|
|
|
No |
The default list of object classes that will be used when creating new user objects in the LDAP tree. This can be overridden by specifying the user object classes during the Create operation. |
||||
|
|
|
|
No |
Defines the type of the alternate key store. Valid values are JKS, JCEKS and PKCS12 |
||||
|
|
|
|
No |
Indicates the algorithm that the Identity system should use to hash the password. Currently supported values are SSHA, SHA, SMD5, MD5 and WIN-AD (when AD is the target). A blank value indicates that the system will not hash passwords. This will cause clear text passwords to be stored in LDAP unless the LDAP server performs the hash (as Forgerocks OpenDJ does, for example). |
||||
|
|
|
|
No |
Defines the filename of an alternate keystore. If specified, the connector will not use the default keystore specified by the javax.net.ssl.keyStore property. |
||||
|
|
|
|
No |
The authentication mechanism to use: Simple or SASL-GSSAPI. Defaults to "simple". |
||||
|
|
|
|
No |
The timeout (in ms) before the connection attempt is aborted. |
||||
|
|
|
|
No |
Specifies whether to use block-based LDAP controls, like the simple paged results or VLV control. When performing search operations on large numbers of entries, the entries are returned in blocks to reduce the amount of memory used by the operation. |
||||
|
|
|
|
No |
If true, the connector will read the schema from the server. If false, the connector will provide a default schema based on the object classes in the configuration. This property must be true in order to use extended object classes. |
||||
|
|
|
|
No |
When enabled, the LDAP Paged Results control is preferred over the VLV control when retrieving entries. If disabled, paged queries will be ignored. |
||||
|
|
|
|
No |
The connector used to transform the AD ObjectGUID in the form <GUID=xxxxxx>. It now used dashed notation (xxxx-xx-xx-xxxx-xxxxxx) by default. Set to true to keep the old format. |
||||
|
|
|
|
No |
Connector can send the Common Audit Transaction Id (if present) to the target OpenDJ server when this value is set to true (defaults to false). The LDAP control TransactionIdControl (1.3.6.1.4.1.36733.2.1.5.1) is used. |
||||
|
|
|
|
No |
Defines the name used in the JAAS configuration file to define the JAAS login configuration. If null, it defaults to "org.identityconnectors.ldap.LdapConnector". |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
SCIM connector
The SCIM connector is based on the Simple Cloud Identity Management (SCIM) protocol and lets you manage user and group accounts on any SCIM-compliant resource provider, such as Slack or Facebook. The SCIM connector implements both 1.1 and 2.0 endpoints.
The SCIM connector uses the Apache HTTP client, which leverages the HTTP client connection pool, not the ICF connector pool.
You cannot configure the SCIM connector through the UI. Configure the connector over REST, as described in Configure Connectors Over REST.
After the connector is properly configured, you can test its status:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system?_action=test" [ { "name": "SCIM", "enabled": true, "config": "config/provisioner.openicf/SCIM", "connectorRef": { "bundleName": "org.forgerock.openicf.connectors.scim-connector", "connectorName": "org.forgerock.openicf.connectors.scim.ScimConnector", "bundleVersion": "[1.5.0.0,1.6.0.0)" }, "displayName": "Scim Connector", "objectTypes": [ "__ACCOUNT__", "__ALL__", "__GROUP__" ], "ok": true } ]
A status of "ok": true
indicates that the SCIM connector can reach the configured resource provider.
Implementation specifics
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The SCIM connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.
Using the SCIM connector with a proxy server
If the Identity Cloud server is hosted behind a firewall and requests to the resource provider are routed through a proxy, you must specify the proxy host and port in the connector configuration.
To specify the proxy server details, set the httpProxyHost
, and httpProxyPort
properties in the connector configuration. For example:
"configurationProperties": {
...
"httpProxyHost": "myproxy.home.com",
"httpProxyPort": 8080,
...
},
OpenICF Interfaces Implemented by the Scim Connector
The Scim Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Scim Connector Configuration
The Scim Connector has the following configurable properties:
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
The HTTP URL defining the root for the SCIM endpoint (https://myserver.com/service/scim) |
||||
|
|
|
|
Yes |
Defines the SCIM protocol version. Values can be either 1 or 2. Default is 1 |
||||
|
|
|
|
Yes |
Defines which method is to be used to authenticate on the remote server. Options are BASIC (username/password), OAUTH (Client id/secret) or TOKEN (static token). Defaults to OAUTH |
||||
|
|
|
|
Yes |
In case of BASIC authentication type, this property defines the remote user. |
||||
|
|
|
Yes |
No |
In case of BASIC authentication type, this property defines the remote password. |
||||
|
|
|
|
No |
When using OAuth, this property defines the endpoint where a new access token should be requested (https://myserver.com/oauth2/token) |
||||
|
|
|
|
Yes |
Secure client identifier for OAuth2 |
||||
|
|
|
Yes |
No |
Secure client secret for OAuth2 |
||||
|
|
|
Yes |
No |
Some service providers (Slack for instance) use static authentication tokens. |
||||
|
|
|
|
Yes |
Used by the refresh_token grant type |
||||
|
|
|
|
No |
The OAuth2 grant type to use (client_credentials or refresh_token) |
||||
|
|
|
|
No |
The OAuth2 scope to use. |
||||
|
|
|
|
Yes |
To be used for debug/test purposes. To be avoided in production. Defaults to false. |
||||
|
|
|
|
Yes |
To be used for debug/test purposes. To be avoided in production. Defaults to false. |
||||
|
|
|
|
Yes |
Content compression is enabled by default. Set this property to true to disable it. Defaults to false. |
||||
|
|
|
|
Yes |
If TLS Mutual Auth is needed, set this to the certificate alias from the keystore. |
||||
|
|
|
Yes |
Yes |
If TLS Mutual Auth is needed and the client certificate (private key) password is different than the keystore password, set this to the client private key password. |
||||
|
|
|
|
Yes |
Defines the max size of the http connection pool used. Defaults to 10. |
||||
|
|
|
|
Yes |
Defines the Hostname if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null. |
||||
|
|
|
|
Yes |
Defines the Port if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null. |
||||
|
|
|
|
Yes |
Defines Proxy Username if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null. |
||||
|
|
|
Yes |
Yes |
Defines Proxy Password if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null. |
||||
|
|
|
|
No |
Defines a timeout for the underlying http connection in seconds. Defaults to 30. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Scripted REST connector
The Scripted REST connector is an implementation of the Scripted Groovy Connector Toolkit. It can interact with any REST API, using Groovy scripts for the ICF operations. This connector type lets you develop a fully functional REST-based connector for in-house applications, or for any cloud-based application not yet supported with the standard set of ForgeRock connectors.
To use this connector, you must write a Groovy script for each operation that you want the connector to perform (create, read, update, delete, authenticate, and so on). No sample scripts are bundled with the connector, but Identity Cloud customers have access to the Scripted REST connector source code at https://stash.forgerock.org/projects/OPENICF/repos/connectors/browse/scriptedrest-connector. This repository includes sample scripts for all the ICF operations.
You cannot configure the Scripted REST connector through the UI. Configure the connector over REST, as described in Configure Connectors Over REST.
Script custom behavior
The Scripted REST connector uses the Apache HTTP client library. Unlike the Scripted SQL connector, which uses JDBC drivers and a Tomcat JDBC connection pool, the Scripted REST connector includes a special script to customize the Apache HTTP client.
This customizer script lets you customize the Apache HTTP client connection pool, proxy, default headers, timeouts, and so on.
The customizer script is referenced in the connector configuration, in the CustomizerScriptFileName
property:
{
...
"configurationProperties": {
...
"customizerScriptFileName": "CustomizerScript.groovy",
...
}
}
The script can implement two predefined Groovy closures — init {}
and decorate {}
.
init {}
-
The Apache HTTP client provides an HTTPClientBuilder class, to build an instance of the HTTPClient. The Scripted REST connector injects this builder into the
init
closure when the connector is first instantiated. Theinit
closure is the ideal place to customize the HTTP client with the builder.You can customize the following elements of the client:
-
Connection pool
-
Connection timeouts
-
Proxy
-
Default HTTP headers
-
Certificate handling
Example init closure
/** * A customizer script defines the custom closures to interact with the default implementation and customize it. * Here, the {@link HttpClientBuilder} is passed to the customize closure. This is where the pooling, the headers, * the timeouts etc... should be defined. */ customize { init { HttpClientBuilder builder -> //SETUP: org.apache.http def c = delegate as ScriptedRESTConfiguration def httpHost = new HttpHost(c.serviceAddress?.host, c.serviceAddress?.port, c.serviceAddress?.scheme) PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager() // Increase max total connection to 200 cm.setMaxTotal(200) // Increase default max connection per route to 20 cm.setDefaultMaxPerRoute(20) // Increase max connections for httpHost to 50 cm.setMaxPerRoute(new HttpRoute(httpHost), 50) builder.setConnectionManager(cm) // configure timeout on the entire client RequestConfig requestConfig = RequestConfig.custom()/* * . * setConnectionRequestTimeout * ( 50). * setConnectTimeout * (50) * .setSocketTimeout * (50) */.build(); builder.setDefaultRequestConfig(requestConfig) ... } }
Call the builder methods to fit your requirements. The
init{}
closure does not need to return anything. -
decorate {}
-
The
init
closure configures a Java instance of the HTTP client, which is injected into every CRUD script. In addition to the libraries provided by the Apache HTTP client, Groovy provides a number of libraries to deal with requests and responses.The
decorate
closure lets you inject a "decorated" instance of the HTTP client into your scripts. For example, the sample scripts use thegroovyx.net.http.RESTClient
library.This excerpt of a sample
delete
script shows the injection of thehttpClient
andconnection
variables into the script. Theconnection
variable is the output of thedecorate
closure.Example decorate closure
def operation = operation as OperationType def configuration = configuration as ScriptedRESTConfiguration def httpClient = connection as HttpClient def connection = customizedConnection as RESTClient def log = log as Log def objectClass = objectClass as ObjectClass def options = options as OperationOptions def uid = uid as Uid log.info("Entering " + operation + " Script"); switch (objectClass) { case ObjectClass.ACCOUNT: connection.delete(path: '/api/users/' + uid.uidValue); break case ObjectClass.GROUP: connection.delete(path: '/api/groups/' + uid.uidValue); }
When you use the
|
Example OAuth2 Authentication Implementation
This example shows how to use the customizer script to implement OAuth2 authentication in the Scripted REST connector.
Although grant types are largely standardized across OAuth2 authentication providers, the way in which different providers handle flows, headers, attribute names, and so on, often differs. This makes it difficult to include a single implementation of OAuth2 authentication in the Scripted REST connector. To make sure that OAuth2 authentication works in your specific use case, you use the customizer script, which can be adapted without requiring a new version of the connector itself.
The Scripted REST connector includes a simple implementation of the OAuth2 Client Credentials grant type. The connector needs to get an access token, using the Client ID and the Client Secret, cache it, and renew it when it expires or when the server revokes it. The Apache client provides interceptors for requests and responses. These interceptors can be used in the customizer script to manage the access token:
-
In the request: If the access token is absent or expired, renew the token and cache it in the Scripted REST connector property bag.
-
In the response: If the server returns a 401 error, delete the Access Token from the connector property bag. This will ensure that the next connector request gets a new access token. The HTTP POST query to get the access token is also handled by the customizer script.
This example shows a complete customizer script for the OAuth2 implementation:
init { HttpClientBuilder builder ->
switch (ScriptedRESTConfiguration.AuthMethod.valueOf(c.defaultAuthMethod)) {
// ......
case ScriptedRESTConfiguration.AuthMethod.OAUTH:
// define a request interceptor to set the Authorization header if absent or expired
HttpRequestInterceptor requestInterceptor = { HttpRequest request, HttpContext context ->
if (null == context.getAttribute("oauth-request")) {
def exp = c.propertyBag.tokenExpiration as Long
if (c.propertyBag.accessToken == null || exp < System.currentTimeMillis() / 1000) {
new NewAccessToken(c).clientCredentials()
}
request.addHeader(new BasicHeader(HttpHeaders.AUTHORIZATION, "Bearer " + c.propertyBag.accessToken))
}
}
// define a response interceptor to catch a 401 response code and delete access token from cache
HttpResponseInterceptor responseInterceptor = { HttpResponse response, HttpContext context ->
if (HttpStatus.SC_UNAUTHORIZED == response.statusLine.statusCode) {
if (c.propertyBag.accessToken != null) {
c.propertyBag.remove("accessToken")
Log.getLog(ScriptedRESTConnector.class).info("Code 401 - accessToken removed")
}
}
}
builder.addInterceptorLast(requestInterceptor)
builder.addInterceptorLast(responseInterceptor)
break
default:
throw new IllegalArgumentException()
}
}
class NewAccessToken {
static final String GRANT_TYPE = "grant_type"
static final String REFRESH_TOKEN = "refresh_token"
static final String CLIENT_CREDENTIALS = "client_credentials"
static final String CLIENT_ID = "client_id"
static final String CLIENT_SECRET = "client_secret"
static final String OAUTH_REQUEST = "oauth-request"
Log logger = Log.getLog(NewAccessToken.class)
ScriptedRESTConfiguration c = null
final CloseableHttpClient client = null
final HttpPost post = null
NewAccessToken(ScriptedRESTConfiguration conf) {
this.c = conf
this.client = c.getHttpClient()
this.post = new HttpPost(c.getOAuthTokenEndpoint())
post.setHeader(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded")
post.setHeader(HttpHeaders.ACCEPT, "application/json")
}
@Synchronized
void clientCredentials() {
boolean expired = (c.propertyBag.tokenExpiration as Long) < System.currentTimeMillis() / 1000
if (c.propertyBag.accessToken == null || expired ) {
if (c.propertyBag.tokenExpiration != null && expired) {
logger.info("Token expired!")
}
logger.info("Getting new access token...")
final List<NameValuePair> pairs = new ArrayList<>()
pairs.add(new BasicNameValuePair(GRANT_TYPE, CLIENT_CREDENTIALS))
pairs.add(new BasicNameValuePair(CLIENT_ID, c.getOAuthClientId()))
pairs.add(new BasicNameValuePair(CLIENT_SECRET, SecurityUtil.decrypt(c.getOAuthClientSecret())))
post.setEntity(new UrlEncodedFormEntity(pairs))
CloseableHttpResponse response = null
try {
HttpClientContext ctx = HttpClientContext.create()
ctx.setAttribute(OAUTH_REQUEST, true)
response = client.execute(post, ctx)
int statusCode = response.getStatusLine().getStatusCode()
if (HttpStatus.SC_OK == statusCode) {
def jsonSlurper = new JsonSlurper()
def oauthResponse = jsonSlurper.parseText(EntityUtils.toString(response.getEntity()))
c.propertyBag.accessToken = oauthResponse.access_token
c.propertyBag.tokenExpiration = System.currentTimeMillis() / 1000 + oauthResponse.expires_in as Long
} else {
throw new InvalidCredentialException("Retrieve Access Token failed with code: " + statusCode)
}
} catch (ClientProtocolException ex) {
logger.info("Trace: {0}", ex.getMessage())
throw new ConnectorException(ex)
} catch (IOException ex) {
logger.info("Trace: {0}", ex.getMessage())
throw new ConnectionFailedException(ex)
} finally {
try {
if (response != null) {
response.close()
}
} catch (IOException e) {
logger.info("Can't close HttpResponse")
}
}
}
}
}
Using the Scripted REST Connector With a Proxy Server
If the Identity Cloud server is hosted behind a firewall and requests to the resource are routed through a proxy, you must specify the proxy host and port in the connector configuration.
To specify the proxy server details, set the proxyAddress
property in the connector configuration. For example:
"configurationProperties": {
...
"proxyAddress": "http://myproxy:8080",
...
}
Implemented Interfaces
This table lists the ICF interfaces that are implemented for the scripted REST connector:
OpenICF Interfaces Implemented by the Scripted REST Connector
The Scripted REST Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Configuration Properties
This table lists the configuration properties for the scripted REST connector:
Scripted REST Connector Configuration
The Scripted REST Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
Custom Sensitive Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
No |
Custom Configuration script for Groovy ConfigSlurper |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Operation Script Files
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
|
The name of the file used to perform the CREATE operation. |
||||
|
|
|
|
No |
The script used to customize some function of the connector. Read the documentation for more details. |
||||
|
|
|
|
|
The name of the file used to perform the AUTHENTICATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RUNSCRIPTONRESOURCE operation. |
||||
|
|
|
|
|
The name of the file used to perform the DELETE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RESOLVE_USERNAME operation. |
||||
|
|
|
|
|
The name of the file used to perform the SEARCH operation. |
||||
|
|
|
|
|
The name of the file used to perform the UPDATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the SCHEMA operation. |
||||
|
|
|
|
|
The name of the file used to perform the TEST operation. |
||||
|
|
|
|
|
The name of the file used to perform the SYNC operation. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Groovy Engine configuration
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
Directory into which to write classes. |
||||
|
|
|
|
No |
Warning Level of the compiler |
||||
|
|
|
|
No |
Gets the extensions used to find groovy files |
||||
|
|
|
|
No |
Sets the minimum of time after a script can be recompiled. |
||||
|
|
|
|
No |
Base class name for scripts (must derive from Script) |
||||
|
|
|
|
Yes |
The root folder to load the scripts from. If the value is null or empty the classpath value is used. |
||||
|
|
|
|
No |
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted. |
||||
|
|
|
|
No |
If true, debugging code should be activated |
||||
|
|
|
|
No |
Classpath for use during compilation. |
||||
|
|
|
|
No |
Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled. |
||||
|
|
|
|
No |
If true, the compiler should produce action information |
||||
|
|
|
|
No |
Encoding for source files |
||||
|
|
|
|
No |
If set to true recompilation is enabled |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
The Remote user to authenticate with |
||||
|
|
|
Yes |
No |
The Password to authenticate with |
||||
|
|
|
|
Yes |
The service URI (example: http://myservice.com/api) |
||||
|
|
|
|
No |
The optional Proxy server URI (example: http://myproxy:8080) |
||||
|
|
|
|
No |
The username to authenticate with the proxy server |
||||
|
|
|
Yes |
No |
The password to authenticate with the proxy server |
||||
|
|
|
|
No |
Authentication method used. Defaults to BASIC. |
||||
|
|
|
|
No |
Default HTTP request content type. Defaults to JSON. Can be: TEXT, XML, HTML, URLENC, BINARY |
||||
|
|
|
|
No |
Placeholder for default HTTP request headers. |
||||
|
|
|
|
No |
When using OAUTH, this property defines the endpoint where a new access token should be queried for (https://myserver.com/oauth2/token) |
||||
|
|
|
|
No |
The client identifier |
||||
|
|
|
Yes |
No |
Secure client secret for OAUTH |
||||
|
|
|
Yes |
No |
The refresh token used to renew the access token for the refresh_token grant type |
||||
|
|
|
|
No |
The optional scope |
||||
|
|
|
|
No |
The grant type to use. Can be CLIENT_CREDENTIALS (default) |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Scripted SQL connector
The Scripted SQL connector is an implementation of the Scripted Groovy Connector Toolkit. This connector lets you interact with any SQL database, using Groovy scripts for the ICF operations.
To use this connector, you must write a Groovy script for each operation that you want the connector to perform (create, read, update, delete, authenticate, and so on). No sample scripts are bundled with the connector, but Identity Cloud customers have access to the Scripted SQL connector source code at https://stash.forgerock.org/projects/OPENICF/repos/connectors/browse/scriptedsql-connector. This repository includes sample scripts for all the ICF operations.
Configure the Scripted SQL connector
You cannot configure the Scripted SQL connector through the UI. Configure the connector over REST, as described in Configure Connectors Over REST.
Implemented interfaces
This table lists the ICF interfaces that are implemented for the scripted SQL connector:
OpenICF Interfaces Implemented by the Scripted SQL Connector
The Scripted SQL Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Configuration properties
This table lists the configuration properties for the scripted SQL connector:
Scripted SQL Connector Configuration
The Scripted SQL Connector has the following configurable properties:
Operation Script Files
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
|
The name of the file used to perform the CREATE operation. |
||||
|
|
|
|
No |
The script used to customize some function of the connector. Read the documentation for more details. |
||||
|
|
|
|
|
The name of the file used to perform the RESOLVE_USERNAME operation. |
||||
|
|
|
|
|
The name of the file used to perform the UPDATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the SCHEMA operation. |
||||
|
|
|
|
|
The name of the file used to perform the AUTHENTICATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RUNSCRIPTONRESOURCE operation. |
||||
|
|
|
|
|
The name of the file used to perform the DELETE operation. |
||||
|
|
|
|
|
The name of the file used to perform the SEARCH operation. |
||||
|
|
|
|
|
The name of the file used to perform the TEST operation. |
||||
|
|
|
|
|
The name of the file used to perform the SYNC operation. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Groovy Engine configuration
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
Directory into which to write classes. |
||||
|
|
|
|
No |
Warning Level of the compiler |
||||
|
|
|
|
No |
Gets the extensions used to find groovy files |
||||
|
|
|
|
No |
Base class name for scripts (must derive from Script) |
||||
|
|
|
|
Yes |
The root folder to load the scripts from. If the value is null or empty the classpath value is used. |
||||
|
|
|
|
No |
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted. |
||||
|
|
|
|
No |
Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled. |
||||
|
|
|
|
No |
Encoding for source files |
||||
|
|
|
|
No |
If set to true recompilation is enabled |
||||
|
|
|
|
No |
Sets the minimum of time after a script can be recompiled. |
||||
|
|
|
|
No |
If true, debugging code should be activated |
||||
|
|
|
|
No |
Classpath for use during compilation. |
||||
|
|
|
|
No |
If true, the compiler should produce action information |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
The connection password to be passed to our JDBC driver to establish a connection. Note that method DataSource.getConnection(username,password) by default will not use credentials passed into the method, but will use the ones configured here. See alternateUsernameAllowed property for more details. |
||||
|
|
|
Yes |
No |
Custom Sensitive Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
No |
Custom Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
No |
The connection properties that will be sent to our JDBC driver when establishing new connections. Format of the string must be [propertyName=property;]* NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here. The default value is null. |
||||
|
|
|
|
No |
Set this to true to propagate the interrupt state for a thread that has been interrupted (not clearing the interrupt state). Default value is false for backwards compatibility. |
||||
|
|
|
|
No |
Set this to true if you wish to put a facade on your connection so that it cannot be reused after it has been closed. This prevents a thread holding on to a reference of a connection it has already called closed on, to execute queries on it. |
||||
|
|
|
|
No |
The default catalog of connections created by this pool. |
||||
|
|
|
|
No |
avoid excess validation, only run validation at most at this frequency - time in milliseconds. If a connection is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 30000 (30 seconds). |
||||
|
|
|
|
No |
Flag whether ignore error of connection creation while initializing the pool. Set to true if you want to ignore error of connection creation while initializing the pool. Set to false if you want to fail the initialization of the pool by throwing exception. |
||||
|
|
|
|
No |
Register the pool with JMX or not. The default value is true. |
||||
|
|
|
|
No |
If autoCommit==false then the pool can complete the transaction by calling commit on the connection as it is returned to the pool If rollbackOnReturn==true then this attribute is ignored. Default value is false. |
||||
|
|
|
|
No |
Flag to log stack traces for application code which abandoned a Connection. Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated. The default value is false. |
||||
|
|
|
|
No |
The maximum number of connections that should be kept in the pool at all times. Default value is maxActive:100 Idle connections are checked periodically (if enabled) and connections that been idle for longer than minEvictableIdleTimeMillis will be released. (also see testWhileIdle) |
||||
|
|
|
|
No |
The indication of whether objects will be validated by the idle object evictor (if any). If an object fails to validate, it will be dropped from the pool. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false and this property has to be set in order for the pool cleaner/test thread is to run (also see timeBetweenEvictionRunsMillis) |
||||
|
|
|
|
No |
Flag to remove abandoned connections if they exceed the removeAbandonedTimeout. If set to true a connection is considered abandoned and eligible for removal if it has been in use longer than the removeAbandonedTimeout Setting this to true can recover db connections from applications that fail to close a connection. See also logAbandoned The default value is false. |
||||
|
|
|
|
No |
Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are above the percentage defined by abandonWhenPercentageFull. The value should be between 0-100. The default value is 0, which implies that connections are eligible for closure as soon as removeAbandonedTimeout has been reached. |
||||
|
|
|
|
No |
The minimum number of established connections that should be kept in the pool at all times. The connection pool can shrink below this number if validation queries fail. Default value is derived from initialSize:10 (also see testWhileIdle) |
||||
|
|
|
|
No |
The default read-only state of connections created by this pool. If not set then the setReadOnly method will not be called. (Some drivers dont support read only mode, ex: Informix) |
||||
|
|
|
|
No |
The maximum number of milliseconds that the pool will wait (when there are no available connections) for a connection to be returned before throwing an exception. Default value is 30000 (30 seconds) |
||||
|
|
|
|
No |
Set this to true to log errors during the validation phase to the log file. If set to true, errors will be logged as SEVERE. Default value is false for backwards compatibility. |
||||
|
|
|
|
No |
The fully qualified Java class name of the JDBC driver to be used. The driver has to be accessible from the same classloader as tomcat-jdbc.jar |
||||
|
|
|
|
No |
Returns the name of the connection pool. By default a JVM unique random name is assigned. |
||||
|
|
|
|
No |
If a statement proxy is set, wrap statements so that equals() and hashCode() methods can be called on closed statements. |
||||
|
|
|
|
No |
A custom query to be run when a connection is first created. The default value is null. |
||||
|
|
|
|
No |
The timeout in seconds before a connection validation queries fail. This works by calling java.test_sample.Statement.setQueryTimeout(seconds) on the statement that executes the validationQuery. The pool itself doesnt timeout the query, it is still up to the JDBC driver to enforce query timeouts. A value less than or equal to zero will disable this feature. The default value is -1. |
||||
|
|
|
|
No |
The SQL query that will be used to validate connections from this pool before returning them to the caller. If specified, this query does not have to return any data, it just cant throw a SQLException. The default value is null. Example values are SELECT 1(mysql), select 1 from dual(oracle), SELECT 1(MS Sql Server) |
||||
|
|
|
|
No |
If autoCommit==false then the pool can terminate the transaction by calling rollback on the connection as it is returned to the pool Default value is false. |
||||
|
|
|
|
No |
By default, the jdbc-pool will ignore the DataSource.getConnection(username,password) call, and simply return a previously pooled connection under the globally configured properties username and password, for performance reasons. The pool can however be configured to allow use of different credentials each time a connection is requested. To enable the functionality described in the DataSource.getConnection(username,password) call, simply set the property alternateUsernameAllowed to true. Should you request a connection with the credentials user1/password1 and the connection was previously connected using different user2/password2, the connection will be closed, and reopened with the requested credentials. This way, the pool size is still managed on a global level, and not on a per schema level. |
||||
|
|
|
|
No |
The JNDI name for a data source to be looked up in JNDI and then used to establish connections to the database. See the dataSource attribute. Default value is null |
||||
|
|
|
|
No |
The name of a class which implements the org.apache.tomcat.jdbc.pool.Validator interface and provides a no-arg constructor (may be implicit). If specified, the class will be used to create a Validator instance which is then used instead of any validation query to validate connections. The default value is null. An example value is com.mycompany.project.SimpleValidator. |
||||
|
|
|
|
No |
Timeout value in seconds. Similar to to the removeAbandonedTimeout value but instead of treating the connection as abandoned, and potentially closing the connection, this simply logs the warning if logAbandoned is set to true. If this value is equal or less than 0, no suspect checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets logged and a JMX notification gets sent once. |
||||
|
|
|
|
No |
Set to true if you wish the ProxyConnection class to use String.equals and set to false when you wish to use == when comparing method names. This property does not apply to added interceptors as those are configured individually. The default value is true. |
||||
|
|
|
|
No |
Timeout in seconds before an abandoned(in use) connection can be removed. The default value is 60 (60 seconds). The value should be set to the longest running query your applications might have. |
||||
|
|
|
|
No |
The default auto-commit state of connections created by this pool. If not set, default is JDBC driver default (If not set then the setAutoCommit method will not be called.) |
||||
|
|
|
|
No |
Validate the connection when connecting to the database for the first time. False by default. Set to true if you want to use the validationQuery as an init query. |
||||
|
|
|
|
No |
A semicolon separated list of classnames extending org.apache.tomcat.jdbc.pool.JdbcInterceptor class. See Configuring JDBC interceptors below for more detailed description of syntaz and examples. These interceptors will be inserted as an interceptor into the chain of operations on a java.test_sample.Connection object. The default value is null. |
||||
|
|
|
|
No |
The initial number of connections that are created when the pool is started. Default value is 10 |
||||
|
|
|
|
No |
The default TransactionIsolation state of connections created by this pool. One of the following: NONE, READ_COMMITTED, READ_UNCOMMITTED, REPEATABLE_READ, SERIALIZABLE If not set, the method will not be called and it defaults to the JDBC driver. |
||||
|
|
|
|
No |
Property not used in tomcat-jdbc-pool. |
||||
|
|
|
|
No |
The URL used to connect to the database. |
||||
|
|
|
|
No |
The indication of whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. In order to have a more efficient validation, see validationInterval. Default value is false |
||||
|
|
|
|
No |
Set to true if you wish that calls to getConnection should be treated fairly in a true FIFO fashion. This uses the org.apache.tomcat.jdbc.pool.FairBlockingQueue implementation for the list of the idle connections. The default value is true. This flag is required when you want to use asynchronous connection retrieval. Setting this flag ensures that threads receive connections in the order they arrive. During performance tests, there is a very large difference in how locks and lock waiting is implemented. When fairQueue=true there is a decision making process based on what operating system the system is running. If the system is running on Linux (property os.name=Linux. To disable this Linux specific behavior and still use the fair queue, simply add the property org.apache.tomcat.jdbc.pool.FairBlockingQueue.ignoreOS=true to your system properties before the connection pool classes are loaded. |
||||
|
|
|
|
No |
Property not used. Access can be achieved by calling unwrap on the pooled connection. see javax.test_sample.DataSource interface, or call getConnection through reflection or cast the object as javax.test_sample.PooledConnection |
||||
|
|
|
|
No |
Time in milliseconds to keep this connection. When a connection is returned to the pool, the pool will check to see if the now - time-when-connected > maxAge has been reached, and if so, it closes the connection rather than returning it to the pool. The default value is 0, which implies that connections will be left open and no age check will be done upon returning the connection to the pool. |
||||
|
|
|
|
No |
The minimum amount of time an object may sit idle in the pool before it is eligible for eviction. The default value is 60000 (60 seconds). |
||||
|
|
|
|
No |
The number of milliseconds to sleep between runs of the idle connection validation/cleaner thread. This value should not be set under 1 second. It dictates how often we check for idle, abandoned connections, and how often we validate idle connections. The default value is 5000 (5 seconds). |
||||
|
|
|
|
No |
The indication of whether objects will be validated before being returned to the pool. NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string. The default value is false. |
||||
|
|
|
|
No |
Use a lock when performing operations on the connection object. False by default. Set to true if you will use a separate background thread for idle and abandon checking (e.g. JMX clients). If the pool sweeper is enabled, a lock is used, regardless of this setting. |
||||
|
|
|
|
No |
The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100 |
||||
|
|
|
|
No |
The connection username to be passed to our JDBC driver to establish a connection. Note that method DataSource.getConnection(username,password) by default will not use credentials passed into the method, but will use the ones configured here. See alternateUsernameAllowed property for more details. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
SSH connector
The SSH connector is an implementation of the Scripted Groovy Connector Toolkit, and is based on Java Secure Channel (JSch) and the Java implementation of the Expect library (Expect4j). This connector lets you interact with any SSH server, using Groovy scripts for the ICF operations.
The SSH connector is a poolable connector. This means that each connector instance is placed into a connection pool every time an action is completed. Subsequent actions can re-use connector instances from the connector pool. When a new connector instance is created, a new SSH client connection is created against the target SSH server. This SSH connection remains open as long as the connector instance is in the connection pool. Note that when a new action is performed, it finds the SSH connection in the exact state that it was left by the previous action.
The following image shows the relationship between SSH connector instances and SSH connections to the target server:

Configure authentication to the SSH server
The SSH connector authenticates to the SSH server using either a login/password or a public/private key. The authentication method is specified in the authenticationType
property in the connector configuration.
- Authenticate with a login and password
-
To authenticate with a login and password, set the
authenticationType
toPASSWORD
in the connector configuration file, and set auser
andpassword
. For example:"configurationProperties" : { ... "authenticationType" : "PASSWORD", "user" : "<USERNAME>", "password" : "<PASSWORD>", ...
The password is encrypted when Identity Cloud loads the provisioner file.
- Authenticate with a passphrase and private key
-
To authenticate with a secure certificate, generate a pair of public/private keys. Install the public key on the server side and the private key on the Identity Cloud host (where the connector is located). Set the
authenticationType
toPUBKEY
in the connector configuration file and set theuser
,password
,passphrase
andprivateKey
properties. For example:"configurationProperties" : { ... "authenticationType" : "PUBKEY", "user" : "<USERNAME>", "password" : "<PASSWORD>", "passphrase" : "secret", "privateKey" : ["-----BEGIN DSA PRIVATE KEY-----", "MIIBugIBAAKBgQDcB0ztVMCFptpJhqlLNZSdN/5cDL3S7aOVy52Ae7vwwCqQPCQr", "6NyUk+wtkDr07NlYd3sg7a9hbsEnlYChsuX+/WUIvbOKdMfeqcQ+jKK26YdkTCGj", "g86dBj9JYhobSHDoQ9ov31pYN/cfW5BAZwkm9TdpEjHPvMIaOxx7GPGKWwIVALbD", "CEuf1yJk9UB7v0dmJS7bKkbxAoGARcbAuDP4rB6MsgAAkVwf+1sHXEiGPShYWrVV", "qBgCZ/S45ELqUuiaN/1N/nip/Cc/0SBPKqwl7o50CUg9GH9kTAjmXiwmbkwvtUv+", "Xjn5vCHS0w18yc3rGwyr2wj+D9KtDLFJ8+T5HmsbPoDQ3mIZ9xPmRQuRFfVMd9wr", "DY0Rs7cCgYAxjGjWDSKThowsvOUCiE0ySz6tWggHH3LTrS4Mfh2t0tnbUfrXq2cw", "3CN+T6brgnpYbyX5XI17p859C+cw90MD8N6vvBxaN8QMDRFk+hHNUeSy8gXeem9x", "O0vdIxCgKvA4dh5nSVb5VGKENEGNEHRlYxEPzbqlPa/C/ZvzIvdKXQIUQMoidPFC", "n9z+mE2dAADnPf2m9vk=", "-----END DSA PRIVATE KEY-----" ], ...
The default value for the
passphrase
property isnull
. If you do not set a passphrase for the private key, the passphrase value must be equal to an empty string.You must set a value for the
password
property, because the connector uses sudo to perform actions on the SSH server.The private key (PEM certificate) must be defined as a JSON String array.
The values of the
passphrase
,password
andprivateKey
are encrypted when Identity Cloud loads the provisioner file.
Configure the SSH connector
You cannot configure the SSHL connector through the UI. Configure the connector over REST, as described in Configure Connectors Over REST.
Set the authentication properties, as described in Configure Authentication to the SSH Server. In addition, set at least the following properties:
host
-
Specify the hostname or IP address of the SSH server.
port
-
Set the port on which the SSH server listens.
Default:
22
user
-
The username of the account that connects to the SSH server.
This account must be able to
ssh
into the server, with the password provided in the next parameter. password
-
The password of the account that is used to connect to the SSH server.
prompt
-
A string representing the remote SSH session prompt. This must be the exact prompt string, in the format
username@target:
, for exampleadmin@myserver:~$
. Include any trailing spaces.
This list describes the required configuration properties of the SSH connector. You can generally use the default values. For a list of all the configuration properties, see [connector-reference:].
sudoCommand
-
A string that shows the full path to the
sudo
command, for example/usr/bin/sudo
. echoOff
-
If set to
true
(the default), the input command echo is disabled. If set tofalse
, every character that is sent to the server is sent back to the client in theexpect()
call. terminalType
-
Sets the terminal type to use for the session. The list of supported types is determined by your Linux/UNIX system. For more information, see the
terminfo
manual page (man terminfo
).Default:
vt102
setLocale
-
If set to
true
, indicates that the default environment locale should be changed to the value of thelocale
property.Default:
false
locale
-
Sets the locale for the LC_ALL, LANG and LANGUAGE environment variables, if
setLocale
is set totrue
.Default:
en_US.utf8
connectionTimeout
-
Specifies the connection timeout to the remote server, in milliseconds.
Default:
5000
expectTimeout
-
Specifies the timeout used by the
expect()
calls in scripts, in milliseconds.Default:
5000
authenticationType
-
Sets the authentication type, either
PASSWORD
orPUBKEY
. For more information, see connector-reference:ssh.adoc#ssh-authentication.Default:
PASSWORD
throwOperationTimeoutException
-
If
true
, the connector throws an exception when theexpectTimeout
is reached for an operation. Otherwise, the operation fails silently.Default:
true
scriptRoots
-
The path to the Groovy scripts that will perform the ICF operations, relative to your Identity Cloud installation directory. The sample connector configuration expects the scripts in
project-dir/tools
, so this parameter is set to&{idm.instance.dir}/tools
in the sample configuration. classpath
-
The directory in which the compiler should look for compiled classes. The default classpath, if not is specified, is
install-dir/lib
. *ScriptFileName
-
The name of the Groovy script that is used for each ICF operation.
OpenICF Interfaces Implemented by the SSH Connector
The SSH Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
SSH Connector Configuration
The SSH Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
Yes |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
||||
|
|
|
|
|
Description is not available |
||||
|
|
|
|
No |
Description is not available |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
The hostname to connect to |
||||
|
|
|
|
Yes |
TCP port to use (defaults to 22) |
||||
|
|
|
|
Yes |
The user name used to login to remote server |
||||
|
|
|
Yes |
No |
The password used to login to remote server |
||||
|
|
|
Yes |
No |
The passphrase used to read the private key when using Public Key authentication |
||||
|
|
|
Yes |
No |
The base 64 encoded value (PEM) of the private key used for Public Key authentication |
||||
|
|
|
|
Yes |
Defines which authentication type should be use: PASSWORD or PUBKEY (defaults to PASSWORD) |
||||
|
|
`root@localhost:# ` |
|
Yes |
A string representing the remote SSH session prompt (defaults to root@localhost:# ) |
||||
|
|
|
|
Yes |
A string representing the sudo command (defaults to /usr/bin/sudo) |
||||
|
|
|
|
Yes |
Disable the input command echo (default to true) |
||||
|
|
|
|
Yes |
Defines the terminal type to use for the session (default to vt102) |
||||
|
|
|
|
Yes |
Define the locale for LC_ALL, LANG and LANGUAGE environment variables to use if setLocale=true |
||||
|
|
|
|
Yes |
Defines if the default environment locale should be changed with the value provided for locale (defaults to false) |
||||
|
|
|
|
Yes |
Defines the connection timeout to the remote server in milliseconds (default to 5000) |
||||
|
|
|
|
Yes |
Defines the timeout used by the expect() calls in the scripts in milliseconds (default to 5000) |
||||
|
|
|
|
Yes |
Defines if an OperationTimeoutException should be thrown if any call to expect times out (defaults to true) |
||||
|
|
|
|
No |
Defines the "prompt ready" timeout for the promptReady() command in milliseconds (default to 20) |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Additional connectors
In addition to the built-in and RCS bundled connectors, ForgeRock supports a number of additional connectors that you can sign in and download from the ForgeRock Download Center.
The following additional connectors are available from the ForgeRock Download Center:
DocuSign ConnectorThe DocuSign connector lets you manage DocuSign service accounts and synchronize accounts between DocuSign and the Identity Cloud managed user repository. |
Epic ConnectorThe Epic connector lets you interact with Epic health systems. |
Google Apps ConnectorThe Google Apps connector lets you interact with Google’s web applications. |
HubSpot ConnectorThe HubSpot connector lets you synchronize HubSpot contacts and companies with managed objects in an Identity Cloud repository. |
MongoDB ConnectorThe MongoDB connector is an implementation of the Scripted Groovy Connector. This connector lets you interact with a MongoDB document database, using Groovy scripts for the ICF operations. |
SAP ConnectorThe SAP connector is an implementation of the Scripted Groovy Connector that connects to any SAP system using the SAP JCo Java libraries. |
Workday ConnectorThe Workday connector lets you synchronize user accounts between Identity Cloud and Workday’s cloud-based HR system. |
DocuSign connector
The DocuSign connector lets you manage DocuSign service accounts and synchronize accounts between DocuSign and the Identity Cloud managed user repository.
This chapter describes how to install and configure the DocuSign connector, and how to perform basic tests to ensure that it’s running correctly.
Before you start
The instructions in this chapter assume that you have a DocuSign administrator account, and that you have added an Integrator Key, as described in the DocuSign Documentation. Before you configure the connector, log in to your administrator account and note the following information:
-
API User ID
-
API Account ID
-
Integration Key
You will also need to set up an RSA Keypair and copy the public and private keys to a location that will be accessible by the connector.
-
Docusign API Hostname
-
Docusign OAuth Hostname
You need these details to configure the connector to interact with your DocuSign environment.
The DocuSign connector uses Oauth to connect to DocuSign. You must grant authorization to the Integration Key by directing your browser to the following URL:
https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=your-integrator-key&redirect_uri=https://client.example.com/callback
In the resulting window, click Accept to grant the required authorization.
The connector requires signing groups to be enabled. Depending on your DocuSign plan, you might need to contact the DocuSign Support team to enable signing groups. For more information, see the DocuSign documentation.
Install the DocuSign connector
-
Download the connector .jar file from the ForgeRock BackStage download site site.
-
If you are running the connector locally, place it in the
/path/to/openidm/connectors
directory, for example:mv ~/Downloads/docusign-connector-1.5.20.5.jar /path/to/openidm/connectors/
-
If you are using a remote connector server (RCS), place it in the
/path/to/openicf/connectors
directory on the RCS.
-
-
Download the connector dependencies. The DocuSign connector has a dependency on the Java JWT library 3.4.0 (java-jwt-3.4.0.jar).
-
If you are running the connector locally, place the library in the
/path/to/openidm/lib
directory:mv ~/Downloads/java-jwt-3.4.0.jar /path/to/openidm/lib/
-
If you are using a remote connector server (RCS), place the library in the
/path/to/openicf/lib
directory on the RCS.
-
Configure the DocuSign connector
If you had already started Identity Cloud (or your RCS) before copying the connector .jar file to the connectors
directory, you must restart the server for the connector to be loaded.
|
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select DocuSign Connector - 1.5.20.5.
-
Complete the Base Connector Details.
-
Click Save.
When your connector is configured correctly, the connector displays as Active in the UI.
Alternatively, test the configuration over REST:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system/docusign?_action=test" { "name": "docusign", "enabled": true, "config": "config/provisioner.openicf/docusign", "connectorRef": { "bundleVersion": "[1.5.0.0,1.6.0.0)", "bundleName": "org.forgerock.openicf.connectors.docusign-connector", "connectorName": "org.forgerock.openicf.connectors.docusign.DocuSignConnector" }, "displayName": "DocuSign Connector", "objectTypes": [ "userSignature", "signingGroup", "__ALL__", "account", "contact" ], "ok": true }
If the command returns "ok": true
, your connector has been configured correctly, and can authenticate to the DocuSign server.
Configure connection pooling
The DocuSign connector supports connection pooling, which can substantially improve the performance of the connector. The basic connection pooling configuration is described in Connection pooling configuration.
Use the DocuSign connector
You can use the DocuSign connector to perform the following actions on a DocuSign account.
Create a DocuSign user
This example creates a user with the minimum required attributes.
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "userName": "Carlos Garcia", "email": "cgarcia@example.com", "password": "Passw0rd" }' \ "https://tenant-name.forgeblocks.com/openidm/system/docusign/account?_action=create" { "_id": "dc1c6940-1de7-4434-a91e-1407424cac91", "accountManagementGranular": [ { "canManageUsers": "false" }, { "canManageAdmins": "false" }, { "canManageGroups": "false" }, { "canManageSharing": "false" }, { "canManageAccountSettings": "false" }, { "canManageReporting": "false" }, { "canManageAccountSecuritySettings": "false" }, { "canManageSigningGroups": "false" } ], "userName": "Carlos Garcia", "enableConnectForUser": "false", "lastName": "Garcia", "createdDateTime": "2018-10-18T07:48:39.3870000Z", "userSettings": [ { "name": "expressSendOnly", "value": "false" } ], "email": "cgarcia@example.com", "sendActivationOnInvalidLogin": "false", "userStatus": "ActivationSent", "firstName": "Carlos", "groupList": [ { "groupName": "Everyone", "groupType": "everyoneGroup", "groupId": "4428049" } ], "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91", "isAdmin": "False", "userType": "CompanyUser" }
When you create a new user, you must specify at least the userName
, email
, and password
. The value of the userName
attribute determines how the remaining name attributes (firstName
, lastName
, and so on) are set in the new DocuSign user entry.
If you create the user with a single word as the value of the userName
attribute, for example, cgarcia
, the user’s userName
and lastName
attributes in DocuSign are both set to cgarcia
.
If you create the user with multiple words as the value of the userName
attribute, for example, Carlos Garcia
), the user’s userName
attribute is set to Carlos Garcia
, their firstName
attribute is set to Carlos
, and their lastName
attribute is set to Garcia
.
Only the first three words of the userName
attribute are parsed, into the firstName
, middleName
, and lastName
attributes. Any additional words are ignored.
By default, DocuSign accounts have a strict password strength setting. If a create operation fails with a Caused by: org.identityconnectors.framework.common.exceptions.ConnectorException: Invalid forgotten password challenge. You can also set a custom curl \ --header "Content-Type: application/json" \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "userName": "Carlos Garcia", "email": "cgarcia@example.com", "password": "Passw0rd", "forgottenPasswordInfo": { "forgottenPasswordQuestion1": "my question", "forgottenPasswordAnswer1": "my answer" } }' \ "https://tenant-name.forgeblocks.com/openidm/system/docusign/account?_action=create" |
Query DocuSign User Entries
This example queries all DocuSign users by their IDs:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/docusign/account?_queryId=query-all-ids" { "result": [ { "_id": "bc9f0464-808a-4703-b4c2-c1e6a77f0c3a", "userName": "Babs Jensen" }, { "_id": "dc1c6940-1de7-4434-a91e-1407424cac91", "userName": "Carlos Garcia" }, { "_id": "94be4fed-cfd7-47d5-9fcc-813405084f17", "userName": "Olayinka Kuti" } ], "resultCount": 3, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 }
The following command queries a specific user by their ID:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/docusign/account/dc1c6940-1de7-4434-a91e-1407424cac91" { "_id": "dc1c6940-1de7-4434-a91e-1407424cac91", "accountManagementGranular": [ { "canManageUsers": "false" }, { "canManageAdmins": "false" }, { "canManageGroups": "false" }, { "canManageSharing": "false" }, { "canManageAccountSettings": "false" }, { "canManageReporting": "false" }, { "canManageAccountSecuritySettings": "false" }, { "canManageSigningGroups": "false" } ], "userName": "Carlos Garcia", "enableConnectForUser": "false", "lastName": "Garcia", "createdDateTime": "2018-10-18T07:48:39.3870000Z", "userSettings": [ { "name": "expressSendOnly", "value": "false" } ], "email": "cgarcia@example.com", "sendActivationOnInvalidLogin": "false", "userStatus": "ActivationSent", "firstName": "Carlos", "groupList": [ { "groupName": "Everyone", "groupType": "everyoneGroup", "groupId": "4428049" } ], "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91", "isAdmin": "False", "userType": "CompanyUser" }
Modify a DocuSign User Entry
You can modify an existing user with a PATCH request or with a PUT request, including all attributes of the account in the request. You can use the connector to modify the following attributes of a user entry:
-
title
-
firstName
-
middleName
-
lastName
-
suffix
-
userName
After creation, a user’s email address is read-only and you cannot modify it using the connector.
If forgotten password recovery has been enabled for the DocuSign user account, (forgottenPasswordQuestion
and forgottenPasswordAnswer
have been set) you can use the connector to change a user’s password. You must include the following attributes in a password change request:
-
currentPassword
-
newPassword
-
email
-
forgottenPasswordQuestion
-
forgottenPasswordAnswer
-
forgottenPasswordInfo
The following example changes Carlos Garcia’s password:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-type: application/json" \ --request PATCH \ --data '[ { "operation": "replace", "field": "password", "value": "MyPassw0rd" } ]' \ "https://tenant-name.forgeblocks.com/openidm/system/docusign/account/dc1c6940-1de7-4434-a91e-1407424cac91" { "_id": "dc1c6940-1de7-4434-a91e-1407424cac91", "accountManagementGranular": [ { "canManageUsers": "false" }, { "canManageAdmins": "false" }, { "canManageGroups": "false" }, { "canManageSharing": "false" }, { "canManageAccountSettings": "false" }, { "canManageReporting": "false" }, { "canManageAccountSecuritySettings": "false" }, { "canManageSigningGroups": "false" } ], "userName": "Carlos Garcia", "userProfileLastModifiedDate": "2018-10-18T01:10:59.4230000Z", "enableConnectForUser": "false", "lastName": "Garcia", "createdDateTime": "2018-10-18T07:48:39.3870000Z", "userSettings": [ { "name": "expressSendOnly", "value": "false" } ], "email": "cgarcia@example.com", "sendActivationOnInvalidLogin": "false", "userStatus": "ActivationSent", "firstName": "Carlos", "groupList": [ { "groupName": "Everyone", "groupType": "everyoneGroup", "groupId": "4428049" } ], "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91", "isAdmin": "False", "userType": "CompanyUser" }
If the naming component attributes are sent in an update, these attribute values are set on the DocuSign user. The user’s userName
attribute is re-generated from the individual naming components. If both the userName
and additional naming component attributes (such as firstName
or lastName
are sent in the update request, the supplied userName
attribute is ignored and its value is regenerated from the individual naming components.
Close a DocuSign User Account
You cannot use the DocuSign connector to delete an account from the DocuSign repository. However, you can use a DELETE request to set the userStatus
attribute of the account to Closed
.
The following example closes Carlos Garcia’s DocuSign account:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "https://tenant-name.forgeblocks.com/openidm/system/docusign/account/dc1c6940-1de7-4434-a91e-1407424cac91" { "_id": "dc1c6940-1de7-4434-a91e-1407424cac91", "accountManagementGranular": [ { "canManageUsers": "false" }, { "canManageAdmins": "false" }, { "canManageGroups": "false" }, { "canManageSharing": "false" }, { "canManageAccountSettings": "false" }, { "canManageReporting": "false" }, { "canManageAccountSecuritySettings": "false" }, { "canManageSigningGroups": "false" } ], "userName": "Carlos Garcia", "userProfileLastModifiedDate": "2018-10-18T01:10:59.4230000Z", "enableConnectForUser": "false", "lastName": "Garcia", "createdDateTime": "2018-10-18T07:48:39.3870000Z", "userSettings": [ { "name": "expressSendOnly", "value": "false" } ], "email": "cgarcia@example.com", "sendActivationOnInvalidLogin": "false", "userStatus": "ActivationSent", "firstName": "Carlos", "groupList": [ { "groupName": "Everyone", "groupType": "everyoneGroup", "groupId": "4428049" } ], "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91", "isAdmin": "False", "userType": "CompanyUser" }
A closed account remains in the DocuSign repository and can still be queried by its ID. |
OpenICF Interfaces Implemented by the DocuSign Connector
The DocuSign Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
DocuSign Connector Configuration
The DocuSign Connector has the following configurable properties:
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
The DNS name or IP address of the DocuSign REST server |
||||
|
|
|
|
Yes |
The OAuth host URL to the DocuSign REST server |
||||
|
|
|
|
Yes |
The DocuSign Account ID to manage |
||||
|
|
|
|
Yes |
The DocuSign integrator key for accessing the REST API |
||||
|
|
|
|
Yes |
The path to the private key used to generate a JSON web token (JWT) |
||||
|
|
|
|
Yes |
The path to the public key used to generate a JSON web token (JWT) |
||||
|
|
|
|
Yes |
The user ID of the user creating the JSON web token (JWT) |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Advanced Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
Specifies that the HTTP client accepts self-signed certificates |
||||
|
|
|
|
Yes |
Specifies that the HTTP client does not verify the host name |
||||
|
|
|
|
No |
The maximum number of connections |
||||
|
|
|
|
Yes |
The hostname of the HTTP proxy (if an HTTP proxy is used between the connector and the DocuSign server) |
||||
|
|
|
|
Yes |
The proxy port number (if an HTTP proxy is used between the connector and the DocuSign server) |
||||
|
|
|
|
Yes |
Specifies that there is consent from the organization |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Epic connector
Epic is a healthcare-related service which handles patient medical records. The Epic connector lets you manage and synchronize accounts between Epic and the Identity Cloud managed user objects. An Epic administrator account on the Epic system you wish to connect to is required for this connector to work.
Before you start
Before you configure the connector, log in to your Epic administrator account and note the following:
-
Client ID
-
Username
-
Password
-
Private key (Generate an RSA keypair and convert to PKCS8)
To generate your private key:
-
Generate and download an RSA key pair.
-
Run the following command to convert the RSA private key to PKCS8 format:
openssl pkcs8 -topk8 -nocrypt -in privatekey.pem -out epic_pkcs8_private_key.pem
-
After generating the private key in PKCS8 format, remove
-----BEGIN PRIVATE KEY-----
and-----END PRIVATE KEY-----
from the generated PKCS8 private key file. -
Remove any escape characters such as
\n
or\r
.
-
-
REST endpoint (Optional)
-
SOAP endpoint (Optional)
-
Max records (Optional)
Install the Epic connector
Download the connector .jar file from the ForgeRock BackStage download site.
-
If you are running the connector locally, place it in the
/path/to/openidm/connectors
directory, for example:mv ~/Downloads/epic-connector-1.5.20.5.jar /path/to/openidm/connectors/
-
If you are using a remote connector server (RCS), place it in the
/path/to/openicf/connectors
directory on the RCS.
Configure the Epic connector
Create a connector configuration using the IDM admin UI:
-
Select Configure > Connectors and click New Connector.
-
Enter a Connector Name.
-
Select Epic Connector - 1.5.20.5 as the Connector Type.
-
Provide the Base Connector Details.
-
Click Save.
When your connector is configured correctly, the connector displays as Active in the IDM admin UI.
Alternatively, test that the configuration is correct by running the following command:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system/Epic?_action=test" { "name": "Epic", "enabled": true, "config": "config/provisioner.openicf/Epic", "connectorRef": { "bundleVersion": "[1.5.0.0,1.6.0.0)", "bundleName": "org.forgerock.openicf.connectors.epic-connector", "connectorName": "org.forgerock.openicf.connectors.epic.EpicConnector" }, "displayName": "Epic Connector", "objectTypes": [ "__ACCOUNT__", "__ALL__" ], "ok": true }
If the command returns "ok": true
, your connector has been configured correctly, and can authenticate to the Epic server.
Configure connection pooling
The Epic connector supports connection pooling, which can substantially improve the performance of the connector. The basic connection pooling configuration is described in Connection pooling configuration.
Use the Epic connector
You can use the Epic connector to perform the following actions on an Epic account:
Create an Epic user
The following example creates a user with the minimum required attributes:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json"\ --request POST \ --data '{ "UserID": "8675309", "__NAME__": "Walter, Taylor" }'\ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__?_action=create" { "_id": "8675309", "UserComplexName": { "FirstName": "Taylor", "GivenNameInitials": "", "MiddleName": "", "LastName": "Walter", "LastNamePrefix": "", "SpouseLastName": "", "SpousePrefix": "", "Suffix": "", "AcademicTitle": "", "PrimaryTitle": "", "SpouseLastNameFirst": false, "FatherName": "", "GrandfatherName": "" }, "BlockStatus": { "IsBlocked": false, "Reason": "", "Comment": "" }, "__GROUP__": [], "ContactComment": "Initial contact created via web service", "UserID": "8675309", "__NAME__": "WALTER, TAYLOR", "UsersManagers": [], "InBasketClassifications": [], "__ENABLE__": true }
|
Query Epic user entries
The following example queries all Epic users:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__?_queryId=query-all-ids" { "result": [ { "_id": "dsully" }, { "_id": "999999999" }, { "_id": "admin@ACECompany.com" }, { "_id": "extuser320" }, { "_id": "Achong" }, { "_id": "dsewell" }, { "_id": "8675309" }, { "_id": "atestuser" }, { "_id": "Amaraphornc" }, { "_id": "jocampo" } ], "resultCount": 10, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 }
The following command queries a specific user by their ID:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__/8675309" { "_id": "8675309", "UserComplexName": { "FirstName": "Taylor", "GivenNameInitials": "", "MiddleName": "", "LastName": "Walter", "LastNamePrefix": "", "SpouseLastName": "", "SpousePrefix": "", "Suffix": "", "AcademicTitle": "", "PrimaryTitle": "", "SpouseLastNameFirst": false, "FatherName": "", "GrandfatherName": "" }, "BlockStatus": { "IsBlocked": false, "Reason": "", "Comment": "" }, "__GROUP__": [], "ContactComment": "Initial contact created via web service", "UserID": "8675309", "__NAME__": "WALTER, TAYLOR", "UsersManagers": [], "InBasketClassifications": [], "__ENABLE__": true }
Modify an Epic user entry
You can modify an existing user with a PUT request, including all attributes of the account in the request. You can use the Epic connector to modify the following attributes of a user entry:
-
__ENABLE__
-
__GROUP__
-
__NAME__
(Required) -
__PASSWORD__
-
ContactComment
-
LDAPOverrideID
-
UserAlias
-
UserPhotoPath
-
Sex
-
ReportGrouper1
-
ReportGrouper2
-
ReportGrouper3
-
Notes
-
UserComplexName
-UserComplexName
has the following sub-attributes:-
FirstName
-
GivenNameInitials
-
MiddleName
-
LastName
-
LastNamePrefix
-
SpouseLastName
-
SpousePrefix
-
SpouseLastNameFirst
-
Suffix
When updating a user, __NAME__
overrides theFirstName
,LastName
andMiddleName
ofUserComplexName
attributes. -
-
BlockStatus
-BlockStatus
has the following sub-attributes:-
IsBlocked
-
BlockStatus.Comment
-
For example, to add a Suffix
to a user:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --header "if-Match:*" \ --request PUT \ --data '{ "__NAME__": "Walter, Taylor", "UserComplexName": { "Suffix": "Junior" } }' \ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__/8675309" { "_id": "8675309", "UserComplexName": { "FirstName": "Taylor", "GivenNameInitials": "", "MiddleName": "", "LastName": "Walter", "LastNamePrefix": "", "SpouseLastName": "", "SpousePrefix": "", "Suffix": "Jr.", "AcademicTitle": "", "PrimaryTitle": "", "SpouseLastNameFirst": false, "FatherName": "", "GrandfatherName": "" }, "BlockStatus": { "IsBlocked": false, "Reason": "", "Comment": "" }, "__GROUP__": [], "UserID": "8675309", "__NAME__": "WALTER, TAYLOR JR.", "UsersManagers": [], "InBasketClassifications": [], "__ENABLE__": true }
Reset an Epic user account password
To reset the password for Epic user account, you can use the connector to change a user’s password.
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --header "if-Match:*" \ --request PUT \ --data '{ "__PASSWORD__": "Passw0rd@123!", "__NAME__": "Walter, Taylor" }' \ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__/8675309" { "_id": "8675309", "UserComplexName": { "FirstName": "Taylor", "GivenNameInitials": "", "MiddleName": "", "LastName": "Walter", "LastNamePrefix": "", "SpouseLastName": "", "SpousePrefix": "", "Suffix": "", "AcademicTitle": "", "PrimaryTitle": "", "SpouseLastNameFirst": false, "FatherName": "", "GrandfatherName": "" }, "BlockStatus": { "IsBlocked": false, "Reason": "", "Comment": "" }, "__GROUP__": [], "UserID": "8675309", "__NAME__": "WALTER, TAYLOR", "UsersManagers": [], "InBasketClassifications": [], "__ENABLE__": true }
Activate an Epic user
The following example activates a user with the minimum required attributes, and updates their name:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --header "if-Match:*" \ --request PUT \ --data '{ "__NAME__": "Walter, Taylorupdate", "__ENABLE__": "true" }' \ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__/8675309" { "_id": "8675309", "UserComplexName": { "FirstName": "Taylorupdate", "GivenNameInitials": "", "MiddleName": "", "LastName": "Walter", "LastNamePrefix": "", "SpouseLastName": "", "SpousePrefix": "", "Suffix": "", "AcademicTitle": "", "PrimaryTitle": "", "SpouseLastNameFirst": false, "FatherName": "", "GrandfatherName": "" }, "BlockStatus": { "IsBlocked": false, "Reason": "", "Comment": "" }, "__GROUP__": [], "UserID": "8675309", "__NAME__": "WALTER, TAYLORUPDATE", "UsersManagers": [], "InBasketClassifications": [], "__ENABLE__": true }
Deactivate an Epic user
The following example deactivates a user with the minimum required attributes:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --header "if-Match:*" \ --request PUT \ --data '{ \ "__NAME__": "TAYLOR, WALTER", "__ENABLE__": false }'\ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__/8675309" { "_id": "8675309", "UserComplexName": { "FirstName": "Taylor", "GivenNameInitials": "", "MiddleName": "", "LastName": "Walter", "LastNamePrefix": "", "SpouseLastName": "", "SpousePrefix": "", "Suffix": "", "AcademicTitle": "", "PrimaryTitle": "", "SpouseLastNameFirst": false, "FatherName": "", "GrandfatherName": "" }, "BlockStatus": { "IsBlocked": false, "Reason": "", "Comment": "" }, "__GROUP__": [], "UserID": "8675309", "__NAME__": "WALTER, TAYLOR", "UsersManagers": [], "InBasketClassifications": [], "__ENABLE__": false }
Close an Epic user account
You can use the Epic connector to delete an account from the Epic repository.
A deleted account technically remains in the Epic repository, but cannot be queried by its ID. |
The following example deletes an Epic account:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --request DELETE \ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__/8675309" { "_id": "8675309", "UserComplexName": { "FirstName": "Taylor", "GivenNameInitials": "", "MiddleName": "", "LastName": "Walter", "LastNamePrefix": "", "SpouseLastName": "", "SpousePrefix": "", "Suffix": "", "AcademicTitle": "", "PrimaryTitle": "", "SpouseLastNameFirst": false, "FatherName": "", "GrandfatherName": "" }, "BlockStatus": { "IsBlocked": false, "Reason": "", "Comment": "" }, "__GROUP__": [], "UserID": "8675309", "__NAME__": "WALTER, TAYLOR", "UsersManagers": [], "InBasketClassifications": [], "__ENABLE__": false }
You can then confirm the account has been deleted by querying the UserID
:
curl \ --header "Authorization: Bearer *token*" \ --header "Content-Type: application/json" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/Epic/__ACCOUNT__/8675309" { "code": 404, "reason": "Not Found", "message": "Object 8675309 not found on system/Epic/__ACCOUNT__" }
OpenICF Interfaces Implemented by the Epic Connector
The Epic Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Epic Connector Configuration
The Epic Connector has the following configurable properties:
Basic configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
Provide the Client ID to authorize the Epic APIs |
||||
|
|
|
Yes |
Yes |
Provide the Private key in pkcs8 format |
||||
|
|
|
|
Yes |
Provide the Username required for Connection |
||||
|
|
|
Yes |
Yes |
Provide the Password required for Connection |
||||
|
|
|
|
No |
Provide the Maximum records for search operation |
||||
|
|
|
|
No |
Provide the Maximum connections |
||||
|
|
|
|
No |
Provide the Maximum Connection Timeout in seconds |
||||
|
|
|
Yes |
No |
Provide the Access token to establish connectivity with the target |
||||
|
|
|
|
No |
Provide the Validity period of the token |
||||
|
|
|
|
No |
Provide the HTTP Proxy Host |
||||
|
|
|
|
No |
Provide the HTTP Proxy Port |
||||
|
|
|
|
No |
Provide the HTTP Proxy Username |
||||
|
|
|
Yes |
No |
Provide the HTTP Proxy Password |
||||
|
|
|
No |
|
The HTTP URL for the REST End point (https://myserver.com/service/) |
||||
|
|
|
No |
|
The HTTP URL for the SOAP End point (https://myserver.com/service/) |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Google Apps connector
Identity Cloud bundles a Google Apps connector, along with a sample connector configuration. The Google Apps connector lets you interact with Google’s web applications.
The Google Apps connector is subject to the API Limits and Quotas imposed by Google. The connector also adheres to the implementation guidelines set out by Google for implementing exponential backoff.
Configure the Google Apps connector
The Google Apps connector uses OAuth2 to authorize the connection to the Google service. To use this authorization mechanism, you must supply a clientId
and clientSecret
, to obtain an access token from Google. You can get the clientId
and clientKey
from the Google Developers Console after you have configured your Web Application.
This excerpt shows a sample Google Apps connector configuration. The default location of the connector .jar file is openidm/connectors
. Therefore, the value of the connectorHostRef
property must be "#LOCAL"
:
{
"connectorHostRef": "#LOCAL",
"connectorName": "org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector",
"bundleName": "org.forgerock.openicf.connectors.googleapps-connector",
"bundleVersion": "[1.5.0.0,1.6.0.0)"
},
The required configuration properties are as follows:
"configurationProperties": {
"domain": "",
"clientId": "",
"clientSecret": null,
"refreshToken": null
},
domain
-
Set to the domain name for OAuth 2-based authorization.
clientId
-
A client identifier, as issued by the OAuth 2 authorization server. For more information, see the following section of RFC 6749: Client Identifier.
clientSecret
-
Sometimes also known as the client password. OAuth 2 authorization servers can support the use of
clientId
andclientSecret
credentials, as noted in the following section of RFC 6749: Client Password. - refreshToken
-
A client can use an OAuth 2 refresh token to continue accessing resources. For more information, see the following section of RFC 6749: Refresh Tokens.
OpenICF Interfaces Implemented by the GoogleApps Connector
The GoogleApps Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
GoogleApps Connector Configuration
The GoogleApps Connector has the following configurable properties:
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
Yes |
Internet domain name. See https://support.google.com/a/answer/177483?hl=en |
||||
|
|
|
|
Yes |
Client identifier issued to the client during the registration process. |
||||
|
|
|
Yes |
Yes |
Client secret issued to the client during the registration process. |
||||
|
|
|
Yes |
Yes |
The refresh token allows you to get a new access token that is good for another hour. Refresh tokens never expire, they can only be revoked by the user or programatically by your app. |
||||
|
|
|
|
Yes |
Defines an HTTP proxy host to use with the connection (example: "myproxy.home.com"). |
||||
|
|
|
|
Yes |
Defines an HTTP proxy port to use with the connection (defaults to 8080). |
||||
|
|
|
|
Yes |
Validate the server certificate from the local truststore (defaults to true). |
||||
|
|
|
|
No |
Maximum number of Users to return. Acceptable values are 1 to 500, inclusive. |
||||
|
|
|
|
No |
Maximum number of Groups to return. Acceptable values are 1 to 200, inclusive. |
||||
|
|
|
|
No |
Maximum number of Members to return. Acceptable values are greater than 1 |
||||
|
|
|
|
No |
Maximum number of Licenses to return. Acceptable values are 1 to 1000, inclusive. |
||||
|
|
|
|
No |
Maximum number of Licenses to return. Acceptable values are 1 to 1000, inclusive. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Use the Google Apps connector with a proxy server
If the Identity Cloud server is hosted behind a firewall and requests to the Google Apps server are routed through a proxy, you must specify the proxy host and port in the connector configuration so that the connector can pass this information to the lower Google API.
To specify the proxy server details, set the proxyHost
, proxyPort
and validateCertificate
properties in the connector configuration. For example:
"configurationProperties": {
...
"proxyHost": "myproxy.home.com",
"proxyPort": 8080,
"validateCertificate": true,
...
}
The validateCertificate
property indicates whether the proxy server should validate the server certificate from the local truststore.
Supported resource types
The Google Apps connector uses the Google Enterprise License Manager and Directory APIs to perform CRUD operations against resources within a Google Apps domain.
The following table lists the resource types that are supported by the Google Apps connector:
ICF Native Type | Google Resource Type | Naming Attribute |
---|---|---|
__ACCOUNT__ |
user |
primaryEmail |
__GROUP__ |
group |
|
Member |
member |
{groupKey}/email |
OrgUnit |
orgUnit |
{parentOrgUnitPath}/__NAME__ |
LicenseAssignment |
licenseAssignment |
{productId}/sku/{skuId}/user/{primaryEmail} |
Functional limitations
The Google Apps connector is subject to the following functional limitations:
-
In an UPDATE request, the old object (before the update) is returned in the request result. This behavior differs from that for other connectors, where the updated object is returned.
Although the update is processed correctly, there is a significant delay from Google, and Identity Cloud sends its GET request to return the object before the update has taken effect. This behavior has no impact on the success of the update.
-
The connector does not implement the ICF Sync operation so you cannot use the connector for liveSync of supported Google Apps resources to Identity Cloud managed objects.
-
The connector does not implement the Authenticate operation so you cannot use the connector to perform pass-through authentication between Identity Cloud and a Google Apps domain. You can also not use this connector to perform password Change operations (as opposed to password Reset) because the connector cannot authenticate on behalf of the end user.
-
Support for Filters when performing Search operations is limited to those attributes described in connector-reference:google.adoc#google-apps-search-filters.
-
Google Apps creates a new User Alias each time the
primaryEmail
address associated with the User object is modified. You cannot delete User Aliases with the Google Apps connector so you must manage Aliases directly from within the Google Apps console. -
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The Google Apps connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.
Supported search filters
The Google Apps connector supports filtered searches against Google Apps resources. However, limitations imposed by the APIs provided by the Google Apps Admin SDK prevent filtering of resource types based on arbitrary attributes and values.
The following filter operators and attributes are supported for Search operations with the Google Apps connector:
Object Type | Operators | Attributes |
---|---|---|
__ACCOUNT__ |
And, Contains, StartsWith, Equals |
primaryEmail |
__GROUP__ |
Contains, Equals |
|
Member |
Equals |
{groupKey}/email |
OrgUnit |
StartsWith |
{parentOrgUnitPath}/__NAME__ |
LicenseAssignment |
Equals |
{productId}/sku/{skuId}/user/{primaryEmail} |
HubSpot connector
The HubSpot connector lets you synchronize HubSpot contacts and companies with managed objects in an Identity Cloud repository.
This topic describes how to install and configure the HubSpot connector and how to perform basic tests to ensure that it’s running correctly.
Before you configure the HubSpot connector, you must have a client app in HubSpot, with the corresponding clientID
, clientSecret
and refreshToken
.
Install the HubSpot connector
-
Download the connector .jar file from the ForgeRock BackStage download site.
-
If you are running the connector locally, place it in the
/path/to/openidm/connectors
directory, for example:mv ~/Downloads/hubspot-connector-1.5.2.0.jar /path/to/openidm/connectors/
-
If you are using a remote connector server (RCS), place it in the
/path/to/openicf/connectors
directory on the RCS.
-
Configure the HubSpot connector
If you had already started Identity Cloud (or your RCS) before copying the connector .jar file to the connectors
directory, you must restart the server for the connector to be loaded.
|
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select HubSpot Connector - 1.5.2.0.
-
Complete the Base Connector Details.
-
Click Save.
When your connector is configured correctly, the connector displays as Active in the UI.
Alternatively, test the configuration over REST:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system?_action=test" [ { "name": "hubspot", "enabled": true, "config": "config/provisioner.openicf/hubspot", "connectorRef": { "bundleVersion": "[1.5.0.0,1.6.0.0)", "bundleName": "org.forgerock.openicf.connectors.hubspot-connector", "connectorName": "org.forgerock.openicf.connectors.hubspot.HubspotConnector" }, "displayName": "Hubspot Connector", "objectTypes": [ "company", "contactProperties", "__ALL__", "companyProperties", "contact" ], "ok": true } ]
A status of "ok": true
indicates that the connector can connect to HubSpot.
Implementation specifics
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The HubSpot connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.
Using the HubSpot connector with a proxy server
If the Identity Cloud server is hosted behind a firewall and requests to the resource provider are routed through a proxy, you must specify the proxy host and port in the connector configuration.
To specify the proxy server details, set the httpProxyHost
, and httpProxyPort
properties in the connector configuration. For example:
"configurationProperties": {
...
"httpProxyHost": "myproxy.home.com",
"httpProxyPort": 8080,
...
}
OpenICF Interfaces implemented by the Hubspot connector
The Hubspot Connector implements the following OpenICF interfaces.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script-arguments passed in by the application.
-
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Test
-
Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
Hubspot connector configuration
The Hubspot Connector has the following configurable properties.
Basic Configuration Properties properties
Property | Type | Default | Encrypted [2] | Required [3] |
---|---|---|---|---|
|
|
|
![]() |
|
Client ID of the OAuth application in Hubspot |
||||
|
|
|
![]() |
![]() |
Client Secret for the preceding Client ID |
||||
|
|
|
![]() |
![]() |
Refresh token for application in Hubspot |
||||
Advanced Connection Properties properties
Property | Type | Default | Encrypted [4] | Required [5] |
---|---|---|---|---|
|
|
|
![]() |
|
Specifies whether the HubSpot server should accept self-signed certificates. Defaults to false. |
||||
|
|
|
![]() |
|
If false, the Hubspot connector provides a default schema for Hubspot contacts and companies |
||||
|
|
|
![]() |
|
If hostname verification is disabled, the HubSpot server accepts connections from any host. Defaults to false. |
||||
|
|
|
![]() |
|
Maximum number of simultaneous connections to HubSpot. |
||||
|
|
|
![]() |
|
Number of Api calls to be made per second |
||||
|
|
|
![]() |
|
Specifies the Hostname if an HTTP proxy is used between the connector and HubSpot. Defaults to null. |
||||
|
|
|
![]() |
|
Specifies the Port number if an HTTP proxy is used between the connector and HubSpot . Defaults to null. |
||||
MongoDB connector
The MongoDB connector is an implementation of the Scripted Groovy Connector. This connector lets you interact with a MongoDB document database, using Groovy scripts for the ICF operations.
Before you start
In a production environment, enable access control on your MongoDB database. If your connector will manage MongoDB users and roles, you must create an administrative user in the admin
database. If your connector will manage collections in a database, this administrative user must create a specific user and role for the connector for the target database.
For information about enabling access control in MongoDB, see the MongoDB documentation.
The commands in this chapter assume an administrative user named myUserAdmin
with password Passw0rd
who has the readWrite
role on the test
database.
Configure the MongoDB connector
Create a connector configuration using the IDM admin UI:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select MongoDB Connector - 1.5.20.5.
-
Complete the Base Connector Details. For information about the configurable properties, see MongoDB Basic Configuration Properties.
-
Click Save.
When your connector is configured correctly, you can test its status by running the following command:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system?_action=test" [ { "name": "mongodb", "enabled": true, "config": "config/provisioner.openicf/mongodb", "connectorRef": { "bundleVersion": "[1.5.0.0,1.6.0.0)", "bundleName": "org.forgerock.openicf.connectors.mongodb-connector", "connectorName": "org.forgerock.openicf.connectors.mongodb.MongoDBConnector" }, "displayName": "MongoDB Connector", "objectTypes": [ "__ALL__", "account", "role" ], "ok": true } ]
A status of "ok": true
indicates that the MongoDB connector can connect to the database.
OpenICF Interfaces Implemented by the MongoDB Connector
The MongoDB Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:
- Authenticate
-
Provides simple authentication with two parameters, presumed to be a user name and password.
- Create
-
Creates an object and its
uid
. - Delete
-
Deletes an object, referenced by its
uid
. - Resolve Username
-
Resolves an object by its username and returns the
uid
of the object. - Schema
-
Describes the object types, operations, and options that the connector supports.
- Script on Connector
-
Enables an application to run a script in the context of the connector.
Any script that runs on the connector has the following characteristics:
-
The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
-
The script has access to a
connector
variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration. -
The script has access to any script arguments passed in by the application.
-
- Script on Resource
-
Runs a script on the target resource that is managed by this connector.
- Search
-
Searches the target resource for all objects that match the specified object class and filter.
- Sync
-
Polls the target resource for synchronization events, that is, native changes to objects on the target resource.
- Test
-
Tests the connector configuration.
Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.
This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).
You can invoke the test operation before a connector configuration has been validated.
- Update
-
Updates (modifies or replaces) objects on a target resource.
MongoDB Connector Configuration
The MongoDB Connector has the following configurable properties:
Configuration properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
Yes |
No |
Custom Sensitive Configuration script for Groovy ConfigSlurper |
||||
|
|
|
|
No |
Custom Configuration script for Groovy ConfigSlurper |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Operation Script Files
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
|
The name of the file used to perform the CREATE operation. |
||||
|
|
|
|
No |
The script used to customize some function of the connector. Read the documentation for more details. |
||||
|
|
|
|
|
The name of the file used to perform the AUTHENTICATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RUNSCRIPTONRESOURCE operation. |
||||
|
|
|
|
|
The name of the file used to perform the DELETE operation. |
||||
|
|
|
|
|
The name of the file used to perform the RESOLVE_USERNAME operation. |
||||
|
|
|
|
|
The name of the file used to perform the SEARCH operation. |
||||
|
|
|
|
|
The name of the file used to perform the UPDATE operation. |
||||
|
|
|
|
|
The name of the file used to perform the SCHEMA operation. |
||||
|
|
|
|
|
The name of the file used to perform the TEST operation. |
||||
|
|
|
|
|
The name of the file used to perform the SYNC operation. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Groovy Engine configuration
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
Directory into which to write classes. |
||||
|
|
|
|
No |
Warning Level of the compiler |
||||
|
|
|
|
No |
Gets the extensions used to find groovy files |
||||
|
|
|
|
No |
Sets the minimum of time after a script can be recompiled. |
||||
|
|
|
|
No |
Base class name for scripts (must derive from Script) |
||||
|
|
|
|
Yes |
The root folder to load the scripts from. If the value is null or empty the classpath value is used. |
||||
|
|
|
|
No |
The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted. |
||||
|
|
|
|
No |
If true, debugging code should be activated |
||||
|
|
|
|
No |
Classpath for use during compilation. |
||||
|
|
|
|
No |
Sets a list of global AST transformations which should not be loaded even if they are defined in META-INF/org.codehaus.groovy.transform.ASTTransformation files. By default, none is disabled. |
||||
|
|
|
|
No |
If true, the compiler should produce action information |
||||
|
|
|
|
No |
Encoding for source files |
||||
|
|
|
|
No |
If set to true recompilation is enabled |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Basic Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
The MongoDB client connection URI, for example "mongodb://localhost:27017". Overides other connection parameters |
||||
|
|
|
|
No |
The MongoDB server host name (localhost by default). |
||||
|
|
|
|
No |
The MongoDB server port number (27017 by default). |
||||
|
|
|
|
No |
The MongoDB username |
||||
|
|
|
Yes |
No |
The password used to connect to MongoDB |
||||
|
|
|
|
No |
The name of the database in which the MongoDB user is defined |
||||
|
|
|
|
No |
A list of additional mongodbDB servers when connecting to a MongoDB cluster (["host1:27017","host2:27017",…]") |
||||
|
|
|
|
No |
Defines the list of attributes to convert to MongoDB BSON Date type on create/update. |
||||
|
|
|
|
No |
The database to use |
||||
|
|
|
|
No |
Defines the list of attributes that should be considered as BSON Arrays. |
||||
|
|
|
|
No |
If set to true, retains null values in the target MongoDB document (false by default). |
||||
|
|
|
|
No |
If set to true, retains null values in the target MongoDB document (false by default). |
||||
|
|
|
|
No |
Defines the date format to use for MongoDB Date attributes (defaults to ISO 8601 "yyyy-MM-ddTHH:mm:ssZ"). |
||||
|
|
|
|
No |
Defines the timezone to use for MongoDB Date attributes. |
||||
|
|
|
|
No |
Defines the name to use in the target MongoDB document for the ICF NAME attribute. |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
Connection Configuration Properties
Property | Type | Default | Encrypted(1) | Required(2) |
---|---|---|---|---|
|
|
|
|
No |
Use secure socket layer to connect to MongoDB (true by default) |
||||
|
|
|
|
No |
Defines if host name should be validated when SSL is enabled |
||||
|
|
|
|
No |
The maximum idle time for a pooled connection in ms (0 means no limit) |
||||
|
|
|
|
No |
The maximum life time for a pooled connection in ms (0 means no limit) |
||||
|
|
|
|
No |
The minimum number of connections per host (must be >= 0) |
||||
|
|
|
|
No |
The maximum number of connections per host (must be > 0) |
(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.
(2) A list of operations in this column indicates that the property is required for those operations.
SAP connector
The SAP connector is an implementation of the Scripted Groovy Connector Toolkit that connects to any SAP system using the SAP JCo Java libraries. This chapter describes how to install and configure the scripted SAP connector, and how to test the sample scripts that are bundled with the connector.
The sample scripts illustrate the following scenarios:
-
Synchronization of users between an SAP HR module and Identity Cloud
-
Synchronization of users between Identity Cloud and an SAP (R/3) system
Before you start
-
Download the SAP connector from the ForgeRock BackStage download site.
-
Copy the SAP connector .jar file (
sap-connector-1.5.1.0.jar
) to theopenidm/connectors
directory, or to the/path/to/openicf/connectors
directory, if you are running the connector remotely. For example:cp ~/Downloads/sap-connector-1.5.1.0.jar /path/to/openidm/connectors
-
The SAP connector requires the SAP Java Connector (JCo) libraries, version 3.0.12 or later. ForgeRock distributes the SAP connector without these JCo libraries. Before you can use the SAP connector, you must obtain the JCo libraries that correspond to your architecture.
Copy the required SAP JCo libraries to the
/path/to/openidm/lib
directory. For example:cp sapjco3.jar /path/to/openidm/lib cp libsapjco3.so /path/to/openidm/lib
Using the SAP connector with an SAP HR system
The SAP HR sample scripts let you manage the email address and global employee UID of records in an SAP HR system.
The following sections explain how to configure Identity Cloud to use these sample scripts, how to test the connection to the SAP HR system, and how to update user records.
Setting up Identity Cloud for the SAP HR samples
-
Create a connector configuration file for the SAP connector and place it in your project’s
conf/
directory.You can use this sample provisioner.openicf-saphr.json as a guide.
Edit that file with the connection details for your SAP HR system. Specifically, set at least the following properties:
destination
-
An alias to the SAP system to which you are connecting, for example,
SAP1
. If you are connecting to more than one SAP system, thedestination
property for each system must be unique.The sample connector configuration assumes a connection to a single SAP system, so the value for this property in the sample configuration is
OPENIDM
. asHost
-
The FQDN of your SAP Application Server, for example
sap.example.com
. user
-
Your SAP user account.
password
-
The password of this SAP user account.
client
-
The SAP Client number that will be used to connect to the SAP system.
systemNumber
-
The SAP system number.
directConnection
-
A boolean (true/false). If
true
, the connection goes directly to an SAP ABAP Application server or SAP router. Iffalse
, the connection goes to a group of SAP instances, through an SAP message server. sapRouter
-
The IP address and port of the SAP router, if applicable. The syntax is
/H/hostport]
, for example/H/203.0.113.0/S/3299
. poolCapacity
-
The maximum number of idle connections kept open by the destination. If there is no connection pooling, set this to
0
. The default value is1
.For optimum performance, set this value to an integer between
5
and10
.
-
The connector bundles a number of SAP-certified sample Groovy scripts:
TestSAP.groovy
SearchSAPHR.groovy
UpdateSAPHR.groovy
SchemaSAPHR.groovy
EmplComm.groovy
If necessary, you can customize these scripts to suit your deployment by extracting them from the connector JAR and updating the connector configuration to point to the new file path.
The sample connector configuration assumes the following locations for the scripts (relative to the value of the
scriptRoots
property):"testScriptFileName" : "scripts/sap/TestSAP.groovy", "searchScriptFileName" : "scripts/sap/hr/SearchSAPHR.groovy", "updateScriptFileName" : "scripts/sap/hr/UpdateSAPHR.groovy", "schemaScriptFileName" : "scripts/sap/hr/SchemaSAPHR.groovy",
The
EmplComm.groovy
must be placed in the same location as the Search, Update, and Schema scripts.The Groovy scripts belong to a specific package. The parent directory where the scripts are located must be the same as the package name. So the TestSAP.groovy
script must be under ascripts/sap
directory (because it belongs to thescripts/sap
package) and the remaining HR scripts must be under ascripts/sap/hr
directory (because they belong to thehr
package).
Testing the connection to the SAP HR system
-
Start Identity Cloud with the configuration for your SAP connector project.
This procedure assumes that the configuration is in the default
path/to/openidm
directory. If your SAP project is in a different directory, use the-p
option with the startup command to point to that directory:path/to/openidm/startup.sh
-
Test that the connector has been configured correctly and that the SAP HR system can be reached:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/?_action=test" { "name" : "saphr", "enabled" : true, "config" : "config/provisioner.openicf/saphr2", "objectTypes" : [ "__ALL__", "employee" ], "connectorRef" : { "connectorName" : "org.forgerock.openicf.connectors.sap.SapConnector", "bundleName" : "org.forgerock.openicf.connectors.sap-connector", "bundleVersion" : "[1.5.0.0,1.6.0.0)" }, "displayName" : "Sap Connector", "ok" : true }
-
Retrieve a list of the existing users (with their employee number) in the SAP HR system:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/employee?_queryId=query-all-ids" { "result" : [ { "_id" : "00000010", "__NAME__" : "00000010" }, { "_id" : "00000069", "__NAME__" : "00000069" }, { "_id" : "00000070", "__NAME__" : "00000070" }, ...
-
Retrieve the complete record of an employee in the SAP HR system by including the employee’s ID in the URL.
The following command retrieves the record for employee Maria Gonzales:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/employee/55099307" { "_id" : "55099307", "PERSONAL_DATA" : { "PERNO" : "55099307", "INFOTYPE" : "0002", "TO_DATE" : "Fri Dec 31 00:00:00 CET 9999", "FROM_DATE" : "Tue Mar 30 00:00:00 CET 1954", "SEQNO" : "000", "CH_ON" : "Thu Mar 27 00:00:00 CET 2003", "CHANGED_BY" : "MAYROCK", "LAST_NAME" : "Gonzales", "FIRSTNAME" : "Maria", "NAME_FORM" : "00", "FORMOFADR" : "2", "GENDER" : "2", "BIRTHDATE" : "Tue Mar 30 00:00:00 CET 1954", "LANGU" : "D", "NO_O_CHLDR" : "0", "BIRTHYEAR" : "1954", "BIRTHMONTH" : "03", "BIRTHDAY" : "30", "LASTNAME_M" : "GONZALES", "FSTNAME_M" : "MARIA" }, ... }
Using the SAP connector to manage employee information (SAP HR)
The following sample commands show how the SAP connector is used to manage the email account of user Maria Gonzales, retrieved in the previous step. Management of the global UID (SYS-UNAME
) works in the same way.
-
Check if Maria Gonzales already has an email account on the SAP HR system by filtering a query on her user account for the
EMAIL
field:curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/employee/55099307?_fields=EMAIL" { "_id" : "55099307", }
No email account is found for Maria Gonzales.
-
Add an email account by sending a PUT request. The JSON payload should include the email address as the value of the
ID
property:curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "EMAIL": { "ID": "maria.gonzales@example.com" } }' \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/employee/55099307" { "_id" : "55099307", "EMAIL" : [ { "EMPLOYEENO" : "55099307", "SUBTYPE" : "0010", "VALIDEND" : "Fri Dec 31 00:00:00 CET 9999", "VALIDBEGIN" : "Fri March 18 00:00:00 CET 2016", "RECORDNR" : "000", "COMMTYPE" : "0010", "NAMEOFCOMMTYPE" : "E-mail", "ID" : "Maria.Gonzales@example.com" } ], ...
By default, the connector sets the
VALIDBEGIN
date to the current date, and theVALIDEND
date to the SAP "END" date (12/31/9999). You can specify different temporal constraints by including these properties in the JSON payload, with the formatYYYYMMDD
. For example:{ "EMAIL": { "ID": "maria.gonzales@example.com" "VALIDBEGIN": "20160401", "VALIDEND": "20161231" } }
-
To change the value of an existing email account, provide a new value for the
ID
.The JSON payload of the change request must also include the
RECORDNR
attribute, as well as theVALIDBEGIN
andVALIDEND
dates, in SAP format (YYYYMMDD
).The following example changes Maria Gonzales' email address to
maria.gonzales-admin@example.com
:curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "EMAIL": { "ID": "maria.gonzales-admin@example.com", "RECORDNR" : "000", "VALIDEND" : "99991231", "VALIDBEGIN" : "20000101" } }' \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/employee/55099307"
-
To change the temporal constraint (
VALIDEND
date) of the record, include the existingVALIDEND
data in the JSON payload, and specify the new end date as a value of theDELIMIT_DATE
attribute.The following example changes the end date of Maria Gonzale’s new mail address to December 31st, 2016:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "EMAIL": { "ID": "maria.gonzales-admin@example.com", "RECORDNR" : "000", "VALIDEND" : "99991231", "VALIDBEGIN" : "20000101", "DELIMIT_DATE": "20161231" } }' \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/employee/55099307"
-
To delete the email address of the record, send a PUT request with the current
RECORDNR
,VALIDBEGIN
, andVALIDEND
attributes, but without theID
.The following request removes the email address from Maria Gonzales' record:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PUT \ --data '{ "EMAIL": { "RECORDNR" : "000", "VALIDEND" : "99991231", "VALIDBEGIN" : "20000101" } }' \ "https://tenant-name.forgeblocks.com/openidm/system/saphr/employee/55099307"
Using the SAP Connector to manage SAP basis system (R/3) users
The SAP Connector enables you to perform the following operations on SAP system user accounts:
-
List all users
-
List all activity groups (roles)
-
Manage user profiles
-
List all user companies
-
Obtain a user’s details
-
Create a user
-
Update a user
-
Assign roles to a user
-
Lock a user account
-
Unlock a user account
-
Delete a user account
Currently, the SAP connector cannot detect changes on the SAP system in real time. You must run a reconciliation operation to detect changes on the SAP system.
Setting up Identity Cloud for the SAP R/3 samples
-
Create a connector configuration file for the SAP connector and place it in your project’s
conf/
directory.You can use this sample provisioner.openicf-sapr3.json as a guide.
Edit that file with the connection details for your SAP R/3 system. Specifically, set at least the following properties:
destination
-
An alias to the SAP system to which you are connecting, for example,
SAP1
. If you are connecting to more than one SAP system, thedestination
property for each system must be unique.The sample connector configuration assumes a connection to a single SAP system,
MYSAP
. asHost
-
The FQDN of your SAP Application Server, for example
sap.example.com
. user
-
Your SAP user account.
password
-
The password of this SAP user account.
client
-
The SAP Client number that will be used to connect to the SAP system.
systemNumber
-
The SAP system number.
directConnection
-
A boolean (true/false). If
true
, the connection goes directly to an SAP ABAP Application server or SAP router. Iffalse
, the connection goes to a group of SAP instances, through an SAP message server. sapRouter
-
The IP address and port of the SAP router, if applicable. The syntax is
/H/hostport]
, for example/H/203.0.113.0/S/3299
. poolCapacity
-
The maximum number of idle connections kept open by the destination. If there is no connection pooling, set this to
0
. The default value is1
.For optimum performance, set this value to an integer between
5
and10
.
-
The connector bundles a number of SAP-certified sample Groovy scripts:
TestSAP.groovy
SearchSAPR3.groovy
CreateSAPR3.groovy
UpdateSAPR3.groovy
DeleteSAPR3.groovy
SchemaSAPR3.groovy
If necessary, you can customize these scripts to suit your deployment by extracting them from the connector JAR and updating the connector configuration to point to the new file path.
The sample connector configuration assumes the following locations for the scripts (relative to the value of the
scriptRoots
property):"testScriptFileName" : "scripts/sap/TestSAP.groovy", "searchScriptFileName" : "scripts/sap/r3/SearchSAPR3.groovy", "createScriptFileName" : "scripts/sap/r3/CreateSAPR3.groovy", "updateScriptFileName" : "scripts/sap/r3/UpdateSAPR3.groovy", "deleteScriptFileName" : "scripts/sap/r3/DeleteSAPR3.groovy", "schemaScriptFileName" : "scripts/sap/r3/SchemaSAPR3.groovy",
The Groovy scripts belong to a specific package. The parent directory where the scripts are located must be the same as the package name. So the TestSAP.groovy
script must be under ascripts/sap
directory (because it belongs to thescripts/sap
package) and the R/3 scripts must be under ascripts/sap/r3
directory (because they belong to ther3
package).
Testing the connection to the SAP R/3 System
-
Start Identity Cloud with the configuration for your SAP R/3 project.
This procedure assumes that the configuration is in the default
path/to/openidm
directory. If your SAP project is in a different directory, use the-p
option with the startup command to point to that directory:/path/to/openidm/startup.sh
-
Test that the connector has been configured correctly and that the SAP R/3 system can be reached:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ "https://tenant-name.forgeblocks.com/openidm/system/mysap/?_action=test" { "name": "mysap", "enabled": true, "config": "config/provisioner.openicf/mysap", "objectTypes": [ "__ALL__", "user", "activity_group", "company", "profile" ], "connectorRef": { "connectorName": "org.forgerock.openicf.connectors.sap.SapConnector", "bundleName": "org.forgerock.openicf.connectors.sap-connector", "bundleVersion": "[1.5.0.0,1.6.0.0)" }, "displayName": "Sap Connector", "ok": true }
Using the SAP connector to manage SAP R/3 Users
This section provides sample commands for managing users in an SAP system.
Listing the users in the SAP system
The following command returns a list of the existing users in the SAP system, with their IDs:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/mysap/user?_queryId=query-all-ids" { "result": [ { "_id": "BJENSEN", "__NAME__": "BJENSEN" }, { "_id": "DDIC", "__NAME__": "DDIC" }, ... { "_id": "USER4", "__NAME__": "USER4" }, { "_id": "USER6", "__NAME__": "USER6" }, { "_id": "USER7", "__NAME__": "USER7" } ], "resultCount": 9, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 }
Obtaining the details of an SAP user
The following command uses the SAP connector to obtain a user’s details from a target SAP system:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https://tenant-name.forgeblocks.com/openidm/system/mysap/user/BJENSEN" { "__NAME__": "BJENSEN", "__ENABLE__": true, "__ENABLE_DATE__": "2015-09-01", "__DISABLE_DATE__": "2016-09-01", "__LOCK_OUT__": false, "ADDTEL": [ { "COUNTRY": "DE", "TELEPHONE": "19851444", ... }, ... ], "PROFILES": [ { "BAPIPROF": "T_ALM_CONF", ... } ], "ISLOCKED": { "WRNG_LOGON": "U", ... }, "ACTIVITYGROUPS": [ { "AGR_NAME": "MW_ADMIN", "FROM_DAT": "2015-07-15", "TO_DAT": "9999-12-31", "AGR_TEXT": "Middleware Administrator" }, ... ], "DEFAULTS": { ... }, "COMPANY": { "COMPANY": "SAP AG" }, "ADDRESS": { ... }, "UCLASS": { ... }, "LASTMODIFIED": { "MODDATE": "2015-07-15", "MODTIME": "14:22:57" }, "LOGONDATA": { "GLTGV": "2015-09-01", "GLTGB": "2016-09-01", ... }, "_id": "BJENSEN" }
In addition to the standard user attributes, the GET request returns the following ICF operational attributes:
-
__ENABLE__
- indicates whether the account is enabled, based on the value of theLOGONDATA
attribute -
__ENABLE_DATE__
- set to the value ofLOGONDATA/GLTGV
(date from which the user account is valid) -
__DISABLE_DATE__
- set to the value ofLOGONDATA/GLTGB
(date to which the user account is valid) -
__LOCK_OUT__
- indicates whether the account is locked
Creating SAP user accounts
To create a user, you must supply at least a username and password. If you do not provide a lastname, the connector uses the value of the username.
The following command creates a new SAP user, SCARTER
:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "__NAME__" : "SCARTER", "__PASSWORD__": "Passw0rd" }' \ "https://tenant-name.forgeblocks.com/openidm/system/mysap/user/?_action=create" { "_id": "SCARTER", "COMPANY": { "COMPANY": "SAP AG" }, "__LOCK_OUT__": false, "ADDRESS": { ... }, "__NAME__": "SCARTER", "LASTMODIFIED": { "MODDATE": "2016-04-20", "MODTIME": "04:14:29" }, "UCLASS": { "COUNTRY_SURCHARGE": "0", "SUBSTITUTE_FROM": "0000-00-00", "SUBSTITUTE_UNTIL": "0000-00-00" }, "__ENABLE__": true, "DEFAULTS": { "SPDB": "H", "SPDA": "K", "DATFM": "1", "TIMEFM": "0" }, "LOGONDATA": { ... }, "ISLOCKED": { "WRNG_LOGON": "U", "LOCAL_LOCK": "U", "GLOB_LOCK": "U", "NO_USER_PW": "U" } }
The SAP account that is created is valid and enabled, but the password is expired by default. To log in to the SAP system, the newly created user must first provide a new password.
To create a user with a valid (non-expired) password, include the __PASSWORD_EXPIRED__
attribute in the JSON payload, with a value of false
. For example:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "__NAME__" : "SCARTER", "__PASSWORD__": "Passw0rd", "__PASSWORD_EXPIRED__": false }' \ "https://tenant-name.forgeblocks.com/openidm/system/mysap/user/?_action=create"
To create an account that is locked by default, include the __LOCK_OUT__
attribute in the JSON payload, with a value of true
. For example:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "__NAME__" : "SCARTER", "__PASSWORD__": "Passw0rd", "__LOCK_OUT__": true }' \ "https://tenant-name.forgeblocks.com/openidm/system/mysap/user/?_ac