Configure Single Sign-on (SSO) from Salesforce to DocuSign

This post provides step-by-step instructions for setting up single sign-on (SSO) from Salesforce to DocuSign.

Prerequisites

• DocuSign account with system administrator access. If you do not already have an account, sign up for a free developer sandbox here.
• In order for single sign-on to function, your DocuSign account must have Organization Management feature enabled (available for Enterprise accounts and developer sandboxes) and you must claim your domain.
• Salesforce org with identify features (developer or enterprise and up) with system administrator access. Sign up for a free developer edition org here.

Step 1: Set up My Domain in Salesforce

The My Domain feature creates a custom subdomain for your org and is required to use Salesforce as an identity provider. Go to Setup -> My Domain, enter a name for your subdomain and click “Check Availability”. Once you get a confirmation that the subdomain is available, click “Register Domain”. Salesforce will send you an email when the custom domain has been registered.

Click the link in the email and log in using your new domain. Navigate back to the My Domain page in setup. Click the “Deploy to Users” button.

Step 2: Enable Salesforce as an Identity Provider

You’ll need a self-signed or commercially signed certificate in order to enable Salesforce as an identity provider. If you don’t already have a certificate in the Salesforce org, you can quickly create one by going to Setup -> Security -> Certificate and Key Management. Click the “Create Self-Signed Certificate. Enter a descriptive name for the label and the unique name will be populated automatically. Click the “Save” button.

Now we can enable the Salesforce org to be an identity provider. Go to Setup -> Identity -> Identity Provider. Click “Enable Identity Provider”. Select the certificate you just created, or an existing one.

Step 3: Prepare DocuSign for SSO

Create a DocuSign Organization

In order to access single sign-on features in DocuSign, you must enable organization management and link your DocuSign account to your newly created organization. You will be setting up SSO with Salesforce as the identity provider and the DocuSign organization as the service provider.

An organization can have multiple DocuSign accounts associated with it, but DocuSign organizations are set up for either sandbox (demo) accounts or production accounts. At the time of writing this post, the organization feature is only available in demo accounts and in enterprise production accounts.

Claim Domain

After creating an organization, you will have have access to more administration settings. Navigate to the DocuSign Admin section and then to the Domains section. Click “Claim Domain”.

Enter your domain, for example “aaronwinters.org”. DocuSign will check that this domain has not already been claimed and will display a code. Add a TXT record for your domain with this code. In the DocuSign Domains admin section, click Actions -> Validate next to your domain.

Important: the domain you claim must be the same domain used by the identity provider, in this case the username of the Salesforce user that will be authenticating via single sign-on.

Get SSO Information from DocuSign

Log into your DocuSign account and navigate to DocuSign Admin -> Identity Providers. Click “New Identity Provider” and enter the following information

• Name: Salesforce
• Identity Provider Issuer: this should be your custom Salesforce domain: https://custom-domain.my.salesforce.com (may also look like this if you are using a developer edition org: https://custom-domain-dev-ed.my.salesforce.com)
• Identity Provider Login URL: enter the same value as the Identity Provider Issuer field (we will change this later)
• Send AuthN request by: POST
• Send logout request by: POST

Click “Save”.

In the list of identity providers there should be an entry for “Salesforce”. Click the “Actions” button and select “Endpoints”. You will need this information for the next step.

Step 4: Create a Connected App in Salesforce

The connected app is going to store information about DocuSign and is also going to be used to create the tile in the App Launcher so that users can quickly launch DocuSign from Salesforce.

Navigate to App Manager in Setup and click “New Connected App” in the top right of the page. Use the following values

• Connected App Name: DocuSign
• API Name: DocuSign
• Contact Email: (any email address)
• Logo Image URL: (click “Upload logo image” and upload an image file that is 125×125 pixels – this will appear in the app launcher tile)
• Enable SAML: true
• Entity Id: (copy the value from the Service Provider Issuer URL from the Endpoints modal in DocuSign)
• ACS URL: (copy the value from the Service Provider Assertion Consumer Service URL from the Endpoints modal in DocuSign)
• Subject Type: Username
• Name ID Format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• Issuer: this should be your custom Salesforce domain: https://<custom-domain>.my.salesforce.com (may also look like this if you are using a developer edition org: https://<custom-domain>.dev-ed.my.salesforce.com)
• IdP Certificate (Keep default value)

Click the “Save” button.

Next we need to give users access to the connected app. Navigate to Manage Connected Apps. Click the “DocuSign” app to open the detail page of the connected app. Click Manage Profiles and add the System Administrator profile.

DocuSign requires several attributes be included in the SAML assertion that are not included by default, so we need to add a few custom attributes. Scroll to the bottom of the page and click the “New” button in the Custom Attributes section.

1st custom attribute:

• Attribute key: firstname
• Attribute value: $User.FirstName

2nd custom attribute:

• Attribute key: lastname
• Attribute value: $User.LastName

Finally, we need to set the Start URL for the connected app. Copy the IdP-initiated login URL in the SAML Login Information section of the connected app detail page. Click the “Edit Policies” button. Paste the IdP-initiated URL into the Start URL field and click the “Save” button.

Step 5: Complete SSO Settings in DocuSign

Download the Certificate from Salesforce

First, download the certificate you used when enabling Salesforce as an identity provider by navigating to Setup -> Security -> Certificate and Key Management. Click the name of the certificate and then the “Download Certificate” button.

Update Identity Provider Settings in DocuSign

Log into DocuSign and navigate to Account Admin-> Identity Providers.

Edit the “Salesforce” identity provider:

• Identity Provider Login URL: now it is time to update – (enter the value of the “SP-Initiated POST Endpoint from the Connected App created in Step 4)
• Identity Provider Certificates: (click “AddCertificate” and select the certificate file you downloaded from Salesforce)

We need to add the mapping for the attributes DocuSign requires:

• surname -> lastname
• givenname -> firstname
• emailaddress -> email

Click “Save”.

Create SSO User

In the DocuSign Admin -> Users page in DocuSign, create a new user to test the SSO authentication flow. On the “User information” tab enter values for the following fields: Last Name, First Name and Email Address. Make sure the email address uses the same domain that you used when claiming your domain. Go through the rest of the user setup steps.

Navigate to the user record in the Salesforce org that you are going to use to test single sign-on. This user should be a system administrator, because that is the only profile we granted access to in the connected app. Make sure the that username and email matches the email address you used when creating the test user in DocuSign.

Step 6: Test the Single Sign-on Flow

Open the App Launcher. You should see a tile for your DocuSign app. Click the tile and DocuSign should open and you should be logged in automatically.

Resources

• Salesforce documentation: App Launcher
• DocuSign documentation: Single Sign-on Overview
• DocuSign documentation: Organization Administration Guide