ICF 1.5.20.24

Connector reference

Connectors let you connect to external resources such as LDAP, Active Directory, flat files, and others. This guide describes all the connectors supported with Advanced Identity Cloud, PingIDM, and RCS, and how to configure them.

Any available connector works with IDM, either directly or using RCS. Advanced Identity Cloud can use any available connector through RCS.

If you are looking for Advanced Identity Cloud applications, refer to:

All connectors are available for download from Backstage, but some connectors are included in the default deployment for Advanced Identity Cloud, IDM, and RCS. The following table identifies which connectors are included in the default deployments:

Connector included in default deployment
Connector IDM RCS

Adobe Admin Console

No

No

Adobe Marketing Cloud

Yes

No

Amazon Web Services (AWS)

No

No

AWS IAM Identity Center

No

No

AS400

No

Yes

Box

No

No

Cerner

No

Yes

CSV file

Yes

Yes

Database table

Yes

Yes

DocuSign

No

No

Dropbox

No

No

Epic

No

Yes

Google Apps

Yes

No

Google Cloud Platform (GCP)

No

No

Groovy connector toolkit

Yes

Yes

HubSpot

No

No

IBM RACF

No

Yes

Kerberos

Yes

Yes

LDAP

Yes

Yes

Marketo

Yes

No

Microsoft Graph API

Yes

No

MongoDB

Yes

Yes

Oracle EBS

No

Yes

PeopleSoft

No

Yes

PingOne

No

No

PowerShell connector toolkit

No

No

Salesforce

Yes

No

SAP

No

Yes

SAP HANA Database

No

Yes

SAP S/4HANA

No

No

SAP SuccessFactors

No

No

SCIM

Yes

Yes

Scripted REST

Yes

Yes

Scripted SQL

Yes

Yes

ServiceNow

Yes

No

SSH

Yes

Yes

Webex

No

No

Workday

No

No

Configurations in this guide are simplified to show essential aspects. Not all resources support all IDM 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 IDM. To connect to resources, IDM 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.

SaaS common connectors

Software as a Service (SaaS) common connectors enable connection to cloud-based apps, data, and services. SaaS common connectors share certain code and configuration templates. When a procedure, feature, or release notes specify something as SaaS common, it applies to all SaaS common connectors.

Saas common connectors

Name changes for ForgeRock products

Product names changed when ForgeRock became part of Ping Identity.

The following name changes have been in effect since early 2024:

Old name New name

ForgeRock Identity Cloud

PingOne Advanced Identity Cloud

ForgeRock Access Management

PingAM

ForgeRock Directory Services

PingDS

ForgeRock Identity Management

PingIDM

ForgeRock Identity Gateway

PingGateway

Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.

Adobe Admin Console connector

This is a SaaS common connector.

The Adobe admin console connector allows you to manage users and groups, as well as manage user group memberships between the Adobe admin console and IDM. You need an administrator account.

Before you start

  1. Create an Adobe Admin Console developer account.

  2. Create a new project. Add User Management API, choose the type of authentication OAuth server-to-server

  3. From the credentials tab, get the client_id, client_secret, orgId, and scope.

Install the Adobe Admin Console connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Adobe Admin Console

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/adobe-connector-1.5.20.23.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 Adobe Admin Console 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 Admin Console Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Adobe Admin Console Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Base Connector Details

  • Adobe User Management API Endpoint : https://usermanagement.adobe.io/v2

  • Use Basic Auth For OAuth Token Neg : true | false

  • Max connections: Max size of the http connection pool used. Defaults to 10.

  • Connection Timeout (seconds): Defines a timeout for the underlying http connection in seconds. Defaults to 30.

Authentication

  • Token Endpoint: https://ims-na1.adobelogin.com/ims/token/v3

  • Client ID: Your Client ID.

  • Client Secret: Your Client Secret.

  • Grant type: client_credentials

  • Scope: openid, AdobeID, user_management_sdk

  • orgId: Your Organization Id

In the Scope field, the scopes must be separated by a comma.
Object Types

If necessary, add or edit your object types to have these three objects with their properties:

__ACCOUNT__
PROPERTY NAME TYPE NATIVE TYPE REQUIRED

_id

String

String

NO

email

String

String

YES

firstname

String

String

NO

lastname

String

String

NO

status

String

String

NO

username

String

String

NO

type

String

String

YES

orgSpecific

boolean

boolean

NO

businessAccount

boolean

boolean

NO

country

String

String

NO

__GROUPS__

Array

String

NO
__GROUP__
PROPERTY NAME TYPE NATIVE TYPE REQUIRED

_id

String

String

NO

groupName

String

String

YES

type

String

String

NO

adminGroupName

String

String

NO

userGroupName

String

String

NO

memberCount

Integer

Integer

NO

productName

String

String

NO

profileGroupName

String

String

NO

If configuring the connector over REST or through the filesystem, specify the connection details to the Adobe resource provider in the configurationProperties for the connector. If you are using OAuth for your connection, the minimum required properties are scope, orgId, grantType, serviceUri, tokenEndpoint, clientId, and clientSecret.

On startup, IDM encrypts the value of the clientSecret.

Sample Configuration 
{
    "configurationProperties" : {
        "tokenExpiration" : null,
        "accessToken" : null,
        "serviceUri" : "https://usermanagement.adobe.io/v2",
        "login" : null,
        "password" : null,
        "authenticationMethod" : "OAUTH",
        "tokenEndpoint" : "https://ims-na1.adobelogin.com/ims/token/v3",
        "clientId" : "xxxxxxxxxxxxxxxxxx",
        "clientSecret" : "xxxxxxxxxxxxxxxxxx",
        "refreshToken" : null,
        "authToken" : null,
        "acceptSelfSignedCertificates" : false,
        "disableHostNameVerifier" : false,
        "disableHttpCompression" : false,
        "clientCertAlias" : null,
        "clientCertPassword" : null,
        "maximumConnections" : "10",
        "httpProxyHost" : null,
        "httpProxyPort" : null,
        "httpProxyUsername" : null,
        "httpProxyPassword" : null,
        "connectionTimeout" : "30",
        "grantType" : "client_credentials",
        "scope" : "openid, AdobeID, user_management_sdk",
        "authorizationTokenPrefix" : "Bearer",
        "useBasicAuthForOauthTokenNeg" : true,
        "groupReadRateLimit" : "0.09/sec",
        "userReadRateLimit" : "0.41/sec",
        "writeRateLimit" : "0.16/sec"
      }
}
If throttling problems continue, this guide may be helpful: Improve reconciliation query performance.

Mapping

From Adobe users to IDM Users

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

id

userId

N/A

email

_id

N/A

firstname

givenName

N/A

lastname

sn

N/A

type

type

N/A

status

status

N/A

username

username

N/A

country

country

N/A

orgSpecific

orgSpecific

N/A

businessAccount

businessAccount

N/A

__GROUPS__

__GROUPS__

N/A
From IDM Users to Adobe Users

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

mail

email

N/A

givenName

firstname

N/A

sn

lastname

N/A

type

type

N/A

username

username

N/A

country

country

N/A

__GROUPS__

__GROUPS__

N/A
From Adobe groups to IDM Groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

groupId

_id

N/A

groupname

groupName

N/A

type

type

N/A

memberCount

memberCount

N/A

adminGroupName

adminGroupName

N/A

productName

productName

N/A

licenseQuota

licenseQuota

N/A

profileGroupName

profileGroupName

N/A
From IDM Groups to Adobe groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

groupName

groupName

N/A

description

description

N/A

Test the Adobe Admin Console connector

Test that the connector was configured correctly:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Accept-API-Version: resource=1.0' \
--request POST \
'http://localhost:8080/system/adobe?_action=test'
{
    "name": "",
    "enabled": true,
    "config": "config/provisioner.openicf/",
    "connectorRef": {
        "bundleVersion": "1.5.20.23",
        "bundleName": "org.forgerock.openicf.connectors.adobe-connector",
        "connectorName": "org.forgerock.openicf.connectors.adobe.AdobeConnector"
    },
    "displayName": "Adobe Admin Console Connector",
    "objectTypes": [
        "__GROUP__",
        "__ACCOUNT__",
        "__ALL__",
    ],
    "ok": true
}

User

Create user

To create a user, it is necessary to provide at least the email and type fields. The possible values for the type field are adobeID, federatedID, and enterpriseID (case insensitive). To add groups or product profiles to a user, you must use the __GROUPS__ field. To do this, you need to provide the corresponding IDs. The country field of a set cannot be updated. If not sent, it defaults to the country of the domain name. When creating a user, the username field is initially set to be the same as the email address; however, this username field can be modified later through user profile updates:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
    "email" : "john.doe@domain1.com",
    "type" : "adobeID",
    "firstName" : "John",
    "lastName" : "Doe",
    "lastName" : "US",
    "__GROUPS__" : [
            "groupId",
            "groupId",
    ]
}' \
'http://localhost:8080/system/adobe/__ACCOUNT__?_action=create'
{
    "_id" : "john.doe@domain1.com",
    "id" : "userID",
    "email" : "john.doe@domain1.com",
    "username" : "john.doe@domain1.com",
    "orgSpecific": true,
    "businessAccount": true,
    "firstName" : "John",
    "lastname" : "Doe",
    "type" : "adobeID",
    "__NAME__" : "john.doe@domain1.com",
    "status" : "active",
    "country" : "US",
    "__GROUPS__" : [
            "groupId"
            "groupId"
    ]
}
Get Users

Retrieve a list of users from Adobe Admin Console. To paginate the results, the parameter pageSize must have a value greater than 1. The size of each page is 2,000 except, for the first page, which can contain fewer results due to technical users not being retrieved. By default, all users are retrieved.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/adobe/__ACCOUNT__?_queryFilter=true'
{
    "result": [
        {
            "_id": "email@domain1.com",
            "__GROUPS__": [
                "groupId"
            ],
            "id": "userID",
            "country": "US",
            "email": "email@domain1.com",
            "orgSpecific": true,
            "username": "email@domain1.com",
            "businessAccount": true,
            "firstname": "John",
            "__NAME__": "john.doe@domain1.com",
            "type": "adobeID",
            "status": "active",
            "lastname": "Doe"
        },
       /…​
    ],
    "resultCount": 999,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}
Get user

Retrieve a user from Adobe Admin Console. The user email must be provided in the URI path.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/adobe/__ACCOUNT__/USER_EMAIL'
{
    "_id" : "email@domain1.com",
    "email" : "email@domain1.com",
    "firstname" : "John",
    "lastname" : "Doe",
    "username" : "email@domain1.com",
    "type" : "adobeID",
    "status" : "active",
    "orgSpecific" : true,
    "businessAccount" : true,
    "__GROUPS__" : [
            "groupId1",
            "groupId2",
    ]
}
Get users type

Retrieves Adobe users only by displaying type and _id field. By default, retrieves all users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/adobe/__ACCOUNT__?_queryFilter=true&_fields=type'
{
    "result": [
        {
            "_id" : "email1@domain.com",
            "type": "adobeID"
        {
            "_id" : "email2@domain.net",
            "type": "federatedID"
        },
        {
            "_id" : "email3@domain.org",
            "type": "enterpriseID"
        }
    ],
    "resultCount": 999,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}
Update user

Only enterprise or federated users can be updated. The fields that can be updated are firstname, lastname, username, and __GROUPS__. The user email must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request PUT \
--data '{
    "firstname" : "Jonny",
    "lastname" : "Doo",
    "username" : "jonnydoo",
    "__GROUPS__" : [
            "groupId1",
            "groupId2",
    ]
}' \
'http://localhost:8080/system/adobe/__ACCOUNT__/USER_EMAIL'
{
    "_id": "john.doe@domain1.com",
    "id": "userID",
    "firstname": "Jonny",
    "username": "jonnydoo",
    "lastname": "Doo",
    "email": "john.doe@domain1.com",
    "orgSpecific": true,
    "status": "active",
    "businessAccount": true,
    "country": "US",
    "type": "federatedID",
    "__NAME__": "userjd",
    "__GROUPS__": [
        "groupId1",
        "groupId2"
    ]
}
Delete user

Delete a user from the Adobe organization. The user email must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request DELETE \
'http://localhost:8080/openidm/system/adobe/__ACCOUNT__/USER_EMAIL'
{
    "_id": "john.doe@domain1.com",
    "id": "946F1E3A65DDEA2A0A495CEB@196c1e336579f87e495faa.e",
    "firstname": "John",
    "username": "userjd",
    "lastname": "Doe",
    "email": "john.doe@domain1.com",
    "orgSpecific": true,
    "status": "active",
    "businessAccount": true,
    "country": "US",
    "type": "federatedID",
    "__NAME__": "userjd",
    "__GROUPS__": [
        "groupId"
    ]
}

GROUPS

Create group

To create a group, it is necessary to at least provide groupName field. The description field is optional and is not returned; it is only visible from the Adobe web interface console:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
    "groupName" : "group name",
    "description" : "group description"
}' \
'http://localhost:8080/openidm/system/adobe/__GROUP__?_action=create'
{
    "_id" : "groupId",
    "__NAME__" : "groupId",
}
Get groups

Retrieve a list of groups. To paginate the results the pageSize parameter value must be greater than 1, the size of each page is 400. By default, retrieves all users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/adobe/__GROUP__?_queryFilter=true'
{
    "result": [
        {
            "_id" : "groupId1"
        },
        {
            "_id" : "groupId2"
        },
        {
            "_id" : "groupId3",
        },
        ...
    ],
    "resultCount": 999,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}
Get group

Retrieve a group, only the _id field can be displayed. The group id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/adobe/__GROUP__/GROUP_ID'
{
    "_id" : "groupId",
    "__NAME__" : "groupId"
}
Update a group

The field that can be updated for a group is description. The group description is only visible from the web interface console. The group id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request PUT \
--header 'If-Match: *' \
--data '{
    "description" : "New Description"
}' \
'http://localhost:8080/openidm/system/adobe/__GROUP__/GROUP_ID'
{
    "_id" : "groupId",
    "__NAME__" : "groupId",
}
Delete a group

The group id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request DELETE \
'http://localhost:8080/openidm/system/adobe/__GROUP__/GROUP_ID'
{
    "_id" : "groupId",
    "__NAME__" : "groupId"
}

OpenICF Interfaces Implemented by the Adobe Admin Console Connector

The Adobe Admin Console 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 Admin Console Connector Configuration

The Adobe Admin Console Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

serviceUri

String

null

Yes

The service endpoint URI.

orgId

String

null

Yes

Your organizations unique ID, for example 12345@AdobeOrg.

login

String

null

Yes

The service login name.

groupReadRateLimit

String

null

Yes

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

password

GuardedString

null

Yes

No

The service user password.

userReadRateLimit

String

null

Yes

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

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

tokenEndpoint

String

null

No

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

writeRateLimit

String

null

Yes

Defines throttling for write operations (create/update/delete) either per second ("30/sec") or per minute ("100/min").

clientId

String

null

Yes

The client identifier for OAuth2.

clientSecret

GuardedString

null

Yes

No

Secure client secret for OAuth2.

authToken

GuardedString

null

Yes

No

Static authentication token.

acceptSelfSignedCertificates

boolean

false

Yes

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

disableHostNameVerifier

boolean

false

Yes

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

disableHttpCompression

boolean

false

Yes

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

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

httpProxyHost

String

null

Yes

Defines the Hostname if an HTTP proxy is used between the connector and the service.

httpProxyPort

Integer

null

Yes

Defines the Port if an HTTP proxy is used between the connector and the service.

httpProxyUsername

String

null

Yes

Defines Proxy Username if an HTTP proxy is used between the connector and the service.

httpProxyPassword

GuardedString

null

Yes

Yes

Defines Proxy Password if an HTTP proxy is used between the connector and the service.

connectionTimeout

int

30

No

Defines a timeout for the underlying HTTP connection in seconds.

refreshToken

GuardedString

null

No

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.

authorizationTokenPrefix

String

Bearer

No

The prefix to be used in the Authorization HTTP header for Token authentication.

useBasicAuthForOauthTokenNeg

boolean

true

Yes

The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).

(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 Marketing Cloud connector

The Adobe Marketing Cloud connector lets you manage profiles in an Adobe Campaign data store. The connector supports a subset of the OpenICF operations, as listed in OpenICF Interfaces Implemented by the Adobe Marketing Cloud Connector.

To use this connector, you need an Adobe ID.

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. For information on the current version, refer to the corresponding Adobe documentation.

The integration requires a public certificate and private key that will be used to sign the JWT token.

  1. You can use IDM’s generated self-signed certificate and private key to test the connector. In a production environment, use a CA-signed certificate and key.

    Export IDM’s self-signed certificate as follows:

    1. Export the certificate and key from JCEKS to standardized format PKCS #12:

      keytool \
-importkeystore \
-srckeystore /path/to/openidm/security/keystore.jceks \
-srcstoretype jceks \
-destkeystore /path/to/keystore.p12 \
-deststoretype PKCS12 \
-srcalias openidm-localhost \
-deststorepass changeit \
-destkeypass changeit

    2. Export the certificate:

      openssl pkcs12 \
-in /path/to/keystore.p12 \
-nokeys \
-out /path/to/cert.pem

    3. Export the unencrypted private key:

      openssl pkcs12 \
-in /path/to/keystore.p12 \
-nodes \
-nocerts \
-out /path/to/key.pem

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

  3. Click Integrations > New Integration.

  4. Click Access an API > Continue.

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

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

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

  8. Select a license, then click Create Integration.

  9. Select Continue to integration details to obtain the Client Credentials required by the connector.

    You will need these details for the connector configuration.

Install the Adobe Marketing Cloud connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Adobe Marketing Cloud

Yes

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/adobecm-connector-1.5.20.23.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 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.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Adobe Marketing Cloud Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Alternatively, you can create a connector configuration file and place it in your project’s conf/ directory. IDM bundles a sample configuration file (/path/to/openidm/samples/example-configurations/provisioners/provisioner.openicf-adobe.json) that you can use as a starting point.

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 tenant (organization) name or sandbox host.

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, refer to Adobe Marketing Cloud Connector Configuration.

Test the Adobe Marketing Cloud connector

When your connector is configured correctly, you can test its status by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/adobe?_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.

Adobe Marketing Cloud remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Adobe Marketing Cloud connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Adobe Marketing Cloud connector from here.

Refer to Remote connectors for configuring the Adobe Marketing Cloud remote connector.

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.

AS400 connector

You can use the AS400 connector to manage and synchronize users between AS400 and IDM or Advanced Identity Cloud.

Before you start

These instructions assume you have an AS400 administrator account and you have access to AS400. You need the following information to configure the connector:

Host Name

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

Username

The AS400 Organizational Admin username.

Password

The AS400 Organizational Admin password.

Is Secure

Whether to enable a secure connection to AS400.

Install the AS400 connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

AS400

No

Yes

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/as400-connector-1.5.20.23.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 AS400 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 AS400 Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to AS400 Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Test the AS400 connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/as400?_action=test"
{
  "name": "as400",
  "enabled": true,
  "config": "config/provisioner.openicf/as400",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.as400-connector",
    "connectorName": "org.forgerock.openicf.connectors.as400.As400Connector"
  },
  "displayName": "AS400 Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__",
    "__GROUP__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector has been configured correctly and can authenticate to the AS400 system.

AS400 remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the AS400 connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the AS400 connector from here.

Refer to Remote connectors for configuring the AS400 remote connector.

Supported resource types

The AS400 connector supports the following resources:

ICF Native Type AS400 Resource Type

__ACCOUNT__

Users

__GROUP__

Groups

Supported search filters

The AS400 connector supports search operations with the following filter operators and attributes:

Object Type Operators Attributes

__GROUP__

id filter

Id

Attributes

The AS400 connector supports the following account attributes:

Attribute Description

USPRF

User Profile Name

PASSWORD

The password used to log in.

PreviousSignOn

The previous sign-on date.

PasswordChangedDate

The last date the password was changed.

IsPasswordNone

Whether or not the password is *NONE.

UserExpirationAction

The user expiration action.

StorageUsed

The storage used.

ObjectAuditValue

A value used for auditing the object.

ActionAuditLevel

The Action Audit Level.

PWDEXP

When the user’s password is set to expire.

STATUS

The user’s status. Permitted values are enable and disable.

USRCLS

The special access control for the user.

ASTLVL

Specifies which user interface to use.

CURLIB

Specifies the name of the current library associated with the job.

INLPGM

The initial program.

INLMNU

The initial menu.

IsUserEntitlementRequired

Whether or not user entitlement is required.

IsAuthCollectionActive

Whether or not authority collection is active.

MTCPB

Limit capabilities.

TEXT

A free-form text field.

SPCAUT

The special access permissions for the user.

SPCENV

The special environment.

DSPSGNINF

The display sign-on information.

PWDEXPITV

The password expiration interval.

PWDCHGBLK

Whether or not to block password change.

LCLPWDMGT

Local password management.

LMTDEVSSN

Limit device session.

KBDBUF

Keyboard buffering.

MAXSTG

Maximum allowed storage.

PTYLMT

Highest schedule priority.

JOBD

Job description.

OWNER

The owner of the user profile.

ACGCDE

The accounting code.

DOCPWD

The document password.

MSGQ

The message queue.

DLVRY

Delivery.

SEV

The severity code.

PRTDEV

The print device.

OUTQ

The output queue.

ATNPGM

The attention program.

SRTSEQ

The sort sequence.

LANGID

The language ID.

CNTRYID

The country or region ID.

CCSID

The Coded Character Set ID.

CHRIDCTL

The character identifier control.

SETJOBATR

The local job attributes.

LOCALE

The locale.

USROPT

The user options.

UID

The user ID number.

HOMEDIR

The home directory.

USREXPDATE

The user’s expiration date.

USREXPITV

The user’s expiration interval.

AUT

Authority.

EIMASSOC

The EIM association.

PasswordExpireDate

The date the password expires.

GRPPRF

Specifies the user’s group profile name whose authority is used when there is no job-specific authority given to the user.

SUPGRPPRF

Specifies the user’s supplemental group profiles. Used with GRPPRF to determine what authority the user has when there is no job-specific authority given to the user.

Use the AS400 connector

The AS400 connector can perform the following actions:

Users

Create an AS400 user

The following example creates a user with all available attributes:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json"\
--request POST \
--data "{
  "__NAME__":"BJENSEN",
  "__PASSWORD__":"ASDE1234",
  "PWDEXP":false,
  "__ENABLE__":true,
  "USRCLS":"*USER",
  "ASTLVL":"*BASIC",
  "CURLIB":"*CRTDFT",
  "INLPGM":"*NONE",
  "INLMNU":"MAIN",
  "TEXT":"TEXTFILEDVALUE",
  "SPCAUT":["*AUDIT"],
  "SPCENV":"*S36",
  "DSPSGNINF":"*YES",
  "PWDEXPITV":"323",
  "PWDCHGBLK":"93",
  "LCLPWDMGT":true,
  "LMTDEVSSN":"*NO",
  "MAXSTG":"10000",
  "PTYLMT":8,
  "JOBD":"QDFTJOBD",
  "OWNER":"*USRPRF",
  "ACGCDE":"*BLANK",
  "DOCPWD":"W12345",
  "MSGQ":"*USRPRF",
  "DLVRY":"*HOLD",
  "SEV":"50",
  "PRTDEV":"*SYSVAL",
  "OUTQ":"*DEV",
  "ATNPGM":"*ASSIST",
  "SRTSEQ":"*HEX",
  "LANGID":"ENG",
  "CCSID":"*HEX",
  "CHRIDCTL":"*DEVD",
  "SETJOBATR":["*CCSID"],
  "LOCALE":"*C",
  "USROPT":["*HLPFULL"],
  "UID":"*GEN",
  "HOMEDIR":"*USRPRF",
  "EIMASSOC":["*NOCHG"],
  "USREXPITV":99,
  "USREXPDATE":"*USREXPITV",
  "LMTCPB":"*YES",
  "CNTRYID":"*SYSVAL",
  "GRPPRF":"AZURE",
  "SUPGRPPRF":["AWS"]
}" \
"https://localhost:8443/openidm/system/As400/__ACCOUNT__?_action=create&_prettyprint=true"
{
  "_id" : "BJENSEN",
  "USROPT" : [ "*HLPFULL" ],
  "SEV" : "50",
  "USREXPITV" : 99,
  "IsAuthCollectionActive" : false,
  "HOMEDIR" : "/home/BJENSEN",
  "MAXSTG" : "10000",
  "UID" : "1277",
  "PTYLMT" : 8,
  "__NAME__" : "BJENSEN",
  "PRTDEV" : "*SYSVAL",
  "__ENABLE__" : true,
  "LMTDEVSSN" : "*NO",
  "__UID__" : "BJENSEN",
  "SRTSEQ" : "*HEX",
  "DSPSGNINF" : "*YES",
  "PWDCHGBLK" : "93",
  "GRPPRF" : "AZURE",
  "USREXPDATE" : "12/06/22",
  "CURLIB" : "*CRTDFT",
  "LMTCPB" : "*YES",
  "ASTLVL" : "*BASIC",
  "SUPGRPPRF" : [ "AWS" ],
  "MSGQ" : "/QSYS.LIB/QUSRSYS.LIB/BJENSEN.MSGQ",
  "LANGID" : "ENG",
  "CCSID" : "65535",
  "PWDEXPITV" : "323",
  "IsUserEntitlementRequired" : true,
  "TEXT" : "TEXTFILEDVALUE",
  "JOBD" : "/QSYS.LIB/QGPL.LIB/QDFTJOBD.JOBD",
  "ActionAuditLevel" : "*BASIC",
  "ObjectAuditValue" : "*NONE",
  "PasswordChangedDate" : "Mon Aug 29 05:15:20 IST 2022",
  "ATNPGM" : "/QSYS.LIB/QEZMAIN.PGM",
  "LCLPWDMGT" : true,
  "INLPGM" : "*NONE",
  "USRCLS" : "*USER",
  "SPCAUT" : [ "*AUDIT" ],
  "SETJOBATR" : [ "*CCSID" ],
  "SPCENV" : "*S36",
  "ACGCDE" : "",
  "IsPasswordNone" : false,
  "DLVRY" : "*HOLD",
  "IsAuthCollectionRepositoryExist" : false,
  "UserExpirationAction" : "*DISABLE",
  "INLMNU" : "/QSYS.LIB/%LIBL%.LIB/MAIN.MNU",
  "LOCALE" : "*C",
  "KBDBUF" : "*SYSVAL",
  "OWNER" : "*USRPRF",
  "PasswordExpireDate" : "Tue Jul 18 00:00:00 IST 2023",
  "PWDEXP" : false,
  "OUTQ" : "*DEV",
  "CNTRYID" : "*SYSVAL",
  "CHRIDCTL" : "*DEVD",
  "StorageUsed" : "12"
}

When you create a new user, you must specify at least the __NAME__ property. This property can be a maximum of 10 characters. These characters may be:

  • Any letter

  • Any digits

  • The #, $, _, and @ special characters.

If the __NAME__ begins with a digit, it must be prefixed with a Q.
Query all users

The following example queries all users in the system:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/as400/__ACCOUNT__?_queryId=query-all-ids"
{
  "result": [
    {"_id": "ADAM"},
    {"_id": "BJENSEN"},
    {"_id": "CHERYL"},
    {"_id": "DAVID"},
    {"_id": "EDDIE"}
  ],
  "resultCount":5,
  "pagedResultsCookie":null,
  "totalPagedResultsPolicy":"NONE",
  "totalPagedResults":-1,
  "remainingPagedResults":-1
}
Query a single user

The following example queries all users in the system:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/as400/__ACCOUNT__/BJENSEN?prettyprint=true"
{
  "_id" : "BJENSEN",
  "USROPT" : [ "*HLPFULL" ],
  "SEV" : "50",
  "USREXPITV" : 99,
  "IsAuthCollectionActive" : false,
  "HOMEDIR" : "/home/BJENSEN",
  "MAXSTG" : "10000",
  "UID" : "1277",
  "PTYLMT" : 8,
  "__NAME__" : "BJENSEN",
  "PRTDEV" : "*SYSVAL",
  "__ENABLE__" : true,
  "LMTDEVSSN" : "*NO",
  "__UID__" : "BJENSEN",
  "SRTSEQ" : "*HEX",
  "DSPSGNINF" : "*YES",
  "PWDCHGBLK" : "93",
  "GRPPRF" : "AZURE",
  "USREXPDATE" : "12/06/22",
  "CURLIB" : "*CRTDFT",
  "LMTCPB" : "*YES",
  "ASTLVL" : "*BASIC",
  "SUPGRPPRF" : [ "AWS" ],
  "MSGQ" : "/QSYS.LIB/QUSRSYS.LIB/BJENSEN.MSGQ",
  "LANGID" : "ENG",
  "CCSID" : "65535",
  "PWDEXPITV" : "323",
  "IsUserEntitlementRequired" : true,
  "TEXT" : "TEXTFILEDVALUE",
  "JOBD" : "/QSYS.LIB/QGPL.LIB/QDFTJOBD.JOBD",
  "ActionAuditLevel" : "*BASIC",
  "ObjectAuditValue" : "*NONE",
  "PasswordChangedDate" : "Mon Aug 29 05:15:20 IST 2022",
  "ATNPGM" : "/QSYS.LIB/QEZMAIN.PGM",
  "LCLPWDMGT" : true,
  "INLPGM" : "*NONE",
  "USRCLS" : "*USER",
  "SPCAUT" : [ "*AUDIT" ],
  "SETJOBATR" : [ "*CCSID" ],
  "SPCENV" : "*S36",
  "ACGCDE" : "",
  "IsPasswordNone" : false,
  "DLVRY" : "*HOLD",
  "IsAuthCollectionRepositoryExist" : false,
  "UserExpirationAction" : "*DISABLE",
  "INLMNU" : "/QSYS.LIB/%LIBL%.LIB/MAIN.MNU",
  "LOCALE" : "*C",
  "KBDBUF" : "*SYSVAL",
  "OWNER" : "*USRPRF",
  "PasswordExpireDate" : "Tue Jul 18 00:00:00 IST 2023",
  "PWDEXP" : false,
  "OUTQ" : "*DEV",
  "CNTRYID" : "*SYSVAL",
  "CHRIDCTL" : "*DEVD",
  "StorageUsed" : "12"
}
Modify a user

You can modify an existing user with a PUT request, including all attributes of the account in the request. You can use the AS400 connector to modify the following attributes:

  • PASSWORD

  • PWDEXP

  • STATUS

  • USRCLS

  • ASTLVL

  • CURLIB

  • INLPGM

  • INLMNU

  • LMTCPB

  • TEXT

  • SPCAUT

  • SPCENV

  • DSPSGNINF

  • PWDEXPITV

  • PWDCHGBLK

  • LCLPWDMGT

  • LMTDEVSSN

  • KBDBUF

  • MAXSTG

  • PTYLMT

  • JOBD

  • OWNER

  • ACGCDE

  • DOCPWD

  • MSGQ

  • DLVRY

  • SEV

  • PRTDEV

  • OUTQ

  • ATNPGM

  • SRTSEQ

  • LANGID

  • CNTRYID

  • CCSID

  • CHRIDCTL

  • SETJOBATR

  • LOCALE

  • USROPT

  • UID

  • HOMEDIR

  • USREXPDATE

  • USREXPITV

  • EIMASSOC

  • GRPPRF

  • SUPGRPPRF

The following request updates a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match: *" \
--request PUT \
--data "{
  "__PASSWORD__":"ASDE1234",
  "PWDEXP":false,
  "__ENABLE__":true,
  "USRCLS":"*USER",
  "ASTLVL":"*BASIC",
  "CURLIB":"*CRTDFT",
  "INLPGM":"*NONE",
  "INLMNU":"MAIN",
  "TEXT":"TEXTFILEDVALUE",
  "SPCAUT":["*AUDIT"],
  "SPCENV":"*S36",
  "DSPSGNINF":"*YES",
  "PWDEXPITV":"323",
  "PWDCHGBLK":"93",
  "LCLPWDMGT":true,
  "LMTDEVSSN":"*NO",
  "MAXSTG":"10000",
  "PTYLMT":8,
  "JOBD":"QDFTJOBD",
  "OWNER":"*USRPRF",
  "ACGCDE":"*BLANK",
  "DOCPWD":"W12345",
  "MSGQ":"*USRPRF",
  "DLVRY":"*HOLD",
  "SEV":"50",
  "PRTDEV":"*SYSVAL",
  "OUTQ":"*DEV",
  "ATNPGM":"*ASSIST",
  "SRTSEQ":"*HEX",
  "LANGID":"ENG",
  "CCSID":"*HEX",
  "CHRIDCTL":"*DEVD",
  "SETJOBATR":["*CCSID"],
  "LOCALE":"*C",
  "USROPT":["*HLPFULL"],
  "UID":"*GEN",
  "HOMEDIR":"*USRPRF",
  "EIMASSOC":["*NOCHG"],
  "USREXPITV":99,
  "USREXPDATE":"*USREXPITV",
  "LMTCPB":"*YES",
  "CNTRYID":"*SYSVAL",
  "GRPPRF":"AZURE","SUPGRPPRF":["AWS"]
}" \
"https://localhost:8443/openidm/system/As400/__ACCOUNT__/BJENSEN_prettyprint=true"
{
  "_id" : "BJENSEN",
  "USROPT" : [ "*HLPFULL" ],
  "SEV" : "50",
  "USREXPITV" : 99,
  "IsAuthCollectionActive" : false,
  "HOMEDIR" : "/home/BJENSEN",
  "MAXSTG" : "10000",
  "UID" : "1277",
  "PTYLMT" : 8,
  "__NAME__" : "BJENSEN",
  "PRTDEV" : "*SYSVAL",
  "__ENABLE__" : true,
  "LMTDEVSSN" : "*NO",
  "__UID__" : "BJENSEN",
  "SRTSEQ" : "*HEX",
  "DSPSGNINF" : "*YES",
  "PWDCHGBLK" : "93",
  "GRPPRF" : "AZURE",
  "USREXPDATE" : "12/06/22",
  "CURLIB" : "*CRTDFT",
  "LMTCPB" : "*YES",
  "ASTLVL" : "*BASIC",
  "SUPGRPPRF" : [ "AWS" ],
  "MSGQ" : "/QSYS.LIB/QUSRSYS.LIB/BJENSEN.MSGQ",
  "LANGID" : "ENG",
  "CCSID" : "65535",
  "PWDEXPITV" : "323",
  "IsUserEntitlementRequired" : true,
  "TEXT" : "TEXTFILEDVALUE",
  "JOBD" : "/QSYS.LIB/QGPL.LIB/QDFTJOBD.JOBD",
  "ActionAuditLevel" : "*BASIC",
  "ObjectAuditValue" : "*NONE",
  "PasswordChangedDate" : "Mon Aug 29 05:15:20 IST 2022",
  "ATNPGM" : "/QSYS.LIB/QEZMAIN.PGM",
  "LCLPWDMGT" : true,
  "INLPGM" : "*NONE",
  "USRCLS" : "*USER",
  "SPCAUT" : [ "*AUDIT" ],
  "SETJOBATR" : [ "*CCSID" ],
  "SPCENV" : "*S36",
  "ACGCDE" : "",
  "IsPasswordNone" : false,
  "DLVRY" : "*HOLD",
  "IsAuthCollectionRepositoryExist" : false,
  "UserExpirationAction" : "*DISABLE",
  "INLMNU" : "/QSYS.LIB/%LIBL%.LIB/MAIN.MNU",
  "LOCALE" : "*C",
  "KBDBUF" : "*SYSVAL",
  "OWNER" : "*USRPRF",
  "PasswordExpireDate" : "Tue Jul 18 00:00:00 IST 2023",
  "PWDEXP" : false,
  "OUTQ" : "*DEV",
  "CNTRYID" : "*SYSVAL",
  "CHRIDCTL" : "*DEVD",
  "StorageUsed" : "12"
}
Reset a user’s password

To reset the password for an AS400 user account, you can use the connector to change the user’s password:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match: *" \
--request PUT \
--data "{
  "__PASSWORD__":"newpassword123"
}" \
"https://localhost:8443/openidm/system/as400/__ACCOUNT__/BJENSEN_prettyprint=true"
{
  "_id" : "BJENSEN",
  "USROPT" : [ "*HLPFULL" ],
  "SEV" : "50",
  ...
}
Activate a user

The following example activates a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match: *" \
--request PUT \
--data "{
  "__ENABLE__": true
}
"https://localhost:8443/openidm/system/as400/__ACCOUNT__/BJENSEN_prettyprint=true"
{
  "_id" : "BJENSEN",
  ...
  "__ENABLE__": true
  ...
}
Deactivate a user

The following example deactivates a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--header "If-Match: *" \
--request PUT \
--data "{"
  ""__ENABLE__": false
}" \
"https://localhost:8443/openidm/system/as400/__ACCOUNT__/BJENSEN_prettyprint=true"
{
  "_id" : "BJENSEN",
  ...
  "__ENABLE__": false
  ...
}
Delete a user

