DocuSign

Before You Begin

Introduction

This document describes how to configure Oracle Identity Cloud Service to provide Single Sign-On (SSO) and user provisioning for DocuSign.

About DocuSign

DocuSign provides electronic signature technology and Digital Transaction Management services for facilitating electronic exchanges of contracts and signed documents. DocuSign's features include authentication services, user identity management, and workflow automation.

After integrating DocuSign with Oracle Identity Cloud Service:

  • Users can access DocuSign using their Oracle Identity Cloud Service login credentials.
  • Users can launch DocuSign using the Oracle Identity Cloud Service My Apps console.
  • Admins can assign and revoke user access to the DocuSign app using the Oracle Identity Cloud Service administrator console.

What Do You Need?

  • An Oracle Identity Cloud Service account with authorization rights to manage apps and users (Identity Domain Administrator or Application Administrator).
  • A DocuSign account with authorization rights to configure federated authentication and user provisioning.
  • Identity provider metadata. You can use the following URL to access the metadata: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/metadata and save the metadata in a text file. Use this file later to obtain the identity provider certificate in the "Obtaining the Identity Provider Certificate" section.

Prerequisite Step

A dedicated host name is required before you can register and activate the DocuSign app. You obtain that host name from DocuSign.

The DocuSign host name appears in the login URL: https://<Host_Name>.docusign.com/ that you received in an email from DocuSign.

Obtaining the Identity Provider Certificate

Use this section to obtain the Identity Provider Certificate in a format that is suitable for DocuSign.

  1. Use the following URL to access the identity provider metadata: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/metadata.

  2. In the metadata file, locate the dsig:X509Certificate tags.

  3. Copy the content between the dsig:X509Certificate tags into a text file. This content is the Oracle Identity Cloud Service signing certificate.

    Image img1.png displays the metadata content with md:IDPSSODescriptor and dsig:X509Certificate tags highlighted.

  4. Add -----BEGIN CERTIFICATE----- at the beginning of the content.

  5. Add -----END CERTIFICATE----- at the end of the content.

    Image img2.png displays the text file with the certificate content highlighted.

  6. Save the text file in .pem format. This is the identity provider certificate.

    Tip: Use this certificate later during DocuSign configuration in the "Configuring SSO for DocuSign" section.

Configuring SSO for DocuSign

  1. Access DocuSign as an administrator using the URL: https://<Host_Name>.docusign.com that you received in an email from DocuSign. The DocuSign home page appears.

  2. In the upper-right corner, click the user icon, and then select Go to Admin from the drop-down list.

  3. Click Identity Providers. The Identity Providers page appears.

  4. Click ADD IDENTITY PROVIDER. The Identity Provider Settings page appears.

  5. Use the table to update the federated authentication attributes, and then click SAVE. A success message is displayed stating that you have successfully added an identity provider.

    Attribute Value
    Name Enter your identity provider name.
    Identity Provider Issuer Enter the Entity ID/Issuer URL. Use the metadata file that you downloaded earlier to obtain the Entity ID/Issuer URL. The Entity ID/Issuer URL information is located in the first line of the metadata. See the "What Do You Need?" section for the metadata file.
    Identity Provider Login URL Enter the Sign-in URL/SSO Endpoint: https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/idp/sso.
    Sign AuthN request Select the check box.

  6. On the Identity Providers page, locate and click Add New Certificate next to the name of your identity provider. The Identity Provider Settings page appears.

  7. Locate the Identity Provider Certificates section, click ADD CERTIFICATE, and then upload the certificate that you obtained earlier by performing the steps in the "Obtaining the Identity Provider Certificate" section. A success message is displayed stating that the certificate is successfully uploaded.

    Image img3.png displays the Identity Providers page with the Add New Certificate link highlighted.

  8. Click SAVE.

  9. On the Identity Providers page, click the ACTIONS drop-down list of your identity provider, and then select Endpoints. The View SAML 2.0 Endpoints pop-up window appears.

  10. Make note of the Service Provider Metadata URL, and then click CLOSE.

    Tip: Use this URL to access the service provider metadata and obtain the DocuSign certificate in the "Obtaining the Service Provider Signing Certificate" section.

    Note: Enabling SSO deactivates the ability to log in using the user name and password for all the users including administrators. To allow password access along with SSO for all users, in the left navigation menu of the Billing and Usage page, click Users under the USERS AND GROUPS section. On the Users page, click the required user to allow password access. Under the Login Policy drop-down list of the Edit User page, change the Default option to Identity Provider or Username / Password and then click SAVE. A success message is displayed stating that you successfully updated the user.

