Identity Cloud

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.

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 Connector

The Adobe Marketing Cloud connector lets you manage profiles in an Adobe Campaign data store.

Marketo Connector

The Marketo connector lets you synchronize between Identity Cloud user identities and a Marketo Lead Database.

MS Graph API Connector

The 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 Connector

The Salesforce connector enables provisioning, reconciliation, and synchronization between Salesforce and the Identity Cloud repository.

ServiceNow Connector

The ServiceNow connector lets you manage objects in the ServiceNow platform, integrating with ServiceNow’s REST API.

SuccessFactors Connector

The 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.

  1. Log in to https://console.adobe.io/.

  2. Click Integrations > New Integration.

  3. Click Access an API > Continue.

  4. Under the Experience Cloud item, click Adobe Campaign > Continue, then click New integration > Continue.

  5. Enter a name and short description for the new integration. For example, IDM-managed.

  6. Drag and drop your public certificate file into the Public keys certificates area. Alternatively, click Select a File, and browse to the file location.

  7. Select a license, then click Create Integration.

  8. 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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select Adobe Marketing Cloud Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. 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)

endpoint

String

mc.adobe.io

Yes

The Adobe IO endpoint for Marketing Cloud. mc.adobe.io by default - you should not have to change this.

imsHost

String

ims-na1.adobelogin.com

Yes

Adobe Identity Management System (IMS) host. ims-na1.adobelogin.com by default - you should not have to change this.

tenant

String

null

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)

apiKey

GuardedString

null

Yes

Yes

The API key (client ID) assigned to your API client account

technicalAccountID

String

null

Yes

Your Technical account ID, required to generate the JWT

organizationID

String

null

Yes

Your organizations unique ID, for example 12345@AdobeOrg

clientSecret

GuardedString

null

Yes

Yes

The client secret assigned to your API client account

privateKey

GuardedString

null

Yes

Yes

The private key used to sign the JWT token, corresponds to the public key certificate attached to the integration

accessToken

GuardedString

null

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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select Marketo Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. 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 is https://some-number.mktorest.com/rest, the value of the instance property must be some-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)

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive Configuration script for Groovy ConfigSlurper

customConfiguration

String

null

No

Custom Configuration script for Groovy ConfigSlurper

instance

String

null

Yes

The Marketo-assigned FQDN for your instance

clientId

String

null

Yes

Your OAuth2 client ID

clientSecret

GuardedString

null

Yes

Yes

Your OAuth2 client secret

leadFields

String

null

No

Comma-delimited list of lead fields to fetch; Leave empty for default set

partitionName

String

null

No

Name of the partition in which to create and update leads; May be left empty

listName

String

null

Yes

Name of the Marketo static list the connector will use to manage leads

accessToken

String

null

Yes

The access token for the application

tokenExpiration

Long

null

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)

createScriptFileName

String

CreateMarketo.groovy

The name of the file used to perform the CREATE operation.

customizerScriptFileName

String

null

No

The script used to customize some function of the connector. Read the documentation for more details.

authenticateScriptFileName

String

null

The name of the file used to perform the AUTHENTICATE operation.

scriptOnResourceScriptFileName

String

null

The name of the file used to perform the RUNSCRIPTONRESOURCE operation.

deleteScriptFileName

String

DeleteMarketo.groovy

The name of the file used to perform the DELETE operation.

resolveUsernameScriptFileName

String

null

The name of the file used to perform the RESOLVE_USERNAME operation.

searchScriptFileName

String

SearchMarketo.groovy

The name of the file used to perform the SEARCH operation.

updateScriptFileName

String

UpdateMarketo.groovy

The name of the file used to perform the UPDATE operation.

schemaScriptFileName

String

SchemaMarketo.groovy

The name of the file used to perform the SCHEMA operation.

testScriptFileName

String

TestMarketo.groovy

The name of the file used to perform the TEST operation.

syncScriptFileName

String

null

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)

targetDirectory

File

null

No

Directory into which to write classes.

warningLevel

int

1

No

Warning Level of the compiler

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files

minimumRecompilationInterval

int

100

No

Sets the minimum of time after a script can be recompiled.

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script)

scriptRoots

String[]

null

Yes

The root folder to load the scripts from. If the value is null or empty the classpath value is used.

tolerance

int

10

No

The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

debug

boolean

false

No

If true, debugging code should be activated

classpath

String[]

[]

No

Classpath for use during compilation.

disabledGlobalASTTransformations

String[]

null

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.

verbose

boolean

false

No

If true, the compiler should produce action information

sourceEncoding

String

UTF-8

No

Encoding for source files

recompileGroovySource

boolean

false

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:

  1. Log in to the Microsoft Azure portal as an administrative user.

  2. Under Azure services, select App registrations.

  3. On the Register an application page, enter a name for the application; for example, FR-Connector.

  4. 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>./.

  5. 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:

    shared:ms-graph-api-app

  6. Generate a client secret:

    1. Select Certificates & secrets > New client secret.

    2. Enter a description, select an expiration date, and click Add.

    3. Copy the client secret Value:

      shared:ms-graph-api-secret
    You will not be able to retrieve the client secret in cleartext after you exit this screen.
  7. Set the API permissions:

    1. Select API permissions, click Microsoft Graph, and then click Application permissions.

      shared:ms-graph-api-app-permissions
    2. From the User item, select the following permissions:

      • User.Export.All

      • User.ManageIdentities.All

      • User.Read.All

      • User.ReadWrite.All

    3. From the Group item, select the following permissions:

      • Group.Create

      • Group.Read.All

      • Group.ReadWrite.All

    4. From the Directory item, select the following permissions:

      • Directory.Read.All

      • Directory.ReadWrite.All

    5. Click Add permissions.

  8. Grant admin consent for the API permissions:

    On the Configured permissions page, Grant admin consent for org-name, then click Yes.

    shared:ms-graph-api-consent

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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select MSGraphAPI Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. 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 add or PATCH remove operations. PATCH replace is supported because it is the equivalent of a PUT operation.

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)

tenant

String

null

Yes

The Azure AD tenant name or id

clientId

String

null

Yes

The clientID used by the connector during the OAuth flow

clientSecret

GuardedString

null

Yes

No

The client secret used by the connector during the OAuth flow

httpProxyHost

String

null

No

The Http proxy host

httpProxyPort

Integer

null

No

The Http proxy port

httpProxyUsername

String

null

No

The Http proxy user name

httpProxyPassword

GuardedString

null

Yes

No

The Http proxy user password

performHardDelete

boolean

true

No

If set to true, the Azure object will be deleted permanently on delete operation.

readRateLimit

String

null

No

Define throttling for read operations either per seconds ("30/sec") or per minute ("100/min").

writeRateLimit

String