The following example deletes a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://localhost:8443/openidm/system/as400/__ACCOUNT__/BJENSEN_prettyprint=true"
{
  "_id" : "BJENSEN",
  ...
}

Groups

Query all groups

The following example queries all AS400 Groups by their IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/as400/__GROUP__?_queryId=query-all-ids&_prettyprint=true"
{
  {
  "result": [
    {"_id": "AWS"},
    {"_id": "AZURE"},
    {"_id": "CLOUD"}
  ],
  "resultCount" : 3,
  "pagedResultsCookie" : null,
  "totalPagedResultsPolicy" : "NONE",
  "totalPagedResults" : -1,
  "remainingPagedResults" : -1
}
Query a single group

The following example queries a single AS400 group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/as400/__GROUP__/AWS?_prettyprint=true"
{
  "_id" : "AWS",
  "GID" : "116",
  "__NAME__" : "AWS",
  "GRPAUT" : "*NONE",
  "GRPAUTTYP" : "*PRIVATE",
  "__UID__" : "AWS"
}

OpenICF Interfaces Implemented by the AS400 Connector

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

AS400 Connector Configuration

The AS400 Connector has the following configurable properties:

Configuration properties

Property Type Default Encrypted(1) Required(2)

hostName

String

null

Yes

Host name or IP address of As400.

userName

String

null

Yes

The username to login As400.

password

GuardedString

null

Yes

Yes

The password to login As400.

isSecure

boolean

true

Yes

Enables or not secure connection to As400.

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

maximumConnections

Integer

10

No

Provides the maximum connections.

maxLifetime

Integer

null

No

Provides the maximum life for an available connection. The default value is 86400000.

maxInactivity

Integer

null

No

Provides the maximum amount of inactive time before an available connection is closed. The default value is 3600000.

maxUseTime

Long

null

No

Provides the maximum amount of time a connection can be in use before it is closed and returned to the pool. The default value is -1 indicating that there is no limit.

maxUseCount

Integer

null

No

Provides the maximum number of times a connection can be used before it is replaced in the pool. The default value is -1 indicating that there is no limit.

isRunMaintenance

boolean

true

No

Indicates whether the maintenance thread is used to cleanup expired connections. The default is true.

isThreadUsed

boolean

true

No

Indicates whether threads are used in communication with the host servers and for running maintenance. The default value is true.

cleanupInterval

Long

null

No

Time interval for how often the maintenance daemon is run. The default value is 300000 milliseconds.

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

Amazon Web Services (AWS) connector

Amazon Web Services (AWS) Identity and Access Management (IAM) is a web service for securely controlling access to AWS services. The AWS connector lets you manage and synchronize accounts between AWS and IDM managed user objects. An AWS administrator account is required for this connector to work.

Before you start

Before you configure the connector, log in to your AWS administrator account and note the following:

Access Key ID

The access key ID is a globally unique IAM user identifier to access the AWS service API.

Secret Key ID

The secret key is a password to access the AWS service API.

Role ARN

Amazon Resource Name (ARN) for the role which has IAM Full Access permissions.

Credentials Expiration

Time (in seconds) to configure the duration in which the temporary credentials would expire. Optional.

Region

The region where the AWS instance is hosted.

Install the AWS connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Amazon Web Services (AWS)

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/aws-connector-1.5.20.23.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 AWS 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 AWS Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to AWS Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Test the AWS connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/aws?_action=test"
{
  "name": "aws",
  "enabled": true,
  "config": "config/provisioner.openicf/aws",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.aws-connector",
    "connectorName": "org.forgerock.openicf.connectors.aws.AwsConnector"
  },
  "displayName": "AWS Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector has been configured correctly and can authenticate to the AWS system.

AWS remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the AWS connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the AWS connector from here.

Refer to Remote connectors for configuring the AWS remote connector.

Use the AWS connector

The following AWS account attributes are supported by the AWS connector:

Attribute Description

__USER__

The username of the user. Only alphanumeric characters, and +=,.@_- symbols are supported. Required.

UserId

Auto-generated user id.

Path

The path to the created user (used to define a hierarchy-based structure). Default value is /.

__PASSWORD__

Password for the user account.

Arn

Amazon Resource Name (ARN), used to uniquely identify the AWS resource. For more information on ARNs, refer to Amazon Resource Names (ARNs) in the AWS documentation.

CreatedDate

Date of profile creation, in ISO 8601 date-time format.

PasswordLastUsed

Date the password was last used.

PermissionBoundary

The ARN of the policy that is used to set the permissions boundary for the user.

Tags

A list of customizable key-value pairs. For more information about tags on AWS, refer to Tagging AWS resources in the AWS documentation. For example:

"Tags": [{
    "Key": "Department",
    "Value": "Accounting"
}]

You can use the AWS connector to perform the following actions on an AWS account:

Create an AWS user

The following example creates a user with the minimum required attributes:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "__NAME__": "bjensen"
}' \
"http://localhost:8080/openidm/system/aws/__ACCOUNT__?_action=create"
{
  "_id": "bjensen",
  "Path": "/",
  "UserId": "AIDAW3FY74V57KNBRIDU6",
  "__NAME__": "bjensen",
  "Arn": "arn:aws:iam::470686885243:user/bjensen",
  "CreatedDate": "Thu Jun 02 16:46:39 PDT 2022"
}

When you create a new user, you must specify at least __NAME__. Refer to the list of available attributes for more information.
Update an AWS user

You can modify an existing user with a PUT request, including all attributes of the account in the request. The following attributes can be modified on a user:

  • __USER__

  • __PASSWORD__

  • Path

  • PermissionsBoundary

  • Tags

For example, to add a new tag to a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "__NAME__": "bjensen",
  "Tags": [{
    "Key": "Project",
    "Value": "Meteor"
  }]
}' \
"http://localhost:8080/openidm/system/aws/__ACCOUNT__/bjensen"
{
  "_id": "bjensen",
  "Path": "/",
  "UserId": "AIDAW3FY74V57KNBRIDU6",
  "__NAME__": "bjensen",
  "Arn": "arn:aws:iam::470686885243:user/bjensen",
  "CreatedDate": "Thu Jun 02 16:46:39 PDT 2022",
  "Tags": [
    {
      "Project": "Meteor"
    }
  ]
}
Query AWS users

The following example queries all AWS users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/aws/__ACCOUNT__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "bjensen"
    },
    {
      "_id": "frank@example.com"
    },
    {
      "_id": "testFR4User"
    },
    {
      "_id": "testFR5User"
    },
    {
      "_id": "testFR6User"
    }
  ],
  "resultCount": 5,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The following command queries a specific user by their ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/aws/__ACCOUNT__/bjensen"
{
  "_id": "bjensen",
  "Path": "/",
  "UserId": "AIDAW3FY74V57KNBRIDU6",
  "__NAME__": "bjensen",
  "Arn": "arn:aws:iam::470686885243:user/bjensen",
  "CreatedDate": "Thu Jun 02 16:46:39 PDT 2022",
  "Tags": [
    {
      "Project": "Meteor"
    }
  ]
}
Reset an AWS user account password 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PATCH \
--data '[{
  "operation": "add",
  "field": "__PASSWORD__",
  "value": "Passw0rd@123!"
}]' \
"http://localhost:8080/openidm/system/aws/__ACCOUNT__/bjensen"
{
  "_id": "bjensen",
  "Path": "/",
  "UserId": "AIDAW3FY74V57KNBRIDU6",
  "__NAME__": "bjensen",
  "Arn": "arn:aws:iam::470686885243:user/bjensen",
  "CreatedDate": "Thu Jun 02 16:46:39 PDT 2022",
  "Tags": [
    {
      "Project": "Meteor"
    }
  ]
}

While the __PASSWORD__ field is not returned as part of the response, the user object is updated.
Delete an AWS user account

You can use the AWS connector to delete an account from the AWS IAM service.

The following example deletes an AWS account:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request DELETE \
"http://localhost:8080/openidm/system/aws/__ACCOUNT__/bjensen"
{
  "_id": "bjensen",
  "Path": "/",
  "UserId": "AIDAW3FY74V57KNBRIDU6",
  "__NAME__": "bjensen",
  "Arn": "arn:aws:iam::470686885243:user/bjensen",
  "CreatedDate": "Thu Jun 02 16:46:39 PDT 2022",
  "Tags": [
    {
      "Project": "Meteor"
    }
  ]
}

OpenICF Interfaces Implemented by the AWS Connector

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

AWS Connector Configuration

The AWS Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

accessKeyId

String

null

Yes

Provides the Access Key ID to access the AWS IAM Service API.

secretKey

GuardedString

null

Yes

Yes

Provides the Secret Key ID to access the AWS IAM Service API.

roleArn

String

null

Yes

Provides the Amazon Resource Name specifying the Role.

region

String

null

No

Provides the Regions.

pageSize

int

100

No

Provides the Page Size.

credentialsExpiration

int

3600

No

Provides the temporary credentials expiration time in seconds.

parentId

String

null

No

Provides the Parent ID to access the Organization Service.

userName

String

null

No

Provides the UserName to access the Inline policy of a User.

proxyHost

String

null

No

Provides the ProxyHost.

proxyPort

Integer

null

No

Provides the ProxyPort.

proxyUsername

String

null

No

Provides the Proxy Username.

proxyPassword

GuardedString

null

No

Provides the Proxy Password.

connectionTimeout

Integer

10000

No

Provides the Maximum Connection Timeout in milliseconds.

maxConnections

Integer

10

No

Provides the number of Maximum Connections.

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

AWS IAM Identity Center connector

The AWS IAM Identity Center connector allows you to manage users and groups, as well as manage user group memberships between the AWS IAM identity center and IDM. You need an administrator account.

Before you start

Before you configure the connector, log in to your AWS administrator account in the web console and obtain the following data to be able to connect: accessKey, secretKey, identityStoreId, region, and roleArn.

Install the AWS IAM Identity Center connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

AWS IAM Identity Center

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/awsiam-connector-1.5.20.23.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 AWS IAM Identity Center 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 AWS IAM Identity Center Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to AWS IAM Identity Center Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Connection details

  • Access Key ID: The access key ID is a globally unique IAM user identifier to access the AWS service API.

  • Secret Key ID: The secret key is a password to access the AWS service API.

  • Role ARN: Amazon Resource Name (ARN) for the role which has IAM Full Access permissions.

  • Session Name: A name used to uniquely identify a user session within the identity service.

  • Credentials Expiration Time: Time (in seconds) to configure the duration in which the temporary credentials would expire. The time must be between 900 and 3600 seconds.

  • Region: The region where the AWS instance is hosted.

  • Identity Store ID: Unique identifier associated with an identity store used by AWS IAM Identity Center.

  • Max connections: Max size of the http connection pool used. Optional.

  • Connection Timeout (seconds): Defines a timeout for the http connection in seconds. Optional.

  • ProxyHost: Proxy server host. Optional.

  • ProxyPort: Proxy server port number. Optional.

  • ReadRateLimit: Limits the request rate for read operations. The recommended rate is 20/sec.

  • WriteRateLimit: Limits the request rate for write operations. The recommended rate is 10/sec.

Object Types

If necessary, add or edit your object types to have these three objects with their properties:

__ACCOUNT__
PROPERTY NAME TYPE NATIVE TYPE REQUIRED

_id

String

String

NO

__NAME__

String

String

YES

name

Object

Object

YES

displayName

String

String

YES

userType

String

String

NO

profileUrl

String

String

NO

title

String

String

NO

preferredLanguage

String

String

NO

locale

String

String

NO

nickName

String

String

NO

timezone

String

String

NO

emails

Array

Object

NO

phoneNumbers

Array

Object

NO

addresses

Array

Object

NO

externalIds

Array

Object

NO

__GROUPS__

Array

String

NO
__GROUP__
PROPERTY NAME TYPE NATIVE TYPE REQUIRED

_id

String

String

NO

__NAME__

String

String

YES

description

String

String

NO

externalIds

Array

Object

NO
The __NAME__ field represents the username for users and the groupName for groups.

If configuring the connector over REST or through the filesystem, specify the connection details to the AWS IAM Identity Center resource provider in the configurationProperties for the connector. The minimum required properties are accessKey, secretKey, roleArn, roleSessionName, region, and identityStoreId.

Sample Configuration 
{
  "configurationProperties": {
    "accessKey": "ACCEES_KEY",
    "secretKey": "xxxxxxxxxxxx",
    "roleArn": "arn:aws:iam::000000000:role/USERNAME_ROLE",
    "roleSessionName": "SESSION_NAME",
    "region": "us-east-2",
    "identityStoreId": "d-0a010101e0",
    "sessionExpirationTime": 3600,
    "proxyHost": null,
    "proxyPort": null,
    "proxyUsername": null,
    "proxyPassword": null,
    "connectionTimeout": null,
    "maxConnections": null,
    "readRateLimit": "20/sec",
    "writeRateLimit": "10/sec"
  }
}
On startup, IDM encrypts the value of the secretKey.

Mapping

From AWS users to IDM or Advanced Identity Cloud users

Attributes mapping table where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

_id

_id

N/A

__NAME__

userName

N/A

displayName

displayName

N/A

timezone

timezone

N/A

nickname

nickname

N/A

title

title

N/A

locale

locale

N/A

preferredLanguage

preferredLanguage

N/A

profileUrl

profileUrl

N/A

userType

userType

N/A

name

name

N/A

phoneNumbers

phoneNumbers

N/A

addresses

addresses

N/A

emails

emails

N/A

externalIds

externalIds

N/A

__GROUPS__

groups

N/A
From IDM or Advanced Identity Cloud users to AWS users

Attributes mapping table where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

userName

__NAME__

N/A

displayName

displayName

N/A

timezone

timezone

N/A

nickname

nickname

N/A

title

title

N/A

locale

locale

N/A

preferredLanguage

preferredLanguage

N/A

profileUrl

profileUrl

N/A

userType

userType

N/A

name

name

N/A

phoneNumbers

phoneNumbers

N/A

addresses

addresses

N/A

emails

emails

N/A

__GROUPS__

groups

N/A
From AWS groups to IDM or Advanced Identity Cloud groups

Attributes mapping table where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

_id

_id

N/A

__NAME__

groupName

N/A

description

description

N/A

externalIds

externalIds

N/A
From IDM or Advanced Identity Cloud groups to AWS Groups

Attributes mapping table where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

__NAME__

groupName

N/A

description

description

N/A

Test the AWS IAM Identity Center connector

Test that the connector was configured correctly:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Accept-API-Version: resource=1.0' \
--request POST \
'http://localhost:8080/system/awsiam?_action=test'
{
    "name": "awsiam",
    "enabled": true,
    "config": "config/provisioner.openicf/awsiam",
    "connectorRef": {
    "bundleVersion": "1.5.20.23",
    "bundleName": "org.forgerock.openicf.connectors.awsiam-connector",
    "connectorName": "org.forgerock.openicf.connectors.awsiam.AwsIamConnector"
    },
    "displayName": "AWS IAM IC Connector",
    "objectTypes": [
    "__ACCOUNT__",
    "__ALL__",
    "__GROUP__"
    ],
    "ok": true
}

Use the AWS IAM Identity Center connector

User

Create user

To create a user in AWS IAM Identity Center, you must provide at least the __NAME__, name (givenName and familyName) and displayName fields.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
    "__NAME__": "JohnDoe",
    "displayName": "John Doe",
    "locale": "US",
    "nickName": "JonnyDoe",
    "timezone": "UTC",
    "title": "Engineer",
    "profileUrl": "https://www.profile.com/jdoe",
    "userType": "USER",
    "preferredLanguage": "us-US",
    "name": {
        "givenName": "John",
        "middleName": "Michael",
        "familyName": "Doe",
        "honorificPrefix": "Sr.",
        "honorificSufix": "PhD",
        "formatted": "Sr. John Michael Doe, PhD"
    },
    "addresses": {
        "type": "home",
        "streetAddress": "123 Main St",
        "locality": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "USA",
        "primary": true,
        "formatted": "123 Main St, Springfield, IL 62701, USA"
    },
    "emails": {
        "type": "home",
        "value": "johndoe@example.com",
        "primary": true
    },
    "phoneNumbers": {
        "type": "mobile",
        "value": "+0101010101",
        "primary": true
    },
    "__GROUPS__": [
        "groupId1",
        "groupId2",
    ]
}' \
'http://localhost:8080/system/awsiam/__ACCOUNT__?_action=create'
{
    "_id" : " "userId",
    "__NAME__": "JohnDoe",
    "displayName": "John Doe",
    "locale": "US",
    "nickName": "JonnyDoe",
    "timezone": "UTC",
    "title": "Engineer",
    "profileUrl": "https://www.profile.com/jdoe",
    "userType": "USER",
    "preferredLanguage": "us-US",
    "name": {
        "givenName": "John",
        "middleName": "Michael",
        "familyName": "Doe",
        "honorificPrefix": "Sr.",
        "honorificSufix": "PhD",
        "formatted": "Sr. John Michael Doe, PhD"
    },
    "addresses": {
        "type": "home",
        "streetAddress": "123 Main St",
        "locality": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "USA",
        "primary": true,
        "formatted": "123 Main St, Springfield, IL 62701, USA"
    },
    "emails": {
        "type": "home",
        "value": "johndoe@example.com",
        "primary": true
    },
    "phoneNumbers": {
        "type": "mobile",
        "value": "+0101010101",
        "primary": true
    },
    "__GROUPS__": [
        "groupId1",
        "groupId2",
    ]
}
Get Users