Obtaining the Required Parameters from DocuSign

  1. On the Identity Providers page header, click your account name next to Admin.

  2. Click Organization. The Organization page appears.

  3. Make note of the Organization ID.

    Tip: Use this Organization ID later during DocuSign registration in Oracle Identity Cloud Service in the "Registering and Activating the DocuSign App" section.

  4. On the Organization page header, click your account name next to Admin.

  5. Click Accounts. The Accounts page appears.

  6. Under the Manage Accounts section, click your account name. The Billing and Usage page appears.

  7. In the left navigation menu, locate and click Users under the USERS AND GROUPS section. The Users page appears.

  8. Locate and click the admin user.

  9. Under the Edit User section, make note of the API Username value.

    Tip: Use this API Username value later while enabling user provisioning for the DocuSign app in Oracle Identity Cloud Service. See the "Enabling Provisioning" section.

  10. In the left navigation menu, locate and click API and Keys under the INTEGRATIONS section. The For Developers: API and Integration Key Information page appears.

  11. Under the My Apps / Integration Keys section, click ADD APP / INTEGRATION KEY. The Add API Integration Key pop-up window appears.

  12. Enter App Name and click ADD. The API & Keys page appears.

    Note: Use the App Name value later as application name while authorizing the application in the succeeding steps.

  13. Under the Integration Key section, hover over and click Copy to clipboard to copy the Integration Key value.

    Tip: Use this Integration Key value later while enabling user provisioning for the DocuSign app in Oracle Identity Cloud Service. See the "Enabling Provisioning" section.

  14. Locate and click + ADD RSA KEYPAIR under the RSA Keypairs (ID) section. The RSA Keypair pop-up window appears.

  15. Make note of the Private Key and click OK.

    Tip: It is recommended to note the Private Key as the same Private Key value appears only once. Use this Private Key later while enabling user provisioning for the DocuSign app in Oracle Identity Cloud Service. See the "Enabling Provisioning" section.

  16. On the API & Keys page, click SAVE. The For Developers: API and Integration Key Information page appears.

  17. On the For Developers: API and Integration Key Information page header, click your account name next to Admin.

  18. Click Applications. The Applications page appears.

  19. Click AUTHORIZE APPLICATION. The Add New Application pop-up window appears.

  20. Under the Select an application from your organization drop-down list, select your application name.

    Note: This is the App Name value that you mentioned earlier in the Add API Integration Key pop-up window.

  21. Enter signature impersonation in the Permissions text box, and then click ADD. A success message is displayed stating that your application was successfully saved.

Obtaining the Service Provider Signing Certificate

Use this section to obtain the service provider certificate from the service provider metadata.

  1. Access the SAML Metadata URL that you obtained while performing the steps in the "Configuring SSO for DocuSign" section.

  2. In the metadata file, locate the X509Certificate tag.

  3. Copy the content between the X509Certificate tags into text file.

  4. Add -----BEGIN CERTIFICATE----- at the beginning of the content.

  5. Add -----END CERTIFICATE----- at the end of the content.

  6. Save the text file in .pem format. This is the service provider signing certificate.

    Tip: Use this service provider certificate later while registering and activating the DocuSign app in Oracle Identity Cloud Service. See the "Registering and Activating the DocuSign App" section.

Configuring DocuSign in Oracle Identity Cloud Service