null

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

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select Salesforce Connector - 1.5.20.5.

  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.
  6. Click Save.

    The connector attempts to access your Salesforce organization.

  7. Enter your Salesforce login credentials.

  8. 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 to null.

    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 is 200. 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)

clientId

String

null

Yes

The client identifier

clientSecret

GuardedString

null

Yes

The secure client secret for OAUTH

refreshToken

GuardedString

null

Yes

The refresh token for the application

loginUrl

String

Yes

The endpoint from which a new access token should be queried (https://login.salesforce.com/services/oauth2/token)

instanceUrl

String

null

Yes

The URL of the Salesforce instance (such as https://example-com.cs1.my.salesforce.com)

version

double

48.0

No

The Salesforce API version

connectTimeout

long

120000

No

The maximum connection timeout

proxyHost

String

null

No

The hostname of an http proxy, used between the connector and the Salesforce service provider

proxyPort

Integer

3128

No

The proxy port number, if an HTTP proxy is used between the connector and the Salesforce service provider

maximumConnections

int

10

No

The maximum size of the HTTP connection pool

supportedObjectTypes

String[]

[]

No

Defines a list of Salesforce objects that will be used to dynamically build the provisioner schema

proxyUri

String

null

No

The URI of an HTTP proxy that contains the scheme, host, and port number for that proxy

proxyUsername

String

null

No

The proxy username to use with a proxy that requires authentication

proxyPassword

GuardedString

null

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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select ServiceNow Connector - 1.5.20.5.

  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 and rest_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.

  6. 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 __ALL__ object type, so you must specify the object type (for example, User) in your liveSync operation.

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)

instance

String

null

Yes

URL of the ServiceNow instance, for example: dev00000.service-now.com

username

String

null

Yes

An API user in ServiceNow that can consume the REST API

password

GuardedString

null

Yes

Yes

Password for the user

clientID

String

null

Yes

Client ID of the OAuth application in ServiceNow

clientSecret

GuardedString

null

Yes

Yes

Client Secret for the preceding Client ID

pageSize

int

100

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)

host

String

null

Yes

Hostname of the target

clientId

String

null

Yes

The client identifier

userId

String

null

Yes

User Id for authentication

privateKey

GuardedString

null

Yes

The private key to be used for signing JWT

companyId

String

null

Yes

Company ID as present in target application

pageSize

int

0

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:

Remote Connector Server (RCS) bundled connectors

ForgeRock provides a number of connectors that are bundled with RCS:

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.

Database Table Connector

The Database Table connector enables provisioning to a single table in a JDBC database.

Groovy Connector

The 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 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). This connector lets you manage Kerberos user principals from Identity Cloud.

LDAP Connector

The 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 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, Facebook, or SalesForce.

Scripted REST Connector

The 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 Connector

The 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 Connector

The 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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select CSV File Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. 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 properties in the connector configuration accordingly.

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)

headerPassword

String

password

No

The CSV header that maps to the password for each row. Use this property when password-based authentication is required.

spaceReplacementString

String

_

No

The character(s) used to replace spaces within column names.

csvFile

File

null

Yes

The full path to the CSV file that is the data source for this connector.

newlineString

String

\n

No

The character string in the CSV file that is used to terminate each line.

headerUid

String

uid

No

The CSV header that maps to the uid (or name) for each row.

quoteCharacter

String

"

No

The character in the CSV file that is used to encapsulate strings.

fieldDelimiter

String

,

No

The character in the CSV file that is used to separate field values.

syncFileRetentionCount

int

3

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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select Database Table Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. 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, or jdbc: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, or com.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 or UID to an attribute in Identity Cloud, change the keyColumn 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 was UNIQUE_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. If inclusiveSync is set to true, the connector synchronizes all entries whose change timestamp is greater than or equal to the syncToken. Be aware that if you set this property to true, 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)

connectionProperties

String

null

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.

propagateInterruptState

boolean

false

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.

useDisposableConnectionFacade

boolean

true

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.

defaultCatalog

String

null

No

The default catalog of connections created by this pool.

validationInterval

long

3000

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).

ignoreExceptionOnPreLoad

boolean

false

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.

jmxEnabled

boolean

true

No

Register the pool with JMX or not. The default value is true.

commitOnReturn

boolean

false

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.

logAbandoned

boolean

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.

maxIdle

int

100

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.)

testWhileIdle

boolean

false

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)

removeAbandoned

boolean

false

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.

abandonWhenPercentageFull

int

0

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.

minIdle

int

10

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.)

defaultReadOnly

Boolean

null

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)

maxWait

int

30000

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)

logValidationErrors

boolean

false

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.

driverClassName

String

null

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

name

String

Tomcat Connection Pool[1-1243567669]

No

Returns the name of the connection pool. By default a JVM unique random name is assigned.

useStatementFacade

boolean

true

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.

initSQL

String

null

No

A custom query to be run when a connection is first created. The default value is null.

validationQueryTimeout

int

-1

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.

validationQuery

String

null

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)

rollbackOnReturn

boolean

false

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.

alternateUsernameAllowed

boolean

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.

validatorClassName

String

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.

suspectTimeout

int

0

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.

useEquals

boolean

true

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.

removeAbandonedTimeout

int

60

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.

defaultAutoCommit

Boolean

null

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.)

testOnConnect

boolean

false

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.

jdbcInterceptors

String

null

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.

initialSize

int

10

No

The initial number of connections that are created when the pool is started. Default value is 10

defaultTransactionIsolation

int

-1

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.

numTestsPerEvictionRun

int

0

No

Property not used in tomcat-jdbc-pool.

url

String

null

No

The URL used to connect to the database.

testOnBorrow

boolean

false

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

fairQueue

boolean

true

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.

accessToUnderlyingConnectionAllowed

boolean

true

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

maxAge

long

0

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.

minEvictableIdleTimeMillis

int

60000

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).

timeBetweenEvictionRunsMillis

int

5000

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).

testOnReturn

boolean

false

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.

useLock

boolean

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.

maxActive

int

100

No

The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100

username

String

null

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.

table

String

TABLE_NAME

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)

password

String

null

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.

quoting

String

NONE

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.

keyColumn

String

KEY_COLUMN

Yes

This mandatory column value will be used as the unique identifier for rows in the table.

passwordColumn

String

null

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.

disablePaging

boolean

false

Yes

If true, optional paging in a query will be ignored by the connector. Defaults to false.

enableEmptyString

boolean

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.

rethrowAllSQLExceptions

boolean

true

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.

nativeTimestamps

boolean

false

No

Select to retrieve Timestamp data type of the columns in java.sql.Timestamp format from the database table.

allNative

boolean

false

No

Select to retrieve all data types of columns in native format from the database table.

changeLogColumn

String

null

The change log column stores the latest change time. Providing this value the Sync capabilities are activated.

suppressPassword

boolean

true

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.

inclusiveSync

boolean

false

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.