Return all users from AWS IAM Identity Center.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__ACCOUNT__?_queryFilter=true'
{
    "result": [
        {
            "_id": "",
            "__NAME__": "jdoe",
            "displayName": "John Doe",
            "name": {
                "givenName": "John",
                "middleName": "Michael",
                "familyName": "Doe",
            },
            "addresses": [].
            "emails": [],
            "phoneNumbers": [],
            "__GROUPS__": [
                "groupId1",
                "groupId2"
            ]
        },
    ...
        {
            "_id": "",
            "__NAME__": "jdoe",
            "displayName": "John Doe",
            "name": {
                "givenName": "John",
                "middleName": "Michael",
                "familyName": "Doe",
            },
            "addresses": [].
            "emails": [],
            "phoneNumbers": [],
            "__GROUPS__": [
                "groupId1",
                "groupId2"
            ]
        },
    ],
    "resultCount": 999,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}
To paginate the results, the maximum value of _pageSize is 100.
Get user

Return a user from AWS IAM Identity Center. The user ID must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__ACCOUNT__/USER_ID'
{
    "_id" : " "userId",
    "__NAME__": "jdoe",
    "displayName": "John Doe",
    "locale": "en-US",
    "nickname": "Johnny",
    "timezone": "America/New_York",
    "title": "Software Engineer",
    "profileUrl": "https://www.profile.com/jdoe",
    "userType": "employee",
    "preferredLanguage": "en",
    "name": {
        "givenName": "John",
        "middleName": "Michael",
        "familyName": "Doe",
        "honorificPrefix": "Sr.",
        "honorificSufix": "PhD",
        "formatted": "Sr. John Michael Doe, PhD"
    },
    "addresses": {
        "type": "home",
        "streetAddress": "123 Main St",
        "locality": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "USA",
        "primary": true,
        "formatted": "123 Main St, Springfield, IL 62701, USA"
    },
    "emails": {
        "type": "work",
        "value": "john.doe@example.com",
        "primary": true
    },
    "phoneNumbers": {
        "type": "mobile",
        "value": "+0101010101",
        "primary": true
    },
    "__GROUPS__": [
        "groupId1",
        "groupId2"
    ]
}
Get user by filter

Return a user from AWS IAM Identity Center:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__ACCOUNT___queryFilter=__NAME__%20eq%20"name"'
{
    "_id" : " "userId",
    "__NAME__": "jdoe",
    "displayName": "John Doe",
    "locale": "en-US",
    "nickname": "Johnny",
    "timezone": "America/New_York",
    "title": "Software Engineer",
    "profileUrl": "https://www.profile.com/jdoe",
    "userType": "employee",
    "preferredLanguage": "en",
    "name": {
        "givenName": "John",
        "middleName": "Michael",
        "familyName": "Doe",
        "honorificPrefix": "Sr.",
        "honorificSufix": "PhD",
        "formatted": "Sr. John Michael Doe, PhD"
    },
    "addresses": {
        "type": "home",
        "streetAddress": "123 Main St",
        "locality": "Springfield",
        "region": "IL",
        "postalCode": "62701",
        "country": "USA",
        "primary": true,
        "formatted": "123 Main St, Springfield, IL 62701, USA"
    },
    "emails": {
        "type": "work",
        "value": "john.doe@example.com",
        "primary": true
    },
    "phoneNumbers": {
        "type": "mobile",
        "value": "+0101010101",
        "primary": true
    },
    "__GROUPS__": [
        "groupId1",
        "groupId2"
    ]
}
The __NAME__ field only supports the equal filter.
Get users IDs

Return all users from AWS IAM Identity Center displaying only the _id field:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__ACCOUNT__?_queryId=query-all-ids'
{
    "result": [
        {
            "_id": "userID1"
        },
        ...
        {
            "_id": userID2"
        }
    ],
    "resultCount": 999,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}
Update user

Update a user in AWS IAM Identity Center. The user ID must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request PUT \
--data '{
    "__NAME__": "JonnyDoe",
    "displayName": "Jonny Doe",
    "locale": "US",
    "nickName": "JonnyDoe",
    "timezone": "UTC",
    "title": "",
    "profileUrl": "https://www.profile.com/jonnydoe",
    "userType": "USER",
    "preferredLanguage": "us-US",
    "name": {
        "givenName": "Jonny",
        "middleName": "Michael",
        "familyName": "Doe",
        "honorificPrefix": "Jr.",
        "honorificSufix": "PhD",
        "formatted": "Jr. John Michael Doe, PhD"
    },
    "addresses": {
        "type": "home",
        "streetAddress": "123 Main St",
        "locality": "Springfield",
        "region": "IL",
        "postalCode": "60999",
        "country": "US",
        "primary": true,
        "formatted": "123 Main St, Springfield, IL 62701, USA"
    },
    "emails": {
        "type": "home",
        "value": "johndoe@example.com",
        "primary": true
    },
    "phoneNumbers": {
        "type": "home",
        "value": "505050",
        "primary": true
    },
    "__GROUPS__": [
        "groupID1",
        "groupID2",
    ]
}' \
'http://localhost:8080/system/awsiam/__ACCOUNT__/USER_ID'
{
    "_id" : "userId",
    "__NAME__" : "JonnyDoe",
    "displayName" : "Jonny Doe",
    "locale" : "US",
    "nickName" : "JonnyDoe",
    "timezone" : "UTC",
    "title" : "",
    "profileUrl" : "https://www.profile.com/jonnydoe",
    "userType" : "USER",
    "preferredLanguage" : "us-US",
    "name" : {
        "givenName" : "Jonny",
        "middleName" : "middleName",
        "familyName" : "Doe",
        "honorificPrefix" : "Jr",
        "honorificSufix" : "PhD",
        "formatted" : "Jr. John Doe, PhD"
    },
    "addresses": {
        "type": "home",
        "streetAddress": "123 Main St",
        "locality": "Springfield",
        "region": "IL",
        "postalCode": "60999",
        "country": "US",
        "primary": true,
        "formatted": "123 Main St, Springfield, IL 62701, USA"
    },
    "emails" : {
        "type" : "home",
        "value" : "johndoe@example.com",
        "primary" : true
    },
    "phoneNumbers" : {
        "type" : "home",
        "value" : "505050",
        "primary" : true
    },
    "__GROUPS__" : [
        "groupID1",
        "groupID2",
    ]
}
Delete user

Delete a user in the AWS IAM Identity Center. The user ID must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request DELETE \
'http://localhost:8080/openidm/system/awsiam/__ACCOUNT__/USER_ID'
{
    "_id" : "userId",
    "__NAME__" : "JohnDoe",
    "displayName" : "John Doe",
    "locale" : "US",
    "nickName" : "JonnyDoe",
    "timezone" : "UTC",
    "title" : "",
    "profileUrl" : "www.example.doe",
    "userType" : "USER",
    "preferredLanguage" : "us-US",
    "name" : {
        "givenName" : "John",
        "middleName" : "middleName",
        "familyName" : "Doe",
        "honorificPrefix" : "Sr",
        "honorificSufix" : "PhD",
        "formatted" : "Sr. John Doe, PhD"
    },
    "addresses" : {
        "type" : "home",
        "streetAddress" : "false street",
        "locality" : "springfield",
        "region" : "north",
        "postalCode" : "0000",
        "country" : "US",
        "primary" : false,
        "formatted" : "no"
    },
    "emails" : {
        "type" : "home",
        "value" : "testeruser@example.com",
        "primary" : true
    },
    "phoneNumbers" : {
        "type" : "home",
        "value" : "505050",
        "primary" : true
    },
    "__GROUPS__" : [
        "groupID1",
        "groupID2",
    ]
}

GROUPS

Create group

To create a group in AWS IAM Identity Center, it is necessary to at least provide the __NAME__ field. The description field is optional:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
    "__NAME__" : "New Group",
    "description" : "Some description"
}' \
'http://localhost:8080/openidm/system/awsiam/__GROUP__?_action=create'
{
    "_id": "groupId",
    "description": "description",
    "__NAME__": "New Group",
    "externalIds": []
}
Get groups

Return all groups from AWS IAM Identity Center.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__GROUP__?_queryFilter=true'
{
    "result": [
        {
            "_id": "groupId1",
            "__NAME__": "Display name group 1",
            "description": "description",
            "externalIds": []
        },
        ...
        {
            "_id": "groupId99",
            "__NAME__": "Display name group 99",
            "description": "description",
            "externalIds": []
        }
    ],
    "resultCount": 99,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}
To paginate the results, the maximum value of _pageSize is 100.
Get groups IDs

Return all groups from AWS IAM Identity Center displaying only the _id field:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__GROUP__?_queryId=query-all-ids'
{
    "result": [
        {
            "_id": "groupID1",
        },
        ...
        {
            "_id": "groupID99",
        }
    ],
    "resultCount": 99,
    "pagedResultsCookie": null,
    "totalPagedResultsPolicy": "NONE",
    "totalPagedResults": -1,
    "remainingPagedResults": -1
}
Get group

Return a group from AWS IAM Identity Center. The group ID must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__GROUP__/GROUP_ID'
{
    "_id": "groupId",
    "description": "Some description",
    "__NAME__": "Group Name",
    "externalIds": []
}
Get group by filter

Return a group from AWS IAM Identity Center:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/awsiam/__GROUP___queryFilter=__NAME__%20eq%20"username"'
{
    "_id": "groupId",
    "description": "Some description",
    "__NAME__": "Group Name",
    "externalIds": []
}
The __NAME__ field only supports the equal filter.
Update a group

Update a group in AWS IAM Identity Center. The group ID must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request PUT \
--header 'If-Match: *' \
--data '{
    "__NAME__" : "New DisplayName",
    "description" : "New Description"
}' \
'http://localhost:8080/openidm/system/awsiam/__GROUP__/GROUP_ID'
{
    "_id": "groupId",
    "description": "New description",
    "__NAME__": "New DisplayName",
    "externalIds": []
}
Delete a group

Delete a group in AWS IAM Identity Center. The group ID must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request DELETE \
'http://localhost:8080/openidm/system/awsiam/__GROUP__/GROUP_ID'
{
    "_id": "groupId",
    "description": "description",
    "__NAME__": "deleted group",
    "externalIds": []
}

OpenICF Interfaces Implemented by the AWS IAM Identity Center Connector

The AWS IAM Identity Center 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.

AWS IAM Identity Center Connector Configuration

The AWS IAM Identity Center Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

accessKey

String

null

Yes

Provides the Access Key ID to access the AWS IAM IC Service API.

secretKey

GuardedString

null

Yes

Yes

Provides the Secret Key ID to access the AWS IAM IC Service API.

roleArn

String

null

Yes

Provides the Amazon Resource Name specifying the Role.

roleSessionName

String

null

Yes

Temporary name for the role session.

region

String

null

Yes

Provides the Regions.

identityStoreId

String

null

Yes

Provides the identity store ID for the user and group store.

sessionExpirationTime

Integer

3600

Yes

Provides the temporary Session expiration time in seconds.

proxyHost

String

null

No

Provides the Proxy Host.

proxyPort

String

null

No

Provides the Proxy Port.

proxyUsername

String

null

No

Provides the Proxy Username.

proxyPassword

GuardedString

null

Yes

No

Provides the Proxy Password.

connectionTimeout

Integer

null

No

Provides the Maximum Connection Timeout in seconds.

maxConnections

Integer

null

No

Provides the number of Maximum Connections.

readRateLimit

String

null

Yes

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

writeRateLimit

String

null

Yes

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

Box connector

This is a SaaS common connector.

The Box connector lets you manage Box service accounts and synchronize accounts and groups between Box and the IDM managed user repository.

This topic describes how to install and configure the Box connector and how to perform basic tests to ensure that it’s running correctly.

Before you start

The instructions in this guide assume you have a Box Administrator Account and you have created and authorized a Custom Application, as described in the Box Documentation. Before you configure the connector, log in to your administrator account and note the following information:

  • Client ID

  • Client Secret

  • Authentication Method

  • Grant Type

  • Subject Type

  • Subject ID

  • Service Uri

  • Token Endpoint

Install the Box connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Box

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/box-connector-1.5.20.23.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 Box 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 Box Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Box Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

The following excerpt shows sample configuration properties:

"configurationProperties": {
  "serviceUri" : "_CHANGEME_",
  "tokenEndpoint" : "_CHANGEME_",
  "clientId" : "_CHANGEME_",
  "clientSecret" : "_CHANGEME_",
  "acceptSelfSignedCertificates" : true,
  "disableHostNameVerifier" : true,
  "authenticationMethod" : "_CHANGEME_",
  "grantType" : "_CHANGEME_",
  "useBasicAuthForOauthTokenNeg" : false,
  "boxSubjectType" : "_CHANGEME_",
  "boxSubjectId" : "_CHANGEME_"
  "rateLimit": "_CHANGEME_"
}
serviceUri

The Box API hostname. In most cases it should be https://api.box.com/2.0.

tokenEndpoint

URL to obtain access tokens and refresh tokens. In most cases it should be https://api.box.com/oauth2/token.

clientId

The Box Application Client ID. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > Configuration > OAuth 2.0 Credentials > Client ID.

clientSecret

The Box Application Secret Key. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > Configuration > OAuth 2.0 Credentials > Client Secret.

acceptSelfSignedCertificates

The acceptSelfSignedCertificates option enables Box Sync to connect to Box servers that present self-signed digital certificates.

disableHostNameVerifier

The disableHostNameVerifier is a configuration option used to disable host name verification on HTTPS connections.

grantType

Parameter used within the OAuth 2.0 authorization flow to specify the type of grant being used to obtain an access token. The only value supported is client_credentials.

boxSubjectType

The Box Application SubjectType. User or Enterprise, according to availability. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > General Settings > UserID / EnterpriseID.

boxSubjectId

The Box Application User ID or Enterprise ID. It must match with the selected boxSubjectType. To locate this value, log in to your Box account and go to Dev Console > Box Developer > My Apps > Select the app > General Settings > UserID / EnterpriseID.

rateLimit

Limits how many requests the connector makes over a certain period of time. The default value is 1000 requests per minute (1000/min) as described in the Box Documentation. Additional examples: 997/min or 600/sec.

If throttling problems occur, this guide can be helpful:

Improve reconciliation query performance

Test the Box connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
'http://localhost:8080/openidm/system/box?_action=test'
{
  "name": box,
  "enabled": true,
  "config": "config/provisioner.openicf/box",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.box-connector",
    "connectorName": "org.forgerock.openicf.connectors.box.BoxConnector"
  },
  "displayName": "org.forgerock.openicf.connectors.box.BoxConnector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__",
    "__GROUP__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly and can authenticate to the Box server.

Box remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Box connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Box connector from here.

Refer to Remote connectors for configuring the Box remote connector.

Use the Box connector

You can use the Box connector to perform the following actions on a Box account.

Users

Create a Box user

This example creates a Box user with the minimum required attributes.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \ \
--header 'Content-Type: application/json' \
--request POST \
--data '{
  "__NAME__": "Jane Doe",
  "login": "janeDoe@example.com"
}' \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__'
{
  "_id": "34383152830",
  "hostname": "https://app.box.com/",
  "__NAME__": "Jane Doe",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "",
  "space_amount": "1.000000456753152E15",
  "phone": "",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "janedoe@nexter.net",
  "avatar_url": "https://app.box.com/api/avatar/large/34721687671",
  "role": "user",
  "address": "",
  "is_platform_access_only": "false"
}

When you create a new user, you must specify at least the login and __NAME__ attributes. The login attribute is typically the user’s email address.
Create a Box full user

This example creates a Box full user.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Designer",
  "space_amount": "1.000000456753152E15",
  "phone": "578945621",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": ["20013904637", "20013904699"],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "San Carlos Buenos Aires",
  "is_platform_access_only": "false"
}' \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__'
{
  "_id": "34721853021",
  "hostname": "https://app.box.com/",
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Designer",
  "space_amount": "1.000000456753152E15",
  "phone": "578945621",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "San Carlos, Buenos Aires",
  "is_platform_access_only": "false"
}

Attribute limitations:

  • job_title: Max length 100.

  • phone: Max length 100.

  • address: Max length 255.

  • language: The language of the user, formatted in a modified version of the ISO 639-1 format.

  • role: The user’s enterprise role. Value is coadmin or user.

  • status: Value is one of active, inactive, cannot_delete_edit, cannot_delete_edit_upload.

  • space_amount: (int64) The user’s total available space in bytes. Set this to -1 to indicate unlimited storage.

  • timezone: The user’s timezone. Example: "Africa/Bujumbura".
List all Box users

This example queries all Box users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__?_queryFilter=True'
{
  "result": [
    {
      "_id": "34383152830",
      "hostname": "https://app.box.com/",
      "__NAME__": "Jane Doe",
      "is_exempt_from_device_limits": "false",
      "type": "user",
      "job_title": "",
      "space_amount": "1.000000456753152E15",
      "phone": "",
      "status": "active",
      "enterprise": [
        {
          "type": "enterprise",
          "id": "1162568706",
          "name": "testing"
        }
      ],
      "can_see_managed_users": "true",
      "is_external_collab_restricted": "false",
      "external_app_user_id": null,
      "is_exempt_from_login_verification": "false",
      "is_sync_enabled": "true",
      "groups": [],
      "max_upload_size": "5.36870912E10",
      "language": "en",
      "login": "janedoe@nexter.net",
      "avatar_url": "https://app.box.com/api/avatar/large/34383152830",
      "role": "user",
      "address": "",
      "is_platform_access_only": "false"
    },
    ...
    {
      "_id": "34721853021",
      "hostname": "https://app.box.com/",
      "__NAME__": "Miguel Benitez",
      "is_exempt_from_device_limits": "false",
      "type": "user",
      "job_title": "Designer",
      "space_amount": "1.000000456753152E15",
      "phone": "578945621",
      "status": "active",
      "enterprise": [
        {
          "type": "enterprise",
          "id": "1162568706",
          "name": "testing"
        }
      ],
      "can_see_managed_users": "true",
      "is_external_collab_restricted": "false",
      "external_app_user_id": null,
      "is_exempt_from_login_verification": "false",
      "is_sync_enabled": "true",
      "groups": ["20013904637", "20013904699"],
      "max_upload_size": "5.36870912E10",
      "language": "en",
      "login": "someone@example.com",
      "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
      "role": "user",
      "address": "San Carlos, Buenos Aires",
      "is_platform_access_only": "false"
    }
  ],
  "resultCount": 10,
  "pagedResultsCookie": "eyJ0eXBlIjoiaWQiLCJkaXIiOiJuZXh0IiwidGFpbCI6IjM0NzIxODUzMDIxIn0",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

  • For pagedResultsCookie, the last page returned is empty.

  • startsWith for __NAME__ is the only filter available.
List all Box user IDs

This example queries all Box users by their IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__?_queryId=query-all-ids'
{
  "result": [
    {
      "_id": "32996521506"
    },
    ...
    {
      "_id": "34721853021"
    }
  ],
  "resultCount": 10,
  "pagedResultsCookie": "eyJ0eXBlIjoiaWQiLCJkaXIiOiJuZXh0IiwidGFpbCI6IjM0NzIxODUzMDIxIn0",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Get Box user

The following command queries a specific Box user by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__/34721853021'
{
  "_id": "34721853021",
  "hostname": "https://app.box.com/",
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "",
  "space_amount": "1.000000456753152E15",
  "phone": "578945621",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "San Carlos, Buenos Aires",
  "is_platform_access_only": "false"
}
Update a Box user

The following command updates a specific Box user by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request PUT \
--data '{
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Web Developer",
  "space_amount": "1.000000456753152E15",
  "phone": "1157199024",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [agregarle el grupo que esta arriba],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "Puerto La Cruz P.R",
  "is_platform_access_only": "false"
}' \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__/34721853021'
{
  "_id": "34721853021",
  "hostname": "https://app.box.com/",
  "__NAME__": "Miguel Benitez",
  "is_exempt_from_device_limits": "false",
  "type": "user",
  "job_title": "Web Developer",
  "space_amount": "9.99999999999999E14",
  "phone": "1157199024",
  "status": "active",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "can_see_managed_users": "true",
  "is_external_collab_restricted": "false",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "is_sync_enabled": "true",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "max_upload_size": "5.36870912E10",
  "language": "en",
  "login": "someone@example.com",
  "avatar_url": "https://app.box.com/api/avatar/large/34721853021",
  "role": "user",
  "address": "Puerto La Cruz, P.R",
  "is_platform_access_only": "false"
}

If the target user’s email is not confirmed, you can’t change the primary login email address.
Delete a Box user

The following example deletes a Box user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request DELETE \
'http://localhost:8080/openidm/system/Box/__ACCOUNT__/34721853021'
{
  "_id": "34721853021",
  "is_platform_access_only": "false",
  "is_sync_enabled": "true",
  "avatar_url": "https://app.box.com/api/avatar/large/34740572881",
  "hostname": "https://app.box.com/",
  "external_app_user_id": null,
  "is_exempt_from_login_verification": "false",
  "groups": [
    "20013904637",
    "20013904699"
  ],
  "type": "user",
  "enterprise": [
    {
      "type": "enterprise",
      "id": "1162568706",
      "name": "testing"
    }
  ],
  "max_upload_size": "5.36870912E10",
  "__NAME__": "Miguel Benitez",
  "space_amount": "9.99999999999999E14",
  "language": "en",
  "is_external_collab_restricted": "false",
  "address": "Puerto La Cruz, P.R",
  "can_see_managed_users": "true",
  "job_title": "Web Developer",
  "is_exempt_from_device_limits": "false",
  "status": "active",
  "role": "user",
  "phone": "1157199024",
  "login": "someone@example.com"
}

The response returns the user object before deletion.

GROUPS

Create a Box group

This example creates a Box group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request POST \
--data '{
  "type": "group",
  "description": "Support Group - as imported from Active Directory",
  "external_sync_identifier": "AD:123456",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "permissions": {
    "can_invite_as_collaborator": true
  },
  "provenance": "Active Directory"
}' \
'http://localhost:8080/openidm/system/Box/__GROUP__'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}
Query all Box groups

This example queries all Box groups:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__GROUP__?_queryFilter=True'
{
  "result": [
    {
      "_id": "20005069402",
      "provenance": null,
      "description": "generic_description",
      "group_type": "managed_group",
      "invitability_level": "all_managed_users",
      "member_viewability_level": "all_managed_users",
      "__NAME__": "A_20240611161336713",
      "type": "group",
      "external_sync_identifier": null
    },
    ...
    {
      "_id": "20147818911",
      "provenance": "Active Directory",
      "description": "Support Group - as imported from Active Directory",
      "group_type": "managed_group",
      "invitability_level": "admins_only",
      "member_viewability_level": "admins_only",
      "__NAME__": "Support",
      "type": "group",
      "external_sync_identifier": "AD:123456"
    }
  ],
  "resultCount": 22,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Get a Box group

This example gets a Box group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--request GET \
'http://localhost:8080/openidm/system/Box/__GROUP__/20147818911'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}
Update a Box group

This example updates a Box group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request PUT \
--data '{
  "type": "group",
  "description": "Support Group - as imported from Active Directory",
  "external_sync_identifier": "AD:123456",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "name": "Support",
  "permissions": {
    "can_invite_as_collaborator": true
  },
  "provenance": "Active Directory"
}' \
'http://localhost:8080/openidm/system/Box/__GROUP__/20147818911'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}

Other fields you can update are:

  • invitability_level: Specifies who can invite the group to collaborate on folders. Available values:

    • admins_only

    • admins_and_members

    • all_managed_users

  • member_viewability_level: Specifies who can see the members of the group. Available values:

    • admins_only

    • admins_and_members

    • all_managed_users

  • provenance: Max length 255
Delete a Box group

This example deletes a Box group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--header "If-Match: *" \
--request DELETE \
'http://localhost:8080/openidm/system/Box/__GROUP__/20147818911'
{
  "_id": "20147818911",
  "provenance": "Active Directory",
  "description": "Support Group - as imported from Active Directory",
  "group_type": "managed_group",
  "invitability_level": "admins_only",
  "member_viewability_level": "admins_only",
  "__NAME__": "Support",
  "type": "group",
  "external_sync_identifier": "AD:123456"
}

The response returns the group object before deletion.

Mapping

From Box users to IDM users

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

id

userId

N/A

__NAME__

UserName

N/A

enterprise

enterprise

N/A

external_app_user_id

external_app_user_id

N/A

login

mail

N/A

type

type

N/A

address

address

N/A

avatar_url

avatar_url

N/A

can_see_managed_users

can_see_managed_users

N/A

hostname

hostname

N/A

is_exempt_from_device_limits

is_exempt_from_device_limits

N/A

is_exempt_from_login_verification

is_exempt_from_login_verification

N/A

job_title

job_title

N/A

phone

phone

N/A

space_amount

space_amounts

N/A

max_upload_size

max_upload_size

N/A

language

language

N/A

status

status

N/A

memberof

memberof

N/A

is_sync_enabled

is_sync_enabled

N/A

is_external_collab_restricted

is_external_collab_restricted

N/A

is_platform_access_only

is_platform_access_only

N/A

role

role

N/A
From IDM users to Box users

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE

TARGET

TRANSFORMATION SCRIPT

userId

id

N/A

UserName

__NAME__

N/A

enterprise

enterprise

N/A

external_app_user_id

external_app_user_id

N/A

mail

login

N/A

type

type

N/A

address

address

N/A

avatar_url

avatar_url

N/A

can_see_managed_users

can_see_managed_users

N/A

hostname

hostname

N/A

is_exempt_from_device_limits

is_exempt_from_device_limits

N/A

is_exempt_from_login_verification

is_exempt_from_login_verification

N/A

job_title

job_title

N/A

phone

phone

N/A

space_amount

space_amounts

N/A

max_upload_size

max_upload_size

N/A

language

language

N/A

status

status

N/A

memberof

memberof

N/A

is_sync_enabled

is_sync_enabled

N/A

is_external_collab_restricted

is_external_collab_restricted

N/A

is_platform_access_only

is_platform_access_only

N/A

role

role

N/A
From Box groups to IDM groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

_id

_id

N/A

__NAME__

groupName

N/A

group_type

group_type

N/A

invitability_level

invitability_level

N/A

permissions

can_invite_as_collaborator

source.can_invite_as_collaborator

external_sync_identifier

external_sync_identifier

N/A

provenance

provenance

N/A

description

description

N/A

member_viewability_level

member_viewability_level

N/A

type

type

N/A
From IDM groups to Box groups

Attributes Grid: Where the columns represent the attribute name mapped from source to target and the necessary data transformation to synchronize successfully.

SOURCE TARGET TRANSFORMATION SCRIPT

groupName

__NAME__

N/A

group_type

group_type

N/A

_id

