How do I rotate SAML2 certificates in AM 7.x using secrets?

Overview

AM provides secret ID mappings for SAML2 signing and encryption. See Secret ID Default Mappings: SAML v2.0 for further information.

You can use this functionality to rotate SAML2 certificates as described in this article, that is, start signing tokens with a new key, while still accepting tokens signed with an old key. You can only have one active certificate alias at any one time; active aliases are used for signing and encryption, and non-active aliases are used for verifying signatures and decryption. This allows for a grace period where multiple SAML2 certificates are valid before the old certificate expires and the new certificate is enforced.

SAML2 certificates

The following certificates are used in SAML2 flows, where AM is the hosted entity provider and a third party is the remote entity provider:

These are the certificates that can be rotated per this article, because SAML2 secrets are only applicable to hosted entity providers.

The remote equivalents of these certificates are derived from the SAML2 metadata provided by the third party and are outside the scope of this article.

Steps involved

1. Generate a CA certificate for signing
2. Create initial SAML2 signing or encryption certificate
3. Add certificate to AM keystore and apply to entity provider in AM
4. Test initial certificate works
5. Create new SAML2 signing or encryption certificate for rotation
6. Add new certificate to AM keystore and update secret mapping
7. Check existing certificate continues to work
8. Rotate SAML2 certificates
9. Test new certificate works

Prerequisites

• You have a working AM deployment.
• You have already set up the necessary entity providers in AM and have a working SAML2 federation.

Generating a CA certificate for signing

You need to generate a CA certificate before you start. This certificate is then used to sign all the subsequent SAML2 signing and/or encryption certificates.

1. Generate a new private key for the CA certificate. For example:$ openssl genrsa -out <CA-key.pem> 4096
2. Generate the CA certificate using the private key you created. For example:$ openssl req -new -x509 -key <CA-key.pem> -out <CA-cert.pem> -days 365 -subj /CN=am-ca

Creating initial SAML2 signing or encryption certificate

1. Generate a new private key. For example:$ openssl genrsa -out <key1.pem> 4096
2. Create a certificate signing request (CSR) using your private key. For example:$ openssl req -new -key <key1.pem> -out <csr1.csr> -days 365 -subj /CN=am-cert-1
3. Generate a certificate by signing the CSR using the CA key/certificate. For example:$ openssl x509 -req -in <csr1.csr> -CA <CA-cert.pem> -CAkey <CA-key.pem> -set_serial 01 -days 365 -out <cert1.pem>
4. Combine the private key and certificate you created in steps 1 and 3 into a single certificate file. For example:$ cat <key1.pem> <cert1.pem> > <key-cert1.pem>

Adding certificate to AM keystore and applying to entity provider in AM

1. Export the keypair in p12 format. For example:$ openssl pkcs12 -export -inkey <key1.pem> -in <key-cert1.pem> -name <alias> -out <keypair1.p12>
2. Enter the export password twice when prompted. The export password must match the password in /path/to/am/security/secrets/default/.keypass otherwise you will encounter this error: Unable to read secret/private key error in AM 6.5.x or 7.x.
3. Import the keypair into the AM keystore. For example:$ keytool -importkeystore -srckeystore <keypair1.p12> -srcstoretype pkcs12 -destkeystore keystore.jceks -deststoretype JCEKS
4. Enter the password for the AM keystore when prompted.
5. In the AM admin UI, go to Realms > [Realm Name] > Applications > Federation > Entity Providers and click the name of your entity provider.
6. On the Assertion Content tab, go to Secret ID And Algorithms and enter the ID of the secret (for example, idpAM) you want to use for this entity provider in the Secret ID Identifier field.

7. Scroll down and click Save Changes.
8. In the AM admin UI, go to Realms > [Realm Name] > Secret Stores > [Secret Store Name] > Mappings and click Add Mapping.
9. Select the applicable secret from the Secret ID field. This will be in the format am.applications.federation.entity.providers.saml2.<secretID>.<purpose>, where <secretID> is the ID you entered for the entity provider in step 6 and <purpose> is either signing or encryption, depending on what you are using your certificate for.