returnGeneratedKeys

boolean

true

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)

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive Configuration script for Groovy ConfigSlurper

customConfiguration

String

null

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)

createScriptFileName

String

null

The name of the file used to perform the CREATE operation.

customizerScriptFileName

String

null

No

The script used to customize some function of the connector. Read the documentation for more details.

authenticateScriptFileName

String

null

The name of the file used to perform the AUTHENTICATE operation.

scriptOnResourceScriptFileName

String

null

The name of the file used to perform the RUNSCRIPTONRESOURCE operation.

deleteScriptFileName

String

null

The name of the file used to perform the DELETE operation.

resolveUsernameScriptFileName

String

null

The name of the file used to perform the RESOLVE_USERNAME operation.

searchScriptFileName

String

null

The name of the file used to perform the SEARCH operation.

updateScriptFileName

String

null

The name of the file used to perform the UPDATE operation.

schemaScriptFileName

String

null

The name of the file used to perform the SCHEMA operation.

testScriptFileName

String

null

The name of the file used to perform the TEST operation.

syncScriptFileName

String

null

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)

targetDirectory

File

null

No

Directory into which to write classes.

warningLevel

int

1

No

Warning Level of the compiler

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files

minimumRecompilationInterval

int

100

No

Sets the minimum of time after a script can be recompiled.

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script)

scriptRoots

String[]

null

Yes

The root folder to load the scripts from. If the value is null or empty the classpath value is used.

tolerance

int

10

No

The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

debug

boolean

false

No

If true, debugging code should be activated

classpath

String[]

[]

No

Classpath for use during compilation.

disabledGlobalASTTransformations

String[]

null

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.

verbose

boolean

false

No

If true, the compiler should produce action information

sourceEncoding

String

UTF-8

No

Encoding for source files

recompileGroovySource

boolean

false

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)

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive Configuration script for Groovy ConfigSlurper

customConfiguration

String

null

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)

createScriptFileName

String

null

The name of the file used to perform the CREATE operation.

customizerScriptFileName

String

null

No

The script used to customize some function of the connector. Read the documentation for more details.

authenticateScriptFileName

String

null

The name of the file used to perform the AUTHENTICATE operation.

scriptOnResourceScriptFileName

String

null

The name of the file used to perform the RUNSCRIPTONRESOURCE operation.

deleteScriptFileName

String

null

The name of the file used to perform the DELETE operation.

resolveUsernameScriptFileName

String

null

The name of the file used to perform the RESOLVE_USERNAME operation.

searchScriptFileName

String

null

The name of the file used to perform the SEARCH operation.

updateScriptFileName

String

null

The name of the file used to perform the UPDATE operation.

schemaScriptFileName

String

null

The name of the file used to perform the SCHEMA operation.

testScriptFileName

String

null

The name of the file used to perform the TEST operation.

syncScriptFileName

String

null

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)

targetDirectory

File

null

No

Directory into which to write classes.

warningLevel

int

1

No

Warning Level of the compiler

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files

minimumRecompilationInterval

int

100

No

Sets the minimum of time after a script can be recompiled.

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script)

scriptRoots

String[]

null

Yes

The root folder to load the scripts from. If the value is null or empty the classpath value is used.

tolerance

int

10

No

The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

debug

boolean

false

No

If true, debugging code should be activated

classpath

String[]

[]

No

Classpath for use during compilation.

disabledGlobalASTTransformations

String[]

null

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.

verbose

boolean

false

No

If true, the compiler should produce action information

sourceEncoding

String

UTF-8

No

Encoding for source files

recompileGroovySource

boolean

false

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 to false

  • 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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select Kerberos Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. Click Save.

  7. 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, the sudo command in the Test script will never get the 'pass::' prompt. Instead of using the root user, create a regular user and add that user to the group that has sudo privileges. Alternatively, modify the Test script so that it does not use sudo.

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 example root@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 and PS2 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 to false, every character that is sent to the server is sent back to the client in the expect() 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 the locale property.

Default: false

locale

Sets the locale for LC_ALL, LANG, and LANGUAGE environment variables, if setLocale is set to true.

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 or PUBKEY. 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)

customSensitiveConfiguration

GuardedString

null

Yes

No

Description is not available

createScriptFileName

String

null

Description is not available

targetDirectory

File

null

No

Description is not available

customizerScriptFileName

String

null

No

Description is not available

warningLevel

int

1

No

Description is not available

authenticateScriptFileName

String

null

Description is not available

scriptExtensions

String[]

['groovy']

No

Description is not available

scriptOnResourceScriptFileName

String

null

Description is not available

minimumRecompilationInterval

int

100

No

Description is not available

deleteScriptFileName

String

null

Description is not available

scriptBaseClass

String

null

No

Description is not available

scriptRoots

String[]

null

Yes

Description is not available

customConfiguration

String

null

No

Description is not available

resolveUsernameScriptFileName

String

null

Description is not available

searchScriptFileName

String

null

Description is not available

tolerance

int

10

No

Description is not available

updateScriptFileName

String

null

Description is not available

debug

boolean

false

No

Description is not available

classpath

String[]

[]

No

Description is not available

disabledGlobalASTTransformations

String[]

null

No

Description is not available

schemaScriptFileName

String

null

Description is not available

verbose

boolean

false

No

Description is not available

testScriptFileName

String

null

Description is not available

sourceEncoding

String

UTF-8

No

Description is not available

syncScriptFileName

String

null

Description is not available

recompileGroovySource

boolean

false

No

Description is not available

host

String

null

Yes

Description is not available

port

int

22

Yes

Description is not available

user

String

null

Yes

Description is not available

password

GuardedString

null

Yes

No

Description is not available

passphrase

GuardedString

null

Yes

No

Description is not available

privateKey

String[]

[]

Yes

No

Description is not available

authenticationType

String

PASSWORD

Yes

Description is not available

prompt

String

`root@localhost:# `

Yes

Description is not available

sudoCommand

String

/usr/bin/sudo

Yes

Description is not available

echoOff

boolean

true

Yes

Description is not available

terminalType

String

vt102

Yes

Description is not available

locale

String

en_US.utf8

Yes

Description is not available

setLocale

boolean

false

Yes

Description is not available

connectionTimeout

int

5000

Yes

Description is not available

expectTimeout

long

5000

Yes

Description is not available

throwOperationTimeoutException

boolean

true

Yes

Description is not available

promptReadyTimeout

long

