DocuSign Connect Now Includes Basic Authentication Support
Available now for the DocuSign Developer Sandbox and production systems, the Connect notification service has been updated to support the Basic Authentication scheme with customers’ Connect servers (listeners).
When the optional feature is activated by a System Administrator for a Connect custom configuration (subscription), Connect will include the Authorization header in its requests to the customer’s web server.
The System Administrator uses the Connect configuration panel (see below) to enable Basic Authentication and to set the user name and password that will be sent.
Using the Edit command for the Connect custom configuration, the Basic Authentication setting can be enabled or disabled, and the user name and password can be updated.
The Basic Authentication option is only available for custom Connect configurations (account-level webhook subscriptions). Individual Envelope Connect configurations created with the eventNotifications API option do not support Basic Authentication at this time.
If enabled, the Basic Authentication header will be included with the Connect notifications. Enabling the Connect Basic Authentication option does NOT ensure that your server is implementing access control.
Access control and Basic Authentication requirements are implemented by your web server, not by DocuSign Connect.
FAQ
Q: Can the Basic Authentication feature be managed from the classic admin panel?
A: No, only the NDSE Admin tool can be used. If the NDSE Admin tool is used to add the Basic Authentication settings to a Connect configuration (subscription) then the other aspects of the configuration can still be managed via the classic admin panel.
Q: If my server (my Connect listener) is using Basic Authentication and either Connect is not set to use Basic Authentication or the user name/password is wrong, what error will be shown in the Connect retry queue?
A: The error message will be “401 Unauthorized”.
Q: If a Connect account-level configuration (subscription) is created programmatically, can the Basic Authentication parameters be included
A: Not at this time. This is planned for a future version of the Connect API.
Q: If an account has two custom configurations, are their Basic Authentication settings independent of each other?
A: Yes, each configuration has its own Basic Authentication settings.
Q: Why can’t an envelope-level Connect configuration created with the eventNotifications object include Basic Authentication settings?
A: The current API doesn’t support the additional parameters. A future version of the API will support Basic Authentication for envelope-level Connect configurations.
Q: If a Connect configuration includes Basic Authentication settings, won’t this ensure that my server is using access control?
A: No. Connect would send the Basic Authentication settings via the Authorization header, but your web server could simply ignore the header. The only way to ensure that your web server is using access control is for you to implement access control on the server itself.
Q: Can the Connect Basic Authentication settings be used to test the web server’s access control?
A: Yes. First set the Basic Authentication settings to a bad user name / password pair. Eg foo / foo. Send a Connect notification. The notification should fail. Then update the settings to a correct user name and password pair and the notification should succeed. You should also test that the notification will fail if Basic Authentication is turned off.
Q: When I edit a Connect configuration that includes Basic Authentication, the password is blank. If I change just the user name will the prior password still be used?
A: Yes, the prior password will still be used. On the edit screen, if you enter a new password then you’ll update the password.
Q: Can the Basic Authentication setting be combined with Mutual TLS?
A: Yes, they are independent.
Q: How do I configure my web server to require Basic Authentication?
A: This depends on the web server that’s being used. Instructions for Apache and Nginx servers. Instructions for IIS web servers. Use a search engine to find instructions for adding Basic Authentication to other web platforms such as Tomcat, Express, Flask, etc.
Q: Are the Basic Authentication user name and password sent in the clear?
A: Since all Connect transactions use HTTPS, the Basic Authentication parameters are encrypted during transit. Basic Authentication, when combined with HTTPS, is a good authentication technique.
Q: Should my web server and its Connect configurations use the Basic Authentication feature?
A: Yes. It is an excellent upgrade in security for Connect web servers.
Q: Will Basic Authentication become mandatory for Connect servers at some point?
A: No, it will always be an optional feature.
Additional Resources
Stay up-to-date with DocuSign developer news and information by visiting these additional resources:
