When I receive a Docusign custom connect POST message at my httpS server. How can I verify that it has in fact come from Docusign?
Does docusign have a list of IP addresses that they will send the post message from?
Is there some other recommended method to verify that the POST message was sent by DocuSign?
You have a few options to validate that the message is coming from Docusign depending on your requirements.
See this great Docusign Blog post about securing connect webhook listener
Use a Pre-shared Secret
Use Mutual TLS to authenticate the client(Docusign)
Check the SSL/TLS certificate of the webhook caller (DocuSign).
Set DocuSign to digitally sign the data in the notification XML
(Not recommended)Whitelist Docusign's IP addresses on your server that is listening to the connect messages.
More info here(Scroll to the bottom of the page. There's more section)
Related
On this page: https://developers.docusign.com/esign-rest-api/code-examples/webhook-status, the last section is called: There’s more. And there you can read that there are 3 ways to check that DocuSign is making the web hook request:
you can check the SSL/TSL certificate of the webhook caller (DocuSign).
set DocuSign to digitally sign the data
DocuSign publishes the IP address ranges
If we examine all these options we have:
This is false, you can't check the SSL certificate of who is making the request to you. SSL certs are designed to be used by clients connecting to servers to check that there is no man in the middle attack. And only the client can verify the cert of a server, not the other way around.
I can't find on the page any mention how to set the signature, and most importantly, how to check it.
The link provided to the Public IPs: https://trust.docusign.com/en-us/trust-certifications/ip-ranges/, does not work.
My questions are:
Where can I find some documentation about the signature process?
Where is the page with the public IPs?
The best way to do that is to create an HMAC key and use that to confirm that the calls are authentic.
Here is a full article on how to do that - https://developers.docusign.com/esign-rest-api/guides/connect-hmac
Thank you for reporting the out of date documentation. I've filed an internal bug report, DEVDOCS-1565, to have it updated.
As Inbar says in his answer, these days, the best solution is HMAC. You can also combine it with Basic Authentication if you're using DocuSign webhooks at the account level.
HMAC gives you the guarantees that the message did originate from DocuSign and that the message was not altered in transmission.
Don't set up a server on the Internet
The old way of receiving webhook messages was to set up a server that is accessible on the public internet. Due to the costs and Information Security issues creating and maintaining a service on the Internet, these days I suggest that you skip it.
Instead, use a cloud PAAS (AWS, Azure, Google Cloud, etc etc) to receive and queue the messages. Then, from behind your firewall, you can dequeue and process them. (With no changes to your firewall.)
See the Connect- series of code examples.
Mutual TLS for checking the client's certificate
Note that you can check the certificate of a client. This feature of the TLS (ne SSL) protocol is called Mutual TLS and is supported by DocuSign webhooks.
But HMAC is better since it also guarantees message integrity.
I would like to secure my servers for incoming traffic from BigCommerce.
BigCommerce allows for configuring a 3rd party email server
as well as webhooks. What are the addresses that will be used by these services?
We can't guarantee that webhooks will be sent from a specific block of IPs--those addresses can change any time and without notice. But if the purpose is to confirm that incoming webhooks are coming from BigCommerce, you can specify custom headers when creating your webhook. The headers are returned in the webhook payload, so you could set the custom header to a basic auth username/password, and check that at runtime to authenticate the POST.
We do have a list of IPs that I can send you for the SMTP server. Happy to connect by email if your contact info is still the same!
I am trying to get DocuSign Connect to make HTTP Post request to my URL.
I have done some testing with POSTMAN app on google chrome and I am able to process the DocuSign XML Messages sent through this HTTP Post Request.
Attached is my setup.
I am unable to receive any messages from DocuSign (I have tried both sending and signing) and additionally I do not see any logs under Logs or Failures.
Is there any possible reason for this?
Updates: I was using a Self-Signed Certificate on my application and hence DocuSign was unable to post the XML message to my web service.
This has been resolved after installation of a DocuSign accepted certificate.
Assuming your account is configured properly for Connect and you do not see anything in the logs or failures here's some possible reasons:
Security software or firewall on your side blocking/catching the message before it reaches your listener
You are filtering for an envelope you do not have permission to.
Your tests are invalid (i.e. you've configured for a signing event but the user is declining or taking some other action).
Also, I just realized you don't have Require Acknowledgement enabled in your Connect config- try turning that on to see if any failures start showing up. Here's the description from the docs of this option:
"Require Acknowledgment: Select this option to log posting failures. DocuSign waits 100 seconds for an acknowledgement before recording a failure. DocuSign logs a failure if the attempt to reach the external endpoint returns anything other than an HTTP 200. The acknowledgment failure messages are logged on the Failures page, which is accessed by clicking FAILURES on the Connect page. When this option is selected, DocuSign will automatically attempt to repost any failures. You can also manually repost from the Failures page."
Check that you have "Connect" enabled as one of the account's features. Do this using the admin tool (New DocuSign Experience) or Preferences in Classic.
Also, if you're trying out Connect on a production account, only some types of accounts include the Connect feature. Contact your Account Manager if it isn't enabled.
All Developer Sandbox accounts on the demo platform do include Connect.
All account types support webhook subscriptions at the envelope level using the eventNotification feature.
Are you using production account or sandbox account for docusign connect.. You must include the protocol HTTP or HTTPS in the web address for sandox account and you must include HTTPS:// in the web address for Production accounts because SSL is required in Production account. Docusign Connect sends the xml to the default ports of 443 for HTTPS: and 80 for HTTP. If you cannot use port 443 for Production contact DocuSign to review possible options. Check this link for docusign connect technical information.. Hope you have handled the server side of it (i.e, the url which you have mentioned in the URL to publish) inorder to get the response from the docusign to the desired url when some event happens..
For example:
If you are using sandbox docusign account for Connect means, URL to publish as to be something like this http://domain.com/Home/DocuConnect (Hosted application port number as to be 80). For sandbox account,docusign connect are enabled defaultly for all the users.
If you are using production account for Connect means, URL to publish as to be something like this https://domain.com/Home/DocuConnect (Hosted application port number as to be 443). In some cases docusign connect are enabled based on the respective subscription plans. To check that go to features tab see for Docusign Connect and try to tick the checkbox and if it is not checked then you got to contact the Docusign Account Manager.
I want to write an application which can receive emails locally and can response with successful and error responses.
After reading some tutorials about how SMTP works I was trying to send an email using telnet to my locally running SMTP server.
Connect to SMTP server
HELO/EHLO command
AUTH ...
MAIL from command
RCPT to command
DATA command
write somedata
QUITE
What I couldn't understand is step 3. Why do I need to be authenticated to send an email to localhost. I mean if I am yahoo user and I have to send an email to gmail user, how can I be authenticated to gmail SMTP server?
SMTP Auth is used to authenticate the send email. SMTP AUTH authenticates you directly with our SMTP server. This is transparent to you as a user.
SMTP is the protocol (the language) your email program uses to send email through our email server. AUTH is the part of that protocol that is used to verify that you are one of our users.
SMTP authentication allows the client to show the server that this client has permission to relay e-mail through this server.
In most cases, you can send without authentication to local e-mail addresses of this domain
(i.e. send from bob#domain.com to alice#domain.com)
because the server does not need to relay your e-mail to external servers. Authentication is required whenever the recipient is not of a local domain
(i.e. send from joe#company.com to tom#example.com, provided that
company.com and example.com use different e-mail servers).
If you want to read more about this Here I find the some reference where it explain very clearly.
http://www.afterlogic.com/mailbee-net/docs/smtp_authentication.html
http://www.softhome.net/help/faq/smtp-auth.html
Hope this can help full for you.
SMTP AUTH protects the server from unauthorized use. For example, Google doesn't allow people to send email from Google's email servers unless they have an account. You prove that you have an account (or that you are somehow authorized to use their servers) by authenticating with the AUTH command.
Maybe an example where the email service isn't free would be more clear. If you are trying to send email using GoDaddy's email servers, but you don't have an account, they will prevent you from doing it. GoDaddy charges people to use their services.
If you are running a company called mycompany.com, and you run your own mail servers, you don't want every spammer in the world using your servers to send email out of your company. You require senders to authenticate using AUTH in order to protect your servers from unauthorized use.
How do I secure my DocuSign Connect https listener so that only requests from DocuSign are accepted?
I have read the Connect service guide and am uncleared on whether the following setting can be used for this purpose:
Sign Message with X509 Certificate
Does this setting apply to both the SOAP and HTTPS listener interfaces?
Can this setting be used to secure my listener so that only DocuSign requests will be accepted?
How do I set up my service to validate the signed message as valid?
Does this setting apply to both the SOAP and HTTPS listener interfaces?
Yes, it does indeed apply to both listener interfaces.
Can this setting be used to secure my listener so that only DocuSign requests will be accepted?
Yes, that's what using the X509 certificates accomplishes.
How do I set up my service to validate the signed message as valid?
It is dependent on the encryption technology you decide to use. If you have something chosen already you should be able to go through its documentation to find out how to verify the messages. Often times it will be binary security token in the header.
More Info
Additionally, please note that DocuSign uses the standard WSE3 BinarySecurityToken
in the SoapHeader to pass the certificate.
From Page #9 of the DocuSign Connect Service Guide