For example, if your secret ID was idpAM and you are using your certificate for signing, you would select am.applications.federation.entity.providers.saml2.idpAM.signing in this field.

10. Enter the name of the alias you used when you exported the keypair in step 1 in the Aliases field and click Add.

For example, if you used the option -name saml-idp when you exported the keypair, your alias would be saml-idp.

11. Click Create.

Testing initial certificate works

1. Export the entity provider metadata and exchange it with the remote entity provider. See How do I export and import SAML2 metadata in AM (All versions)? for further information.
2. Test your SAML2 federation flow using the URL or authentication tree you normally use.
3. Verify the certificate in the SAML2 assertion corresponds to the newly created certificate. There are third-party tools you can use, for example, CSR Decoder and Certificate Decoder.

Creating new SAML2 signing or encryption certificate for rotation

1. Generate a new private key. For example:$ openssl genrsa -out <key2.pem> 4096
2. Create a certificate signing request (CSR) using your private key. For example:$ openssl req -new -key <key2.pem> -out <csr2.csr> -days 365 -subj /CN=am-cert-2
3. Generate a certificate by signing the CSR using the CA key/certificate. For example:$ openssl x509 -req -in <csr2.csr> -CA <CA-cert.pem> -CAkey <CA-key.pem> -set_serial 01 -days 365 -out <cert2.pem>
4. Combine the private key and certificate you created in steps 1 and 3 into a single certificate file. For example:$ cat <key2.pem> <cert2.pem> > <key-cert2.pem>

Adding new certificate to AM keystore and updating secret mapping

1. Export the keypair in p12 format. For example:$ openssl pkcs12 -export -inkey <key2.pem> -in <key-cert2.pem> -name <aliasNew> -out <keypair2.p12>
2. Enter the export password twice when prompted. The export password must match the password in /path/to/am/security/secrets/default/.keypass otherwise you will encounter this error: Unable to read secret/private key error in AM 6.5.x or 7.x.
3. Import the keypair into the AM keystore. For example:$ keytool -importkeystore -srckeystore <keypair2.p12> -srcstoretype pkcs12 -destkeystore keystore.jceks -deststoretype JCEKS
4. Enter the password for the AM keystore when prompted.
5. In the AM admin UI, go to Realms > [Realm Name] > Secret Stores > [Secret Store Name] > Mappings and click the name of the secret mapping you created previously (for example, am.applications.federation.entity.providers.saml2.idpAM.signing).
6. Enter the name of the alias you used when you exported the keypair in step 1 in the Aliases field and click Add.

For example, if you used the option -name saml-idp-new when you exported the keypair, your alias would be saml-idp-new.

The original alias is still the active alias.

7. Click Save.

Checking existing certificate continues to work

1. Export the entity provider metadata with two certificates and exchange it with the remote entity provider. See How do I export and import SAML2 metadata in AM (All versions)? for further information.
2. Test your SAML2 federation flow again using the URL or authentication tree you normally use.
3. Verify the certificate in the SAML2 assertion still corresponds to the original certificate. There are third-party tools you can use, for example, CSR Decoder and Certificate Decoder.

Rotating SAML2 certificates

1. In the AM admin UI, go to Realms > [Realm Name] > Secret Stores > [Secret Store Name] > Mappings and click the name of the secret mapping you created previously (for example, am.applications.federation.entity.providers.saml2.idpAM.signing).
2. Drag and drop the new inactive alias so it becomes the first element in the alias list; this makes the new alias active, meaning it will now be used for signing and encryption.

You can delete the inactive alias in this window when you are ready.

3. Click Save.

Testing new certificate works

1. Test your SAML2 federation flow again using the URL or authentication tree you normally use.
2. Verify the certificate in the SAML2 assertion corresponds to the rotated certificate. There are third-party tools you can use, for example, CSR Decoder and Certificate Decoder.

See Also

SAML 2.0 federation in AM

Mapping and Rotating Secrets

Signing and Encryption