Securing DocuSign Connect SOAP endpoint

0
votes

Per my initial question here, I'd like to go in depth regarding the proper way to secure a SOAP Connect endpoint.

@Drew indicated that the x509 signature should be used to verify the content. I've search through DocuSign's documentation, but I am unable to find concrete instructions.

In addition, I'm finding conflicting information on end point security. For example, this documentation says,

Mutual TLS can be used for XML or SOAP Connect configurations

While this documentation says,

This [Enable Mutual TLS] option is only available if Use SOAP Interface is not checked.

This adds to my confusion since I'm unsure whether some documentation is out dated.

1
c#docusignapi
Can you explain why you prefer to use SOAP over REST? - Inbar Gazit
@InbarGazit - At this point, time constraints and having a typed object (DocuSignEnvelopeInformation). I was far enough down the SOAP path to not have enough time to transition to REST. I did, however, transition to XML based instead of SOAP. - EnterTheCode

1 Answers

1
votes

The longer Connect guide, https://docs.docusign.com/supportdocs/ndse-admin-guide/Content/custom-connect-configuration.htm is, unfortunately, out of date. A new version is on the roadmap.

When SOAP format messages are used, there are two ways for the server (the "listener" operated by the customer) to authenticate the client (DocuSign Connect system).

Mutual TLS

Connect can be configured to make a SOAP request and to respond to Mutual TLS certificate requests. (If queried by the customer's server.)

Remember that Mutual TLS must be initiated by the server. DocuSign, the client, can only respond to Mutual TLS requests. And it will only do so if the request matches the cert held by DocuSign. I have written several blog posts about this on the DocuSign Developer Blog

Digital Signature

Connect can be configured to include a digital signature with the XML notification. Your app can then verify the signature. This can be quite complicated.

Recommendation: Don't use your own public server

If you can, I suggest not using your own server (with either SOAP or XML messages). Instead, you can receive the notifications from behind your firewall, with no changes to the firewall, by using an intermediary PaaS (Platform as a Service) to buffer/queue the notification messages. See this post and another post on the same subject is planned for the week of 2020.01.27.

This suggested Connect architecture uses both Basic Authentication and HMAC to authenticate the client (DocuSign).

Recommendation: Use XML, not SOAP

If you really want to create your own listener server, I suggest using XML, not SOAP. You can use HMAC to both authenticate the client (DocuSign) and verify that the payload was not altered. You'll also have much much earlier access to new Connect features which are in development.