FAQ: SAML certificate management in AM 6.x

Frequently asked questions

• Q. How do I change the signing key for SAML2?
• Q. Where are the SAML keys stored?
• Q. How do I list the keys in my keystore?
• Q. Does AM support multiple signing keys to allow for key rollover?
• Q. Can I use the same signing key for multiple IdPs?
• Q. Can I have multiple keys in the keystore used for signing so that I can have a different key for each IdP?
• Q. Do I need to create a new IdP or SP to update a certificate?
• Q. Do I have to import a certificate into the keystore for XML signing or will AM use the certificate provided in the MetaData?
• Q. Why isn't the SAML certificate expiration date checked?
• Q. Does AM validate certificates against the Certificate Revocation List (CRL)?
• Q. What signatures are supported for SAML XML signing?
• Q. How can I check if SAML signing has been implemented?
• Q. Can I sign anything other than the assertion?
• Q. Can I use a Hardware Security Module (HSM) for signing SAML assertions?
• Q. How do I use an existing CA signed certificate (in PEM format) for signing SAML requests?
• Q. How do I get the certificate out of the keystore in PEM format?
• Q. How do I convert a PEM certificate file and private key to PKCS#12 (.pfx .p12)?
• Q. How do I convert a PKCS#12 file (.pfx .p12) that contains a private key and certificates to PEM format?
• Q. What is the certificate alias setting under Server Defaults used for?

Q. How do I change the signing key for SAML2?

A. The default 'test' certificate alias used for SAML2 (and OAuth) signing keys is also used by the XUI and for REST authentication.

See Changing Default Key Aliases for further information.

Q. Where are the SAML keys stored?

A. Assuming SAML signing has been implemented, the keypair (private/public key) for SAML encryption and signing is stored in the AM keystore, which differs depending on which version you are using.

AM uses a JCEKS keystore as its default keystore. The default location is: /path/to/am/keystore.jceks. You can change this by navigating to: Configure > Server Defaults > Security > Key Store > Keystore File.

Q. How do I list the keys in my keystore?

A. You can list all the keys in your keystore using one of the following commands depending on your keystore format:

• JCEKS format: $ keytool -list -v -keystore [keystore] -storetype JCEKS -storepass [password]
• JKS format: $ keytool -list -v -keystore [keystore] -storepass [password]

replacing [keystore] with the full path and name of the keystore file, and [password] with the keystore password.

Q. Does AM support multiple signing keys to allow for key rollover?

A. Yes AM supports multiple signing keys to allow for key rollover; this means you can cutover to a new certificate when the current one is either revoked or expires:

• How do I rollover certificates for an IdP or SP in AM 6.x? describes how to perform key rollover for federation certificates (signing and encryption).
• Assertion Content (IdP) and Assertion Content (SP) provides further information on certificate aliases used for signing keys.

Q. Can I use the same signing key for multiple IdPs?

A. Yes, you can use the same signing key with multiple hosted IdPs if required.

Q. Can I have multiple keys in the keystore used for signing so that I can have a different key for each IdP?

A. Yes you can. You then need to add the right alias and password combination to each IdP entity.

See Setting Up Keys and Keystores for further information.

Q. Do I need to create a new IdP or SP to update a certificate?

A. No, you can update the certificate for an existing IdP or SP without needing to create a new provider or circle of trust (COT).

See How do I renew expired certificates for a hosted IdP or SP in AM 6.x? and How do I renew expired certificates for a remote IdP or SP in AM (All versions)? for further information depending on whether your entity provider is hosted or remote.

Q. Do I have to import a certificate into the keystore for XML signing or will AM use the certificate provided in the MetaData?

A. It depends on what you are trying to do in the following situations:

Setting up federation

When you initially configure federation between AM and the entity provider, you need to import the entity provider's metadata. The metadata itself can be signed. If it is signed, you must have a way to trust it and typically this means you need to import the certificate into the keystore. However, if you have obtained the metadata from a trusted source, you can remove the Signature block from the metadata and import it without needing to import the certificate.

The Signature block in the metadata is the <Signature ... </Signature> part as shown in the following example:

When this Signature block is present, the certificate in the <X509Certificate> tag must be trusted.

Verifying signatures

Once federation is configured, you may choose to receive signed requests from the Service Provider for example. If the metadata imported into AM contained a certificate, AM will use that certificate to verify the signature of the request meaning you do not need to import a certificate. This certificate will be in the <SPSSODescriptor> or the <IDPSSODescriptor> block, for example:

If either the <SPSSODescriptor> or the <IDPSSODescriptor> block is present, AM will use that certificate to verify the signatures; if it is not present, you will need to import the certificate into the keystore.

Q. Why isn't the SAML certificate expiration date checked?

A. The expiration date isn't checked per the SAML specs: SAML V2.0 Metadata Interoperability Profile. In particular, refer to the Key Representation section, which states:

In the case of an X.509 certificate, there are no requirements as to the content of the certificate apart from the requirement that it contain the appropriate public key. Specifically, the certificate may be expired, not yet valid, carry critical or non-critical extensions or usage flags, and contain any subject or issuer. The use of the certificate structure is merely a matter of notational convenience to communicate a key and has no semantics in this profile apart from that. However, it is RECOMMENDED that certificates be unexpired.

An RFE exists to provide an option for checking for expiration dates: OPENAM-8973 (request for an configuration enhancement that allows the option to check for a SAML/Federation based certificate expiration date).

Q. Does AM validate certificates against the Certificate Revocation List (CRL)?

A. AM can validate certificates (both signing and CA) against the CRL, although this functionality is not enabled by default.

See How do I enable validation checks for SAML certificates in AM 6.x? for information on enabling these validation checks.

When enabled, AM checks certificates against the CRL for every signed assertion received; any issues will cause federation to completely fail with errors such as:

AM does not validate certificates when encrypting or signing an assertion. An RFE exists for this: OPENAM-6134 (Perform revocation check on certificate before encrypting SAML2 assertions).

Q. What signatures are supported for SAML XML signing?

A. The list of supported signature algorithms is shown in the documentation: Algorithms.

Using non-supported XML signatures will result in the following error:

See Signature algorithm is not supported error when verifying a signed SAML assertion in AM 6.x for further information.

Q. How can I check if SAML signing has been implemented?

A. You can check in the AM admin UI by navigating to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption and checking which options have been selected.

Q. Can I sign anything other than the assertion?

A. Yes, you can choose which parts of the request or response are signed as follows:

• In the SP, you can sign the following:
  • Authentication Requests
  • Assertions
  • Post Response
  • Artifact Response
  • Logout Request
  • Logout Response
  • Manage Name ID Request
  • Manage Name ID Response
• In the IdP, you can sign the following:
  • Authentication Request
  • Artifact Resolve
  • Logout Request
  • Logout Response
  • Manage Name ID Request
  • Manage Name ID Response

You can set these options in the AM admin UI by navigating to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption.

Q. Can I use a Hardware Security Module (HSM) for signing SAML assertions?

A. Yes, you can use a HSM for signing SAML assertions, where the SAML keys are stored in a PKCS11 keystore.

See How do I configure AM 6.x to use a Hardware Security Module (HSM) for signing SAML assertions? for further information.

Q. How do I use an existing CA signed certificate (in PEM format) for signing SAML requests?

A. You need to add the CA signed certificate to the AM keystore in order to use it for SAML signing. You can do this as follows:

1. Convert the PEM certificate file to PKCS#12 (.p12) using the openssl third-party tool: $ openssl pkcs12 -export -in [saml.crt] -inkey [saml.key] -out [saml.p12] -name [alias]replacing [saml.crt], [saml.key], [saml.p12] and [alias] with appropriate values.
2. Import the p12 file generated in step 1 into the AM keystore using the keytool command: $ keytool -importkeystore -deststorepass [changeit] -destkeypass [changeit] -destkeystore [AMkeystore] -srckeystore [saml.p12] -srcstoretype PKCS12 -srcstorepass [password] -alias [alias]replacing [changeit], [AMkeystore], [saml.p12], [password] and [alias] with appropriate values.

Q. How do I get the certificate out of the keystore in PEM format?

A. You can use the following keytool command to retrieve the certificate from the keystore in PEM format:

replacing [alias], [keypassword], [keystore], [storepassword] and [keyStore.pem] with appropriate values, where:

• [keypassword] is the password used to protect the private key of the generated key pair.
• [keystore] is the full path and name of the keystore file.
• [storepassword] is the keystore password.

Q. How do I convert a PEM certificate file and private key to PKCS#12 (.pfx .p12)?

A. You can use the openssl third-party tool to perform this conversion using the following command:

replacing [certificate.pfx], [privateKey.key], [certificate.crt] and [CACert.crt] with appropriate values.

Q. How do I convert a PKCS#12 file (.pfx .p12) that contains a private key and certificates to PEM format?

A. You can use the openssl third-party tool to perform this conversion using the following command:

replacing [keyStore.pfx] and [keyStore.pem] with appropriate values

Q. What is the certificate alias setting under Server Defaults used for?

A. The default server certificate alias setting is used for SAML 1.x federation. This property (com.sun.identity.saml.xmlsig.certalias) is equivalent to the SAML 1.x default signing key. It can be found by navigating to: Configure > Server Defaults > Security > Key Store.

Certificate aliases used for SAML2 federation are maintainable in the AM admin UI by navigating to Realms > [Realm Name] > Applications > Federation > Entity Providers > [Name of Provider] > Assertion Content > Signing and Encryption.

See Also

FAQ: SAML2 federation in AM

SAML 2.0 federation in AM

SAML v2.0 Guide

Setting Up Keys and Keystores

The Most Common OpenSSL Commands

keytool command