_id

N/A

invitability_level

invitability_level

N/A

can_invite_as_collaborator

permissions

source.can_invite_as_collaborator

external_sync_identifier

external_sync_identifier

N/A

provenance

provenance

N/A

description

description

N/A

member_viewability_level

member_viewability_level

N/A

type

type

N/A

OpenICF Interfaces Implemented by the Box.com Connector

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

Box.com Connector Configuration

The Box.com Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

serviceUri

String

null

Yes

The service endpoint URI.

boxSubjectType

String

null

Yes

Description is not available

login

String

null

Yes

The service login name.

boxSubjectId

String

null

Yes

Description is not available

password

GuardedString

null

Yes

No

The service user password.

rateLimit

String

null

Yes

Description is not available

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

tokenEndpoint

String

null

No

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

clientId

String

null

Yes

Client Id of the application registered at Box.com.

clientSecret

GuardedString

null

Yes

No

Client Secret of the application registered at Box.com.

authToken

GuardedString

null

Yes

No

Static authentication token.

acceptSelfSignedCertificates

boolean

false

Yes

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

disableHostNameVerifier

boolean

false

Yes

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

disableHttpCompression

boolean

false

Yes

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

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

httpProxyHost

String

null

Yes

Defines the Hostname if an HTTP proxy is used between the connector and the service.

httpProxyPort

Integer

null

Yes

Defines the Port if an HTTP proxy is used between the connector and the service.

httpProxyUsername

String

null

Yes

Defines Proxy Username if an HTTP proxy is used between the connector and the service.

httpProxyPassword

GuardedString

null

Yes

Yes

Defines Proxy Password if an HTTP proxy is used between the connector and the service.

connectionTimeout

int

30

No

Defines a timeout for the underlying HTTP connection in seconds.

refreshToken

GuardedString

null

No

A refresh token retrieved in the final leg of OAuth 2. In most cases these are valid for 60 days, or until used.

grantType

String

null

No

The OAuth2 grant type to use (client_credentials or refresh_token).

scope

String

null

No

The OAuth2 scope to use.

authorizationTokenPrefix

String

Bearer

No

The prefix to be used in the Authorization HTTP header for Token authentication.

useBasicAuthForOauthTokenNeg

boolean

true

Yes

The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).

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

Cerner connector

Cerner is a healthcare-related service which provides an integrated healthcare IT solution for large healthcare providers. The Cerner connector lets you manage and synchronize accounts between Cerner and IDM managed user objects. A Cerner system account is required for this connector to work.

Before you start

Before you configure the connector, log in to your Cerner system account and note the following:

Bearer token

The bearer token associated with your system account.

Tenant

Your Cerner tenant ID.

Region

The Cerner Cloud region where the tenant resides.

Install the Cerner connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Cerner

No

Yes

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/cerner-connector-1.5.20.23.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 Cerner 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 Cerner Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Cerner Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Test the Cerner connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/Cerner?_action=test"
{
  "name": "Cerner",
  "enabled": true,
  "config": "config/provisioner.openicf/Cerner",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.cerner-connector",
    "connectorName": "org.forgerock.openicf.connectors.cerner.CernerConnector"
  },
  "displayName": "Cerner Connector",
  "objectTypes": [
    "__ORGANIZATION__",
    "__ACCOUNT__",
    "__ORGANIZATIONGROUP__",
    "__ALL__",
    "__PERSONNELGROUP__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the Cerner system.

Cerner remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Cerner connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Cerner connector from here.

Refer to Remote connectors for configuring the Cerner remote connector.

Use the Cerner connector

Supported object types
Connector resource Cerner resource type

__ACCOUNT__

Personnel

__ORGANIZATION__

Organization

__PERSONNELGROUP__

Personnel Group

__ORGANIZATIONGROUP__

Organization Group
__ACCOUNT__ attributes
Attribute Notes

__NAME__

The user’s name, in a FAMILY, GIVEN format. Required.

birthDate

Must be in YYYY-MM-DD format.

gender

Accepted values are MALE, FEMALE, OTHER, UNKNOWN.

given

The user’s first name. Required.

family

The user’s last name. Required.

name

given

middle

family

suffix

prefix

addresses

postalCode

country

use

Accepted values are HOME or WORK.

city

state

lines

The street portion of the address.

aliasType

Accepted values are: SPI, TAX, SL, EXTERNAL, UPIN, USER, or UNKNOWN. Required.

aliasValue

aliasSystem

sourceIdentifiers

id

dataPartitionId

qualifications

issuer

code

Qualification code such as MD or PhD.

Accepted values are: AA, AAS, ABA, AE, AS, BA, BBA, BE, BFA, BN, BS, BSL, BSN, BT, CANP, CER, CMA, CNM, CNP, CNS, CPNP, CRN, CTR, DBA, DED, DIP, DO, EMT, EMTP, FPNP, HS, JD, MA, MBA, MCE, MD, MDA, MDI, ME, MED, MEE, MFA, MME, MS, MSL, MSN, MT, MTH, NG, NP, PA, PHD, PHE, PNS, PN, PharmD, RMA, RN, RPH, SEC, or TS.

start

The first date and time that the qualification is valid, in a YYYY-MM-DDThh:mm:ssZ date format.

end

The date and time that the qualification expires, in a YYYY-MM-DDThh:mm:ssZ date format.

telecoms

system

Accepted values are PHONE, EMAIL, or OTHER.

value

languages

For a list of valid language tags, refer to the Internet Assigned Numbers Authority (IANA) language subtag registry.
__ORGANIZATION__ attributes
Attribute Notes

__NAME__

The name of the organization. This corresponds to aliasValue, aliasSystem, comma separated. Required.

name

The name of the organization. Required.

aliasType

Alias types related to the organization. DEA, TAX, SOI, and NPI are supported for queries. Organizations with NPI and DEA cannot be created or updated.

telecoms

system

Accepted values are PHONE, EMAIL, or OTHER.

value

addresses

postalCode

country

text

Formatted display text of the address.

city

state

lines

The street portion of the address.

aliases

type

Types of alias for the organization.

system

value

languages

For a list of valid language tags, refer to the Internet Assigned Numbers Authority (IANA) language subtag registry.

coverageAreaPostalCodes

The postal codes indicating the area of coverage provided by the organization.

sourceIdentifiers

id

dataPartitionId
__PERSONNELGROUP__ attributes
Attribute Notes

__NAME__

A comma-separated name for the personnel group.

mnemonic

The mnemonic determines the function of the personnel group.

mnemonicType

The type of the personnel group mnemonic. Usually either SINGLETON or MULTIVALUED.

name

The name of the personnel group.

aliases

type

system

value

aliasType

The type of alias. Requires aliasValue and aliasSystem.

aliasSystem

The source of the alias value. Requires aliasType and aliasValue.

aliasValue

The unique identifier of alias. Requires aliasType and aliasSystem.
__ORGANIZATIONGROUP__ attributes
Attribute Notes

__NAME__

A comma-separated name for the organization group.

organizationId

A list of organization IDs that are members of the organization group.

name

The name of the organization group.

aliases

type

system

value

aliasType

The type of alias. Requires aliasValue and aliasSystem.

aliasSystem

The source of the alias value. Requires aliasType and aliasValue.

aliasValue

The unique identifier of alias. Requires aliasType and aliasSystem.

You can use the Cerner connector to perform the following actions on a Cerner account:

Create a Cerner user

The following example creates a user with the minimum required attributes:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "given": "Barbara",
  "family": "Jensen",
  "aliasType": "USER",
  "__NAME__": "Jensen, Barbara"
}' \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__?_action=create"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "updatedAt": "2022-04-29T22:54:08Z",
  "given": "Barbara",
  "name": {
    "given": "Barbara",
    "family": "Jensen",
    "formatted": "Barbara Jensen"
  },
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "languages": [],
  "formattedName": "Barbara Jensen",
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "aliasValue": "Jensen",
  "__NAME__": "Jensen,Barbara",
  "createdAt": "2022-04-29T22:54:08Z",
  "aliasType": "USER",
  "family": "Jensen",
  "isManual": true,
  "aliasSystem": "Barbara"
}

When you create a new user, you must specify at least __NAME__, aliasType, given, and family. Refer to the list of account attributes for more information.
Update a Cerner user

You can modify an existing user with a PUT request, including all attributes of the account in the request:

For example, to add the user’s middle name:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "given": "Barbara",
  "family": "Jensen",
  "aliasType": "USER",
  "__NAME__": "Jensen, Barbara",
  "name": {
    "middle": "Simone"
  }
}' \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__/5170a9cd-e501-4cbf-a1bf-9e6d293362c6"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "updatedAt": "2022-04-29T23:03:57Z",
  "given": "Barbara",
  "name": {
    "given": "Barbara",
    "middle": "Simone",
    "family": "Jensen",
    "formatted": "Barbara Simone Jensen"
  },
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "languages": [],
  "formattedName": "Barbara Simone Jensen",
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "aliasValue": "Jensen",
  "__NAME__": "Jensen,Barbara",
  "createdAt": "2022-04-29T22:54:08Z",
  "aliasType": "USER",
  "family": "Jensen",
  "isManual": true,
  "aliasSystem": "Barbara"
}
Query Cerner users

The following example queries all Cerner users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "7d9538c8-1c2a-4894-a403-129b35308f39"
    },
    {
      "_id": "8f1c2671-9ebb-4105-9537-a3a0fc24afce"
    },
    {
      "_id": "ac944860-705f-4487-99bf-6959c5e6157c"
    },
    {
      "_id": "d308e459-51fa-469a-a07e-72f96906a4b4"
    },
    {
      "_id": "ff9d6902-20be-4c6e-821a-5a0f3ccaebc8"
    },
    {
      "_id": "bf2b9346-715e-4f59-9dc5-2bc89b8216cd"
    },
    {
      "_id": "055def33-a845-4100-bcd1-2b59a3526ec5"
    },
    {
      "_id": "167609b8-dfd0-4302-9022-4a3e8809b166"
    },
    [ ... ]
    {
      "_id": "9f4ea23d-bacc-46ee-b8c9-75916a5f5128"
    },
    {
      "_id": "a4d6be21-a5ce-4a56-91af-94c627701d4f"
    }
  ],
  "resultCount": 1020,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Querying all ids can take a significant amount of time to return when the data set is large. Consider using paginated results instead, for example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__?_queryFilter=true&_fields=_id&_pageSize=2&_pagedResultsOffset=50"
{
  "result": [
    {
      "_id": "878c87d4-8322-4908-a858-555a1cb45e36"
    },
    {
      "_id": "9ecaa98b-58df-4dd1-bc99-34341411b151"
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The following command queries a specific user by their ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__/5170a9cd-e501-4cbf-a1bf-9e6d293362c6"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "updatedAt": "2022-04-29T23:03:57Z",
  "given": "Barbara",
  "name": {
    "given": "Barbara",
    "middle": "Simone",
    "family": "Jensen",
    "formatted": "Barbara Simone Jensen"
  },
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "languages": [],
  "formattedName": "Barbara Simone Jensen",
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "aliasValue": "Jensen",
  "__NAME__": "Jensen,Barbara",
  "createdAt": "2022-04-29T22:54:08Z",
  "aliasType": "USER",
  "family": "Jensen",
  "isManual": true,
  "aliasSystem": "Barbara"
}
Delete a Cerner user account

You can use the Cerner connector to delete an account from the Cerner repository.

The following example deletes a Cerner account:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request DELETE \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__/5170a9cd-e501-4cbf-a1bf-9e6d293362c6"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "updatedAt": "2022-04-29T23:03:57Z",
  "given": "Barbara",
  "name": {
    "given": "Barbara",
    "middle": "Simone",
    "family": "Jensen",
    "formatted": "Barbara Simone Jensen"
  },
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "languages": [],
  "formattedName": "Barbara Simone Jensen",
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "aliasValue": "Jensen",
  "__NAME__": "Jensen,Barbara",
  "createdAt": "2022-04-29T22:54:08Z",
  "aliasType": "USER",
  "family": "Jensen",
  "isManual": true,
  "aliasSystem": "Barbara"
}

All supported resources can be queried. You can update user accounts, organizations, organization groups, and personnel groups, but only user accounts can be created or deleted. Available additional operations include:

Assign personnel groups to a user 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "given": "Barbara",
  "family": "Jensen",
  "aliasType": "USER",
  "__NAME__": "Jensen, Barbara",
  "name": {
    "middle": "Simone"
  },
  "personnelGroupId": [
  	"8636d4c3-de7c-4f8a-828b-b709d6bfd636"
  ]
}' \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__/5170a9cd-e501-4cbf-a1bf-9e6d293362c6"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "formattedName": "Barbara Simone Jensen",
  "__NAME__": "Jensen,Barbara",
  "aliasValue": "Jensen",
  "family": "Jensen",
  "updatedAt": "2022-10-25T23:50:31Z",
  "aliasType": "USER",
  "given": "Barbara",
  "organizationId": [],
  "aliasSystem": "Barbara",
  "name": {
    "given": "Barbara",
    "middle": "Simone",
    "family": "Jensen",
    "formatted": "Barbara Simone Jensen"
  },
  "languages": [],
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "isManual": true,
  "personnelGroupId": [
    "8636d4c3-de7c-4f8a-828b-b709d6bfd636"
  ],
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "createdAt": "2022-04-29T22:54:08Z"
}
Remove a user from a personnel group 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "given": "Barbara",
  "family": "Jensen",
  "aliasType": "USER",
  "__NAME__": "Jensen, Barbara",
  "name": {
    "middle": "Simone"
  },
  "personnelGroupId": []
}' \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__/5170a9cd-e501-4cbf-a1bf-9e6d293362c6"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "formattedName": "Barbara Simone Jensen",
  "__NAME__": "Jensen,Barbara",
  "aliasValue": "Jensen",
  "family": "Jensen",
  "updatedAt": "2022-10-26T00:03:40Z",
  "aliasType": "USER",
  "given": "Barbara",
  "organizationId": [],
  "aliasSystem": "Barbara",
  "name": {
    "given": "Barbara",
    "middle": "Simone",
    "family": "Jensen",
    "formatted": "Barbara Simone Jensen"
  },
  "languages": [],
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "isManual": true,
  "personnelGroupId": [],
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "createdAt": "2022-04-29T22:54:08Z"
}
Assign an organization member 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "given": "Barbara",
  "family": "Jensen",
  "aliasType": "USER",
  "__NAME__": "Jensen, Barbara",
  "name": {
    "middle": "Simone"
  },
  "organizationId": [
    "c66f037b-50f5-4703-b51f-838f42a49e84"
  ]
}' \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__/5170a9cd-e501-4cbf-a1bf-9e6d293362c6"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "formattedName": "Barbara Simone Jensen",
  "__NAME__": "Jensen,Barbara",
  "aliasValue": "Jensen",
  "family": "Jensen",
  "updatedAt": "2022-10-26T00:03:40Z",
  "aliasType": "USER",
  "given": "Barbara",
  "organizationId": [
    "c66f037b-50f5-4703-b51f-838f42a49e84"
  ],
  "aliasSystem": "Barbara",
  "name": {
    "given": "Barbara",
    "middle": "Simone",
    "family": "Jensen",
    "formatted": "Barbara Simone Jensen"
  },
  "languages": [],
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "isManual": true,
  "personnelGroupId": [],
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "createdAt": "2022-04-29T22:54:08Z"
}
Remove an organization member 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "given": "Barbara",
  "family": "Jensen",
  "aliasType": "USER",
  "__NAME__": "Jensen, Barbara",
  "name": {
    "middle": "Simone"
  },
  "organizationId": []
}' \
"http://localhost:8080/openidm/system/Cerner/__ACCOUNT__/5170a9cd-e501-4cbf-a1bf-9e6d293362c6"
{
  "_id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "formattedName": "Barbara Simone Jensen",
  "__NAME__": "Jensen,Barbara",
  "aliasValue": "Jensen",
  "family": "Jensen",
  "updatedAt": "2022-10-26T00:03:40Z",
  "aliasType": "USER",
  "given": "Barbara",
  "organizationId": [],
  "aliasSystem": "Barbara",
  "name": {
    "given": "Barbara",
    "middle": "Simone",
    "family": "Jensen",
    "formatted": "Barbara Simone Jensen"
  },
  "languages": [],
  "id": "5170a9cd-e501-4cbf-a1bf-9e6d293362c6",
  "isManual": true,
  "personnelGroupId": [],
  "aliases": {
    "type": "USER",
    "value": "Jensen",
    "system": "Barbara"
  },
  "createdAt": "2022-04-29T22:54:08Z"
}
Assign an organization to an organization group 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "organizationId": [
    "f90a6224-1880-4935-a838-e19d3079a23c",
    "19b5157e-6fbe-4716-860b-28d6df90f331",
    "c66f037b-50f5-4703-b51f-838f42a49e84"
  ]
}' \
"http://localhost:8080/openidm/system/Cerner/__ORGANIZATIONGROUP__/67203020-aae7-4f44-865f-c8591d618ffc"
{
  "_id": "67203020-aae7-4f44-865f-c8591d618ffc",
  "organizationId": [
    "c66f037b-50f5-4703-b51f-838f42a49e84",
    "f90a6224-1880-4935-a838-e19d3079a23c",
    "19b5157e-6fbe-4716-860b-28d6df90f331"
  ],
  "updatedAt": "2022-05-06T12:56:02Z",
  "aliases": {
    "type": "SOGI",
    "value": "0001ORGVALUE",
    "system": "0001System"
  },
  "id": "67203020-aae7-4f44-865f-c8591d618ffc",
  "aliasType": "SOGI",
  "aliasValue": "0001ORGVALUE",
  "aliasSystem": "0001System",
  "name": "ABC SK ORG GROUP",
  "createdAt": "2022-05-06T12:56:02Z",
  "__NAME__": "0001ORGVALUE,0001System"
}
Remove an organization from an organization group 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "organizationId": [
    "f90a6224-1880-4935-a838-e19d3079a23c",
    "19b5157e-6fbe-4716-860b-28d6df90f331"
  ]
}' \
"http://localhost:8080/openidm/system/Cerner/__ORGANIZATIONGROUP__/67203020-aae7-4f44-865f-c8591d618ffc"
{
  "_id": "67203020-aae7-4f44-865f-c8591d618ffc",
  "organizationId": [
    "f90a6224-1880-4935-a838-e19d3079a23c",
    "19b5157e-6fbe-4716-860b-28d6df90f331"
  ],
  "updatedAt": "2022-05-06T12:56:02Z",
  "aliases": {
    "type": "SOGI",
    "value": "0001ORGVALUE",
    "system": "0001System"
  },
  "id": "67203020-aae7-4f44-865f-c8591d618ffc",
  "aliasType": "SOGI",
  "aliasValue": "0001ORGVALUE",
  "aliasSystem": "0001System",
  "name": "ABC SK ORG GROUP",
  "createdAt": "2022-05-06T12:56:02Z",
  "__NAME__": "0001ORGVALUE,0001System"
}

OpenICF Interfaces Implemented by the Cerner Connector

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

Cerner Connector Configuration

The Cerner Connector has the following configurable properties:

Configuration properties

Property Type Default Encrypted(1) Required(2)

bearerToken

GuardedString

null

Yes

Yes

Provides the bearer token to authorize Cerner.

tenant

String

playground

No

Provides the tenant to authorize Cerner.

region

String

us-1

No

Provides the region to authorize Cerner.

maximumConnections

Integer

10

No

Provides the maximum connections.

connectionTimeout

Integer

300

No

Provides the maximum connection timeout in seconds.

httpProxyHost

String

null

Yes

Provides the Proxy Host.

httpProxyPort

Integer

null

Yes

Provides the Proxy Port.

httpProxyUsername

String

null

Yes

Provides the Proxy Username.

httpProxyPassword

GuardedString

null

Yes

Yes

Provides the Proxy Password.

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

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.

Install the CSV file connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

CSV file

Yes

Yes

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/csvfile-connector-1.5.20.23.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 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.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to CSV file Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Alternatively, use the sample CSV file connector configuration in openidm/samples/example-configurations/provisioners/provisioner.openicf-csvfile.json as a basis for your configuration.

The following example shows an excerpt of the connector configuration. The connectorHostRef property is optional and must be provided only if the connector runs remotely.

{
    "connectorRef": {
        "connectorHostRef": "#LOCAL",
        "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector",
        "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
        "bundleVersion": "[1.5.0.0,1.6.0.0)"
    }
}

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, refer to 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.

CSV file remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the CSV file connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the CSV file connector from here.

Refer to Remote connectors for configuring the CSV file remote connector.

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.

escapeCharacter

String

\

No

The character in the CSV file that is used to escape characters.

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.

Install the Database Table connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Database table

Yes

Yes

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/databasetable-connector-1.5.20.23.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 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.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Database Table Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Alternatively, use the sample connector configuration for the Database Table connector in samples/example-configurations/provisioners/provisioner.openicf-contractordb.json. The corresponding data definition language file is provided in samples/example-configurations/provisioners/provisioner.openicf-contractordb.sql.

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 IDM, 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 IDM 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.

Tomcat JDBC connection pool

The Database Table connector uses the Apache Tomcat JDBC Connection Pool. Additional configurable properties and information are available in the Apache Tomcat documentation.

Database Table remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Database Table connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Database Table connector from here.

Refer to Remote connectors for configuring the Database Table remote connector.

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 11gR2 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, refer to 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-2629388]

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 Properties

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

If set to true then the JDBC Statement.RETURN_GENERATED_KEYS is used for prepared statement. It may need to be set to false with Oracle JDBC driver for create() operation. Defaults to tue.

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

DocuSign connector

This is a SaaS common connector.

The DocuSign connector lets you manage DocuSign service accounts and synchronize accounts between DocuSign and the IDM 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.

Only applicable to connector version 1.5.20.21 and lower.

For a complete example that includes the configuration required to synchronize users with this connector, refer to Synchronize data between IDM and DocuSign.

Before you start

The instructions in this guide 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:

  • Secret Key

  • API Account ID

  • Integration Key

  • Account Base URI

  • Hourly Limit

  • Burst Limit

Install the DocuSign connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

DocuSign

No

No

Download the connector .jar file from Backstage.

  • 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.23.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 DocuSign 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 DocuSign Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to DocuSign Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Alternatively, configure the connector with a configuration file. IDM provides a sample connector configuration file in the /path/to/openidm/samples/example-configurations/provisioners directory. Copy this sample file (provisioner.openicf-docusign.json) to your project’s conf directory.

The following excerpt shows sample configuration properties:

"configurationProperties": {
    "serviceUri" : "_CHANGEME_",
    "clientId" : "_CHANGEME_",
    "clientSecret" : "_CHANGEME_",
    "account" : "_CHANGEME_",
    "hourRateLimit" : "_CHANGEME_",
    "burstRateLimit" : "_CHANGEME_",
    ...
}
serviceUri

The Docusign API hostname, in the most of the cases labeled Account Base URI, for example https://demo.docusign.net.

clientId

The Docusign Application Integration Key. You can locate this ID under Integrations > Apps and Keys > Apps and Integration Keys when you log in to your DocuSign account

clientSecret

The Docusign Application Secret Key. You can locate this ID under Integrations > Apps and Keys > Apps and Integration Keys > Actions > Edit > Authentication when you log in to your DocuSign account.

account

The API Account ID. You can locate this account ID under Integrations > Apps and Keys > My Account Information when you log in to your DocuSign account.

hourRateLimit

The Hourly Limit. You can locate this value under Integrations > API Usage Center > API Limit when you log in to your DocuSign account.

burstRateLimit

The Burst Limit. You can locate this value under Integrations > API Usage Center > API Limit when you log in to your DocuSign account.

When your connector is configured correctly, the connector displays as Active in the UI.

If throttling problems continue, this guide may be helpful:

Improve reconciliation query performance

Test the DocuSign connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request POST \
"http://localhost:8080/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",
    "__GROUP__",
    "__ALL__",
    "contact",
    "permissionProfile",
    "__ACCOUNT__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the DocuSign server.

DocuSign remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the DocuSign connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the DocuSign connector from here.

Refer to Remote connectors for configuring the DocuSign remote connector.

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.

Users

Create a DocuSign User

