Public Key Certificates for JWTs
You need a valid digital signing certificate to verify your identity in the JWT for your service-to-service integration with an Adobe I/O API or service. You upload a public-key certificate file to the Adobe I/O Console as part of creating your API key, and use the corresponding private key to sign any JWTs that you create.
You can create a self-signed certificate, or purchase one from a Certificate Authority.
- When you create your own self-signed 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 CRT, CER, DER, or PEM format. See Creating a self-signed certificate.
- If you purchase a digital certificate from a Certificate Authority, you might receive a PFX or PKCS #12 (.p12) archive file that contains both keys. In this case, you can extract the public key and save it to a public-key file. See Working with certificates from Certificate Authorities.
IMPORTANT The files that contains the public and private keys, but especially the private key, contain sensitive information. You must retain the private key securely. 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. In any case, you must replace a certificate when it expires or is compromised. See Replacing your 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 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. In 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 in Mac OS, 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).
# create the certificate and private key using openssl $ 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 see some instructions, and are prompted 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 upload the certificate to the Adobe I/O Console when you create the API key for access to any Adobe I/O API. The contents of the certificate file look something like this:
-----BEGIN CERTIFICATE----- MIIEPTCCAyWgAwIBAgIJANU6Eel69NilMA0GCSqGSIb3DQEBCwUAMIG0MQswCQYD VQQGEwJVUzETMBEGA1UECAwKQ2FsaWZvcm5pYTERMA8GA1UEBwwIU2FuIEpvc2Ux … 9ygguNdPe5SDGXueubbPVTEaee6mQamXhcnQ/1jQtNutUHJvwGng4MxLUkdim4/g pqNlSLSXS26Dwu6qkBBpxdKA02qSK4lcfDkQwNR+ClrE -----END CERTIFICATE-----
You can learn more about Open SSL and other command parameters here: https://www.openssl.org/docs/man1.0.2/apps/req.html.
Working with certificates from Certificate Authorities
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 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 Adobe I/O API.
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.
Replacing your certificate
You must replace a certificate when it expires or is compromised. You can plan to update certificates as part of your customer's update cycle. For a smooth transition from a certificate that is due to expire, initiate the replacement before the expiration date.
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 you have multiple valid certificates, you can use old and new certificates in parallel, up to the expiration date. When all of your applications have been converted to use the new certificate, you can delete the old certificate from the API key.
To associate a new certificate with your API key, follow these steps:
- Obtain or create the new certificate and private key file.
- Go to the Adobe I/O Portal and find your API Key entry.
- Click EDIT APP for your API Key.
- In the Certificates section, click Choose File and browse to the new certificate file.
- Click UPDATE API KEY.
You should now see two certificate entries for your API Key. To delete a certificate that has expired or been compromised:
- Go to the Adobe I/O Console and find your API Key entry.
- Click EDIT APP for your API Key.
- Click the X by the expired or compromised certificate entry, then click UPDATE API KEY.