Docusign Connect mTLS client certificates

0
votes

Context

I'm using mTLS to secure Docusign Webhooks (Docusign Connect Service). I'm able to make a successful mTLS connection to get certificate fingerprint, according to the documentation.

The next suggested step is to do access control by validating the certificate fingerprint and possibly the Distinguished Name (DN) but I'm confused what should the correct way to do so.

Questions

  • How do we know which client certificate is going to be sent by DocuSign to our listener in live environment (theoretically can be one of these and which logic is used to determine which one is sent? Should we validate which certification is sent by the DN (e.g. connect.docusign.net)?
  • What information should we validate from the certificate message? The fingerprint, DN, both or more?
  • With the above, how can we know all possible fingerprints to validate from server side, assuming different webhooks messages can send different client certificates? Should we compute the fingerprint of all public connect certificates to get a full list?
  • What is the best way to handle expirations of client certificates?
1
docusignapitls1.2docusignconnect

1 Answers

0
votes

Re:

Q. How do we know which client certificate is going to be sent by DocuSign to our listener in live environment (theoretically can be one of these and which logic is used to determine which one is sent? Should we validate which certification is sent by the DN (e.g. connect.docusign.net)?

A. Best is to validate based on the certificate's fingerprint matching a fingerprint of one of the expected certificates. DocuSign uses different certificates depending on the platform. But there's a limited set of certs used, so it should not be a big deal to check to see if the offered cert matches one of the expected certs.

Q. What information should we validate from the certificate message? The fingerprint, DN, both or more?

A. I'd recommend the fingerprint since it is more specific than the DN. With the DN, you're trusting the CAs to not issue a cert with a DocuSign DN to a bad guy. It should never happen but it has in the past (not to DocuSign though). See Rogue certificates

Q. With the above, how can we know all possible fingerprints to validate from server side, assuming different webhooks messages can send different client certificates? Should we compute the fingerprint of all public connect certificates to get a full list?

A. DocuSign uses a limited set of five certificates for webhook notifications, see the list on the trust center in the Connect Certificates section. Checking the incoming certificate against five or ten (see below) fingerprints is not a big deal.

Q. What is the best way to handle expirations of client certificates?

A. When the new certificates are announced, compute their fingerprints and add them to your system.

Then test by switching your DocuSign account to use the new certificates. Once the test succeeds, you can delete the fingerprints of the old certs.