This example creates a user with the minimum required attributes.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "userName": "Carlos Garcia",
  "email": "cgarcia@example.com"
}' \
"http://localhost:8080/openidm/system/docusign/__ACCOUNT__?_action=create"
{
  "_id": "10a0c285-1976-4fb0-8955-875d281e50fd",
  "permissionProfileId": "",
  "createdDateTime": "2024-02-09T16:29:20.9270000Z",
  "__GROUP__": [
    "12580253"
  ],
  "sendActivationOnInvalidLogin": "false",
  "lastName": "Garcia",
  "isAdmin": "False",
  "jobTitle": "",
  "uri": "/users/10a0c285-1976-4fb0-8955-875d281e50fd",
  "permissionProfileName": "",
  "enableConnectForUser": "false",
  "email": "cgarcia@example.com",
  "userStatus": "ActivationSent",
  "workAddress": {
    "address1": "",
    "address2": "",
    "city": "",
    "stateOrProvince": "",
    "postalCode": "",
    "phone": "",
    "country": ""
  },
  "initialsImageUri": "/users/10a0c285-1976-4fb0-8955-875d281e50fd/signatures/9ca8008b-31cd-42a3-89f6-6a9ccd88f25f/initials_image",
  "userId": "10a0c285-1976-4fb0-8955-875d281e50fd",
  "firstName": "Carlos",
  "__NAME__": "Carlos Garcia",
  "userSettings": {
    "canManageAccount": "false",
    "accountManagementGranular": {
      "canManageUsers": "false",
      "canManageAdmins": "false",
      "canManageSharing": "false",
      "canManageEnvelopeTransfer": "false",
      "canManageAccountSettings": "false",
      "canManageReporting": "false",
      "canManageAccountSecuritySettings": "false",
      "canManageSigningGroups": "false",
      "canManageDocumentRetention": "false",
      "canManageConnect": "false",
      "canViewUsers": "false",
      "canManageGroupsButNotUsers": "false",
      "canManageStamps": "false",
      "canManageJointAgreements": "false"
    },
    "canSendEnvelope": "false",
    "canSendAPIRequests": "false",
    "apiAccountWideAccess": "false",
    "enableVaulting": "false",
    "vaultingMode": "none",
    "enableTransactionPoint": "true",
    "enableSequentialSigningAPI": "true",
    "enableSequentialSigningUI": "true",
    "enableDSPro": "false",
    "powerFormMode": "user",
    "allowPowerFormsAdminToAccessAllPowerFormEnvelope": "false",
    "canEditSharedAddressbook": "use_private_and_shared",
    "manageClickwrapsMode": "none",
    "enableSignOnPaperOverride": "false",
    "enableSignerAttachments": "true",
    "allowSendOnBehalfOf": "false",
    "canManageTemplates": "none",
    "allowEnvelopeTransferTo": "false",
    "allowRecipientLanguageSelection": "true",
    "apiCanExportAC": "false",
    "bulkSend": "false",
    "canChargeAccount": "true",
    "canManageDistributor": "false",
    "canSignEnvelope": "true",
    "newSendUI": "false",
    "recipientViewedNotification": "false",
    "templateActiveCreation": "false",
    "templateApplyNotify": "true",
    "templateAutoMatching": "true",
    "templateMatchingSensitivity": "80",
    "templatePageLevelMatching": "false",
    "transactionPointSiteNameURL": "",
    "transactionPointUserName": "",
    "timezoneOffset": "tz_66_pacific",
    "timezoneMask": "",
    "timezoneDST": "",
    "modifiedBy": "",
    "modifiedPage": "update membership settings by acm sync job",
    "modifiedDate": "2/9/2024 5:02:47 pm",
    "adminOnly": "false",
    "selfSignedRecipientEmailDocument": "include_link",
    "signerEmailNotifications": {
      "envelopeActivation": "true",
      "envelopeComplete": "true",
      "carbonCopyNotification": "true",
      "certifiedDeliveryNotification": "true",
      "envelopeDeclined": "true",
      "envelopeVoided": "true",
      "envelopeCorrected": "true",
      "reassignedSigner": "true",
      "purgeDocuments": "true",
      "faxReceived": "true",
      "documentMarkupActivation": "true",
      "agentNotification": "true",
      "offlineSigningFailed": "true",
      "whenSigningGroupMember": "true",
      "commentsReceiveAll": "true",
      "commentsOnlyPrivateAndMention": "true"
    },
    "senderEmailNotifications": {
      "envelopeComplete": "true",
      "changedSigner": "true",
      "senderEnvelopeDeclined": "true",
      "withdrawnConsent": "true",
      "recipientViewed": "true",
      "deliveryFailed": "true",
      "offlineSigningFailed": "true",
      "purgeDocuments": "true",
      "commentsReceiveAll": "true",
      "commentsOnlyPrivateAndMention": "true",
      "powerformResponsesLimitNotificationEmail": "true",
      "clickwrapResponsesLimitNotificationEmail": "true"
    },
    "localePolicy": {
      "cultureName": "en",
      "nameFormat": "first_middle_last",
      "initialFormat": "first1last1",
      "addressFormat": "en_us",
      "dateFormat": "mdyyyy",
      "timeFormat": "none",
      "calendarType": "gregorian",
      "timeZone": "tz_66_pacific",
      "currencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
      "currencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
      "effectiveNameFormat": "first_middle_last",
      "effectiveInitialFormat": "first1last1",
      "effectiveAddressFormat": "en_us",
      "effectiveDateFormat": "longformat",
      "effectiveTimeFormat": "hhmm",
      "effectiveCalendarType": "gregorian",
      "effectiveTimeZone": "tz_66_pacific",
      "effectiveCurrencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
      "effectiveCurrencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
      "currencyCode": "usd",
      "effectiveCurrencyCode": "usd",
      "signDateFormat": "mdyyyy",
      "signTimeFormat": "none"
    },
    "locale": "en",
    "canLockEnvelopes": "true",
    "canUseScratchpad": "true",
    "canCreateWorkspaces": "false",
    "isWorkspaceParticipant": "false",
    "allowEmailChange": "true",
    "allowPasswordChange": "true",
    "federatedStatus": "none",
    "allowSupplementalDocuments": "true",
    "supplementalDocumentsMustView": "true",
    "supplementalDocumentsMustAccept": "true",
    "supplementalDocumentsMustRead": "true",
    "canManageOrganization": "false",
    "expressSendOnly": "false",
    "supplementalDocumentIncludeInDownload": "false",
    "disableDocumentUpload": "false",
    "disableOtherActions": "false",
    "useAccountServerForPasswordChange": "true",
    "isCommentsParticipant": "false",
    "useAccountServerForEmailChange": "true",
    "allowEsealRecipients": "false",
    "sealIdentifiers": [],
    "agreedToComments": "false",
    "canUseSmartContracts": "false",
    "canSendEnvelopesViaSMS": "false",
    "webForms": "none",
    "allowedOrchestrationAccess": "none"
  },
  "userType": "CompanyUser",
  "userName": "Carlos Garcia",
  "groupList": [
    {
      "groupId": "12580253",
      "groupName": "Everyone",
      "groupType": "everyoneGroup"
    }
  ]
}

When you create a new user, you must specify at least the userName and email. 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.

 
curl \
--header "Content-Type: application/json" \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--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"
  }
}' \
"http://localhost:8080/openidm/system/docusign/__ACCOUNT__?_action=create"
Create a DocuSign Full User

This example creates a Docusign Full User.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "userType": "CompanyUser",
  "lastName": "User3",
  "email": "showing3@example.com",
  "permissionProfileId": "",
  "permissionProfileName": "",
  "sendActivationOnInvalidLogin": "false",
  "userName": "showing3",
  "groupList": [
    {
      "groupId": "14261467"
    }
  ],
  "firstName": "showing3",
  "isAdmin": "False",
  "enableConnectForUser": "false",
  "jobTitle": "hired",
  "userSettings":
    {
      "canManageAccount": "false",
      "accountManagementGranular": {
        "canManageUsers": "false",
        "canManageAdmins": "false",
        "canManageSharing": "false",
        "canManageEnvelopeTransfer": "false",
        "canManageAccountSettings": "false",
        "canManageReporting": "false",
        "canManageAccountSecuritySettings": "false",
        "canManageSigningGroups": "false",
        "canManageDocumentRetention": "false",
        "canManageConnect": "false",
        "canViewUsers": "false",
        "canManageGroupsButNotUsers": "false",
        "canManageStamps": "false",
        "canManageJointAgreements": "false"
      },
      "canSendEnvelope": "false",
      "canSendAPIRequests": "false",
      "apiAccountWideAccess": "false",
      "enableVaulting": "false",
      "vaultingMode": "none",
      "enableTransactionPoint": "true",
      "enableSequentialSigningAPI": "true",
      "enableSequentialSigningUI": "true",
      "enableDSPro": "false",
      "powerFormMode": "user",
      "allowPowerFormsAdminToAccessAllPowerFormEnvelope": "false",
      "canEditSharedAddressbook": "use_private_and_shared",
      "manageClickwrapsMode": "none",
      "enableSignOnPaperOverride": "false",
      "enableSignerAttachments": "true",
      "allowSendOnBehalfOf": "false",
      "canManageTemplates": "none",
      "allowEnvelopeTransferTo": "false",
      "allowRecipientLanguageSelection": "true",
      "apiCanExportAC": "false",
      "bulkSend": "false",
      "canChargeAccount": "true",
      "canManageDistributor": "false",
      "canSignEnvelope": "true",
      "newSendUI": "false",
      "recipientViewedNotification": "false",
      "templateActiveCreation": "false",
      "templateApplyNotify": "true",
      "templateAutoMatching": "true",
      "templateMatchingSensitivity": "80",
      "templatePageLevelMatching": "false",
      "transactionPointSiteNameURL": "",
      "transactionPointUserName": "",
      "timezoneOffset": "tz_66_pacific",
      "timezoneMask": "",
      "timezoneDST": "",
      "modifiedBy": "",
      "modifiedPage": "",
      "modifiedDate": "1/9/2024 4:04:55 pm",
      "adminOnly": "false",
      "selfSignedRecipientEmailDocument": "include_link",
      "signerEmailNotifications": {
        "envelopeActivation": "true",
        "envelopeComplete": "true",
        "carbonCopyNotification": "true",
        "certifiedDeliveryNotification": "true",
        "envelopeDeclined": "true",
        "envelopeVoided": "true",
        "envelopeCorrected": "true",
        "reassignedSigner": "true",
        "purgeDocuments": "true",
        "faxReceived": "true",
        "documentMarkupActivation": "true",
        "agentNotification": "true",
        "offlineSigningFailed": "true",
        "whenSigningGroupMember": "true",
        "commentsReceiveAll": "true",
        "commentsOnlyPrivateAndMention": "true"
      },
      "senderEmailNotifications": {
        "envelopeComplete": "true",
        "changedSigner": "true",
        "senderEnvelopeDeclined": "true",
        "withdrawnConsent": "true",
        "recipientViewed": "true",
        "deliveryFailed": "true",
        "offlineSigningFailed": "true",
        "purgeDocuments": "true",
        "commentsReceiveAll": "true",
        "commentsOnlyPrivateAndMention": "true",
        "powerformResponsesLimitNotificationEmail": "true",
        "clickwrapResponsesLimitNotificationEmail": "true"
      },
      "localePolicy": {
        "cultureName": "en",
        "nameFormat": "first_middle_last",
        "initialFormat": "first1last1",
        "addressFormat": "en_us",
        "dateFormat": "mdyyyy",
        "timeFormat": "none",
        "calendarType": "gregorian",
        "timeZone": "tz_66_pacific",
        "currencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
        "currencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
        "effectiveNameFormat": "first_middle_last",
        "effectiveInitialFormat": "first1last1",
        "effectiveAddressFormat": "en_us",
        "effectiveDateFormat": "longformat",
        "effectiveTimeFormat": "hhmm",
        "effectiveCalendarType": "gregorian",
        "effectiveTimeZone": "tz_66_pacific",
        "effectiveCurrencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
        "effectiveCurrencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
        "currencyCode": "usd",
        "effectiveCurrencyCode": "usd",
        "signDateFormat": "mdyyyy",
        "signTimeFormat": "none"
      },
      "locale": "en",
      "canLockEnvelopes": "true",
      "canUseScratchpad": "true",
      "canCreateWorkspaces": "false",
      "isWorkspaceParticipant": "false",
      "allowEmailChange": "true",
      "allowPasswordChange": "true",
      "federatedStatus": "none",
      "allowSupplementalDocuments": "true",
      "supplementalDocumentsMustView": "true",
      "supplementalDocumentsMustAccept": "true",
      "supplementalDocumentsMustRead": "true",
      "canManageOrganization": "false",
      "expressSendOnly": "false",
      "supplementalDocumentIncludeInDownload": "false",
      "disableDocumentUpload": "false",
      "disableOtherActions": "false",
      "useAccountServerForPasswordChange": "true",
      "isCommentsParticipant": "false",
      "useAccountServerForEmailChange": "true",
      "allowEsealRecipients": "false",
      "sealIdentifiers": [],
      "agreedToComments": "false",
      "canUseSmartContracts": "false",
      "canSendEnvelopesViaSMS": "false",
      "webForms": "none",
      "allowedOrchestrationAccess": "none"
    }
}' \
"http://localhost:8080/openidm/system/docusign/__ACCOUNT__?_action=create"
{
  "_id": "10a0c285-1976-4fb0-8955-875d281e50fd",
  "permissionProfileId": "",
  "signatureImageUri": "/users/10a0c285-1976-4fb0-8955-875d281e50fd/signatures/9ca8008b-31cd-42a3-89f6-6a9ccd88f25f/signature_image",
  "createdDateTime": "2024-02-09T16:29:20.9270000Z",
  "__GROUP__": [
    "12580253",
    "14261467"
  ],
  "sendActivationOnInvalidLogin": "false",
  "lastName": "updated",
  "isAdmin": "False",
  "jobTitle": "hired",
  "uri": "/users/10a0c285-1976-4fb0-8955-875d281e50fd",
  "permissionProfileName": "",
  "enableConnectForUser": "false",
  "email": "showing3@example.com",
  "userStatus": "ActivationSent",
  "workAddress": {
    "address1": "",
    "address2": "",
    "city": "",
    "stateOrProvince": "",
    "postalCode": "",
    "phone": "",
    "country": ""
  },
  "initialsImageUri": "/users/10a0c285-1976-4fb0-8955-875d281e50fd/signatures/9ca8008b-31cd-42a3-89f6-6a9ccd88f25f/initials_image",
  "userId": "10a0c285-1976-4fb0-8955-875d281e50fd",
  "firstName": "showing3",
  "__NAME__": "showing3 updated",
  "userSettings": {
    "canManageAccount": "false",
    "accountManagementGranular": {
      "canManageUsers": "false",
      "canManageAdmins": "false",
      "canManageSharing": "false",
      "canManageEnvelopeTransfer": "false",
      "canManageAccountSettings": "false",
      "canManageReporting": "false",
      "canManageAccountSecuritySettings": "false",
      "canManageSigningGroups": "false",
      "canManageDocumentRetention": "false",
      "canManageConnect": "false",
      "canViewUsers": "false",
      "canManageGroupsButNotUsers": "false",
      "canManageStamps": "false",
      "canManageJointAgreements": "false"
    },
    "canSendEnvelope": "false",
    "canSendAPIRequests": "false",
    "apiAccountWideAccess": "false",
    "enableVaulting": "false",
    "vaultingMode": "none",
    "enableTransactionPoint": "true",
    "enableSequentialSigningAPI": "true",
    "enableSequentialSigningUI": "true",
    "enableDSPro": "false",
    "powerFormMode": "user",
    "allowPowerFormsAdminToAccessAllPowerFormEnvelope": "false",
    "canEditSharedAddressbook": "use_private_and_shared",
    "manageClickwrapsMode": "none",
    "enableSignOnPaperOverride": "false",
    "enableSignerAttachments": "true",
    "allowSendOnBehalfOf": "false",
    "canManageTemplates": "none",
    "allowEnvelopeTransferTo": "false",
    "allowRecipientLanguageSelection": "true",
    "apiCanExportAC": "false",
    "bulkSend": "false",
    "canChargeAccount": "true",
    "canManageDistributor": "false",
    "canSignEnvelope": "true",
    "newSendUI": "false",
    "recipientViewedNotification": "false",
    "templateActiveCreation": "false",
    "templateApplyNotify": "true",
    "templateAutoMatching": "true",
    "templateMatchingSensitivity": "80",
    "templatePageLevelMatching": "false",
    "transactionPointSiteNameURL": "",
    "transactionPointUserName": "",
    "timezoneOffset": "tz_66_pacific",
    "timezoneMask": "",
    "timezoneDST": "",
    "modifiedBy": "",
    "modifiedPage": "update membership settings by acm sync job",
    "modifiedDate": "2/9/2024 5:02:47 pm",
    "adminOnly": "false",
    "selfSignedRecipientEmailDocument": "include_link",
    "signerEmailNotifications": {
      "envelopeActivation": "true",
      "envelopeComplete": "true",
      "carbonCopyNotification": "true",
      "certifiedDeliveryNotification": "true",
      "envelopeDeclined": "true",
      "envelopeVoided": "true",
      "envelopeCorrected": "true",
      "reassignedSigner": "true",
      "purgeDocuments": "true",
      "faxReceived": "true",
      "documentMarkupActivation": "true",
      "agentNotification": "true",
      "offlineSigningFailed": "true",
      "whenSigningGroupMember": "true",
      "commentsReceiveAll": "true",
      "commentsOnlyPrivateAndMention": "true"
    },
    "senderEmailNotifications": {
      "envelopeComplete": "true",
      "changedSigner": "true",
      "senderEnvelopeDeclined": "true",
      "withdrawnConsent": "true",
      "recipientViewed": "true",
      "deliveryFailed": "true",
      "offlineSigningFailed": "true",
      "purgeDocuments": "true",
      "commentsReceiveAll": "true",
      "commentsOnlyPrivateAndMention": "true",
      "powerformResponsesLimitNotificationEmail": "true",
      "clickwrapResponsesLimitNotificationEmail": "true"
    },
    "localePolicy": {
      "cultureName": "en",
      "nameFormat": "first_middle_last",
      "initialFormat": "first1last1",
      "addressFormat": "en_us",
      "dateFormat": "mdyyyy",
      "timeFormat": "none",
      "calendarType": "gregorian",
      "timeZone": "tz_66_pacific",
      "currencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
      "currencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
      "effectiveNameFormat": "first_middle_last",
      "effectiveInitialFormat": "first1last1",
      "effectiveAddressFormat": "en_us",
      "effectiveDateFormat": "longformat",
      "effectiveTimeFormat": "hhmm",
      "effectiveCalendarType": "gregorian",
      "effectiveTimeZone": "tz_66_pacific",
      "effectiveCurrencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
      "effectiveCurrencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
      "currencyCode": "usd",
      "effectiveCurrencyCode": "usd",
      "signDateFormat": "mdyyyy",
      "signTimeFormat": "none"
    },
    "locale": "en",
    "canLockEnvelopes": "true",
    "canUseScratchpad": "true",
    "canCreateWorkspaces": "false",
    "isWorkspaceParticipant": "false",
    "allowEmailChange": "true",
    "allowPasswordChange": "true",
    "federatedStatus": "none",
    "allowSupplementalDocuments": "true",
    "supplementalDocumentsMustView": "true",
    "supplementalDocumentsMustAccept": "true",
    "supplementalDocumentsMustRead": "true",
    "canManageOrganization": "false",
    "expressSendOnly": "false",
    "supplementalDocumentIncludeInDownload": "false",
    "disableDocumentUpload": "false",
    "disableOtherActions": "false",
    "useAccountServerForPasswordChange": "true",
    "isCommentsParticipant": "false",
    "useAccountServerForEmailChange": "true",
    "allowEsealRecipients": "false",
    "sealIdentifiers": [],
    "agreedToComments": "false",
    "canUseSmartContracts": "false",
    "canSendEnvelopesViaSMS": "false",
    "webForms": "none",
    "allowedOrchestrationAccess": "none"
  },
  "userType": "CompanyUser",
  "userName": "showing3 updated",
  "groupList": [
    {
      "groupId": "12580253",
      "groupName": "Everyone",
      "groupType": "everyoneGroup"
    },
    {
      "groupId": "14261467",
      "groupName": "GLHFVAV_docusign_group",
      "groupType": "customGroup"
    }
  ]
}
Query DocuSign User

This example queries all DocuSign users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/__ACCOUNT__?_queryFilter=True"
{
  "result": [
    {
      "_id": "bb590b6d-8774-49c4-89fd-821115b8fc00",
      ...
      "userName": "A_20240206164614656_DOCUSINGTEST",
      "createdDateTime": "2024-02-06T19:46:15.4770000Z",
      "userId": "bb590b6d-8774-49c4-89fd-821115b8fc00",
      "permissionProfileName": "",
      "userStatus": "Active",
      "uri": "/users/bb590b6d-8774-49c4-89fd-821115b8fc00"
    },
    {
      "_id": "410d0a11-1923-4e78-b543-1898de76c728",
      ...
      "userName": "A_20240206164614656_DOCUSINGTEST",
      "createdDateTime": "2024-02-08T19:57:28.1270000Z",
      "userId": "410d0a11-1923-4e78-b543-1898de76c728",
      "permissionProfileName": "DocuSign Viewer",
      "userStatus": "Closed",
      "uri": "/users/410d0a11-1923-4e78-b543-1898de76c728"
    },
    ...
    {
      "_id": "451664c9-6425-4595-b823-9493063734fe",
      ...
      "userName": "A_20240206170333281_DOCUSINGTEST",
      "createdDateTime": "2024-02-21T15:03:56.2000000Z",
      "userId": "451664c9-6425-4595-b823-9493063734fe",
      "permissionProfileName": "",
      "userStatus": "ActivationSent",
      "uri": "/users/451664c9-6425-4595-b823-9493063734fe"
    }
  ],
  "resultCount": 50,
  "pagedResultsCookie": "4xj8Qq7Gkd",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

userStatus can be filtered by a comma-separated list of the following:

  • ActivationRequired

  • ActivationSent

  • Active

  • Closed

  • Disabled

  • Some filters won’t work properly unless an userStatus is specified.

  • The maximum page size is 100.
Query IDs DocuSign User

This example queries all DocuSign users by their IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/__ACCOUNT__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "bc9f0464-808a-4703-b4c2-c1e6a77f0c3a"
    },
    {
      "_id": "dc1c6940-1de7-4434-a91e-1407424cac91"
    },
    {
      "_id": "94be4fed-cfd7-47d5-9fcc-813405084f17"
    }
  ],
  "resultCount": 3,
  "pagedResultsCookie": "fXE265UhNb",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Get DocuSign User

The following command queries a specific user by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/__ACCOUNT__/dc1c6940-1de7-4434-a91e-1407424cac91"
{
  "_id": "83947d26-2e69-40a5-892c-7a7a2600d530",
  "userId": "83947d26-2e69-40a5-892c-7a7a2600d530",
  "permissionProfileName": "",
  "createdDateTime": "2024-02-07T12:54:17.3000000Z",
  "email": "IQNREMU@foo.bar",
  "userSettings": {
    "canManageAccount": "false",
    "accountManagementGranular": {
      "canManageUsers": "false",
      "canManageAdmins": "false",
      "canManageSharing": "false",
      "canManageEnvelopeTransfer": "false",
      "canManageAccountSettings": "false",
      "canManageReporting": "false",
      "canManageAccountSecuritySettings": "false",
      "canManageSigningGroups": "false",
      "canManageDocumentRetention": "false",
      "canManageConnect": "false",
      "canViewUsers": "false",
      "canManageGroupsButNotUsers": "false",
      "canManageStamps": "false",
      "canManageJointAgreements": "false"
    },
    "canSendEnvelope": "false",
    "canSendAPIRequests": "false",
    "apiAccountWideAccess": "false",
    "enableVaulting": "false",
    "vaultingMode": "none",
    "enableTransactionPoint": "true",
    "enableSequentialSigningAPI": "true",
    "enableSequentialSigningUI": "true",
    "enableDSPro": "false",
    "powerFormMode": "user",
    "allowPowerFormsAdminToAccessAllPowerFormEnvelope": "false",
    "canEditSharedAddressbook": "use_private_and_shared",
    "manageClickwrapsMode": "none",
    "enableSignOnPaperOverride": "false",
    "enableSignerAttachments": "true",
    "allowSendOnBehalfOf": "false",
    "canManageTemplates": "none",
    "allowEnvelopeTransferTo": "false",
    "allowRecipientLanguageSelection": "true",
    "apiCanExportAC": "false",
    "bulkSend": "false",
    "canChargeAccount": "true",
    "canManageDistributor": "false",
    "canSignEnvelope": "true",
    "newSendUI": "false",
    "recipientViewedNotification": "false",
    "templateActiveCreation": "false",
    "templateApplyNotify": "true",
    "templateAutoMatching": "true",
    "templateMatchingSensitivity": "80",
    "templatePageLevelMatching": "false",
    "transactionPointSiteNameURL": "",
    "transactionPointUserName": "",
    "timezoneOffset": "tz_66_pacific",
    "timezoneMask": "",
    "timezoneDST": "",
    "modifiedBy": "",
    "modifiedPage": "update membership settings by acm sync job",
    "modifiedDate": "2/7/2024 1:02:42 pm",
    "adminOnly": "false",
    "selfSignedRecipientEmailDocument": "include_link",
    "signerEmailNotifications": {
      "envelopeActivation": "true",
      "envelopeComplete": "true",
      "carbonCopyNotification": "true",
      "certifiedDeliveryNotification": "true",
      "envelopeDeclined": "true",
      "envelopeVoided": "true",
      "envelopeCorrected": "true",
      "reassignedSigner": "true",
      "purgeDocuments": "true",
      "faxReceived": "true",
      "documentMarkupActivation": "true",
      "agentNotification": "true",
      "offlineSigningFailed": "true",
      "whenSigningGroupMember": "true",
      "commentsReceiveAll": "true",
      "commentsOnlyPrivateAndMention": "true"
    },
    "senderEmailNotifications": {
      "envelopeComplete": "true",
      "changedSigner": "true",
      "senderEnvelopeDeclined": "true",
      "withdrawnConsent": "true",
      "recipientViewed": "true",
      "deliveryFailed": "true",
      "offlineSigningFailed": "true",
      "purgeDocuments": "true",
      "commentsReceiveAll": "true",
      "commentsOnlyPrivateAndMention": "true",
      "powerformResponsesLimitNotificationEmail": "true",
      "clickwrapResponsesLimitNotificationEmail": "true"
    },
    "localePolicy": {
      "cultureName": "en",
      "nameFormat": "first_middle_last",
      "initialFormat": "first1last1",
      "addressFormat": "en_us",
      "dateFormat": "mdyyyy",
      "timeFormat": "none",
      "calendarType": "gregorian",
      "timeZone": "tz_66_pacific",
      "currencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
      "currencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
      "effectiveNameFormat": "first_middle_last",
      "effectiveInitialFormat": "first1last1",
      "effectiveAddressFormat": "en_us",
      "effectiveDateFormat": "longformat",
      "effectiveTimeFormat": "hhmm",
      "effectiveCalendarType": "gregorian",
      "effectiveTimeZone": "tz_66_pacific",
      "effectiveCurrencyPositiveFormat": "csym_1_comma_234_comma_567_period_89",
      "effectiveCurrencyNegativeFormat": "opar_csym_1_comma_234_comma_567_period_89_cpar",
      "currencyCode": "usd",
      "effectiveCurrencyCode": "usd",
      "signDateFormat": "mdyyyy",
      "signTimeFormat": "none"
    },
    "locale": "en",
    "canLockEnvelopes": "true",
    "canUseScratchpad": "true",
    "canCreateWorkspaces": "false",
    "isWorkspaceParticipant": "false",
    "allowEmailChange": "true",
    "allowPasswordChange": "true",
    "federatedStatus": "none",
    "allowSupplementalDocuments": "true",
    "supplementalDocumentsMustView": "true",
    "supplementalDocumentsMustAccept": "true",
    "supplementalDocumentsMustRead": "true",
    "canManageOrganization": "false",
    "expressSendOnly": "false",
    "supplementalDocumentIncludeInDownload": "false",
    "disableDocumentUpload": "false",
    "disableOtherActions": "false",
    "useAccountServerForPasswordChange": "true",
    "isCommentsParticipant": "false",
    "useAccountServerForEmailChange": "true",
    "allowEsealRecipients": "false",
    "sealIdentifiers": [],
    "agreedToComments": "false",
    "canUseSmartContracts": "false",
    "canSendEnvelopesViaSMS": "false",
    "webForms": "none",
    "allowedOrchestrationAccess": "none"
  },
  "uri": "/users/83947d26-2e69-40a5-892c-7a7a2600d530",
  "enableConnectForUser": "false",
  "__GROUP__": [
    "12580253"
  ],
  "jobTitle": "",
  "userStatus": "ActivationSent",
  "firstName": "IQNREMU",
  "sendActivationOnInvalidLogin": "false",
  "signatureImageUri": "/users/83947d26-2e69-40a5-892c-7a7a2600d530/signatures/9ca8008b-31cd-42a3-89f6-6a9ccd88f25f/signature_image",
  "userType": "CompanyUser",
  "userName": "IQNREMU_DOCUSINGTEST",
  "workAddress": {
    "address1": "",
    "address2": "",
    "city": "",
    "stateOrProvince": "",
    "postalCode": "",
    "phone": "",
    "country": ""
  },
  "initialsImageUri": "/users/83947d26-2e69-40a5-892c-7a7a2600d530/signatures/9ca8008b-31cd-42a3-89f6-6a9ccd88f25f/initials_image",
  "permissionProfileId": "",
  "lastName": "DOCUSINGTEST",
  "groupList": [
    {
      "groupId": "12580253",
      "groupName": "Everyone",
      "groupType": "everyoneGroup"
    }
  ],
  "__NAME__": "IQNREMU_DOCUSINGTEST",
  "isAdmin": "False"
}
Update a DocuSign User

Sometimes, Docusign returns a successful response with an "updated user", but this is not always the case. It is recommended to check the user with a Get operation after a modification.

After creation, a user’s email address is read-only and you cannot modify it using the connector.
Close a DocuSign User

You cannot use the DocuSign connector to delete a user from the DocuSign repository. However, you can use a DELETE request to set the userStatus attribute of the user to Closed.

The following example closes a DocuSign user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request DELETE \
"http://localhost:8080/openidm/system/docusign/__ACCOUNT__/dc1c6940-1de7-4434-a91e-1407424cac91"
{
  "_id": "83947d26-2e69-40a5-892c-7a7a2600d530",
  "userId": "83947d26-2e69-40a5-892c-7a7a2600d530",
  "permissionProfileName": "",
  "createdDateTime": "2024-02-07T12:54:17.3000000Z",
  "email": "IQNREMU@foo.bar",
  "userSettings": {
    "canManageAccount": "false",
    ...
    "allowedOrchestrationAccess": "none"
  },
  "uri": "/users/83947d26-2e69-40a5-892c-7a7a2600d530",
  "enableConnectForUser": "false",
  "__GROUP__": [
    "12580253"
  ],
  "jobTitle": "",
  "userStatus": "Closed",
  "firstName": "IQNREMU",
  "sendActivationOnInvalidLogin": "false",
  "signatureImageUri": "/users/83947d26-2e69-40a5-892c-7a7a2600d530/signatures/9ca8008b-31cd-42a3-89f6-6a9ccd88f25f/signature_image",
  "userType": "CompanyUser",
  "userName": "IQNREMU_DOCUSINGTEST",
  "workAddress": {
    "address1": "",
    "address2": "",
    "city": "",
    "stateOrProvince": "",
    "postalCode": "",
    "phone": "",
    "country": ""
  },
  "initialsImageUri": "/users/83947d26-2e69-40a5-892c-7a7a2600d530/signatures/9ca8008b-31cd-42a3-89f6-6a9ccd88f25f/initials_image",
  "permissionProfileId": "",
  "lastName": "DOCUSINGTEST",
  "groupList": [
    {
      "groupId": "12580253",
      "groupName": "Everyone",
      "groupType": "everyoneGroup"
    }
  ],
  "__NAME__": "IQNREMU_DOCUSINGTEST",
  "isAdmin": "False"
}

A Closed account:

  • Remains in the DocuSign repository.

  • Can still be queried by its ID.

  • Cannot be updated.

GROUPS

Create a DocuSign Group

This example creates a DocuSign group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "groupName": "testing group 4",
  "permissionProfileId": "1597"
}' \
"http://localhost:8080/openidm/system/docusign/__GROUP__?_action=create"
{
  "_id": "14756690",
  "groupName": "testing group 4",
  "usersCount": "0",
  "__NAME__": "testing group 4",
  "groupId": "14756690",
  "groupType": "customGroup",
  "permissionProfileId": "1597"
}
Get a DocuSign Group

This example gets a DocuSign Group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/__GROUP__/14756690"
{
  "_id": "14756690",
  "groupName": "testing group 4",
  "usersCount": "0",
  "__NAME__": "testing group 4",
  "groupId": "14756690",
  "groupType": "customGroup",
  "permissionProfileId": "1597"
}
Query DocuSign Groups

This example queries all DocuSign groups:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/__GROUP__?_queryFilter=True"
{
  "result": [
    {
      "_id": "14189207",
      "groupName": "ABZAECX_docusign_group",
      "__NAME__": "ABZAECX_docusign_group",
      "groupType": "customGroup",
      "groupId": "14189207",
      "usersCount": "0"
    },
    {
      "_id": "12580252",
      "groupName": "Administrators",
      "__NAME__": "Administrators",
      "groupType": "adminGroup",
      "groupId": "12580252",
      "usersCount": "2"
    },
    ...
    {
      "_id": "14188985",
      "groupName": "AOMJYHH_docusign_group",
      "__NAME__": "AOMJYHH_docusign_group",
      "groupType": "customGroup",
      "groupId": "14188985",
       "usersCount": "0"
    }
  ],
  "resultCount": 17,
  "pagedResultsCookie": "9eoQJIWWyP",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
List All ID’s of DocuSign Groups

This example queries all DocuSign groups by their IDs:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/__GROUP__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "14189207"
    },
    {
      "_id": "12580252"
    },
    ...
    {
      "_id": "14189460"
    }
  ],
  "resultCount": 17,
  "pagedResultsCookie": "9eoQJIWWyP",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Update a DocuSign Group

This example updates a DocuSign Group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match: *" \
--request PUT \
--data '{
  "groupName": "newGroupName",
  "permissionProfileId": "3108"
}' \
"http://localhost:8080/openidm/system/docusign/__GROUP__/14756690"
{
  "_id": "14756690",
  "groupType": "customGroup",
  "groupId": "14756690",
  "groupName": "newGroupName",
  "__NAME__": "newGroupName",
  "usersCount": "0",
  "permissionProfileId": "3108"
}
Delete a DocuSign Group

This example deletes a DocuSign Group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request DELETE \
"http://localhost:8080/openidm/system/docusign/__GROUP__/14756690"
{
  "_id": "14756690",
  "groupType": "customGroup",
  "groupId": "14261434",
  "groupName": "newGroupName",
  "__NAME__": "newGroupName",
  "usersCount": "0",
  "permissionProfileId": "3108"
}

The response of the example is the group data before deletion.

SIGNING GROUPS

Create a DocuSign Signing Group

This example creates a DocuSign Signing Group:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "groupEmail": "example@mail.com",
  "groupType": "sharedSigningGroup",
  "groupName": "SigningGroup Name"
}' \
"http://localhost:8080/openidm/system/docusign/signingGroup?_action=create"
{
  "_id": "950719",
  "groupEmail": "example@mail.com",
  "createdBy": "Carlos Garcia",
  "created": "2024-02-25T23:54:47.0000000Z",
  "modifiedBy": "Carlos Garcia",
  "signingGroupId": "950719",
  "groupName": "SigningGroup Name",
  "groupType": "sharedSigningGroup",
  "__NAME__": "SigningGroup Name",
  "modified": "2024-02-25T23:54:47.0000000Z"
}

The only valid value for groupType is sharedSigningGroup.
Get a DocuSign Signing Group

This example gets a DocuSign Signing Group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/signingGroup/946554"
{
  "_id": "946554",
  "createdBy": "Carlos Garcia",
  "created": "2024-02-07T15:26:28.0000000Z",
  "modifiedBy": "Carlos Garcia",
  "signingGroupId": "946554",
  "groupName": "EZGHHNE_DOCUSINGSigningGroup",
  "groupType": "sharedSigningGroup",
  "__NAME__": "EZGHHNE_DOCUSINGSigningGroup",
  "modified": "2024-02-07T15:26:28.0000000Z"
}
Query DocuSign Signing Groups

This example queries all DocuSign Signing Groups:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/signingGroup?_queryFilter=True"
{
  "result": [
    {
      "_id": "946554",
      "createdBy": "Carlos Garcia",
      "created": "2024-02-07T15:26:28.0000000Z",
      "modifiedBy": "Carlos Garcia",
      "signingGroupId": "946554",
      "groupName": "EZGHHNE_DOCUSINGSigningGroup",
      "groupType": "sharedSigningGroup",
      "__NAME__": "EZGHHNE_DOCUSINGSigningGroup",
      "modified": "2024-02-07T15:26:28.0000000Z"
    },
    {
      "_id": "946555",
      "createdBy": "Carlos Garcia",
      "created": "2024-02-07T15:26:28.0000000Z",
      "modifiedBy": "Carlos Garcia",
      "signingGroupId": "946555",
      "groupName": "LPEFDWL_DOCUSINGSigningGroup",
      "groupType": "sharedSigningGroup",
      "__NAME__": "LPEFDWL_DOCUSINGSigningGroup",
      "modified": "2024-02-07T15:26:28.0000000Z"
    },
    ...
    {
      "_id": "946556",
      "createdBy": "Carlos Garcia",
      "created": "2024-02-07T15:26:29.0000000Z",
      "modifiedBy": "Carlos Garcia",
      "signingGroupId": "946556",
      "groupName": "HQYGJAA_DOCUSINGSigningGroup",
      "groupType": "sharedSigningGroup",
      "__NAME__": "HQYGJAA_DOCUSINGSigningGroup",
      "modified": "2024-02-07T15:26:29.0000000Z"
    }
  ],
  "resultCount": 159,
  "pagedResultsCookie": "FgIJ0KDqSv",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

Querying a non-existent Signing Group will lead to a 409 response.
Update a DocuSign Signing Group

This example updates a DocuSign Signing Group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match: *" \
--request PUT \
--data '{
  "groupEmail": "example@mail.com",
  "groupType": "sharedSigningGroup",
  "groupName": "New group name"
}' \
"http://localhost:8080/openidm/system/docusign/signingGroup/946554"
{
  "_id": "946554",
  "groupEmail": "example@mail.com",
  "createdBy": "Carlos Garcia",
  "created": "2024-02-07T15:26:28.0000000Z",
  "modifiedBy": "Carlos Garcia",
  "signingGroupId": "946554",
  "groupName": "New group name",
  "groupType": "sharedSigningGroup",
  "__NAME__": "SigningGroup Test 6 changed",
  "modified": "2024-02-26T02:21:02.0000000Z"
}
Delete a DocuSign Signing Group

This example deletes a DocuSign Signing Group by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request DELETE \
"http://localhost:8080/openidm/system/docusign/signingGroup/946554"
{
  "_id": "946554",
  "groupEmail": "example@mail.com",
  "createdBy": "Carlos Garcia",
  "created": "2024-02-07T15:26:28.0000000Z",
  "modifiedBy": "Carlos Garcia",
  "signingGroupId": "946554",
  "groupName": "New group name",
  "groupType": "sharedSigningGroup",
  "__NAME__": "SigningGroup Test 6 changed",
  "modified": "2024-02-26T02:21:02.0000000Z"
}

CONTACTS

Create a DocuSign Contact

This example creates a DocuSign Contact:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "shared": "False",
  "organization": "contact co",
  "emails": [
    "contacttesting5@mail15.com"
  ],
  "contactPhoneNumbers": [
    {
      "phoneNumber": "+12223331177",
      "phoneType": "mobile"   (1)
    },
    {
      "phoneNumber": "+12213332255",
      "phoneType": "home"  (1)
    }
  ],
  "name": "contact testing5"
}' \
"http://localhost:8080/openidm/system/docusign/contact?_action=create"
{
  "_id": "04468c26-ce0e-4484-9057-86881ed2d329",
  "shared": "False",
  "organization": "contact co",
  "contactId": "04468c26-ce0e-4484-9057-86881ed2d329",
  "__NAME__": "contact testing5",
  "emails": [
    "contacttesting5@mail15.com"
  ],
  "contactPhoneNumbers": [
    {
      "phoneNumber": "+12223331177",
      "phoneType": "mobile"
    },
    {
      "phoneNumber": "+12213332255",
      "phoneType": "home"
    }
  ],
  "name": "contact testing5"
}
1 phoneType valid values are:

  • home

  • mobile

  • work

  • other

  • fax
Get a DocuSign Contact

This example gets a DocuSign Contact by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/contact/dac27654-b3aa-4b25-b1fb-dd2b34091809"
{
  "_id": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
  "shared": "False",
  "contactId": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
  "__NAME__": "A_20240220153034606_DOCUSINGContact",
  "contactPhoneNumbers": [
    {
      "phoneNumber": "+122234976",
      "phoneType": "mobile"
    },
    {
      "phoneNumber": "+122564976",
      "phoneType": "home"
    }
  ],
  "organization": "contact co",
  "emails": [
    "A_20240220153034606@foo.bar"
  ],
  "name": "A_20240220153034606_DOCUSINGContact"
}
Query DocuSign Contacts

This example queries all DocuSign contacts:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/contact?_queryFilter=True"
{
  "result": [
    {
      "_id": "4702c98b-e781-4528-bf76-dcba838bdf64",
      "shared": "False",
      "contactId": "4702c98b-e781-4528-bf76-dcba838bdf64",
      "__NAME__": "A_20240219163557433_DOCUSINGContact",
      "organization": "contact co",
      "emails": [
        "A_20240219163557433@foo.bar"
      ],
      "name": "A_20240219163557433_DOCUSINGContact"
    },
    {
      "_id": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
      "shared": "False",
      "contactId": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
      "__NAME__": "A_20240220153034606_DOCUSINGContact",
      "organization": "contact co",
      "emails": [
        "A_20240220153034606@foo.bar"
      ],
      "name": "A_20240220153034606_DOCUSINGContact"
    },
    ...
    {
      "_id": "84d3fc99-f566-433f-b291-974e3daed207",
      "shared": "False",
      "contactId": "84d3fc99-f566-433f-b291-974e3daed207",
      "__NAME__": "A_20240220181425723_DOCUSINGContact",
      "organization": "contact co",
      "emails": [
        "A_20240220181425723@foo.bar"
      ],
      "name": "A_20240220181425723_DOCUSINGContact"
    }
  ],
  "resultCount": 20,
  "pagedResultsCookie": "Zu0tReY0z1",
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Update a DocuSign Contact

This example updates a DocuSign Contact by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match: *" \
--request PUT \
--data '{
  "shared": "False",
  "contactPhoneNumbers": [
    {
      "phoneNumber": "+122234888",
      "phoneType": "mobile"
    },
    {
      "phoneNumber": "+122564999",
      "phoneType": "home"
    }
  ],
  "organization": "New Org",
  "emails": [
    "newemail@foo.bar"
  ],
  "name": "New Contact Name"
}' \
"http://localhost:8080/openidm/system/docusign/contact/dac27654-b3aa-4b25-b1fb-dd2b34091809"
{
  "_id": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
  "shared": "False",
  "contactId": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
  "__NAME__": "New Contact Name",
  "contactPhoneNumbers": [
    {
      "phoneNumber": "+122234888",
      "phoneType": "mobile"
    },
    {
      "phoneNumber": "+122564999",
      "phoneType": "home"
    }
  ],
  "organization": "New Org",
  "emails": [
    "newemail@foo.bar"
  ],
  "name": "New Contact Name"
}
Delete a DocuSign Contact

This example deletes a DocuSign Contact by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request DELETE \
"http://localhost:8080/openidm/system/docusign/contact/dac27654-b3aa-4b25-b1fb-dd2b34091809"
{
  "_id": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
  "shared": "False",
  "contactId": "dac27654-b3aa-4b25-b1fb-dd2b34091809",
  "__NAME__": "New Contact Name",
  "contactPhoneNumbers": [
    {
      "phoneNumber": "+122234888",
      "phoneType": "mobile"
    },
    {
      "phoneNumber": "+122564999",
      "phoneType": "home"
    }
  ],
  "organization": "New Org",
  "emails": [
    "newemail@foo.bar"
  ],
  "name": "New Contact Name"
}

PERMISSION PROFILE

Get a DocuSign Permission Profile

This example gets a DocuSign Permission Profile by its ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/permissionProfile/17560262"
{
  "_id": "17560262",
  "permissionProfileId": "17560262",
  "modifiedByUsername": "",
  "settings": {
    "allowAccountManagement": "false",
    "useNewDocuSignExperienceInterface": "optional",
    "canCreateWorkspaces": "true",
    "allowBulkSending": "false",
    "allowEnvelopeSending": "true",
    "allowESealRecipients": "false",
    "allowSignerAttachments": "true",
    "allowTaggingInSendAndCorrect": "true",
    "allowWetSigningOverride": "true",
    "allowedAddressBookAccess": "usePersonalAndShared",
    "allowedClickwrapsAccess": "none",
    "allowedTemplateAccess": "use",
    "enableRecipientViewingNotifications": "true",
    "enableSequentialSigningInterface": "true",
    "receiveCompletedSelfSignedDocumentsAsEmailLinks": "false",
    "signingUiVersion": "v2",
    "useNewSendingInterface": "true",
    "allowSupplementalDocuments": "true",
    "supplementalDocumentsMustView": "true",
    "supplementalDocumentsMustAccept": "true",
    "supplementalDocumentsMustRead": "true",
    "disableDocumentUpload": "false",
    "disableOtherActions": "false",
    "allowAutoTagging": "false",
    "enableKeyTermsSuggestionsByDocumentType": "false",
    "allowApiAccess": "false",
    "allowApiAccessToAccount": "false",
    "allowApiSendingOnBehalfOfOthers": "false",
    "allowApiSequentialSigning": "true",
    "enableApiRequestLogging": "false",
    "allowTransactions": "false",
    "canCreateTransaction": "false",
    "canDeleteTransaction": "false",
    "canDeleteDocumentsInTransaction": "false",
    "allowDocuSignDesktopClient": "false",
    "allowSendersToSetRecipientEmailLanguage": "true",
    "allowVaulting": "false",
    "allowedToBeEnvelopeTransferRecipient": "false",
    "enableTransactionPointIntegration": "false",
    "powerFormRole": "user",
    "allowPowerFormsAdminToAccessAllPowerFormEnvelopes": "false",
    "vaultingMode": "none",
    "canSendEnvelopesViaSMS": "true",
    "webForms": "none",
    "allowedOrchestrationAccess": "none"
  },
  "__NAME__": "DocuSign Sender",
  "permissionProfileName": "DocuSign Sender",
  "modifiedDateTime": "2023-12-22T14:38:29.6070000Z"
}
Query DocuSign Permission Profiles

This example queries all DocuSign Permission Profiles:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--request GET \
"http://localhost:8080/openidm/system/docusign/permissionProfile?_queryFilter=True"
{
  "result": [
    {
      "_id": "17560261",
      "permissionProfileId": "17560261",
      "modifiedByUsername": "",
      "__NAME__": "Account Administrator",
      "permissionProfileName": "Account Administrator",
      "modifiedDateTime": "2023-12-22T14:38:29.6030000Z"
    },
    {
      "_id": "17560262",
      "permissionProfileId": "17560262",
      "modifiedByUsername": "",
      "__NAME__": "DocuSign Sender",
      "permissionProfileName": "DocuSign Sender",
      "modifiedDateTime": "2023-12-22T14:38:29.6070000Z"
    },
    {
      "_id": "17560263",
      "permissionProfileId": "17560263",
      "modifiedByUsername": "",
      "__NAME__": "DocuSign Viewer",
      "permissionProfileName": "DocuSign Viewer",
      "modifiedDateTime": "2023-12-22T14:38:29.6100000Z"
    },
    {
      "_id": "20022036",
      "permissionProfileId": "20022036",
      "modifiedByUsername": "Carlos Garcia",
      "__NAME__": "API Admin",
      "permissionProfileName": "API Admin",
      "modifiedDateTime": "2024-02-07T15:38:03.1770000Z"
    }
  ],
  "resultCount": 4,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

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)

serviceUri

String

null

Yes

The service endpoint URI.

account

String

account

Yes

Description is not available

login

String

null

Yes

The service login name.

hourRateLimit

String

null

Yes

Description is not available

burstRateLimit

String

null

Yes

Description is not available

password

GuardedString

null

Yes

No

The service user password.

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

tokenEndpoint

String

null

No

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

clientId

String

null

Yes

The client identifier for OAuth2.

clientSecret

GuardedString

null

Yes

No

Secure client secret for OAuth2.

authToken

GuardedString

null

Yes

No

Static authentication token.

acceptSelfSignedCertificates

boolean

false

Yes

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

disableHostNameVerifier

boolean

false

Yes

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

disableHttpCompression

boolean

false

Yes

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

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

httpProxyHost

String

null

Yes

Defines the Hostname if an HTTP proxy is used between the connector and the service.

httpProxyPort

Integer

null

Yes

Defines the Port if an HTTP proxy is used between the connector and the service.

httpProxyUsername

String

null

Yes

Defines Proxy Username if an HTTP proxy is used between the connector and the service.

httpProxyPassword

GuardedString

null

Yes

Yes

Defines Proxy Password if an HTTP proxy is used between the connector and the service.

connectionTimeout

int

30

No

Defines a timeout for the underlying HTTP connection in seconds.

refreshToken

GuardedString

null

No

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.

authorizationTokenPrefix

String

Bearer

No

The prefix to be used in the Authorization HTTP header for Token authentication.

useBasicAuthForOauthTokenNeg

boolean

true

Yes

The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).

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

Dropbox connector

This is a SaaS common connector.

Before you start

  1. Create a Dropbox developer account.

  2. Create a new application with full Dropbox access. Add the required read and write permissions for team, member, and group. Remember to save the app key and app secret.

  3. Get a refresh token.

Install the Dropbox connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Dropbox

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/dropbox-connector-1.5.20.23.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 Dropbox 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 Dropbox Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Dropbox Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Base Connector Details

  • Dropbox Endpoint : https://api.dropboxapi.com/2

  • Use Basic Auth For OAuth Token Neg : true | false

  • Max connections: max size of the http connection pool used. Defaults to 10.

  • Connection Timeout (seconds): Defines a timeout for the underlying http connection in seconds. Defaults to 30.

Authentication

  • Token Endpoint: https://api.dropboxapi.com/oauth2/token

  • Client ID: Your Client ID.

  • Client Secret: Your Client Secret.

  • Refresh Token: Your Refresh Token.

Object Types

If necessary, add or edit your object types to have these three objects with their properties:

__ACCOUNT__
PROPERTY NAME TYPE NATIVE TYPE REQUIRED

team_member_id

String

String

NO

given_name

String

String

NO

surname

String

String

NO

email

String

String

YES

member_status

String

String

NO

membership_type

String

String

NO

role_id

String

String

NO

email_verified

Boolean

Boolean

NO

invited_on

String

String

NO

groups

Array

Object

NO

secondary_emails

Array

String

NO

abbreviated_name

String

String

NO

joined_on

String

String

NO
__GROUP__
PROPERTY NAME TYPE NATIVE TYPE REQUIRED

group_id

String

String

NO

group_name

String

String

YES

group_external_id

String

String

YES

members

Array

Object

NO

group_management_type

String

String

NO

member_count

Integer

Integer

NO
Role
PROPERTY NAME TYPE NATIVE TYPE REQUIRED

name

String

String

NO

description

String

String

NO

_id

String

String

NO

If configuring the connector over REST or through the filesystem, specify the connection details to the Dropbox resource provider in the configurationProperties for the connector. If you are using OAuth for your connection, the minimum required properties are serviceUri, tokenEndpoint, refreshToken, clientId, and clientSecret.

Sample Configuration 
{
    "configurationProperties" : {
        "tokenExpiration" : null,
        "accessToken" : null,
        "serviceUri" : "https://api.dropboxapi.com/2",
        "login" : null,
        "password" : null,
        "authenticationMethod" : "OAUTH",
        "tokenEndpoint" : "https://api.dropboxapi.com/oauth2/token",
        "clientId" : "k3..........5g",
        "clientSecret" : "xxxxxxxxxxxxxxxxxx",
        "refreshToken" : "xxxxxxxxxxxxxxxxxx",
        "authToken" : null,
        "acceptSelfSignedCertificates" : false,
        "disableHostNameVerifier" : false,
        "disableHttpCompression" : false,
        "clientCertAlias" : null,
        "clientCertPassword" : null,
        "maximumConnections" : "10",
        "httpProxyHost" : null,
        "httpProxyPort" : null,
        "httpProxyUsername" : null,
        "httpProxyPassword" : null,
        "connectionTimeout" : "30",
        "grantType" : null,
        "scope" : null,
        "authorizationTokenPrefix" : "Bearer",
        "useBasicAuthForOauthTokenNeg" : true
    }
}
On startup, IDM encrypts the value of the clientSecret.

Mapping

From Dropbox users to OpenIDM Users

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

team_member_id

teamMemberId

N/A

email

mail

N/A

surname

sn

N/A

given_name

givenName

N/A

member_status

memberStatus

N/A

membership_type

membershipType

N/A

email_verified

emailVerified

N/A

groups

groups

N/A

secondary_emails

secondaryEmails

N/A

member_status

memberStatus

N/A

Association>Association Rules>Correlation Queries

  • Link Qualifier: default

  • Any of the following fields: mail

From OpenIDM Users to Dropbox Users

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

givenName

given_name

N/A

sn

surname

N/A

mail

email

N/A

roleId

role_id

N/A

Association>Association Rules>Correlation Queries

  • Link Qualifier: default

  • Any of the following fields: email

From Dropbox groups to OpenIDM Groups
When a member is added or removed from a group, it is necessary to perform a reconciliation from dropbox members to IDM members to keep the members of a group up to date.

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

group_name

groupName

N/A

members

members

N/A

member_count

memberCount

N/A

group_external_id

groupExternalId

 
var result = source.group_external_id;
if(result == undefined){
result = source.group_id;
}
result;

group_management_type

groupManagementType

N/A

Association>Association Rules>Correlation Queries

  • Link Qualifier: default

  • Any of the following fields: groupExternalId

From OpenIDM Groups to Dropbox groups

Attributes Grid

SOURCE TARGET TRANSFORMATION SCRIPT

groupName

group_name

N/A

members

members

N/A

groupManagementType

group_management_type

N/A

groupExternalId

group_external_id

N/A

Association>Association Rules>Correlation Queries

  • Link Qualifier: default

  • Any of the following fields: group_id, group_external_id

Test the Dropbox connector

Test that the connector was configured correctly:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Accept-API-Version: resource=1.0' \
--request POST  'http://localhost:8080/system/Dropbox?_action=test'
{
    "name" : "Dropbox",
    "enabled" : true,
    "config" : "config/provisioner.openicf/Dropbox",
    "connectorRef" : {
        "bundleVersion" : [1.5.0.0,1.6.0.0),
        "bundleName" : "org.forgerock.openicf.connectors.dropbox-connector",
        "connectorName" : "org.forgerock.openicf.connectors.dropbox.DropboxConnector"
    },
    "displayName" : "Dropbox Connector",
    "objectTypes" : [
        "__GROUP__",
        "role",
        "__ACCOUNT__",
        "__ALL__"
    ],
    "ok" : true
}

MEMBERS

Invite a member

To invite a member, it is necessary to at least provide the email field. The fields given_name, surname, role_id are not required, but it is advisable to fill them in because these fields cannot be modified later. To get the list of roles go here:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Accept-API-Version: resource=1.0' \
--header 'Content-Type: application/json' \
--data '{
    "email" : "NEW.MEMBER@EMAIL.COM",
    "given_name" : "GIVENNAME",
    "surname" : "SURNAME",
    "role_id" : "ROLE ID"
}'
--request POST 'http://localhost:8080/system/Dropbox/__ACCOUNT__?_action=create'
{
    "_id" : "TEAM_MEMBER_ID",
    "role_id" : "ROLE_ID",
    "email" : "NEW.MEMBER@EMAIL.COM",
    ...
}
Get members

