IDM 7.2.2

DocuSign Connector

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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.

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

Before you start

The instructions in this chapter assume that you have a DocuSign administrator account, and that you have added an Integrator Key, as described in the DocuSign Documentation. Before you configure the connector, log in to your administrator account and note the following information:

  • API User ID

  • API Account ID

  • Integration Key

    You will also need to set up an RSA Keypair and copy the public and private keys to a location that will be accessible by the connector.

  • Docusign API Hostname

  • Docusign OAuth Hostname

You need these details to configure the connector to interact with your DocuSign environment.

The DocuSign connector uses Oauth to connect to DocuSign. You must grant authorization to the Integration Key by directing your browser to the following URL:

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=your-integrator-key&redirect_uri=https://client.example.com/callback

In the resulting window, click Accept to grant the required authorization.

The connector requires signing groups to be enabled. Depending on your DocuSign plan, you might need to contact the DocuSign Support team to enable signing groups. For more information, see the DocuSign documentation.

Install the DocuSign connector

  1. Download the connector .jar file from the ForgeRock BackStage download site site.

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

      mv ~/Downloads/docusign-connector-1.5.20.15.jar /path/to/openidm/connectors/

    • If you are using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

  2. Download the connector dependencies. The DocuSign connector has a dependency on the Java JWT library 3.4.0 (java-jwt-3.4.0.jar).

    • If you are running the connector locally, place the library in the /path/to/openidm/lib directory:

      mv ~/Downloads/java-jwt-3.4.0.jar /path/to/openidm/lib/

    • If you are using a remote connector server (RCS), place the library in the /path/to/openicf/lib directory on the RCS.

Configure the DocuSign connector

If you had already started IDM (or your RCS) before copying the connector .jar file to the connectors directory, you must restart the server for the connector to be loaded.

Create a connector configuration using the 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.15.

  5. Complete the Base Connector Details.

  6. Click Save.

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": {
    "host" : "_CHANGEME_",
    "oAuthHost" : "_CHANGEME_",
    "accountId" : "_CHANGEME_",
    "integratorKey" : "_CHANGEME_",
    "privateKeyFilePath" : "_CHANGEME_",
    "publicKeyFilePath" : "_CHANGEME_",
    "userId" : "_CHANGEME_",
    ...
}
host

The Docusign API hostname, for example, demo.docusign.net.

oAuthHost

The Docusign OAuth hostname, for example, https://account.docusign.com/oauth.

userId

The API User ID of the DocuSign user that will authenticate to the REST server. You can locate this ID under Admin > Integrations > API and Keys when you log in to your DocuSign account.

accountId

The API Account ID of the user specified previously. You can locate this account ID under Admin > Integrations > API and Keys when you log in to your DocuSign account.

integratorKey

The DocuSign Integration Key or client ID. You can locate the Integrator Key under Admin > Integrations > API and Keys when you log in to your DocuSign account. For more information, see the corresponding DocuSign documentation.

privateKeyFilePath

The full path to the Private Key of the RSA Keypair. To obtain the Private Key, select Admin > Integrations > API and Keys, then select Add RSA Keypair. Copy the value of the Private Key to a file and specify the file path in this property, for example: "privateKeyFilePath" : "/path/to/private-key.txt".

publicKeyFilePath

The full path to the Public Key of the RSA Keypair. To obtain the Public Key, select Admin > Integrations > API and Keys, then select Add RSA Keypair. Copy the value of the Public Key to a file and specify the file path in this property, for example: "publicKeyFilePath" : "/path/to/public-key.txt".

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

Alternatively, test the configuration over REST:

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/docusign?_action=test"
{
  "name": "docusign",
  "enabled": true,
  "config": "config/provisioner.openicf/docusign",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.docusign-connector",
    "connectorName": "org.forgerock.openicf.connectors.docusign.DocuSignConnector"
  },
  "displayName": "DocuSign Connector",
  "objectTypes": [
    "userSignature",
    "signingGroup",
    "__ALL__",
    "account",
    "contact"
  ],
  "ok": true
}

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

Configure Connection Pooling

The DocuSign connector supports connection pooling, which can substantially improve the performance of the connector. The basic connection pooling configuration is described in Connection pooling configuration.

Use the DocuSign Connector

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

Create a DocuSign User

