PingAM 7.5.0

Import PEM-formatted keys

AM supports loading certificates, keys, and secrets in PEM format in the following secret stores:

  1. Create or obtain PEM-formatted secrets.

    Supported PEM formats

    Standard PEM-formatted secrets

    • Elliptic Curve and RSA private keys, in OpenSSL and PKCS#8 formats.

    • Elliptic Curve and RSA public keys, in OpenSSL and X.509 formats.

    ForgeRock non-standard PEM-formatted secrets

    • AES and HMAC secrets.

    • UTF-8-encoded generic secrets, such as passwords and API keys.

    You may obtain standard PEM-formatted secrets from your CA authority, or you can create your own files using, for example, the openssl utility. Standard PEM-formatted private keys can also be password-encrypted using the openssl utility.

    To create non-standard PEM-formatted secrets, perform the following steps:

    • To create AES or HMAC secrets, create a string of random bytes to work as cryptographic material, and base64-encode it.

      For example:

      $ head -c32 /dev/urandom | base64 > myEncodedSecret.txt

    • To create generic secrets, base64-encode the secret or key.

      For example:

      $ base64 myDecodedSecret.txt > myEncodedSecret.txt

    • Open the file with the secret and wrap it in PEM labels, such as the following:

      • HMAC Secrets

      • AES Secrets

      • Generic Secrets

      -----BEGIN HMAC SECRET KEY-----
Base64-encoded cryptographic material
-----END HMAC SECRET KEY-----
      -----BEGIN AES SECRET KEY-----
Base64-encoded cryptographic material
-----END AES SECRET KEY-----
      -----BEGIN GENERIC SECRET-----
Base64-encoded secret
-----END GENERIC SECRET-----

    • Encrypt the contents of the non-standard PEM-formatted file using the https://openam.example.com:8443/openam/encode.jsp page, and save it to a file.

      The encryption process will create a string that is not PEM-formatted: do not add the PEM labels again. When AM reads the secret from the secret store that you will configure in the following step, it will decrypt it automatically and use it as a PEM secret.

  2. Save the secret in the relevant place:

    1. For file system secret volume stores, copy the file with the secret to the location defined as the source of the store.

      For information on the file name to use, see Map files in file system secret volumes secret stores.

    2. For the environment and system property secrets store, add the contents of the file to an environment variable, or Java system property.

      For information on the variable or property name to use, see Environment and system property secret store.

    3. For Google GSM secret stores, add the contents of the file to a GSM secret.

      For information on the secret name to use, see Google GSM secret stores.

      You can concatenate the contents of several related PEM-formatted files in a single GSM secret; for example, a private key and its associated certificate chain. AM will correctly extract the different components.

      Example

      Concatenate keys and multiple certificates in a PEM file in order, such that the following certificate directly certifies the one preceding it:

      -----BEGIN RSA PRIVATE KEY-----
The Private Key: domain_name.key
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
The Primary SSL certificate: domain_name.crt
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
The Intermediate certificate: CA_cert.crt
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
The Root certificate: Root.crt
-----END CERTIFICATE-----

  3. If the standard PEM-formatted secret is password-encrypted, make the password available to AM as follows:

    • Encode the password using the https://openam.example.com:8443/openam/encode.jsp page.

    • Write the result to a file system secret, or environment variable, that maps to the am.global.services.secret.pem.decryption secret label:

      • File system secret

      • Environment variable

      $ echo -n AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K > am.global.services.secret.pem.decryption
      $ export AM_GLOBAL_SERVICES_SECRET_PEM_DECRYPTION=AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K

    • Make the password available to AM in either the environment and system property secrets store or a file system secret volumes secret store, depending on how you created the secret in the previous step.

      AM only checks global stores for the passwords used to decrypt PEM-formatted files. The PEM-formatted secret can be configured and used in any realm, but the decryption password must be available in a global store.

      Configure global stores by navigating to Configure > Secret Stores.

  4. Configure AM to use the new PEM-formatted certificate or key.

    See Map and rotate secrets.