Use this section to register and activate DocuSign, and to enable provisioning and synchronization for DocuSign.

Registering and Activating the DocuSign App

  1. Access the Oracle Identity Cloud Service administrator console, select Applications, and then click Add.

  2. Click App Catalog.

  3. Search for DocuSign, and then click Add.

  4. In the App Details section, enter your DocuSign Organization ID.

    Note: This is the Organization ID that you obtained while performing the steps in the "Obtaining the Required Parameters from DocuSign" section.

  5. Enter your DocuSign Host Name, and then click Next.

    Note: This is the host name value that you obtained while performing the steps in the "Prerequisite Step" section.

  6. In the SSO Configuration section, upload the signing certificate of the service provider.

    Note: This is the service provider signing certificate that you obtained by performing the steps in the "Obtaining the Service Provider Signing Certificate" section.

  7. Click Next to enable provisioning and synchronization for DocuSign. Oracle Identity Cloud Service displays the Provisioning page.

Enabling Provisioning and Synchronization for DocuSign

Use this section to enable provisioning and synchronization for managing user accounts in DocuSign through Oracle Identity Cloud Service.

Enabling Provisioning

  1. On the Provisioning page, select Enable Provisioning.

  2. Under the Configure Connectivity section, enter the API Username, Integrator Key, and RSA Private Key.

    Note: These are the values that you obtained while performing the steps in the "Obtaining the Required Parameters from DocuSign" section.

  3. Click Test Connectivity. A success message is displayed stating that the connection is successful.

  4. To view predefined attribute mappings between the user account fields defined in DocuSign and the corresponding fields defined in Oracle Identity Cloud Service, click Attribute Mapping, and then click OK.

    Note: To add a new attribute for provisioning, click Add Row, specify the attributes in the User and DocuSign Account columns, and then click OK. For example, if you want to add the External ID field, enter $(user.externalId) in the User column, and then select the corresponding field from the drop-down list in the DocuSign Account column.

  5. Specify the provisioning operations that you want to enable for DocuSign:

    Note: By default, the Create Account, Update Account, and Delete Account check boxes are selected.

    Create Account: Automatically creates a DocuSign account when DocuSign access is granted to the corresponding user in Oracle Identity Cloud Service.

    Note: When the user account is deleted, the same can be created again with either a different user name or email address in Docusign.

    Update Account: Automatically updates a DocuSign account when the corresponding user account is edited in Oracle Identity Cloud Service.

    Delete Account: Automatically removes an account from DocuSign when DocuSign access is revoked from the corresponding user in Oracle Identity Cloud Service.

    Note: When a user assigned to DocuSign is revoked in the Users tab of Oracle Identity Cloud Service, the user status will be changed to Closed in the DocuSign app. The same user can be reactivated in DocuSign, only if the user is not created again with the combination of both the same user name and email address in both Oracle Identity Cloud Service and DocuSign.

Enabling Synchronization

  1. On the Provisioning page, select Enable Synchronization.

  2. From the User Identifier drop-down list, select the Oracle Identity Cloud Service user attribute that you want to match with the corresponding record fetched from DocuSign:

    Note: By default, the Primary Email Address option is selected from the drop-down list. It is recommended to leave this default attribute for accurate synchronization of user records.

    Primary Email Address: Primary email address of the Oracle Identity Cloud Service user.

    User Name: User name of the Oracle Identity Cloud Service user.

  3. To match a DocuSign account attribute with the existing Oracle Identity Cloud Service user, select an attribute from the Application Identifier drop-down list.

    Note: By default, the name option is selected that represents the Email attribute of the DocuSign account. It is recommended not to change this default option.    

  1. From the When exact match is found drop-down list, select one of the following actions to be performed when a matching Oracle Identity Cloud Service user is found for an account:

    Link and confirm: Automatically links and confirms the matched account to the corresponding Oracle Identity Cloud Service users based on the defined User Identifier and Application Identifier fields. 

    Link but do not confirm: Automatically links all the matched accounts to the corresponding Oracle Identity Cloud Service users based on the defined User Identifier and Application Identifier fields. You need to manually confirm the linked accounts. 

  2. In the Max. number of creates field, enter a number that is greater than or equal to 10. This value limits the number of accounts to be created during the synchronization run.

  3. In the Max. number of deletes field, enter a number that is greater than or equal to 10. This value limits the number of accounts to be deleted during the synchronization run.

    After enabling provisioning and synchronization for DocuSign, you can synchronize the existing account details from DocuSign and link them to the corresponding Oracle Identity Cloud Service users. For more information on performing synchronization tasks, see the Importing User Accounts from a Software as a Service Application section in Administering Oracle Identity Cloud Service.

    You can also manage DocuSign accounts through Oracle Identity Cloud Service. For more information on performing provisioning tasks, see the Managing Oracle Identity Cloud Service Users and Managing Oracle Identity Cloud Service Groups sections in Administering Oracle Identity Cloud Service.

  4. Click Finish, and Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Verifying the Integration