This example creates a user with the minimum required attributes.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "userName": "Carlos Garcia",
  "email": "cgarcia@example.com",
  "password": "Passw0rd"
}' \
"http://localhost:8080/openidm/system/docusign/account?_action=create"
{
  "_id": "dc1c6940-1de7-4434-a91e-1407424cac91",
  "accountManagementGranular": [
    {
      "canManageUsers": "false"
    },
    {
      "canManageAdmins": "false"
    },
    {
      "canManageGroups": "false"
    },
    {
      "canManageSharing": "false"
    },
    {
      "canManageAccountSettings": "false"
    },
    {
      "canManageReporting": "false"
    },
    {
      "canManageAccountSecuritySettings": "false"
    },
    {
      "canManageSigningGroups": "false"
    }
  ],
  "userName": "Carlos Garcia",
  "enableConnectForUser": "false",
  "lastName": "Garcia",
  "createdDateTime": "2018-10-18T07:48:39.3870000Z",
  "userSettings": [
    {
      "name": "expressSendOnly",
      "value": "false"
    }
  ],
  "email": "cgarcia@example.com",
  "sendActivationOnInvalidLogin": "false",
  "userStatus": "ActivationSent",
  "firstName": "Carlos",
  "groupList": [
    {
      "groupName": "Everyone",
      "groupType": "everyoneGroup",
      "groupId": "4428049"
    }
  ],
  "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91",
  "isAdmin": "False",
  "userType": "CompanyUser"
}

When you create a new user, you must specify at least the userName, email, and password. The value of the userName attribute determines how the remaining name attributes (firstName, lastName, and so on) are set in the new DocuSign user entry.

If you create the user with a single word as the value of the userName attribute, for example, cgarcia, the user’s userName and lastName attributes in DocuSign are both set to cgarcia.

If you create the user with multiple words as the value of the userName attribute, for example, Carlos Garcia), the user’s userName attribute is set to Carlos Garcia, their firstName attribute is set to Carlos, and their lastName attribute is set to Garcia.

Only the first three words of the userName attribute are parsed, into the firstName, middleName, and lastName attributes. Any additional words are ignored.

By default, DocuSign accounts have a strict password strength setting. If a create operation fails with a ConnectorException and you see the following error in the logs, you may need to adjust Password Rules in DocuSign:

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

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

curl \
--header "Content-Type: application/json" \
--header "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"

Query DocuSign User Entries

This example queries all DocuSign users by their IDs:

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/docusign/account?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "bc9f0464-808a-4703-b4c2-c1e6a77f0c3a",
      "userName": "Babs Jensen"
    },
    {
      "_id": "dc1c6940-1de7-4434-a91e-1407424cac91",
      "userName": "Carlos Garcia"
    },
    {
      "_id": "94be4fed-cfd7-47d5-9fcc-813405084f17",
      "userName": "Olayinka Kuti"
    }
  ],
  "resultCount": 3,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The following command queries a specific user by their ID:

curl \
--header "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/docusign/account/dc1c6940-1de7-4434-a91e-1407424cac91"
{
  "_id": "dc1c6940-1de7-4434-a91e-1407424cac91",
  "accountManagementGranular": [
    {
      "canManageUsers": "false"
    },
    {
      "canManageAdmins": "false"
    },
    {
      "canManageGroups": "false"
    },
    {
      "canManageSharing": "false"
    },
    {
      "canManageAccountSettings": "false"
    },
    {
      "canManageReporting": "false"
    },
    {
      "canManageAccountSecuritySettings": "false"
    },
    {
      "canManageSigningGroups": "false"
    }
  ],
  "userName": "Carlos Garcia",
  "enableConnectForUser": "false",
  "lastName": "Garcia",
  "createdDateTime": "2018-10-18T07:48:39.3870000Z",
  "userSettings": [
    {
      "name": "expressSendOnly",
      "value": "false"
    }
  ],
  "email": "cgarcia@example.com",
  "sendActivationOnInvalidLogin": "false",
  "userStatus": "ActivationSent",
  "firstName": "Carlos",
  "groupList": [
    {
      "groupName": "Everyone",
      "groupType": "everyoneGroup",
      "groupId": "4428049"
    }
  ],
  "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91",
  "isAdmin": "False",
  "userType": "CompanyUser"
}

Modify a DocuSign User Entry

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

  • title

  • firstName

  • middleName

  • lastName

  • suffix

  • userName

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

If forgotten password recovery has been enabled for the DocuSign user account, (forgottenPasswordQuestion and forgottenPasswordAnswer have been set) you can use the connector to change a user’s password. You must include the following attributes in a password change request:

  • currentPassword

  • newPassword

  • email

  • forgottenPasswordQuestion

  • forgottenPasswordAnswer

  • forgottenPasswordInfo