Retrieve a list of team members ids from Dropbox. The limit of results and the default value are 1000:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__?_queryId=query-all-ids'
{
    "result": [
        {
            "_id" : "001"
        },
        {
            "_id" : "002"
        },
        {
            "_id" : "003"
        },
        ...
    ]
}
Get member

Retrieve a team member from Dropbox. The team member id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__/TEAM_MEMBER_ID'
{
    "_id" : "TEAM_MEMBER_ID",
    "groups" : [
        {
            "access_type" : "member",
            "group_id" : "GROUP_ID"
        }
    ],
    "email" : "test@email.com",
    "abbreviated_name" : "gs",
    "joined_on" : "2023-01-01T00:00:00Z",
    "surname" : "surname",
    "member_status" : "active",
    "email_verified" : true,
    "given_name" : "givenname",
    "membership_type" : "full",
    "role_id" : "ROLE_ID"
}
Get member email

Retrieve a team member in Dropbox filtering by email field. The team member id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__/TEAM_MEMBER_ID?_fields=email'
{
    "_id" : "TEAM_MEMBER_ID",
    "email" : "test@email.com"
}
Delete member

Delete a member from a team. The team member id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Accept-API-Version: resource=1.0' \
--request DELETE 'http://localhost:8080/openidm/system/Dropbox/__ACCOUNT__/TEAM_MEMBER_ID'
{
    "_id" : "TEAM_MEMBER_ID",
    "email" : "deleted.member@email.com",
    ...
}

GROUPS

Create a new empty group

Group name must be provided at least when creating a new group. group_management_type can be user_managed or company_managed, default is company_managed.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Content-Type: application/json' \
--data '{
    "group_name" : "GROUP NAME",
    "group_management_type" : "company_managed",
    "group_external_id" : "GROUP EXTERNAL ID"
}'
--request POST 'http://localhost:8080/openidm/system/Dropbox/__GROUP__?_action=create' \
{
    "_id" : "_id",
    "group_id" : "GROUP_ID",
    "member_count" : 0,
    "group_name" : "GROUP NAME",
    "group_external_id" : "GROUP EXTERNAL ID",
    "group_management_type" : "company_managed",
    "members" : []
}
Get groups

Retrieves a list of groups showing only the ids. The limit of results and the default value are 1000:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/__GROUP__?_queryId=query-all-ids'
{
    "result": [
        {
            "_id" : "001"
        },
        {
            "_id" : "002"
        },
        {
            "_id" : "003",
        },
        ...
    ]
}
Update a group
The default group in Dropbox cannot be updated.

The fields that can be updated for a group are group_name, group_external_id, group_management_type (company_managed or user_managed). To add a member to a group, you need to provide the type of access and the team member id; to delete a member, delete the object. The group id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'If-Match: *' \
--header 'Content-Type: application/json' \
--data '{
    "group_name" : "new name",
    "group_management_type" : "company_managed",
    "group_external_id" : "new external id",
    "members" : [
        {
            "access_type" : "member",
            "team_member_id" : "TEAM_MEMBER_ID"
        }
    ]
}
--request PUT 'http://localhost:8080/openidm/system/Dropbox/__GROUP__/GROUP_ID'
{
    "group_id" : "GROUP_ID",
    "group_external_id" : "new extenal id",
    "group_name" : "new name",
    "member_count" : 1,
    "group_management_type" : "company_managed",
    "members" : [
        {
            "access_type" : "member",
            "team_member_id" : "TEAM_MEMBER_ID"
        }
    ]
}
Delete a group

The group id must be provided in the URI path:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header 'Accept-API-Version: resource=1.0' \
--request DELETE 'http://localhost:8080/openidm/system/Dropbox/__GROUP__/GROUP_ID'
{
    "_id" : "GROUP_ID",
    "group_name" : "group name",
    ...
}

ROLES

Get available roles from Dropbox members.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET 'http://localhost:8080/openidm/system/Dropbox/role/?_queryFilter=true'
{
    "result" : [
        {
            "_id" : "ROLE_ID",
            "name" : "Name role",
            "description" : "Description role"
        },
        ...
    ]
}

OpenICF Interfaces Implemented by the Dropbox Connector

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

Dropbox Connector Configuration

The Dropbox Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

serviceUri

String

null

Yes

The Dropbox endpoint URI.

login

String

null

Yes

The Dropbox login name.

password

GuardedString

null

Yes

No

The Dropbox user password.

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

tokenEndpoint

String

null

No

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

clientId

String

null

Yes

The client identifier for OAuth2.

clientSecret

GuardedString

null

Yes

No

Secure client secret for OAuth2.

authToken

GuardedString

null

Yes

No

Static authentication token.

acceptSelfSignedCertificates

boolean

false

Yes

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

disableHostNameVerifier

boolean

false

Yes

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

disableHttpCompression

boolean

false

Yes

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

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

httpProxyHost

String

null

Yes

Defines the Hostname if an HTTP proxy is used between the connector and the service.

httpProxyPort

Integer

null

Yes

Defines the Port if an HTTP proxy is used between the connector and the service.

httpProxyUsername

String

null

Yes

Defines Proxy Username if an HTTP proxy is used between the connector and the service.

httpProxyPassword

GuardedString

null

Yes

Yes

Defines Proxy Password if an HTTP proxy is used between the connector and the service.

connectionTimeout

int

30

No

Defines a timeout for the underlying HTTP connection in seconds.

refreshToken

GuardedString

null

No

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.

authorizationTokenPrefix

String

Bearer

No

The prefix to be used in the Authorization HTTP header for Token authentication.

useBasicAuthForOauthTokenNeg

boolean

true

Yes

The Authentication method for refresh token (Basic Authentication or Sending the ClientId and Client Secret in the Header).

(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 that handles medical records. The Epic connector enables customers to manage Epic EMP user and SER provider accounts along with their entitlements (Template and SubTemplate) using Epic APIs. For more information, refer to the Personnel Management and Demographics API documentation available at https://open.epic.com.

The Epic connector supports the following features:

  • Account management

    • Manage Epic EMP records as users

    • Create, update, delete

    • Enable, disable, unblock

  • Provider management

    • Manage SER records as linked provider

    • Create, update

    • Enable, disable

  • Other object types (only search operations)

    • Manage Epic Linked Template

    • Manage Epic Linked SubTemplates

    • Manage Epic InBasketClassifications

    • Manage Epic Login Department

    • Manage Epic Groups

  • Supported Epic versions: May 2019, August 2020, May 2020, February 2020

  • The Epic connector supports EMP user and SER provider records.

  • An Epic administrator account on the Epic system you want 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

    A valid Epic Client ID with access to Epic’s personnel management and demographics (user) web services.

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

  • User template file path (Optional)

  • User sub template file path (Optional)

  • In Basket classification file path (Optional)

  • Group file path (Optional)

The user template, user sub template, in basket, and group file paths are local paths that are accessible to the IDM or RCS instance.

Additional connector requirements:

  • Epic’s SOAP 1.1 version of web services enabled and accessible.

  • Epic system’s Personnel management and demographics (user) web services enabled for access.

  • Valid Epic web services credentials.

  • A list of Templates and SubTemplates.

    Epic does not provide APIs to programmatically query for Templates and SubTemplates. You must export separate CSV files for use with the Epic connector.

  • Contact Epic to enable the following APIs:

    GetImportDataLog

    Used to get provider response log
    ImportData (2019)

    Used to create/update provider
    InactivateUser

    Used to Disable user
    GetRecords

    Used to get all employee/provider records

  • Unlocked user attributes

    If you need any of the following attributes unlocked, you must request them from the Epic Data Courier team:

    • displayLicense

    • recipientType

    • isMedsAuth

    • isOrdersAuth

    • communicationPreference

    • taxId

    • isInPatientOrderProvider

    • isOutPatientOrderProvider

Install the Epic connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Epic

No

Yes

Download the connector .jar file from Backstage.

  • 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.23.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. 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 Epic Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Epic Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Test the Epic connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/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.

Epic remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Epic connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Epic connector from here.

Refer to Remote connectors for configuring the Epic remote connector.

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.

Supported resource types

The Epic connector supports the following resource types:

Epic connector supported resource types
ICF Native Type Epic Resource Type Naming Attribute

__ACCOUNT__

User

__NAME__

Department

Department

__NAME__

Provider

Linked Provider

__NAME__

UserTemplate

User Template

__NAME__

UserSubTemplate

User Sub Template

__NAME__

InBasketClassifications

In Basket Classifications

__NAME__

__GROUP__

Groups

__NAME__

Supported search filters

The Epic connector supports Search operations with the following filter operators and attributes:

Supported Operators and Filter Attributes With Epic Searches
Object Type Operators Attributes

__ACCOUNT__

Id filter

Id

Department

Id filter

Id

Provider

Id filter

Id

UserTemplate

Id filter

Id

UserSubTemplate

Id filter

Id

InBasketClassifications

Id filter

Id

__GROUP__

Id filter

Id

Attributes

The Epic connector supports the following attributes:

Account attributes

Attribute Description

Name

The name of the user

ContactDate

Date to use for the newly created contact

IsActive

Whether the user record should be set to active or inactive

UserID

External identifier for the user

UserIDType

Type of identifier provided in UserID

UserComplexName

Individual pieces of a user’s name which includes Academic Title, Father Name, First Name, Given Name initials, Last Name, Last Name Prefix, Primary Title, Spouse Last Name, Spouse Last Name First, Spouse Prefix, Suffix

ContactComment

Contact comment that will appear for the initial contact

SystemLoginID

New value for the user’s system login

LDAPOverrideID

A string that can be provided to identify the user to the LDAP server in place of the SystemLogin

UserAlias

New value for the user’s alias

UserPhotoPath

A URL or file path identifying the location of a picture to show for this user

Sex

The sex of the user

ReportGrouper1

New value for the user’s first freetext report grouper item

ReportGrouper2

New value for the user’s second free-text report grouper item

ReportGrouper3

New value for the user’s third freetext report grouper item

Notes

Free text notes about the user

UsersManagers

The user’s managers

PrimaryManager

The primary manager of this user

BlockStatus

A user’s block status which includes IsBlocked, BlockReason, BlockComment

DefaultLoginDepartmentID

The ID and ID type of the default login department

CategoryReportGrouper6

A list of values for the user’s sixth category report grouper item, which does not have an Epic-defined meaning

InBasketClassifications

List of new values for a user In Basket classifications

UserSubtemplateIDs

Sub template of the user

DefaultTemplateID

Default and Linked template of the user

Group

Group the user belongs to

Provider

The user’s provider id

LinkedProviderID

Links a provider’s schedule to a user

Department

Department the user belongs to

UserTemplate

Template of the User

InBasketClassifications attributes

Attribute Description

Value

The ID of the InBasketClassifications

Title

Description of the InBasketClassifications

UserSubtemplateID attributes

Attribute Description

User Subtemplate ID

The ID of the Linked Sub-template

User Subtemplate Name

The Name of the Linked Sub-template

Group attributes

Attribute Description

Value

The ID of the Group

Title

Display name of the Group

Type

Type of the Group

Provider attributes

Attribute Description

ExternalID

The ID of the Provider

Name

The name of the Provider

Title

Title of the Provider

NPI ID

NPI ID of the Provider

Provider Type

Type of the Provider

Specialty

Specialty of the Provider

Practice Name

Practice Name of the Provider

Street Address

Street Address of the Provider

Phone

Phone of the Provider

Specialties

The specialties of the Provider

Doctors Degree

The qualification of the Provider

Department attributes

Attribute Description

ExternalID

The ID of the Department

Name

The name of the Department

Center

Center of the Department

Specialty

Specialty of the Department

Location

Location of the Department

Service Area

Service Area of the Department

UserTemplate attributes

Attribute Description

User Template ID

The ID of the LinkedTemplate

User Template Name

The Name of the LinkedTemplate

Use the Epic connector

The Epic connector supports EMP user and SER provider records.

The Epic connector can perform the following actions:

Users

Create an Epic user

The following example creates a user with the minimum required attributes:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json"\
--request POST \
--data '{
  "UserID": "8675309”,
  "__NAME__": "Walter, Taylor"
}'\
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/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:

User accounts

  • __ENABLE__

  • __GROUP__

  • __NAME__ (Required)

  • __PASSWORD__

  • UserID

  • UserIDType

  • UserAlias

  • UserPhotoPath

  • Sex

  • Notes

  • Provider

  • LinkedProviderID

  • Department

  • ContactComment

  • ContactDate

  • SystemLoginID

  • LDAPOverrideID

  • DefaultLoginDepartmentID

  • ReportGrouper1

  • ReportGrouper2

  • ReportGrouper3

  • CategoryReportGrouper

  • InBasketClassifications

  • UsersManagers

  • PrimaryManager

  • DefaultTemplateID

  • UserTemplate

  • UserSubtemplateIDs

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

  • IsActive

  • BlockStatus - BlockStatus has the following sub-attributes:

    • IsBlocked

    • BlockStatus.Comment

In Basket Classifications

  • __UID__

  • __NAME__

Groups

  • __UID__

  • __NAME__

  • Type

User Templates

  • __UID__

  • __NAME__

User Sub Templates

  • __UID__

  • __NAME__

Provider

  • __NAME__

  • __UID__

  • ExternalID

  • Title

  • NPI ID

  • Provider Type

  • Specialty

  • Practice Name

  • Street Address

  • Phone

For example, to add a Suffix to a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PUT \
--data '{
  "__NAME__": "Walter, Taylor",
  "UserComplexName": {
    "Suffix": "Junior"
  }
}' \
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PUT \
--data '{
  "__PASSWORD__": "Passw0rd@123!",
  "__NAME__": "Walter, Taylor"
}' \
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PUT \
--data '{
  "__NAME__": "Walter, Taylorupdate",
  "__ENABLE__": "true"
}' \
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PUT \
--data '{ \
  "__NAME__": "TAYLOR, WALTER",
  "__ENABLE__": false
}'\
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request DELETE \
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/__ACCOUNT__/8675309"
{
  "code": 404,
  "reason": "Not Found",
  "message": "Object 8675309 not found on system/Epic/__ACCOUNT__"
}

Other objects

All supported resources can be queried, such as Department, Provider, Template, Sub Template, InBasketClassifications, and Groups:

Query Epic departments
Query all departments
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/Department?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "40"
    },
    {
      "_id": "56"
    },
    {
      "_id": "71"
    },
    {
      "_id": "77"
    },
    {
      "_id": "58"
    },
    [ ... ]
    {
      "_id": "46"
    },
    {
      "_id": "10120160"
    },
    {
      "_id": "1002020"
    },
    {
      "_id": "31"
    },
    {
      "_id": "83"
    },
    {
      "_id": "115"
    }
  ],
  "resultCount": 548,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query Epic providers
Query all providers
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/Provider?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "116"
    },
    {
      "_id": "E3087"
    },
    {
      "_id": "E4000"
    },
    {
      "_id": "E4913"
    },
    {
      "_id": "E5335"
    },
    {
      "_id": "E4716"
    },
    {
      "_id": "E5370"
    },
    [ ... ]
    {
      "_id": "E4001"
    },
    {
      "_id": "E4002"
    },
    {
      "_id": "E5137"
    },
    {
      "_id": "E5199"
    },
    {
      "_id": "E4003"
    },
    {
      "_id": "E4694"
    },
    {
      "_id": "E4004"
    },
    {
      "_id": "E4005"
    },
    {
      "_id": "E5019"
    },
    {
      "_id": "E4843"
    }
  ],
  "resultCount": 2560,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query a specific provider
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/Provider/E4716"
{
  "_id": "E4716",
  "Specialty": "Family Medicine",
  "__UID__": "E4716",
  "Provider Type": "Physician",
  "__NAME__": "WELLHIVE, PROVIDER"
}
Query user templates
Query all user templates
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/UserTemplate?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "T00004"
    },
    {
      "_id": "T00024"
    },
    {
      "_id": "T00033"
    },
    {
      "_id": "T00038"
    },
    {
      "_id": "T00076"
    },
    {
      "_id": "T00077"
    },
    {
      "_id": "T00078"
    },
    {
      "_id": "T00088"
    },
    {
      "_id": "T00089"
    },
    {
      "_id": "T00090"
    },
    {
      "_id": "T1000601"
    },
    {
      "_id": "T1002020"
    },
    {
      "_id": "T1020101"
    },
    {
      "_id": "T1020102"
    },
    [ ... ]
    {
      "_id": "T8888001"
    },
    {
      "_id": "T8889901"
    },
    {
      "_id": "T9998001"
    }
  ],
  "resultCount": 431,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query a specific user template
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/UserTemplate/T8888001"
{
  "_id": "T8888001",
  "__UID__": "T8888001",
  "__NAME__": "RESEARCH ADMINISTRATOR TEMPLATE"
}
Query user sub templates
Query all user sub templates
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/UserSubTemplate?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "ST00007"
    },
    {
      "_id": "ST00030"
    },
    {
      "_id": "ST10200"
    },
    {
      "_id": "ST10201"
    },
    {
      "_id": "ST10202"
    },
    {
      "_id": "ST10203"
    },
    {
      "_id": "ST10204"
    },
    [ ... ]
    {
      "_id": "ST10401"
    },
    {
      "_id": "ST10402"
    },
    {
      "_id": "ST10700"
    },
    {
      "_id": "ST107001"
    },
    {
      "_id": "T5080002"
    },
    {
      "_id": "T99901"
    },
    {
      "_id": "TCVREPSUB"
    }
  ],
  "resultCount": 91,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query a specific user sub template
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/UserSubTemplate/T00007"
{
  "_id": "T00007",
  "__NAME__": "EXCEL MEDICAL",
  "__UID__": "T00007"
}
Query In Basket classifications
Query all In Basket classifications
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/InBasketClassifications?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "15"
    },
    {
      "_id": "29"
    },
    {
      "_id": "30"
    },
    {
      "_id": "31"
    },
    {
      "_id": "84"
    },
    {
      "_id": "85"
    },
    {
      "_id": "100"
    },
    {
      "_id": "140"
    },
    {
      "_id": "141"
    },
    {
      "_id": "212"
    }
  ],
  "resultCount": 12,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query a specific In Basket classification
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/InBasketClassifications/140"
{
  "_id": "140",
  "__NAME__": "Model AP Pt Clinical Msg Pool",
  "__UID__": "140"
}
Query Epic groups
Query all groups
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/__GROUP__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    },
    {
      "_id": "3"
    },
    {
      "_id": "4"
    },
    {
      "_id": "5"
    },
    {
      "_id": "6"
    },
    {
      "_id": "7"
    },
    {
      "_id": "1000"
    },
    {
      "_id": "1001"
    },
    {
      "_id": "1002"
    },
    {
      "_id": "1003"
    },
    {
      "_id": "1004"
    },
    {
      "_id": "1005"
    },
    {
      "_id": "1006"
    }
  ],
  "resultCount": 14,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Query a specific group
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/Epic/__GROUP__/1000"
{
  "_id": "1000",
  "__NAME__": "Community",
  "__UID__": "1000",
  "Type": "Community",
  "Undefined3": "Customer~Epic Customer"
}

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

Provides the Client ID to authorize the Epic APIs.

privateKey

GuardedString

null

Yes

Yes

Provides the Private key in pkcs8 format.

userName

String

null

Yes

Provides the Username required for Connection.

password

GuardedString

null

Yes

Yes

Provides the Password required for Connection.

userTemplatesFilePath

String

null

No

Provides the location of User Template file.

subTemplatesFilePath

String

null

No

Provides the location of User Subtemplate file.

inBasketFilePath

String

null

No

Provides the location of In Basket Classifications File.

groupsFilePath

String

null

No

Provides the location of Group File.

maxRecords

int

50

No

Provides the Maximum records for search operation.

maxConnections

Integer

10

No

Provides the Maximum connections.

connectionTimeout

int

600

No

Provides the Maximum Connection Timeout in seconds.

accessToken

GuardedString

null

Yes

No

Provides the Access token to establish connectivity with the target.

tokenValidity

Long

null

No

Provides the Validity period of the token.

httpProxyHost

String

null

No

Provides the HTTP Proxy Host.

httpProxyPort

Integer

null

No

Provides the HTTP Proxy Port.

httpProxyUsername

String

null

No

Provides the HTTP Proxy Username.

httpProxyPassword

GuardedString

null

Yes

No

Provides the HTTP Proxy Password.

restEndpoint

String

https://vendorservices.epic.com/Interconnect-amcurprd-personnel-oauth/

No

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

soapEndpoint

String

https://vendorservices.epic.com/Interconnect-amcurprd-personnel-username/

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

The Google Apps connector is bundled with IDM and Advanced Identity Cloud. A sample connector configuration is also included with IDM. 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.

Google project requirements

Use of the Google Apps connector requires a properly configured Google project. The basic steps for configuring a Google project should be used as an outline, as the specific options, menus, and features may have changed.

  1. Log in to the Google Apps Developers Console and update your existing project or create a new project.

  2. Enable the following APIs for your project:

    Failure to enable the specified APIs results in the following depending on the Google Apps connector version:

    • For version 1.5.20.19 and earlier, connector requests hang indefinitely with no error message.

    • For version 1.5.20.20 and later, the connector logs an error.

  3. Set up an OAuth2 Client.

    The Google Apps connector uses OAuth2 to authorize the connection to the Google service:

    1. In the Google Apps Developers Console, select Credentials > Create Credentials > OAuth client ID.

    2. Click Configure Consent Screen, select Internal, and click Create.

    3. On the OAuth consent screen, enter an Application name; for example, RCS, and click Save.

      This name displays for all applications registered in this project.

    4. Select Credentials > Create Credentials > OAuth client ID > Web application, and enter information in the following fields:

      Authorized JavaScript origins

      The URI that clients use to access your application. The default URI is https://localhost:8443.

      The URI that you enter here must be the same you use to access RCS.
      Authorized redirect URIs

      The OAuth redirect URI, https://localhost:8443/admin/oauth.html by default.

    5. Click Create.

    6. On the OAuth client created pop-up, make a note of your Client ID and Client Secret.

  4. Add RCS to the Trusted Apps list:

    1. Log in to the Google Admin Console.

    2. From the top left menu, select Security > API Controls.

    3. Select MANAGE THIRD-PARTY APP ACCESS, click Change Access, and change the RCS app settings to Trusted.

Install the Google Apps connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Google Apps

Yes

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/googleapps-connector-1.5.20.23.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 Google Apps 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 Google Apps Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Google Apps Connector Configuration

    A Sign in with Google page displays.

  6. Log in.

    After you log in, Google requests access for the project.

  7. Click Allow.

    If you click Deny, you must return to the Connector Configuration > Details tab in the admin UI, and save your changes again.

When your connector is configured correctly, the connector displays as Active in the admin UI.

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.

A sample Google Apps connector configuration file is provided in samples/example-configurations/provisioners/provisioner.openicf-google.json with IDM.

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, refer to 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, refer to the following section of RFC 6749: Refresh Tokens.

For a sample Google Apps configuration that includes OAuth 2-based entries for configurationProperties, refer to Synchronize accounts with the Google Apps connector.

Test the Google Apps connector

You can test the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/googleapps?_action=test"
{
  "name": "googleapps",
  "enabled": true,
  "config": "config/provisioner.openicf/googleapps",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.googleapps-connector",
    "connectorName": "org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector"
  },
  "displayName": "GoogleApps Connector",
  "objectTypes": [
    "Role",
    "OrgUnit",
    "LicenseAssignment",
    "__GROUP__",
    "__ALL__",
    "RoleAssignment",
    "Privilege",
    "__ACCOUNT__",
    "Member"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the Google Cloud Platform system.

Google Apps remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Google Apps connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Google Apps connector from here.

Refer to Remote connectors for configuring the Google Apps remote connector.

Use the Google Apps connector with a proxy server

If the IDM 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:

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}

Role

role

{roleId}

RoleAssignment

roleassignment

{roleAssignmentId}

Privilege

privilege

Supported user attributes

The Google Apps connector supports the following user resource attributes:

Attribute Description

addresses

An array of addresses for the user account.

agreedToTerms

Whether the user has agreed to the Terms of Service.

aliases

An array of aliases for the user account.

archived

Whether the user account is archived.

changePasswordAtNextLogin

Whether the user must change their password at next login.

creationTime

The user creation time.

customerId

An ID used to identify the customer.

customSchemas

Define custom fields for user accounts.

deletionTime

The user deletion time.

emails

This attribute is managed using other attributes (primaryEmail, __SECONDARY_EMAILS__, aliases, nonEditableAliases).

etag

The ETag of the user account. Read-only attribute.

externalIds

An array of external IDs for the user account.

hashFunction

The hash function for the user’s password.

id

The unique ID for the user. id can be used as a user request URL’s userKey.

ims

An array of instant messenger accounts for the user.

includeInGlobalAddressList

Whether to include the user in the global address list.

ipWhitelisted

Whether the user’s IP is allowlisted.

isAdmin

Whether the user is an admin.

isDelegatedAdmin

Whether the user is a delegated administrator.

isEnforcedIn2Sv

Whether the user is enforcing two-step verification.

isEnrolledIn2Sv

Whether the user is enrolled in two-step verification.

isMailboxSetup

Whether the user’s mailbox is set up.

kind

The kind of user, typically admin#directory#user. Read-only attribute.

languages

An array of the user’s language preferences.

lastLoginTime

The last time the user logged in.

name

An object containing the fullName, givenName and familyName attributes.

nonEditableAliases

An array of non-editable aliases for the user account.

organizations

An array of organizations for the user account.

orgUnitPath

The full path of the parent organization associated with the user. If the parent organization is top-level, it is represented as a forward slash (/).

password

The user’s password.

phones

An array of phone numbers for the user account.

primaryEmail

The user’s primary email address.

recoveryEmail

The user’s recovery email address.

recoveryPhone

The user’s recovery phone number.

relations

An array of relations for the user account.

__SECONDARY_EMAIL__

(Deprecated)

Do not use this attribute.

As of version 1.5.20.21, __SECONDARY_EMAIL__ is deprecated. Use the newer attribute __SECONDARY_EMAILS__. These two attributes are mutually exclusive.

__SECONDARY_EMAILS__

An array of the user’s email addresses, excluding their primary email address and all editable and non-editable aliases.

suspended

Whether the user is suspended.

suspensionReason

The reason the user account is suspended.

thumbnailPhotoUrl

The url to a user’s thumbnail photo.

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 IDM 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 IDM managed objects.

  • The connector does not implement the Authenticate operation so you cannot use the connector to perform pass-through authentication between IDM 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:

Supported Operators and Filter Attributes With Google Apps Searches
Object Type Operators Attributes

__ACCOUNT__

And, Contains1, StartsWith, Equals

name, email, givenName, familyName, orgUnitPath, im, externalId, address, addressPoBox, addressExtended, addressStreet, addressLocality, addressRegion, addressPostalCode, addressCountry, orgName, orgTitle, orgDepartment, orgDescription, orgCostCenter

__GROUP__

Contains1, Equals

customer (Equals only), userKey (Equals only), _MEMBERS_ (Contains only)

Member

And, Equals

groupKey, memberKey (And only)

OrgUnit

StartsWith

orgUnitPath

LicenseAssignment

N/A

Role

N/A

RoleAssignment

N/A

Privilege

N/A

1 "Contains" looks for a whole word match, in the given order. For example, an API request with _queryFilter=givenName+co+'Ana' matches users with givenName values of "Ana" and "Ana Lucia" but not "Anabelle". A multi-word query for _queryFilter=givenName+co+'Ana Lucia' would match values of "Ana Lucia Evans" and "Ana Lucia Ball" but not "Lucia Ana".

Product licenses

The Google Apps connector can query all available licenses and return details of individual product licenses.

Query all available product licenses 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/googleapps/License?_queryFilter=true"
{
  "result": [
    {
      "_id": "Google-Apps/1010020027",
      "__NAME__": "Google Workspace Business Starter",
      "productId": "Google-Apps",
      "productName": "Google Workspace",
      "skuId": "1010020027",
      "skuName": "Google Workspace Business Starter"
    },
    {
      "_id": "Google-Drive-storage/Google-Drive-storage-20GB",
      "__NAME__": "Google-Drive-storage-20GB",
      "productId": "Google-Drive-storage",
      "productName": "Google-Drive-storage",
      "skuId": "Google-Drive-storage-20GB",
      "skuName": "Google-Drive-storage-20GB"
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Read a product license

To read the details of a license, perform a GET request on the endpoint:

system/googleapps/License/{PRODUCT_ID}/{SKU_ID}
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/googleapps/License/Google-Drive-storage/Google-Drive-storage-20GB"
{
  "_id": "Google-Drive-storage/Google-Drive-storage-20GB",
  "__NAME__": "Google-Drive-storage-20GB",
  "productId": "Google-Drive-storage",
  "productName": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-20GB",
  "skuName": "Google-Drive-storage-20GB"
}

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

Internet domain name. See https://support.google.com/a/answer/177483?hl=en.

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

Specifies whether the validation of the server certificate from the locally stored truststore is enabled. (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.

availableLicenses

String[]

['101005/1010050001', '101001/1010010001', '101031/1010310010', '101034/1010340002', '101038/1010380002', '101034/1010340001', '101038/1010380003', '101034/1010340004', '101034/1010340003', '101034/1010340006', 'Google-Apps/Google-Apps-For-Business', '101034/1010340005', 'Google-Vault/Google-Vault', 'Google-Apps/1010020031', 'Google-Apps/1010020030', 'Google-Apps/1010060003', 'Google-Apps/1010060005', 'Google-Apps/Google-Apps-Unlimited', 'Google-Apps/1010020029', 'Google-Apps/Google-Apps-Lite', '101031/1010310003', '101033/1010330002', '101033/1010330004', 'Google-Apps/Google-Apps-For-Education', '101031/1010310002', '101033/1010330003', 'Google-Apps/1010020026', '101031/1010310007', 'Google-Apps/1010020025', '101031/1010310008', 'Google-Apps/1010020028', 'Google-Apps/Google-Apps-For-Postini', '101031/1010310005', 'Google-Apps/1010020027', '101031/1010310006', '101031/1010310009', 'Google-Vault/Google-Vault-Former-Employee', '101038/1010370001', 'Google-Apps/1010020020', 'Google-Apps/1010060001']

No

All Google Licenses that will be queried when requesting licenses assigned to a user. The format of the license is ProductId/SkuId (e.g. Google-Apps/101002002).

roleMaxResults

int

100

No

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

roleAssignmentMaxResults

int

100

No

Maximum number of Licenses to return. Acceptable values are 1 to 100, 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.

Google Cloud Platform connector

Google Cloud Platform (GCP) is a suite of cloud computing services offered by Google. The GCP connector lets you manage and synchronize accounts between GCP and IDM managed user objects. A GCP administrator account is required for this connector to work.

Before you start

Before you configure the connector, log in to your GCP administrator account and note the following:

Domain name

The domain name of the account on GCP — for example, example.com.

Private key

The private key is required to sign the JWT token used to authenticate with GCP.

Service account

The GCP connector uses a service account with two-legged OAuth to connect to GCP. A service account is identified by its email address, which is unique to the account.

Admin user

The GCP administrator username.

The Admin SDK API must also be enabled to allow viewing and managing users in the Google Cloud Platform.

Install the GCP connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Google Cloud Platform (GCP)

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/gcp-connector-1.5.20.23.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 GCP 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 GCP Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to GCP Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Test the GCP connector

You can test the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/gcp?_action=test"
{
  "name": "gcp",
  "enabled": true,
  "config": "config/provisioner.openicf/gcp",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.gcp-connector",
    "connectorName": "org.forgerock.openicf.connectors.gcp.GcpConnector"
  },
  "displayName": "GCP Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the Google Cloud Platform system.

GCP remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the GCP connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the GCP connector from here.

Refer to Remote connectors for configuring the GCP remote connector.

Use the GCP connector

The following GCP account attributes are supported by the GCP connector:

Attribute Description

__NAME__

The username of the user. This maps to a user’s primaryEmail property in GCP. Required.

__PASSWORD__

Password for the user account. Required.

givenName

The first name of the user. Required.

familyName

The last name of the user. Required.

__UID__

The user ID for the user account.

emails

A list of emails associated with the user account. For example:

"emails": [
    {
        "address": "liz@example.com",
        "type": "home",
        "customType": "",
        "primary": false
    }
],

addresses

A list of addresses associated with the user account. For example:

"addresses": [
    {
        "type": "work",
        "customType": "",
        "streetAddress": "1234 Example Road",
        "locality": "Mountain View",
        "region": "CA",
        "postalCode": "94043"
    }
],

organizations

A list of organizations the user account is associated with. For example:

"organizations": [
    {
        "symbol": "Texas",
        "customType": "te",
        "costCenter": "Accounting Principles",
        "domain": "IAM",
        "name": "cloudauth",
        "description": "Agreed Accounting Principles",
        "location": "California",
        "department": "engineering",
        "title": "member",
        "type": "unknown"
    }
],

phones

A list of phone numbers associated with the user account. For example:

"phones": [
    {
        "customType": "custom",
        "type": "custom",
        "value": "+1 888 555 2312",
        "primary": false
    }
],

relations

A list of the user’s relationships to other users. For example:

"relations": [
    {
        "customType": "Cousin",
        "type": "custom",
        "value": "Bob Jensen"
    }
]

externalIds

A list of external IDs for the user, such as employee or network IDs. For example:

"externalIds": [
    {
        "customType": "employee",
        "type": "custom",
        "value": "12345"
    }
],

For a full list of attributes on GCP user accounts, refer to the GCP documentation.

You can use the GCP connector to perform the following actions on a GCP account:

Create a GCP user

The following example creates a user with the minimum required attributes:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "__NAME__": "bjensen@example.com",
  "__PASSWORD__": "Passw0rd!",
  "givenName": "Barbara",
  "familyName": "Jensen"
}' \
"http://localhost:8080/openidm/system/gcp/__ACCOUNT__?_action=create"
{
  "_id": "115637914640083360831"
}

When you create a new user, you must specify at least __NAME__, __PASSWORD__, givenName, and familyName. Refer to the list of available attributes for more information.
Update a GCP user

You can modify an existing user with a PUT request, including all attributes of the account in the request. The following attributes can be modified on a user:

  • primaryEmail

  • __PASSWORD__

  • givenName

  • familyName

  • organizations

  • addresses

  • emails

  • externalIds

  • relations

  • phones

For example, to add a new phone to a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "If-Match:*" \
--request PUT \
--data '{
  "__NAME__": "bjensen@example.com",
  "phones": [{
    "type": "mobile",
    "value": "+1 888 555 2312",
    "primary": true
  }]
}' \
"http://localhost:8080/openidm/system/gcp/__ACCOUNT__/115637914640083360831"
{
  "_id": "115637914640083360831",
  "givenName": "Barbara",
  "__UID__": "115637914640083360831",
  "phones": [
    {
      "value": "+1 888 555 2312",
      "type": "mobile"
    }
  ],
  "__NAME__": "bjensen@example.com",
  "familyName": "Jensen",
  "__ENABLE__": false,
  "emails": [
    {
      "address": "bjensen@example.com",
      "primary": true
    },
    {
      "address": "bjensen@example.com.test-google-a.com"
    }
  ]
}

The updated data may not appear in the initial response, but appears on any future queries of that user.
Query GCP users

The following example queries all GCP users:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/gcp/__ACCOUNT__?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "103181194086915091216"
    },
    {
      "_id": "104153234757881174617"
    },
    {
      "_id": "105181741894703739324"
    },
    {
      "_id": "105644268361304742523"
    },
    {
      "_id": "101682225764075422695"
    },
    {
      "_id": "101516788947553424126"
    },
    {
      "_id": "102825554929567443783"
    },
    {
      "_id": "101429904015255587067"
    },
    {
      "_id": "115637914640083360831"
    }
  ],
  "resultCount": 9,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The following command queries a specific user by their ID:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/system/gcp/__ACCOUNT__/115637914640083360831"
{
  "_id": "115637914640083360831",
  "givenName": "Barbara",
  "__UID__": "115637914640083360831",
  "phones": [
    {
      "value": "+1 888 555 2312",
      "type": "mobile"
    }
  ],
  "__NAME__": "bjensen@example.com",
  "familyName": "Jensen",
  "__ENABLE__": false,
  "emails": [
    {
      "address": "bjensen@example.com",
      "primary": true
    },
    {
      "address": "bjensen@example.com.test-google-a.com"
    }
  ]
}
Reset a GCP account password 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "if-Match:*" \
--request PATCH \
--data '[{
  "operation": "add",
  "field": "__PASSWORD__",
  "value": "Passw0rd@123!"
}]' \
"http://localhost:8080/openidm/system/gcp/__ACCOUNT__/115637914640083360831"
{
  "_id": "115637914640083360831",
  "givenName": "Barbara",
  "__UID__": "115637914640083360831",
  "phones": [
    {
      "value": "+1 888 555 2312",
      "type": "mobile"
    }
  ],
  "__NAME__": "bjensen@example.com",
  "familyName": "Jensen",
  "__ENABLE__": false,
  "emails": [
    {
      "address": "bjensen@example.com",
      "primary": true
    },
    {
      "address": "bjensen@example.com.test-google-a.com"
    }
  ]
}

While the __PASSWORD__ field is not returned as part of the response, the user object is updated.
Delete a GCP account

You can use the GCP connector to delete an account from the GCP service.

The following example deletes a GCP account:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request DELETE \
"http://localhost:8080/openidm/system/gcp/__ACCOUNT__/115637914640083360831"
{
  "_id": "115637914640083360831",
  "givenName": "Barbara",
  "__UID__": "115637914640083360831",
  "phones": [
    {
      "value": "+1 888 555 2312",
      "type": "mobile"
    }
  ],
  "__NAME__": "bjensen@example.com",
  "familyName": "Jensen",
  "__ENABLE__": false,
  "emails": [
    {
      "address": "bjensen@example.com",
      "primary": true
    },
    {
      "address": "bjensen@example.com.test-google-a.com"
    }
  ]
}

OpenICF Interfaces Implemented by the GCP Connector

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

GCP Connector Configuration

The GCP Connector has the following configurable properties:

Configuration properties

Property Type Default Encrypted(1) Required(2)

domainName

String

null

Yes

Provides the domain name for GCP.

privateKey

GuardedString

null

Yes

Yes

Provides private key to authenticate GCP.

serviceAccount

String

null

Yes

Provides service account for fetching users from GCP.

adminUser

String

null

Yes

Provides admin user for fetching users from GCP.

maxResults

int

50

No

Provides user max results for fetching users from GCP.

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

httpProxyHost

String

null

No

Provides the HTTP proxy host.

httpProxyPort

Integer

null

No

Provides the HTTP proxy port.

httpProxyUsername

String

null

No

Provides the HTTP proxy username.

httpProxyPassword

GuardedString

null

Yes

No

Provides the HTTP Proxy password.

connectionTimeout

Integer

300

No

Provides the maximum connection timeout in seconds.

maximumConnections

Integer

10

No

Provides the maximum connections.

(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. Instead, it is a framework where you must write your own Groovy scripts to address your implementation requirements.

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.

Alternatively, create a connector configuration file in your project’s conf directory. A number of sample configurations for scripted Groovy implementations are provided in openidm/samples/example-configurations/provisioners/provisioner.openicf-scriptedimplementation.json. Use these as the basis for configuring your own scripted connector.

Samples describes a number of scripted connector implementations. The scripts provided with these samples demonstrate how the Groovy connector toolkit can be used. These scripts cannot be used as is in your deployment but are a good starting point to base your customization. For information about writing your own scripts, refer to Scripted connectors with Groovy.

Validate pooled connections

The scripted SQL connector uses the Tomcat JDBC Connection Pool to manage its connections. Occasionally, a JDBC resource accessed by the scripted SQL connector might become unavailable for a period. When the resource comes back online, IDM is 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 IDM 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, refer to the KnowledgeBase article How do I add logging to Groovy scripts in IDM.

Run scripts through the connector

Groovy toolkit connectors have two operations that allow you to run arbitrary script actions: runScriptOnConnector and runScriptOnResource. runScriptOnConnector is an operation that sends the script action to the connector to be compiled and executed. runScriptOnResource is an operation that sends the script to another script to be handled.

runScriptOnConnector

The runScriptOnConnector script lets you run an arbitrary script action through the connector. This script takes the following variables as input:

configuration

A handler to the connector’s configuration object.

options

A handler to the Operation Options.

operation

The operation type that corresponds to the action (RUNSCRIPTONCONNECTOR in this case).

log

A handler to the connector’s log.

To run an arbitrary script on a Groovy toolkit connector, define the script in the systemActions property of your provisioner file:

"systemActions" : [
    {
        "scriptId" : "MyScript",
        "actions" : [
            {
                "systemType" : ".*ScriptedConnector",
                "actionType" : "groovy",
                "actionFile" : "path/to/<script-name>.groovy"
            }
        ]
    }
]

If you want to define your script in the provisioner file itself rather than in a separate file, you can use the actionSource property instead of the actionFile one. A simple example follows:

"systemActions" : [
    {
        "scriptId" : "MyScript",
        "actions" : [
            {
                "systemType" : ".*ScriptedConnector",
                "actionType" : "groovy",
                "actionSource" : "2 * 2"
            }
        ]
    }
]
It is optional to prepend the last script statement in actionSource with return.

Running MyScript will return:

{
  "actions" : [
    {
      "result": 4
    }
  ]
}

If your script accepts parameters, you may supply them in the request body or the query string. For example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data-raw '{"param1":"value1"}'
"http://localhost:8080/openidm/system/groovy?_action=script&scriptId=MyScript&param2=value2"**

You can also call it through the IDM script engine. Note that the system can accept arbitrary parameters, as demonstrated here:

openidm.action("/system/groovy", "script", {"contentParameter": "value"}, {"scriptId": "MyScript", "additionalParameter1": "value1", "additionalParameter2": "value2"})

runScriptOnResource

To run an arbitrary script using runScriptOnResource, you must add some configuration details to your provisioner file. These details include a scriptOnResourceScriptFileName which references a script file located in a path contained in the scriptRoots array.

Define these properties in your provisioner file as follows:

"configurationProperties": {
  "scriptRoots": [
    "path/to/scripts"
  ],
  "scriptOnResourceScriptFileName": "ScriptOnResourceScript.groovy"
},
"systemActions" : [
    {
        "scriptId" : "script-1",
        "actions" : [
            {
                "systemType" : ".*ScriptedConnector",
                "actionType" : "groovy",
                "actionFile" : "path/to/<script-name>.groovy"
            }
        ]
    }
]

When you have defined the script, you can call it over REST on the system endpoint, as follows:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/groovy?_action=script&scriptId=scriptOnResourceScript&scriptExecuteMode=resource"

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

Groovy Engine configuration
Property Type Default Encrypted(1) Required(2)

scriptRoots

String[]

null

Yes

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

classpath

String[]

[]

No

Classpath for use during compilation.

debug

boolean

false

No

If true, debugging code should be activated.

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.

minimumRecompilationInterval

int

100

No

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

recompileGroovySource

boolean

false

No

If set to true recompilation is enabled.

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script).

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files.

sourceEncoding

String

UTF-8

No

Encoding for source files.

targetDirectory

File

null

No

Directory into which to write classes.

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.

verbose

boolean

false

No

If true, the compiler should produce action information.

warningLevel

int

1

No

Warning Level of the compiler.

customConfiguration

String

null

No

Custom Configuration script for Groovy ConfigSlurper.

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive 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)

authenticateScriptFileName

String

null

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

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.

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.

schemaScriptFileName

String

null

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

scriptOnResourceScriptFileName

String

null

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

searchScriptFileName

String

null

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

syncScriptFileName

String

null

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

testScriptFileName

String

null

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

updateScriptFileName

String

null

The name of the file used to perform the UPDATE 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.

Scripted Poolable Groovy Connector Configuration

The Scripted Poolable Groovy Connector has the following configurable properties:

Groovy Engine configuration
Property Type Default Encrypted(1) Required(2)

scriptRoots

String[]

null

Yes

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

classpath

String[]

[]

No

Classpath for use during compilation.

debug

boolean

false

No

If true, debugging code should be activated.

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.

minimumRecompilationInterval

int

100

No

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

recompileGroovySource

boolean

false

No

If set to true recompilation is enabled.

scriptBaseClass

String

null

No

Base class name for scripts (must derive from Script).

scriptExtensions

String[]

['groovy']

No

Gets the extensions used to find groovy files.

sourceEncoding

String

UTF-8

No

Encoding for source files.

targetDirectory

File

null

No

Directory into which to write classes.

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.

verbose

boolean

false

No

If true, the compiler should produce action information.

warningLevel

int

1

No

Warning Level of the compiler.

customConfiguration

String

null

No

Custom Configuration script for Groovy ConfigSlurper.

customSensitiveConfiguration

GuardedString

null

Yes

No

Custom Sensitive 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)

authenticateScriptFileName

String

null

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

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.

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.

schemaScriptFileName

String

null

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

scriptOnResourceScriptFileName

String

null

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

searchScriptFileName

String

null

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

syncScriptFileName

String

null

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

testScriptFileName

String

null

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

updateScriptFileName

String

null

The name of the file used to perform the UPDATE 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.

HubSpot connector

The HubSpot connector lets you synchronize HubSpot contacts and companies with managed objects in an IDM 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.

For a complete example that includes the configuration required to synchronize users with this connector, refer to Synchronize data between IDM and HubSpot.

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

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

HubSpot

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/hubspot-connector-1.5.20.23.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

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

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to HubSpot Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Alternatively, configure the connector with a configuration file. IDM provides a sample connector configuration file in the /path/to/openidm/samples/example-configurations/provisioners directory. Copy this sample file (provisioner.openicf-hubspot.json) to your project’s conf directory.

Adjust the configurationProperties to match your HubSpot application details. You must provide a clientId, clientSecret, and refreshToken. Other properties are optional:

"configurationProperties" : {
    "clientId" : "daa533ae-xxxx-xxxx-xxxx-6e66d84e6448",
    "clientSecret" : "c598a365-xxxx-xxxx-xxxx-24b32b6ae04d",
    "refreshToken" : "f37e1132-xxxx-xxxx-xxxx-4b9e724ce4a0",
    "acceptSelfSignedCertificates" : true,
    "readSchema" : "true",
    "disableHostNameVerifier" : false,
    "maximumConnections" : "10",
    "permitsPerSecond" : "10",
    "httpProxyHost" : null,
    "httpProxyPort" : null
}

IDM encrypts the clientSecret and refreshToken as soon as the connector is enabled.

Test the HubSpot connector

Test that the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/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.

HubSpot remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the HubSpot connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the HubSpot connector from here.

Refer to Remote connectors for configuring the HubSpot remote connector.

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

Hubspot Connector Configuration

The Hubspot Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

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.

(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 Connection Properties

Property Type Default Encrypted(1) Required(2)

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.

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

IBM RACF connector

IBM Resource Access Control Facility (RACF) is an access control system for IBM mainframes running z/OS. The RACF connector lets you manage and synchronize accounts between RACF and IDM managed user objects. A RACF administrator account is required for this connector to work.

Before you start

The User ID and Password combination you use for connector setup must have access to the /rseapi/api/v1/tso RACF endpoint and be able to perform the following RACF commands:

  • SEARCH

  • LISTUSER

  • ADDUSER

  • ALTUSER

  • DELUSER

  • LISTGRP

  • ADDGROUP

  • ALTGROUP

  • DELGROUP

Before you configure the connector, log in to your RACF administrator account and note the following:

Host name

The domain name or IP address of the host where RACF is running.

Port

The port RACF is configured to use.

User ID

The RACF administrator user ID.

Password

The password for the RACF administrator account.

Segments

A list of RACF user profile segments that are supported. Refer to RACF segments and attributes for a list of available segments.

Accept self-signed certificates

A boolean determining whether RACF is configured to allow self-signed certificates. This should usually be false in production environments, but may be true during development.

Client certificate alias

Alias name for the client certificate.

Client certificate password

Password for the client certificate.

Install a signed certificate

You can install a signed certificate to access the ZD&T Enterprise Edition web server. To generate your own pkcs12 keystore (zdtkey.p12) containing the certificate and add the encrypted password to the server.env file, do the following:

  1. Check your installed web server’s installation directory. For example, /opt/ibm/zDT is the default installation directory, but you can specify your own installation directory during the installation process.

  2. Generate zdtkey.p12 and place it in the /path/to/zDT/zDTServer/resources/security.

    openssl pkcs12 -export -out zdtkey.p12 -inkey cert.key -in cert.crt -password pass:$passcert

  3. Modify the encrypted key store password:

    1. Get the value of wlp.password.encryption.key in the /path/to/zDT/zDTServer/resources/security/bootstrap.properties.

    2. Run the following command where you installed the web server:

      /path/to/zDT/Liberty/bin/securityUtility encode --encoding=aes --key=<value_of_wlp.password.encryption.key> <password>
      To run securityUtility successfully, the Java path must be set. For more information, refer to Java requirements.

    3. Modify the /path/to/zDT/Liberty/usr/servers/zDTServer/server.env file with your encoded password value. For example:

      POSTGRES_SERVER=xxx
POSTGRES_PORT=5432
...
KEYSTORE_PASSWORD={aes}AG6i...JiS0p

Install the RACF connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

IBM RACF

No

Yes

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/racf-connector-1.5.20.23.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 RACF 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 RACF Connector - 1.5.20.23.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to RACF Connector Configuration

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Test the RACF connector

You can test the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/racf?_action=test"
{
  "name": "racf",
  "enabled": true,
  "config": "config/provisioner.openicf/racf",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.racf-connector",
    "connectorName": "org.forgerock.openicf.connectors.racf.RacfConnector"
  },
  "displayName": "RACF Connector",
  "objectTypes": [
    "__ACCOUNT__",
    "__ALL__",
    "__GROUP__"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the RACF system.

RACF remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the RACF connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the RACF connector from here.

Refer to Remote connectors for configuring the RACF remote connector.

Configure connection pooling

The RACF connector uses the Apache HTTP client, which leverages the HTTP client connection pool, not the ICF connector pool.

RACF segments and attributes

The following tables list available attributes by segment. Attributes listed in the BASE segment are available by default. To use any other attributes, include the segment name in the list of segments in the RACF connector configuration.

User accounts support create, update, query, and delete actions. Groups only support query actions.

Account attributes

The following attributes are available to the __ACCOUNT__ resource object:

BASE segment
Attribute Description

userId

The user’s ID. Required.

__NAME__

The user’s system name. Must match userID. Required.

NAME

The user’s name.

OWNER

Owner of the user’s profile.

DFLTGRP

User’s default group.

AUTHORITY

User’s authority in the default group.

__PASSWORD__

User’s password.

PHRASE

Optional password phrase.

REVOKE

Expiration date for the user’s system access.

RESUME

Date the user’s system access is restored.

WHEN

Days of the week and hours of the day the user has access to the system.

CLAUTH

Classes in which the user can define profiles.

MODEL

Name of the data model profile used when creating new data profiles (either generic or discrete).

GROUP

The group the user belongs to.

SECLABEL

The user’s default security label.

GRPACC

Whether other group members have access to any other group set the user protects.

RESTRICTED

Indicates that when checking global access, the account will not be used to allow access to a resource.

AUDITOR

Gives the user the system-wide auditor attribute.

OPERATIONS

Gives the user the system-wide operations attribute.

SPECIAL

Gives the user the system-wide special attribute.

ADSP

Indicates all permanent data sets this user creates should be discrete profiles in RACF.
CICS segment
Attribute Description

CICS_OPCLASS

The classes the user is assigned in CICS. Determines which basic mapping support (BMS) messages are routed to the user. Represented as a number ranging from 01 to 24.

CICS_OPIDENT

A 1-3 character identification of the user for use by BMS.

CICS_OPPRTY

The number (0 to 255) that represents the priority of the user.

CICS_RSLKEY

The resource security level (RSL) keys assigned to the user.

CICS_TIMEOUT

The time in hours and minutes (either HMM or HHMM format) that the operator is allowed to be idle before being signed out.

CICS_TSLKEY

The transaction security level (TLS) keys assigned to the user.

CICS_XRFSOFF

Indicates whether the user should be signed out when an XRF takeover occurs.
DCE segment
Attribute Description

DCE_AUTOLOGIN

Single Sign On (SSO) processing. Either YES or NO.

DCE_DCENAME

The user’s DCE principal name.

DCE_HOMECELL

The user’s DCE home cell.

DCE_HOMEUUID

Defines the mapping between the user’s RACF user ID and the corresponding DCE principal UUID.

DCE_UUID

The user’s principal DCE UUID.
DFP segment
Attribute Description

DFP_DATAAPPL

The user’s DFP data application identifier.

DFP_DATACLAS

The user’s default data class for attributes used during allocation of any new data sets.

DFP_MGMTCLAS

The user’s default management class for attributes used in managing a data set after it is allocated.

DFP_STORCLAS

The user’s default storage class for logical storage attributes.
KERB segment
Attribute Description

KERB_ENCRYPT

The user’s encryption key types. Available values include: DES, DES3, DESD, AES128, and AES256.

KERB_KERBNAME

The user’s local principal name. The value specified must be unique.

KERB_MAXTKTLFE

The maximum Kerberos ticket life specified in seconds. Note that 0 is not a valid value.
LANGUAGE segment
Attribute Description

LANGUAGE_PRIMARY

The user’s primary language.

LANGUAGE_SECONDARY

The user’s secondary language.
LNOTES segment
Attribute Description

LNOTES_SNAME

The user’s short name for use with Lotus Notes in z/OS.
NDS segment
Attribute Description

NDS_UNAME

The user’s name for use with Novell Directory Services.
NETVIEW segment
Attribute Description

NETVIEW_CONSNAME

Master Console Station (MCS) console identifier. The console name value is an identifier 1-8 characters in length whose validity is checked by MVS processing.

NETVIEW_CTL

Specifies whether a security check is performed for this user. Either GLOBAL, GENERAL, or SPECIFIC.

NETVIEW_DOMAINS

The domain identifier for any dom