Use this section to verify that SSO works when initiated from Oracle Identity Cloud Service (IdP initiated SSO) and DocuSign (SP initiated SSO).

Verifying Identity Provider Initiated SSO from Oracle Identity Cloud Service

  1. Access the Oracle Identity Cloud Service My Profile console using the URL: https://<IDCS-Service-Instance>.identity.oraclecloud.com/ui/v1/myconsole.

  2. Log in using credentials for a user that is assigned to the DocuSign app. Oracle Identity Cloud Service displays a shortcut to DocuSign under My Apps.

  3. Click DocuSign. The DocuSign home page appears.

  4. Confirm that the user that is logged in is the same for both DocuSign and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from Oracle Identity Cloud Service works.

Verifying Service Provider Initiated SSO from DocuSign

  1. Access DocuSign using the URL: https://<Host_Name>.docusign.com/. The DocuSign login page appears.

  2. Enter your email address, and then click CONTINUE. You are redirected to the Oracle Identity Cloud Service login page.

    Note: If password access is enabled, click USE COMPANY LOGIN in the DocuSign login page. You are redirected to the Oracle Identity Cloud Service login page.

  3. Log in using credentials for a user that is assigned to the DocuSign app. The DocuSign home page appears.

  4. Confirm that the user that is logged in is the same for both DocuSign and Oracle Identity Cloud Service.

    This confirms that SSO that is initiated from DocuSign works.

Troubleshooting

Use this section to locate solutions to common integration issues.

Known Issues

DocuSign displays the message, "The email address provided is not registered to your organization. Please contact your DocuSign Administrator."

Cause: The domain name in the email address sent by Oracle Identity Cloud Service during SSO doesn't match the administrator's domain name.

Solution: Ensure that the user that you assign to the DocuSign app has the same domain name as the administrator in both Oracle Identity Cloud Service and DocuSign.

Oracle Identity Cloud Service displays the message, "You are not authorized to access the app. Contact your system administrator."

Cause 1: The SAML 2.0 integration between the Oracle Identity Cloud Service DocuSign app and DocuSign is deactivated.

Solution 1:

  • Access the Oracle Identity Cloud Service administrator console, select Applications, and then select DocuSign.
  • In the App Details section, click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Cause 2: The administrator revokes access for the user at the same time that the user tries to access the DocuSign app using Oracle Identity Cloud Service.

Solution 2:

  • Access the Oracle Identity Cloud Service administrator console, select Applications, and then select DocuSign.
  • In the App Details section, select Users, and then click Assign to re-assign the user.

Unknown Issues

For unknown issues, contact Oracle Support:

  1. Go to https://support.oracle.com.

  2. Select Cloud Support, and then sign in with your support credentials.

  3. In the Cloud Dashboard, confirm that there are no planned outages in Oracle Identity Cloud Service, and then click Create Service Request.

  4. Select Oracle Identity Cloud Service as the service type.

  5. Complete your service request.