Demystifying DocuSign certificates for developers
DocuSign offers many different digital certificates that are important to the security of our business. In this blog post, I would like to demystify and differentiate between the most commonly used certificates in the world of DocuSign. This is not an extensive list of all the different certificates, so you should check the full list of publicly offered certificates on DocuSign Support.
Network certificates
The first two certificates I’ll cover are related, so I will group them together; however, I will dive into the actual differences between the two, since they are used for different services. These are the Account Server certificates and the Site Certificates, which you can find under the Docusign Network Traffic Certificates tab in our list on DocuSign Support.
These certificates are used to encrypt the traffic for two of the services offered by the DocuSign platform:
- The authentication service to your account: account server certificate
- The REST API or, simply put, Signature services offered once you have authenticated into your account: site certificates
Let’s focus on the account server certificate. The endpoint or service offered behind this endpoint can quickly be seen when you attempt to log into your DocuSign account. It looks like this: https://account-d.docusign.com for demo and like this: https://account.docusign.com for your production account.
You can also see this if you are using the API to authenticate to DocuSign. In this image I am authenticating via JWT. For more information on the authentication methods with REST API, see eSignature REST API Authentication
As you can see in both examples, the URL includes https, which means the connection is encrypted with TLS. In some instances you may choose to validate the certificate for your custom integration. If you choose to do so, you will require the certificate offered by DocuSign. This is typically renewed once a year.
The Site certificate is used once you authenticate into your DocuSign account. You will notice that once I am logged into my account, the endpoint changes from https://account-d.docusign.com to https://apps-d.docusign.com/send/home or https://apps.docusign.com/send/home in production.
Again, the connection is encrypted with https and, as with the first certificate, you may choose to validate this certificate on your side for your custom integration, for example.
In this image you can see the endpoint being demo.docusign.net (apps.docusign.com in the UI); this may also be, depending on the production server your account is served from: eu.docusign.net, na1.docusign.net, na2.docusign.net, na3.docusign.net, na4.docusign.net, au.docusign.net, or ca.docusign.net.
This is not the full list of endpoints; however, I hope the examples I am providing should be enough to grasp the concept. Additionally, all the endpoints are reflecting where your account resides. DocuSign services are hosted in different locations, such as EU, NA1, AU, and more.
To get further into the nitty-gritty aspect of certificate validation, here is some more context:
The way SSL works is that the client connects to our server. Our server sends a certificate chain, and the client uses those certificates to encrypt and decrypt data. If you go to https://docusign.com, for example, this all happens in the browser you use. So you are always using our certificates.
Why then do you ever need to install our SSL certs?
Trust issues: Java 8, for example, doesn't trust our root certificate, because that version of Java is quite old. So instead you can install our certificate into the trust store for your app, which is essentially saying, “this is a safe certificate, I trust it.” Or, in some cases, you have set up SSL to only be trusted with installed SSL certificates in your trust store. This is even rarer than Java 8 (or another older platform). In almost all cases, the SSL process happens seamlessly.
SSO certificates
In this section I’ll describe two different types of single sign-on (SSO) certificates. To keep the topic from becoming confusing, I will describe these at a very high level, but I am including some additional links for experts to dive in.
IDPprovided SSO certificate
This type of SSO certificate needs to be uploaded in DocuSign Admin. This may often be mixed up with the account server certificate, which we already discussed, since both of them are related to authentication. The difference here is that the SSO certificate is used for users logging in with single sign-on, which uses SAML. This certificate is most commonly provided by your Identity provider (IDP): for example, Okta, Azure, Ping Identity, and others.
When this certificate expires, your users may lose the ability to access their DocuSign accounts via SSO. Since the provider of the certificate may vary, it is important to make sure you are aware of the origins of the certificate and the expiration date so that you can update it in DocuSign Admin to avoid this scenario. The certificate can be updated in DocuSign Admin under the Identity provider settings.
DocuSign’s optional SSO certificate
This self-signed certificate is offered on our DocuSign SSO Service Provider Certificate support page. For a further discussion of this topic, see the DocuSign support page DocuSign SSO Cert Renewal - Action Required.
This SSO certificate is only used as a key container. We use it to contain the key for the following use cases:
- SAML requests from DocuSign (the Service Provider) to IDPs, also known as AuthN requests, are signed with the private key, and IDPs validate the signature using the pub key.
- SAML responses from IDPs are encrypted with the public key, then we decrypt with the private key. (This is configured by the IDP)
Connect certificate
DocuSign Connect is a publishing service that essentially works as a reverse API service. You may choose to use a custom-made webhook or application to receive these events. Once an event occurs on the platform, such as “envelope sent”, then, if configured, your webhook or application should receive the event’s information. You can find out more about Connect on our Connect support page or the Connect section of our Developer Center.
You can add Mutual TLS authentication and authorization to your DocuSign Connect configuration to guarantee the identity of the server to the client and the identity of the client to the server, and provide a two-way encrypted channel between the two. To read more about this topic please check our developer guide.
The updated Connect certificates can be found on our Connect Certificates support page.
Additional resources
- DocuSign Developer Center
- @DocuSignAPI on X
- DocuSign for Developers on LinkedIn
- DocuSign for Developers on YouTube
- DocuSign Developer Newsletter