20

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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select LDAP Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. 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 (typically 389 or 1389 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 class organizationalPerson AND the object class inetOrgPerson 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 and port 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 to true 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 maps inetOrgPerson to the OpenICF __ACCOUNT__ property, and groupOfUniqueNames 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 the changeLogEntry object class, and Identity Cloud expects no entries with other object types in the change log. The default setting is true.

respectResourcePasswordPolicyChangeAfterReset

If true, bind with the Password Expired and Password Policy controls, and throw PasswordExpiredException 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 the entryUUID. For a DS resource, you must use the entryUUID as the uidAttribute, otherwise you might encounter problems with synchronizing delete operations.

useBlocks

If useBlocks is false, no pagination is used. If useBlocks is true, the connector uses block-based LDAP controls, either the simple paged results control, or the virtual list view control, depending on the setting of the usePagedResultControl property.

usePagedResultControl

Taken into account only if useBlocks is true. If usePagedResultControl is false, the connector uses the virtual list view (VLV) control, if it is available. If usePagedResultControl is true, 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:

  1. For a connection over SSL, set the ssl property to true and set the port to a secure port, for example, 636.

    To initiate a connection using startTLS, set "startTLS":true, and "ssl":false. Set the port to an insecure LDAP port, for example, 389.

  2. 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
  3. 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 to null, 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 are JKS, JCEKS and PKCS12.

      • alternateKeyStorePassword - specifies password for the alternate keystore.

  4. 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 and subjectAltName with a simple hostname pattern defined in the hostNameVerification property.

    To enable hostname verification, set "hostNameVerification" : true and set the hostNameVerification 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. The hostNameVerification 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 of modifiersNamesToFilterOut. 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 the userAccountControl 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", where date 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__ to FALSE, the LDAP connector sets the Active Directory lockoutTime to 0 to unlock the account.

If Identity Cloud sets __LOCK_OUT__ to TRUE, 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 to 0. The LDAP connector sets pwdLastSet to 0, if Identity Cloud sets __PASSWORD_EXPIRED__ to TRUE.

To remove password expiration, set pwdLastSet to 0 and then to -1. This sets the value of pwdLastSet to the current time. The LDAP connector sets pwdLastSet to -1 if Identity Cloud sets __PASSWORD_EXPIRED__ to FALSE.

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 an openidm.patch call in a postCreate 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": []
}
  • Previous versions of the LDAP connector appended <GUID= to the GUID for Active Directory objects. This behavior ensured compatibility with the legacy .NET connector.

    The LDAP connector no longer appends <GUID= to the object GUID. The new GUID format is compatible with objects created using the AD Powershell connector; for example, e1418d64-096c-4cb0-b903-ebb66562d99d. In existing deployments, this might mean that your links are incompatible with the new GUID format. To update links to the new format, run a reconciliation operation. To retain the legacy behavior, set "useOldADGUIDFormat" : true in your provisioner file.

  • You cannot sort by _id when you return results from an Active Directory (or Active Directory LDS) server. The _id attribute used by default is the objectGUID, which is a binary attribute, and cannot be used for sorting.

  • When you page and sort query results (using the sortKeys parameter), the pagedResultsCookie applies only to the first connection that makes the sorted, paginated query. Active Directory (and AD LDS) build a cached index for sorted searches, which is attached to the original connection.

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 USN value for liveSync but must connect to the GC in this case, and ensure that you never failover to a different GC or to a DC. Using the USN for liveSync instead of the timestamp mechanism is generally preferred, because of the issue with detecting delete operations.

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 to uid=user123.

This part of the filter is processed first.

User Filter

You can define a user filter with the properties accountSearchFilter and groupSearchFilter 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 and groupSearchFilter set to null 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 properties accountObjectClasses and groupObjectClasses in the connector configuration. For example, the following configuration indicates that the accountObjectClasses include the LDAP object classes top, person, organizationalPerson, and inetOrgPerson:

"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 or groupObjectClasses are defined in the connector configuration, the connector uses the name of the ICF ObjectClass in the filter. For example, an object of type organizationUnit 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)

filterWithOrInsteadOfAnd

boolean

false

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.

objectClassesToSynchronize

String[]

['inetOrgPerson']

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.

baseContextsToSynchronize

String[]

[]

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.

attributesToSynchronize

String[]

[]

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.

changeNumberAttribute

String

changeNumber

The name of the change number attribute in the change log entry.

modifiersNamesToFilterOut

String[]

[]

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".

credentials

GuardedString

null

Yes

No

Password for the principal.

changeLogBlockSize

int

100

The number of change log entries to fetch per query.

useTimestampsForSync

boolean

false

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.

accountSynchronizationFilter

String

null

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.

removeLogEntryObjectClassFromFilter

boolean

true

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.

alternateKeyStorePassword

GuardedString

null

Yes

No

Password to use for the alternate keystore

groupSynchronizationFilter

String

null

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.

groupMemberAttribute

String

uniqueMember

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.

accountSearchFilter

String

null

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.

privateKeyAlias

String

null

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.

ssl

boolean

false

No

Select the check box to connect to the LDAP server using SSL.

maintainPosixGroupMembership

boolean

false

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.

checkAliveMinInterval

long

60

No

The minimum interval (seconds) at which the target directory is polled when a connection is reused from the pool. Defaults to 60 seconds.

groupSearchFilter

String

null

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.

referralsHandling

String

follow

No

Defines how to handle LDAP referrals. Possible values can be follow, ignore or throw.

host

String

null

No

The name or IP address of the host where the LDAP server is running.

maintainLdapGroupMembership

boolean

false

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.

resetSyncToken

String

never

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.

vlvSortAttribute

String

uid

No

Specify the sort attribute to use for VLV indexes on the resource.

convertGTToISO8601

String[]

['whenCreated', 'whenChanged']

No

Converts the Greenwich Time to ISO8601 format

baseContexts

String[]

[]

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.

hostNameVerification

boolean

false

No

If true, the connector will verify the hostname in the certificate (subject + alternative subject) against the defined hostNameVerifierPattern.

blockSize

int

100

No

The maximum number of entries that can be in a block when retrieving entries in blocks.

groupObjectClasses

String[]

['top', 'groupOfUniqueNames']

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.

accountUserNameAttributes

String[]

['uid', 'cn']

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.

failover

String[]

[]

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.

port

int

389

No

TCP/IP port number used to communicate with the LDAP server.

convertADIntervalToISO8601

String[]

['pwdLastSet', 'accountExpires', 'lockoutTime', 'lastLogon']

No

Converts the AD Interval to ISO8601

hostNameVerifierPattern

String

null

No

A simple pattern used to match the hostname from the certificate. It can contains * character (server1.example.com, *.example.com)

passwordAttribute

String

userPassword

No

The name of the LDAP attribute that holds the password. When changing a users password, the new password is set to this attribute.

useDNSSRVRecord

boolean

false

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.

getGroupMemberId

boolean

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.

lastCheckAlive

long

1645039764698

No

The last time the connector was checked to see if it was alive

startTLS

boolean

false

No

Specifies whether to use the startTLS operation to initiate a TLS/SSL session.

allowTreeDelete

boolean

false

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.

respectResourcePasswordPolicyChangeAfterReset

