Certificates for Secure API Access

You must purchase or create a digital signing certificate for your organization before you can create your API key. A certificate defines a public key and a private key. In order to make calls to the Document Cloud API, you package your API client credentials in a JSON Web Token (JWT), and sign it with the private key. Adobe uses the public key to authenticate the request.

You can purchase a certificate from a vendor, or create your own using openssh on Mac or Cygwin on Windows (which includes openssh). See Creating a Self-signed Certificate for details. When you create your own certificate, you create two separate files. One file contains the public key and another contains the private key. The public-key file can be in a CRT, CER, DER, or PEM format. If you purchase a digital certificate, you might receive a PFX or PKCS #12 (.p12) archive file that contains both keys. In this case, you must extract the public key and save it to a public-key file. See Splitting a certificate file.

  • You must provide the public-key certificate file to the Document Cloud API Support team as part of creating your API key and use the corresponding private key to sign JWTs that you create.
  • Your API key must be associated with at least one valid certificate. You can associate more than one certificate with your API key. If you do so, you can use the private key of any associated certificate to sign your JWT.
  • Adobe does not check for revocation or trust chains of the certificate. If you want to revoke a certificate that you have associated with an API key, you must do so by requesting the Document Cloud API Support team to disassociate the certificate from the API key. When you have done so, you can no longer use any JWT signed with the private key for that certificate to gain access to the Document Cloud API.

To replace certificates, see Adding, replacing or deleting your certificate.

Important: The files that contains the public and private keys, but especially the private key, contain sensitive information. You must secure your private key as it cannot be recovered or replaced. If you lose it or it is compromised, you must delete the corresponding certificate from your account. If necessary, you must create and upload a new certificate. You must protect these files at least as well as you would protect an account name and password. The best practice is to store the key files in a credential management system or use a file system protection so that it can only be accessed by authorized users.

Creating a self-signed certificate

You can create certificates in Windows with Cygwin, which includes openssl. On the Mac OS, you can use the built-in command-line tool openssl. To create a certificate with the command-line tool, open a terminal window on Mac or a Cygwin shell window in Windows, and run the platform-specific tool. In either case, the tool creates a public key in a certificate (CRT) file, and a private key.

The openssl req command creates a private-key file and a certificate (CRT) file containing the public key. During the key-generation process, you are prompted to enter additional information to create a DN (Distinguished Name) for the public key. You can accept default values in some cases. To leave a field blank, enter "." (a dot character). For example:

$ openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate_pub.crt

    Generating Generating a 2048 bit RSA private key
    ....................................................................................+++
    ............................+++
    writing new private key to 'private.key'
    -----

When the private key generation is complete, you'll see some instructions and a prompt to enter DN information. For example:

Country Name (2 letter code) [AU]: US
State or Province Name (full name) [Some-State]: California
Locality Name (eg, city) []: San Jose
Organization Name (eg, company) [Internet Widgits Pty Ltd]: My Company
Organizational Unit Name (eg, section) []: My Department
Common Name (e.g. server FQDN or YOUR name) []: Jane Administrator
Email Address []: j_admin@my_company.com

The certificate generated by this command expires in 1 year (365 days), at which point you can create a new one. You can make the period longer, but rotating credentials periodically is a good security practice.

In this example, the new private key file is named "private.key". You use the private key to sign your JSON Web Token (JWT). The contents of the private-key file look something like this:

-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDuRjXRJVYouxCl
o5fMCikkjaEgaIN6hVqsyM8hzAXJkPglpB1tSwFy968+S/4YnLZ2sZs2WCM17oVX
…
ObGhwhcnvUoqweQ3rMlJH3nGVg==
-----END PRIVATE KEY-----

The command also creates a new certificate file named "certificate_pub.crt" that contains the public key. You must provide the certificate to the Document Cloud API Support team when you request creation of a new API key for access to the Document Cloud API. The contents of the certificate file look something like this:

-----BEGIN CERTIFICATE-----
MIIEPTCCAyWgAwIBAgIJANU6Eel69NilMA0GCSqGSIb3DQEBCwUAMIG0MQswCQYD
VQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTERMA8GA1UEBwwIU2FuIEpvc2Ux
…
9ygguNdPe5SDGXueubbPVTEaee6mQamXhcnQ/1jQtNutUHJvwGng4MxLUkdim4/g
pqNlSLSXS26Dwu6qkBBpxdKA02qSK4lcfDkQwNR+ClrE
-----END CERTIFICATE-----

While setting up to run the samples in the Document Cloud SDK you will need to include in your configuration file a reference to a file containing your private key. The expected file format of the module generating the JWT is a PEM file containing an RSA private key. You can generate that file using the following openssl rsa command:

$ openssl rsa -in private.key -out keyout.pem

The 'private.key' file is the same file you generated in the previous step and keyout.pem is the file you will use in the JSON configuration file for the Document Cloud SDK samples. The contents of the PEM file look something like this:

-----BEGIN RSA PRIVATE KEY-----
F7aWZvcm5pYTEsMA8G31UEB4wIU2FuIEpvc2UxVQQGEwJVUzETMBEGA1UECAwKQ2
CAyWgAwIBAgIJANU6Eel79NilMb0GCSqGSIbfDQEBCwUAMIG0MQswCQYDMIIEPTC
…
9ygtuNdPe5SDGXueudbPVTEaxe6mQamXhcnQw1jQtNutUHJvwGng4MxLUkdim4fg
qe5SDGXueubbPVTEaee6mQamXhcnQ/1jQtNutUHJvwG1
-----END RSA PRIVATE KEY-----

You can learn more about Open SSL and other command parameters here: https://www.openssl.org/docs/man1.0.2/apps/req.html.

Adding, replacing or deleting your certificate

To associate a new certificate with your API key, follow these steps:

  1. Obtain or create the new certificate and private key file.
  2. Request the Document Cloud API Support team to associate the public key stored in the certificate with the API key. Do not share your private key with anybody.

To delete a certificate that has expired or been compromised:

  1. Request the Document Cloud API Support team to delete the certificate with the API key. Do not share your private key with anybody.

You must replace a certificate when it expires or is compromised. For a smooth transition from a certificate that is due to expire, initiate the replacement before the expiration date. Replacing a certificate involves assigning a new certificate with the API key, transitioning all the applications that depend on the API key to use the new private key and then deleting the old certificate. As soon as you have associated a new certificate with your API Key you can begin using the new private key to sign requests. When all of your applications have been converted to use the new certificate, you can delete the old certificate from the API Key.

Splitting a single certificate file

If you purchase a certificate or obtain one from an internal department that manages security in your company, you typically receive a single file in PKCS#12 format (PFX), containing both the public and private keys. In some cases, the file might also contain additional information that is not needed for Document Cloud API access, and could interfere with processing.

You can use the openssl command-line tool to extract the certificate and private key from the single file. If necessary, you can then use a text editor to reformat the extracted certificate for use with the Document Cloud API.

Extract keys

For example, this command extracts the certificate file from the PFX file:

$ openssl pkcs12 -in YourCertificate.pfx -out certificate_pub.cer -nokeys -nodes
    Enter Import Password:
    MAC verified OK

This command extracts the private key from the PFX file:

$ openssl pkcs12 -in YourCertificate.pfx -out private.key -nocerts -nodes
    Enter Import Password:
    MAC verified OK

Important: When you have extracted the private key file, it is no longer password protected. You must take extra measures to ensure its security such as storing it in a credential management system and setting file system permissions to restrict access to only authorized users.

Reformat extracted files

Open the files in a plain text editor. Do not use a word processing editor.

For the certificate file, remove any lines before or after the "-----BEGIN CERTIFICATE-----" and "------END CERTIFICATE-----" marker lines.

For the private key file, remove any lines before or after the "-----BEGIN PRIVATE KEY-----" and "------END PRIVATE KEY-----" marker lines.