From the Trenches: Tracing DocuSign transactions in Fiddler
Telerik Fiddler is a network analyzer that behaves like a proxy; as such, it is a very powerful tool in particular to monitor, inspect and log all DocuSign HTTPS traffic.
When you find you need to analyze DocuSign API request traffic, your first reflex will often be to activate DocuSign API request logging. You may find API request logging limited, however, when you need to analyze a high volume of queries, OAuth2.0 flow (which doesn’t appearing in DocuSign logging), or low-level issues related to TLS handshakes, encryption algorithm, and more.
Install and configure Fiddler Classic
First, you’ll need to download Fiddler Classic and install it on the machine running the DocuSign API, most of the time on a backend server.
HTTPS decryption
By default, Fiddler Classic does not capture and decrypt secure HTTPS traffic. To capture data sent through HTTPS, you’ll need to enable HTTPS traffic decryption in Fiddler:
- Select Tools > Options > HTTPS.
- Under “Capture HTTPS CONNECTs”, check the “Decrypt HTTPS Traffic” box.
Host filtering
To avoid being overwhelmed by all your internet traffic captured by Fiddler, I advise that you define a specific Host filter and flag the DocuSign domain names that will be accepted. Don’t hesitate to make other adjustments specific to your environment if needed:
- Click the Filters tab.
- Select “Show only the following Hosts”.
- Add the filter:
*akamaihd.net; *docusign.com; *docusign.net;in the text box.
Web traffic capture
You can enable or disable web traffic capture of the (it is enabled by default). To do so, select File > Capture Traffic, or you can simply use the keyboard shortcut F12.
Traffic archiving
Once your HTTP/HTTPS traffic has been captured under Fiddler, you can save a trace of it that will contain all requests and responses, plus an index page:
- Select File > Save > All Sessions.
- Save the traffic to a .SAZ file.
Capture DocuSign API traffic
I show you in this section some common DocuSign API operations captured with Fiddler, allowing you to see how this is structured.
JWT Grant authentication
Fiddler can show you traffic related to getting an access token with JSON Web Token Grant authentication:
- Obtain the access token:
POST https://account-d.docusign.com/oauth/token
If needed, you can decrypt the access token using an online tool such as https://token.dev/, and verify basic assertion field values. - Get the user’s base URI:
GET https://account-d.docusign.com/oauth/userinfo
Authorization Code Grant authentication
Fiddler can also show you traffic related to getting an access token with Authorization Code Grant:
- Request the authorization code:
GET https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature&client_id=7c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&redirect_uri=http://example.com/callback/
- Obtain the access token:
POST https://account-d.docusign.com/oauth/token
Envelope creation based on embedded signing
Use Fiddler to see the results of embedded signing operations:
- Create an envelope:
POST https://demo.docusign.net/restapi/v2.1/accounts/9dcf139b-xxxx-xxxx-xxxx-69dee73dcdfc/envelopes
- Create the recipient view:
POST https://demo.docusign.net/restapi/v2.1/accounts/9dcf139b-xxxx-xxxx-xxxx-69dee73dcdfc/envelopes/3b467b37-xxxx-xxxx-xxxx-1d289ae06f45/views/recipient
TLS handshake
A TLS handshake takes place whenever a communication uses HTTPS protocol, before the client can send API queries to the DocuSign service.
It’s pretty unlikely for an issue to be raised during the handshake, but we can imagine some possible ones:
- A cipher suite mismatch
- A protocol used by the client that isn’t supported by the server (ie: TLS 1.1)
- A wrong date or time on the client side
- A connection that is being intercepted by a third party
To see these or any other TLS handshake errors, double-click any of the tunnel entries shown in Fiddler:
In this case, you can see the client starts the negotiation with a "Hello" message based on a RSA key exchange, including:
- TLS version supported by the client =
TLS/1.2 - Cipher algorithm supported by the client =
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,... - A random byte string that will be used to generate the key for encryption =
62 A3...4E E7
DocuSign server answers to the "Hello" message and gives:
- The server TLS certificate:
"CN=account.docusign.com, O="DocuSign. Inc.", L=San Francisco..." - The TLS certificate issuer:
"CN=DigiCert SHA2 Extended Validation Server CA, OU=www.digicert.com, O=DigiCert Inc, C=US" - The cipher algorithm chosen by the server among the list given by the client:
Aes256 256bits / Sha384 bits / ECDHE_RSA (0xae06) 256bits
=> Equivalent to TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
It is important to recognize that in HTTPS decryption mode, the handshakes will likely behave slightly differently (due to the presence of Fiddler itself). If you want to see the handshake without any differences, disable decryption, or better yet, use the Wireshark network protocol analyzer.
Workflow timeline
To view a waterfall diagram of the transfer timeline:
- Select one or more HTTPS sessions in the list. Hold down the CTRL key and click to select more than one row.
- Select the Timeline tab:
And you can scroll horizontally all along the time period of these sessions:
With this diagram, it becomes clear if there is a request latency, or a long period without API activities. It also highlights if there are overlaps between requests, which in some cases could be considered as a potential issue.
Fiddler is a convenient and easy to use a HTTP/HTTPS/WebSockets proxy, but it also has its own limits if you need to visualize socket traffic that doesn't use those protocols. If you need to analyze other protocols, where the captured packet details are below TCP/IP, you should consider using a network protocol analyzer like Wireshark instead.