The following example changes Carlos Garcia’s password:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-type: application/json" \
--request PATCH \
--data '[
  {
    "operation": "replace",
    "field": "password",
    "value": "MyPassw0rd"
  }
]' \
"http://localhost:8080/openidm/system/docusign/account/dc1c6940-1de7-4434-a91e-1407424cac91"
{
  "_id": "dc1c6940-1de7-4434-a91e-1407424cac91",
  "accountManagementGranular": [
    {
      "canManageUsers": "false"
    },
    {
      "canManageAdmins": "false"
    },
    {
      "canManageGroups": "false"
    },
    {
      "canManageSharing": "false"
    },
    {
      "canManageAccountSettings": "false"
    },
    {
      "canManageReporting": "false"
    },
    {
      "canManageAccountSecuritySettings": "false"
    },
    {
      "canManageSigningGroups": "false"
    }
  ],
  "userName": "Carlos Garcia",
  "userProfileLastModifiedDate": "2018-10-18T01:10:59.4230000Z",
  "enableConnectForUser": "false",
  "lastName": "Garcia",
  "createdDateTime": "2018-10-18T07:48:39.3870000Z",
  "userSettings": [
    {
      "name": "expressSendOnly",
      "value": "false"
    }
  ],
  "email": "cgarcia@example.com",
  "sendActivationOnInvalidLogin": "false",
  "userStatus": "ActivationSent",
  "firstName": "Carlos",
  "groupList": [
    {
      "groupName": "Everyone",
      "groupType": "everyoneGroup",
      "groupId": "4428049"
    }
  ],
  "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91",
  "isAdmin": "False",
  "userType": "CompanyUser"
}

If the naming component attributes are sent in an update, these attribute values are set on the DocuSign user. The user’s userName attribute is re-generated from the individual naming components. If both the userName and additional naming component attributes (such as firstName or lastName are sent in the update request, the supplied userName attribute is ignored and its value is regenerated from the individual naming components.

Close a DocuSign User Account

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

The following example closes Carlos Garcia’s DocuSign account:

curl \
--header "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/docusign/account/dc1c6940-1de7-4434-a91e-1407424cac91"
{
  "_id": "dc1c6940-1de7-4434-a91e-1407424cac91",
  "accountManagementGranular": [
    {
      "canManageUsers": "false"
    },
    {
      "canManageAdmins": "false"
    },
    {
      "canManageGroups": "false"
    },
    {
      "canManageSharing": "false"
    },
    {
      "canManageAccountSettings": "false"
    },
    {
      "canManageReporting": "false"
    },
    {
      "canManageAccountSecuritySettings": "false"
    },
    {
      "canManageSigningGroups": "false"
    }
  ],
  "userName": "Carlos Garcia",
  "userProfileLastModifiedDate": "2018-10-18T01:10:59.4230000Z",
  "enableConnectForUser": "false",
  "lastName": "Garcia",
  "createdDateTime": "2018-10-18T07:48:39.3870000Z",
  "userSettings": [
    {
      "name": "expressSendOnly",
      "value": "false"
    }
  ],
  "email": "cgarcia@example.com",
  "sendActivationOnInvalidLogin": "false",
  "userStatus": "ActivationSent",
  "firstName": "Carlos",
  "groupList": [
    {
      "groupName": "Everyone",
      "groupType": "everyoneGroup",
      "groupId": "4428049"
    }
  ],
  "uri": "/users/dc1c6940-1de7-4434-a91e-1407424cac91",
  "isAdmin": "False",
  "userType": "CompanyUser"
}

A closed account remains in the DocuSign repository and can still be queried by its ID.

OpenICF Interfaces Implemented by the DocuSign Connector

The DocuSign Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector.

Any script that runs on the connector has the following characteristics:

  • The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.

  • The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.

  • The script has access to any script arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Test

Tests the connector configuration.

Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

DocuSign Connector Configuration

The DocuSign Connector has the following configurable properties:

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

host

String

null

Yes

The DNS name or IP address of the DocuSign REST server

oAuthHost

String

null

Yes

The OAuth host URL to the DocuSign REST server

accountId

String

null

Yes

The DocuSign Account ID to manage

integratorKey

String

null

Yes

The DocuSign integrator key for accessing the REST API

privateKeyFilePath

String

null

Yes

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

publicKeyFilePath

String

null

Yes

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

userId

String

null

Yes

The user ID of the user creating the JSON web token (JWT)

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.

Advanced Configuration Properties

Property Type Default Encrypted(1) Required(2)

acceptSelfSignedCertificates

boolean

false

Yes

Specifies that the HTTP client accepts self-signed certificates

disableHostNameVerifier

boolean

false

Yes

Specifies that the HTTP client does not verify the host name

maximumConnections

Integer

10

No

The maximum number of connections

httpProxyHost

String

null

Yes

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

httpProxyPort

Integer

null

Yes

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

organizationConsent

Boolean

false

Yes

Specifies that there is consent from the organization

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.