boolean

false

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.

uidAttribute

String

entryUUID

No

The name of the LDAP attribute that is mapped to the OpenICF UID attribute.

principal

String

null

No

The distinguished name with which to authenticate to the LDAP server.

accountObjectClasses

String[]

['top', 'person', 'organizationalPerson', 'inetOrgPerson']

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.

alternateKeyStoreType

String

null

No

Defines the type of the alternate key store. Valid values are JKS, JCEKS and PKCS12

passwordHashAlgorithm

String

null

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).

alternateKeyStore

String

null

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.

authType

String

simple

No

The authentication mechanism to use: Simple or SASL-GSSAPI. Defaults to "simple".

connectionTimeout

int

30000

No

The timeout (in ms) before the connection attempt is aborted.

useBlocks

boolean

false

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.

readSchema

boolean

true

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.

usePagedResultControl

boolean

false

No

When enabled, the LDAP Paged Results control is preferred over the VLV control when retrieving entries. If disabled, paged queries will be ignored.

useOldADGUIDFormat

boolean

false

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.

sendCAUDTxId

boolean

false

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.

gssapiLoginContext

String

null

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)

SCIMEndpoint

String

null

Yes

The HTTP URL defining the root for the SCIM endpoint (https://myserver.com/service/scim)

SCIMVersion

Integer

1

Yes

Defines the SCIM protocol version. Values can be either 1 or 2. Default is 1

authenticationMethod

String

OAUTH

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

user

String

null

Yes

In case of BASIC authentication type, this property defines the remote user.

password

GuardedString

null

Yes

No

In case of BASIC authentication type, this property defines the remote password.

tokenEndpoint

String

null

No

When using OAuth, this property defines the endpoint where a new access token should be requested (https://myserver.com/oauth2/token)

clientId

String

null

Yes

Secure client identifier for OAuth2

clientSecret

GuardedString

null

Yes

No

Secure client secret for OAuth2

authToken

GuardedString

null

Yes

No

Some service providers (Slack for instance) use static authentication tokens.

refreshToken

GuardedString

null

Yes

Used by the refresh_token grant type

grantType

String

null

No

The OAuth2 grant type to use (client_credentials or refresh_token)

scope

String

null

No

The OAuth2 scope to use.

acceptSelfSignedCertificates

boolean

false

Yes

To be used for debug/test purposes. To be avoided in production. Defaults to false.

disableHostNameVerifier

boolean

false

Yes

To be used for debug/test purposes. To be avoided in production. Defaults to false.

disableHttpCompression

boolean

false

Yes

Content compression is enabled by default. Set this property to true to disable it. Defaults to false.

clientCertAlias

String

null

Yes

If TLS Mutual Auth is needed, set this to the certificate alias from the keystore.

clientCertPassword

GuardedString

null

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.

maximumConnections

Integer

10

Yes

Defines the max size of the http connection pool used. Defaults to 10.

httpProxyHost

String

null

Yes

Defines the Hostname if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null.

httpProxyPort

Integer

null

Yes

Defines the Port if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null.

httpProxyUsername

String

null

Yes

Defines Proxy Username if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null.

httpProxyPassword

GuardedString

null

Yes

Yes

Defines Proxy Password if an HTTP proxy is used between the connector and the SCIM service provider. Defaults to null.

connectionTimeout

int

30

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. The init 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 the groovyx.net.http.RESTClient library.

This excerpt of a sample delete script shows the injection of the httpClient and connection variables into the script. The connection variable is the output of the decorate 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 defaultRequestHeaders configuration property to set HTTP request headers, the syntax requires an = sign rather than a :. For example, to generate a request header such as "Authorization: Bearer rg1cwAeQJxEf", you must set the following value for defaultRequestHeaders in the connector configuration:

"defaultRequestHeaders" : [ "Authorization = Bearer rg1cwAeQJxEf" ]
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)

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive Configuration script for Groovy ConfigSlurper

customConfiguration

String

null

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)

createScriptFileName

String

null

The name of the file used to perform the CREATE operation.

customizerScriptFileName

String

null

No

The script used to customize some function of the connector. Read the documentation for more details.

authenticateScriptFileName

String

null

The name of the file used to perform the AUTHENTICATE operation.

scriptOnResourceScriptFileName

String

null

The name of the file used to perform the RUNSCRIPTONRESOURCE operation.

deleteScriptFileName

String

null

The name of the file used to perform the DELETE operation.

resolveUsernameScriptFileName

String

null

The name of the file used to perform the RESOLVE_USERNAME operation.

searchScriptFileName

String

null

The name of the file used to perform the SEARCH operation.

updateScriptFileName

String

null

The name of the file used to perform the UPDATE operation.

schemaScriptFileName

String

null

The name of the file used to perform the SCHEMA operation.

testScriptFileName

String

null

The name of the file used to perform the TEST operation.

syncScriptFileName

String

null

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)

targetDirectory

File

null

No

Directory into which to write classes.

warningLevel

int

1

No

Warning Level of the compiler

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files

minimumRecompilationInterval

int

100

No

Sets the minimum of time after a script can be recompiled.

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script)

scriptRoots

String[]

null

Yes

The root folder to load the scripts from. If the value is null or empty the classpath value is used.

tolerance

int

10

No

The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

debug

boolean

false

No

If true, debugging code should be activated

classpath

String[]

[]

No

Classpath for use during compilation.

disabledGlobalASTTransformations

String[]

null

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.

verbose

boolean

false

No

If true, the compiler should produce action information

sourceEncoding

String

UTF-8

No

Encoding for source files

recompileGroovySource

boolean

false

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)

username

String

null

No

The Remote user to authenticate with

password

GuardedString

null

Yes

No

The Password to authenticate with

serviceAddress

URI

null

Yes

