DocuSign SSO - How can I tell if my X509 certificate uploaded to DocuSign is the same as the one required by my IdP?

Issue

There is a problem logging in to DocuSign using SSO and it is unclear if the correct X.509 certificate is being used.  

Possible Causes

X.509 certificates can expire or require an update from the issuing IdP (Identity Provider). If the currently issued certificate is not the certificate uploaded to DocuSign, then you may experience an error that prevents users from logging in.  

Solution

The first item to check is the thumbprint on the certificate that is uploaded to DocuSign. This can be found by the Organization Administrator of the DocuSign account. 
  1. Log in to DocuSign with an Organization Administrator that can bypass SSO/Federated login
  2. Select the drop down in the upper right corner
  3. Choose the option Go to Admin
  4. Under the heading Organization, select the option Identity Providers
  5. Select Actions then Edit to the right of the IdP that is experiencing the issue.
  6. At the bottom of the next page is your certificate that is uploaded into DocuSign along with the thumbprint of that certificate. (See the below image)
  User-added image

There are two options you can take.

If you are aware of the location and can download the X.509 certificate from within your IdP you can:
  1. Double click to open the certificate
  2. Click on the details tab
  3. Scroll to the bottom of the window
  4. Confirm that the thumbprint at the bottom of that tab matches the thumbprint of the certificate in DocuSign (spaces are not relevant)
User-added image

The second option, while more difficult, is more thorough and can help you validate exactly what is being sent by your IdP in the SAML response. It can also provide you a copy of the IdP X509 certificate if you are unsure of where to locate it.
  1. To begin, familiarize yourself with and perform the steps in the article found here. (How to view a SAML Response in your browser for troubleshooting)
    • If these steps are too daunting, there are other tools that exist as plugins for the Chrome(SAML Chrome Panel) and Firefox(SAML Tracer) browsers that can simplify this process and provide a decoded response.
    • These plugins are third party applications and we cannot guarantee the availability or security involved with using them.
  2. In the SAML response from the IdP, the X509 certificate that is being passed will be included as part of the encoded response, usually in a node labeled <x509Certificate> or something similar  (see the below example)
    User-added image
  3. Copy the certificate data from this node (only copy the raw text seen in the highlighted portion of the example above)
  4. Place that data into a new text file
  5. Save the file to your desktop naming it anything you like but with the extension of ".cer".
  6. You can now repeat the steps from above:
    1. ​Double click to open the certificate
    2. Click on the details tab
    3. Scroll to the bottom of the window
    4. Confirm that the thumbprint at the bottom of that tab matches the thumbprint of the certificate in DocuSign (spaces are not relevant)

If you find that the certificates are not a match, upload the certificate from your IdP/SAML trace to DocuSign by using the below steps:
  1. Log in to DocuSign with an Organization Administrator that can bypass SSO/Federated login
  2. Click the drop-down in the upper right hand corner
  3. Select Go to Admin
  4. Select Identity Providers
  5. Select Actions next to the Identity Provider in question
  6. Select Edit
  7. Select Add Certificate
  8. Upload the certificate from saved location on the PC.
  9. Click Save
 

Related