Two-way SSL, often called Client-Side SSL or mutual TLS, is a mode of SSL wherein both the server and the client (web browser) present certificates to identify themselves.

Account admins can configure a client-side certificate on the Security Settings page.

Acrobat Sign verifies the SSL certificates when delivering payloads to the webhook URL. Webhooks that fail the SSL certificate verification will not deliver the JSON payload successfully.

Use Two-way SSL to authenticate the client (Acrobat Sign) and listening service to ensure that only Acrobat Sign can reach your webhook URL.

If the webhook was created by a Partner Application, the webhook will use a client certificate (if available) from the Partner Application's Account to identify itself when sending webhook notifications.

Navigate to the UI controls to upload a client certificate

Below are the most common questions for both the web server verification process and the client certification verification.

Web server verification

During the registration of a webhook, Acrobat Sign verifies the webhook server URL.

Customers won't be able to register the webhook if the connection to the webhook callback URL cannot be completed from Acrobat Sign.

No.

The webhook callback URL can only be HTTPS on port 443 or 8443.

Acrobat Sign blocks outbound HTTPS traffic to all other ports.

A good way to verify the server certificate is to use the DigiCert® SSL Installation Diagnostics Tool.

Only enter the hostname e.g.: www.digicert.com

Common issues include:

Problem: Using an untrusted CA or self-signed certificate

Fix: Use a public CA issued SSL certificate for the webhook callback server.

Problem: The server is not sending the intermediate certificate

Fix: Install the intermediate certificates on the webhook callback server.

See https://www.digicert.com/kb/ssl-certificate-installation.htm for detailed information.

Client certificate verification

In order to set up a two-way SSL for a webhook, we require the administrator to upload a .p12 (or .pfx) file that contains the private key. The file is stored securely within the customer account, and the administrator has full control to remove it at any time.

In a two-way webhook setup, Acrobat Sign is the caller/client and needs the private key to prove that the call is made by Acrobat Sign on behalf of the customer account.

Verify that two-way SSL is enabled

Two-way SSL must be enabled on the webhook callback server.

Using any web browser, connect to the webhook callback URL. You should get:
```
400 Bad Request
No required SSL certificate sent
```
This means the server is expecting the client to send client certificates (i.e.: Two-way SSL is enabled for the server).

If you don't see the above message, then two-way SSL is not enabled.

Note:

You can use Postman, and do a POST request to the webhook callback URL. You should get a similar result.

Verify client certificate locally

The client credential can either be a self-signed certificate or CA issued certificate. However, it must minimally conform to the following X.509 v3 extensions:

X.509 v3 extension	Value
ExtendedKeyUsage	clientAuth (OID: 1.3.6.1.5.5.7.3.2)
KeyUsage	digitalSignature

The client certificate must be a PKCS12 file with extension .p12 or .pfx, and it must include both the client certificate (so the server can verify the identity of the client) and the client's private key (so the client can digitally sign messages for the server to verify during the SSL handshake).

Use the openssl command to verify the p12 (pfx) file:

openssl pkcs12 -info -in outfile.p12

The passphrase for the private key should be requested. The output should contain both certificates as well as an Encrypted Private Key like:

Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com
issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
-----BEGIN CERTIFICATE-----
MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE
...
JAKQLQ==
-----END CERTIFICATE-----
Bag Attributes: <No Attributes>
subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA
-----BEGIN CERTIFICATE-----
MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
...
-----END CERTIFICATE-----
Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
Key Attributes: <No Attributes>
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA
...
FHE=
-----END ENCRYPTED PRIVATE KEY-----

Certificates should minimally include the end-entity certificate and the intermediate certificates. Ideally, it will also include the root CA certificate.

Alert:

Make sure the .p12 or .pfx file is passphrase protected.

Create a self-signed client certificate (optional)

Client certificates can either be CA issued or self-signed, depending on your need.

To generate a self-signed client certificate, use the following openssl command:

openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

Caution:

Keep the resulting files secret as they are your self-signed CA certificates.
Next, generate the client .p12 file:
1. Generate a private key for the SSL client:
  openssl genrsa -out client.key 2048
2. Use the client’s private key to generate a cert request:
  openssl req -new -key client.key -out client.req
3. Issue the client certificate using the cert request and the CA cert/key:
  openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
4. Convert the client certificate and private key to pkcs#12 format for use by browsers:
  openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
5. Remove the client private key, client certificate, and client request files as the pkcs12 has everything you need.
  rm client.key client.cer client.req
Verify the client certificate against the remote server
- Use Postman to load the client PFX file in Settings > Certificates.
- Select Add Certificate to add the client certificate.
- Configure the HTTP header for x-adobesign-clientid:
Once configured, send a POST request to the webhook callback URL.

You should get a 200 response.
Why does Acrobat Sign reject my PFX file even after I have verified it with Postman?

If you have followed the above process for pfx file verification, and Acrobat Sign still rejects the pfx file, it's likely the file was generated by a Microsoft tool that can produce a non-standard PKCS12 file.

In that case, use the below openssl commands to extract the certificates and private key from the pfx file, and then generate a properly formatted PKCS12 file:
```
// Extract certificates and private key from pfx file
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.crt -nokeys
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.key -nodes -nocerts

// Create new PKCS12 file
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
```

Get help faster and easier

New user?

Two-way (mutual) SSL authentication

Two-way SSL authentication

Web server verification

Client certificate verification

Get help faster and easier

Ask the Community

Contact Us