The service URI (example: http://myservice.com/api)

proxyAddress

URI

null

No

The optional Proxy server URI (example: http://myproxy:8080)

proxyUsername

String

null

No

The username to authenticate with the proxy server

proxyPassword

GuardedString

null

Yes

No

The password to authenticate with the proxy server

defaultAuthMethod

String

BASIC

No

Authentication method used. Defaults to BASIC.

defaultContentType

String

application/json

No

Default HTTP request content type. Defaults to JSON. Can be: TEXT, XML, HTML, URLENC, BINARY

defaultRequestHeaders

String[]

null

No

Placeholder for default HTTP request headers.

OAuthTokenEndpoint

URI

null

No

When using OAUTH, this property defines the endpoint where a new access token should be queried for (https://myserver.com/oauth2/token)

OAuthClientId

String

null

No

The client identifier

OAuthClientSecret

GuardedString

null

Yes

No

Secure client secret for OAUTH

OAuthRefreshToken

GuardedString

null

Yes

No

The refresh token used to renew the access token for the refresh_token grant type

OAuthScope

String

null

No

The optional scope

OAuthGrantType

String

CLIENT_CREDENTIALS

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)

createScriptFileName

String

null

The name of the file used to perform the CREATE operation.

customizerScriptFileName

String

null

No

The script used to customize some function of the connector. Read the documentation for more details.

resolveUsernameScriptFileName

String

null

The name of the file used to perform the RESOLVE_USERNAME operation.

updateScriptFileName

String

null

The name of the file used to perform the UPDATE operation.

schemaScriptFileName

String

null

The name of the file used to perform the SCHEMA operation.

authenticateScriptFileName

String

null

The name of the file used to perform the AUTHENTICATE operation.

scriptOnResourceScriptFileName

String

null

The name of the file used to perform the RUNSCRIPTONRESOURCE operation.

deleteScriptFileName

String

null

The name of the file used to perform the DELETE operation.

searchScriptFileName

String

null

The name of the file used to perform the SEARCH operation.

testScriptFileName

String

null

The name of the file used to perform the TEST operation.

syncScriptFileName

String

null

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)

targetDirectory

File

null

No

Directory into which to write classes.

warningLevel

int

1

No

Warning Level of the compiler

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script)

scriptRoots

String[]

null

Yes

The root folder to load the scripts from. If the value is null or empty the classpath value is used.

tolerance

int

10

No

The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

disabledGlobalASTTransformations

String[]

null

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.

sourceEncoding

String

UTF-8

No

Encoding for source files

recompileGroovySource

boolean

false

No

If set to true recompilation is enabled

minimumRecompilationInterval

int

100

No

Sets the minimum of time after a script can be recompiled.

debug

boolean

false

No

If true, debugging code should be activated

classpath

String[]

[]

No

Classpath for use during compilation.

verbose

boolean

false

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)

password

String

null

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.

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive Configuration script for Groovy ConfigSlurper

customConfiguration

String

null

No

Custom Configuration script for Groovy ConfigSlurper

connectionProperties

String

null

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.

propagateInterruptState

boolean

false

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.

useDisposableConnectionFacade

boolean

true

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.

defaultCatalog

String

null

No

The default catalog of connections created by this pool.

validationInterval

long

3000

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).

ignoreExceptionOnPreLoad

boolean

false

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.

jmxEnabled

boolean

true

No

Register the pool with JMX or not. The default value is true.

commitOnReturn

boolean

false

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.

logAbandoned

boolean

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.

maxIdle

int

100

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)

testWhileIdle

boolean

false

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)

removeAbandoned

boolean

false

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.

abandonWhenPercentageFull

int

0

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.

minIdle

int

10

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)

defaultReadOnly

Boolean

null

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)

maxWait

int

30000

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)

logValidationErrors

boolean

false

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.

driverClassName

String

null

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

name

String

Tomcat Connection Pool[4-1243567669]

No

Returns the name of the connection pool. By default a JVM unique random name is assigned.

useStatementFacade

boolean

true

No

If a statement proxy is set, wrap statements so that equals() and hashCode() methods can be called on closed statements.

initSQL

String

null

No

A custom query to be run when a connection is first created. The default value is null.

validationQueryTimeout

int

-1

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.

validationQuery

String

null

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)

rollbackOnReturn

boolean

false

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.

alternateUsernameAllowed

boolean

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.

dataSourceJNDI

String

null

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

validatorClassName

String

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.

suspectTimeout

int

0

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.

useEquals

boolean

true

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.

removeAbandonedTimeout

int

60

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.

defaultAutoCommit

Boolean

null

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.)

testOnConnect

boolean

false

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.

jdbcInterceptors

String

null

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.

initialSize

int

10

No

The initial number of connections that are created when the pool is started. Default value is 10

defaultTransactionIsolation

int

-1

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.

numTestsPerEvictionRun

int

0

No

Property not used in tomcat-jdbc-pool.

url

String

null

No

The URL used to connect to the database.

testOnBorrow

boolean

false

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

fairQueue

boolean

true

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.

accessToUnderlyingConnectionAllowed

boolean

true

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

maxAge

long

0

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.

minEvictableIdleTimeMillis

int

60000

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).

timeBetweenEvictionRunsMillis

int

5000

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).

testOnReturn

boolean

false

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.

useLock

boolean

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.

maxActive

int

100

No

The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100

username

String

null

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:

ssh-connector

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 to PASSWORD in the connector configuration file, and set a user and password. 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 to PUBKEY in the connector configuration file and set the user, password, passphrase and privateKey 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 is null. 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 and privateKey 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 example admin@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 to false, every character that is sent to the server is sent back to the client in the expect() 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 the locale property.

Default: false

locale

Sets the locale for the LC_ALL, LANG and LANGUAGE environment variables, if setLocale is set to true.

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 or PUBKEY. For more information, see connector-reference:ssh.adoc#ssh-authentication.

Default: PASSWORD

throwOperationTimeoutException

If true, the connector throws an exception when the expectTimeout 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)

customSensitiveConfiguration

GuardedString

null

Yes

No

Description is not available

createScriptFileName

String

null

Description is not available

targetDirectory

File

null

No

Description is not available

customizerScriptFileName

String

null

No

Description is not available

warningLevel

int

1

No

Description is not available

authenticateScriptFileName

String

null

Description is not available

scriptExtensions

String[]

['groovy']

No

Description is not available

scriptOnResourceScriptFileName

String

null

Description is not available

minimumRecompilationInterval

int

100

No

Description is not available

deleteScriptFileName

String

null

Description is not available

scriptBaseClass

String

null

No

Description is not available

scriptRoots

String[]

null

Yes

Description is not available

customConfiguration

String

null

No

Description is not available

resolveUsernameScriptFileName

String

null

Description is not available

searchScriptFileName

String

null

Description is not available

tolerance

int

10

No

Description is not available

updateScriptFileName

String

null

Description is not available

debug

boolean

false

No

Description is not available

classpath

String[]

[]

No

Description is not available

disabledGlobalASTTransformations

String[]

null

No

Description is not available

schemaScriptFileName

String

null

Description is not available

verbose

boolean

false

No

Description is not available

testScriptFileName

String

null

Description is not available

sourceEncoding

String

UTF-8

No

Description is not available

syncScriptFileName

String

null

Description is not available

recompileGroovySource

boolean

false

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)

host

String

null

Yes

The hostname to connect to

port

int

22

Yes

TCP port to use (defaults to 22)

user

String

null

Yes

The user name used to login to remote server

password

GuardedString

null

Yes

No

The password used to login to remote server

passphrase

GuardedString

null

Yes

No

The passphrase used to read the private key when using Public Key authentication

privateKey

String[]

[]

Yes

No

The base 64 encoded value (PEM) of the private key used for Public Key authentication

authenticationType

String

PASSWORD

Yes

Defines which authentication type should be use: PASSWORD or PUBKEY (defaults to PASSWORD)

prompt

String

`root@localhost:# `

Yes

A string representing the remote SSH session prompt (defaults to root@localhost:# )

sudoCommand

String

/usr/bin/sudo

Yes

A string representing the sudo command (defaults to /usr/bin/sudo)

echoOff

boolean

true

Yes

Disable the input command echo (default to true)

terminalType

String

vt102

Yes

Defines the terminal type to use for the session (default to vt102)

locale

String

en_US.utf8

Yes

Define the locale for LC_ALL, LANG and LANGUAGE environment variables to use if setLocale=true

setLocale

boolean

false

Yes

Defines if the default environment locale should be changed with the value provided for locale (defaults to false)

connectionTimeout

int

5000

Yes

Defines the connection timeout to the remote server in milliseconds (default to 5000)

expectTimeout

long

5000

Yes

Defines the timeout used by the expect() calls in the scripts in milliseconds (default to 5000)

throwOperationTimeoutException

boolean

true

Yes

Defines if an OperationTimeoutException should be thrown if any call to expect times out (defaults to true)

promptReadyTimeout

long

20

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 Connector

The DocuSign connector lets you manage DocuSign service accounts and synchronize accounts between DocuSign and the Identity Cloud managed user repository.

Epic Connector

The Epic connector lets you interact with Epic health systems.

Google Apps Connector

The Google Apps connector lets you interact with Google’s web applications.

HubSpot Connector

The HubSpot connector lets you synchronize HubSpot contacts and companies with managed objects in an Identity Cloud repository.

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.

SAP Connector

The SAP connector is an implementation of the Scripted Groovy Connector that connects to any SAP system using the SAP JCo Java libraries.

Workday Connector

The 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

  1. 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.

  2. 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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select DocuSign Connector - 1.5.20.5.

  5. Complete the Base Connector Details.

  6. 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 ConnectorException and you see the following error in the logs, you may need to adjust Password Rules in DocuSign:

Caused by: org.identityconnectors.framework.common.exceptions.ConnectorException: Invalid forgotten password challenge.

You can also set a custom forgottenPasswordQuestion and forgottenPasswordAnswer attribute during the create operation. For example:

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)

host

String

null

Yes

The DNS name or IP address of the DocuSign REST server

oAuthHost

String

null

Yes

The OAuth host URL to the DocuSign REST server

accountId

String

null

Yes

The DocuSign Account ID to manage

integratorKey

String

null

Yes

The DocuSign integrator key for accessing the REST API

privateKeyFilePath

String

null

Yes

The path to the private key used to generate a JSON web token (JWT)

publicKeyFilePath

String

null

Yes

The path to the public key used to generate a JSON web token (JWT)

userId

String

null

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)

acceptSelfSignedCertificates

boolean

false

Yes

Specifies that the HTTP client accepts self-signed certificates

disableHostNameVerifier

boolean

false

Yes

Specifies that the HTTP client does not verify the host name

maximumConnections

Integer

10

No

The maximum number of connections

httpProxyHost

String

null

Yes

The hostname of the HTTP proxy (if an HTTP proxy is used between the connector and the DocuSign server)

httpProxyPort

Integer

null

Yes

The proxy port number (if an HTTP proxy is used between the connector and the DocuSign server)

organizationConsent

Boolean

false

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:

    1. Generate and download an RSA key pair.

    2. 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
    3. After generating the private key in PKCS8 format, remove -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- from the generated PKCS8 private key file.

    4. 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:

  1. Select Configure > Connectors and click New Connector.

  2. Enter a Connector Name.

  3. Select Epic Connector - 1.5.20.5 as the Connector Type.

  4. Provide the Base Connector Details.

  5. 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
}
  • When you create a new user, you must specify at least UserID and __NAME__.

  • The maximum length of __NAME__ is 100 characters. The format for userName is LAST, FIRST MI format.

  • The maximum number of characters for UserID is 15.

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 the FirstName, LastName and MiddleName of UserComplexName 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)

clientId

String

null

Yes

Provide the Client ID to authorize the Epic APIs

privateKey

GuardedString

null

Yes

Yes

Provide the Private key in pkcs8 format

userName

String

null

Yes

Provide the Username required for Connection

password

GuardedString

null

Yes

Yes

Provide the Password required for Connection

maxRecords

int

50

No

Provide the Maximum records for search operation

maximumConnections

Integer

10

No

Provide the Maximum connections

connectionTimeout

int

600

No

Provide the Maximum Connection Timeout in seconds

accessToken

GuardedString

null

Yes

No

Provide the Access token to establish connectivity with the target

tokenValidity

Long

null

No

Provide the Validity period of the token

httpProxyHost

String

null

No

Provide the HTTP Proxy Host

httpProxyPort

Integer

null

No

Provide the HTTP Proxy Port

httpProxyUsername

String

null

No

Provide the HTTP Proxy Username

httpProxyPassword

GuardedString

null

Yes

No

Provide the HTTP Proxy Password

restEndpoint

String

No

The HTTP URL for the REST End point (https://myserver.com/service/)

soapEndpoint

String

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 and clientSecret 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)

domain

String

null

Yes

clientId

String

null

Yes

Client identifier issued to the client during the registration process.

clientSecret

GuardedString

null

Yes

Yes

Client secret issued to the client during the registration process.

refreshToken

GuardedString

null

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.

proxyHost

String

null

Yes

Defines an HTTP proxy host to use with the connection (example: "myproxy.home.com").

proxyPort

int

8080

Yes

Defines an HTTP proxy port to use with the connection (defaults to 8080).

validateCertificate

boolean

true

Yes

Validate the server certificate from the local truststore (defaults to true).

usersMaxResults

int

100

No

Maximum number of Users to return. Acceptable values are 1 to 500, inclusive.

groupsMaxResults

int

200

No

Maximum number of Groups to return. Acceptable values are 1 to 200, inclusive.

membersMaxResults

int

200

No

Maximum number of Members to return. Acceptable values are greater than 1

listProductMaxResults

long

100

No

Maximum number of Licenses to return. Acceptable values are 1 to 1000, inclusive.

listProductAndSkuMaxResults

long

100

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:

Table 1. Supported Resource Types With the Google Apps Connector
ICF Native Type Google Resource Type Naming Attribute

__ACCOUNT__

user

primaryEmail

__GROUP__

group

email

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:

Table 2. Supported Operators and Filter Attributes With Google Apps Searches
Object Type Operators Attributes

__ACCOUNT__

And, Contains, StartsWith, Equals

primaryEmail

__GROUP__

Contains, Equals

email

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

  1. 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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select HubSpot Connector - 1.5.2.0.

  5. Complete the Base Connector Details.

  6. 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]

clientId

String

null

Yes

Client ID of the OAuth application in Hubspot

clientSecret

GuardedString

null

Yes
Yes

Client Secret for the preceding Client ID

refreshToken

GuardedString

null

Yes
Yes

Refresh token for application in Hubspot

Advanced Connection Properties properties

Property Type Default Encrypted [4] Required [5]

acceptSelfSignedCertificates

boolean

false

Yes

Specifies whether the HubSpot server should accept self-signed certificates. Defaults to false.

readSchema

Boolean

false

Yes

If false, the Hubspot connector provides a default schema for Hubspot contacts and companies

disableHostNameVerifier

boolean

false

Yes

If hostname verification is disabled, the HubSpot server accepts connections from any host. Defaults to false.

maximumConnections

Integer

10

Yes

Maximum number of simultaneous connections to HubSpot.

permitsPerSecond

Integer

10

Yes

Number of Api calls to be made per second

httpProxyHost

String

null

Yes

Specifies the Hostname if an HTTP proxy is used between the connector and HubSpot. Defaults to null.

httpProxyPort

Integer

null

Yes

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:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select MongoDB Connector - 1.5.20.5.

  5. Complete the Base Connector Details. For information about the configurable properties, see MongoDB Basic Configuration Properties.

  6. 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)

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive Configuration script for Groovy ConfigSlurper

customConfiguration

String

null

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)

createScriptFileName

String

null

The name of the file used to perform the CREATE operation.

customizerScriptFileName

String

null

No

The script used to customize some function of the connector. Read the documentation for more details.

authenticateScriptFileName

String

null

The name of the file used to perform the AUTHENTICATE operation.

scriptOnResourceScriptFileName

String

null

The name of the file used to perform the RUNSCRIPTONRESOURCE operation.

deleteScriptFileName

String

null

The name of the file used to perform the DELETE operation.

resolveUsernameScriptFileName

String

null

The name of the file used to perform the RESOLVE_USERNAME operation.

searchScriptFileName

String

null

The name of the file used to perform the SEARCH operation.

updateScriptFileName

String

null

The name of the file used to perform the UPDATE operation.

schemaScriptFileName

String

null

The name of the file used to perform the SCHEMA operation.

testScriptFileName

String

null

The name of the file used to perform the TEST operation.

syncScriptFileName

String

null

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)

targetDirectory

File

null

No

Directory into which to write classes.

warningLevel

int

1

No

Warning Level of the compiler

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files

minimumRecompilationInterval

int

100

No

Sets the minimum of time after a script can be recompiled.

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script)

scriptRoots

String[]

null

Yes

The root folder to load the scripts from. If the value is null or empty the classpath value is used.

tolerance

int

10

No

The error tolerance, which is the number of non-fatal errors (per unit) that should be tolerated before compilation is aborted.

debug

boolean

false

No

If true, debugging code should be activated

classpath

String[]

[]

No

Classpath for use during compilation.

disabledGlobalASTTransformations

String[]

null

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.

verbose

boolean

false

No

If true, the compiler should produce action information

sourceEncoding

String

UTF-8

No

Encoding for source files

recompileGroovySource

boolean

false

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)

connectionURI

String

null

No

The MongoDB client connection URI, for example "mongodb://localhost:27017". Overides other connection parameters

host

String

localhost

No

The MongoDB server host name (localhost by default).

port

int

27017

No

The MongoDB server port number (27017 by default).

user

String

null

No

The MongoDB username

password

GuardedString

null

Yes

No

The password used to connect to MongoDB

userDatabase

String

null

No

The name of the database in which the MongoDB user is defined

clusterAddresses

String[]

null

No

A list of additional mongodbDB servers when connecting to a MongoDB cluster (["host1:27017","host2:27017",…​]")

dateAttributes

String[]

[]

No

Defines the list of attributes to convert to MongoDB BSON Date type on create/update.

database

String

null

No

The database to use

arrayAttributes

String[]

[]

No

Defines the list of attributes that should be considered as BSON Arrays.

includeNullValue

boolean

false

No

If set to true, retains null values in the target MongoDB document (false by default).

includeEmptyList

boolean

false

No

If set to true, retains null values in the target MongoDB document (false by default).

dateFormat

String

yyyy-MM-dd’T’HH:mm:ss’Z'

No

Defines the date format to use for MongoDB Date attributes (defaults to ISO 8601 "yyyy-MM-ddTHH:mm:ssZ").

timeZone

String

UTC

No

Defines the timezone to use for MongoDB Date attributes.

ICFName

String

name

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)

sslEnabled

boolean

true

No

Use secure socket layer to connect to MongoDB (true by default)

sslHostNameValidation

boolean

true

No

Defines if host name should be validated when SSL is enabled

maxConnectionIdleTime

int

0

No

The maximum idle time for a pooled connection in ms (0 means no limit)

maxConnectionLifeTime

int

0

No

The maximum life time for a pooled connection in ms (0 means no limit)

minConnectionsPerHost

int

0

No

The minimum number of connections per host (must be >= 0)

maxConnectionsPerHost

int

5

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

  1. Download the SAP connector from the ForgeRock BackStage download site.

  2. Copy the SAP connector .jar file (sap-connector-1.5.1.0.jar ) to the openidm/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
  3. 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

  1. 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, the destination 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. If false, 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 is 1.

    For optimum performance, set this value to an integer between 5 and 10.

  2. 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 a scripts/sap directory (because it belongs to the scripts/sap package) and the remaining HR scripts must be under a scripts/sap/hr directory (because they belong to the hr package).

Testing the connection to the SAP HR system

  1. 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
  2. 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
    }
  3. 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"
      },
    ...
  4. 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.

  1. 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.

  2. 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 the VALIDEND 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 format YYYYMMDD. For example:

    {
      "EMAIL": {
         "ID": "maria.gonzales@example.com"
         "VALIDBEGIN": "20160401",
         "VALIDEND": "20161231"
      }
    }
  3. 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 the VALIDBEGIN and VALIDEND 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"
  4. To change the temporal constraint (VALIDEND date) of the record, include the existing VALIDEND data in the JSON payload, and specify the new end date as a value of the DELIMIT_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"
  5. To delete the email address of the record, send a PUT request with the current RECORDNR, VALIDBEGIN, and VALIDEND attributes, but without the ID.

    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

  1. 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, the destination 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. If false, 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 is 1.

    For optimum performance, set this value to an integer between 5 and 10.

  2. 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 a scripts/sap directory (because it belongs to the scripts/sap package) and the R/3 scripts must be under a scripts/sap/r3 directory (because they belong to the r3 package).

Testing the connection to the SAP R/3 System

  1. 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
  2. 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 the LOGONDATA attribute

  • __ENABLE_DATE__ - set to the value of LOGONDATA/GLTGV (date from which the user account is valid)

  • __DISABLE_DATE__ - set to the value of LOGONDATA/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