PingAM 7.5.0

Sign and encrypt messages

By default, IDPs and SPs do not sign or encrypt SAML v2.0 messages. While this is useful for test and demo environments, you should secure your production and production-like environments.

How signing works

When AM needs to sign a SAML request or response for the consumption of a remote entity provider, it determines the signing algorithm, and optionally, the digest method, based on the following logic, as recommended by the SAML v2.0 Metadata Profile for AlgorithmSupport Version 1.0 specification:

  1. AM retrieves the remote entity provider’s metadata, and examines the role-specific extensions for a configured digest method, or signing algorithm.

  2. If there is no role-specific algorithm configured, AM checks for algorithms configured in the entity provider-level extensions.

  3. If signing algorithms are specified at either role-specific level or entity provider-level, but AM is unable to find a suitable key, it doesn’t sign the element, and displays an error.

    Possible reasons that AM may not be able to locate a suitable signing key include:

    Algorithm mismatch

    The signing algorithm can’t be used with the private key configured in the relevant secret label.

    Keysize mismatch

    The required key size and actual key size aren’t equal.

  4. If the entity provider doesn’t specify supported signing and digest methods in the standard metadata, AM falls back to the global default algorithm settings.

    To change the global default algorithms AM uses for signing and encrypting different SAML v2.0 components, go to Configure > Global Services > Common Federation Configuration.

  5. If the global default algorithms are not configured, AM examines the configured signing key type, and uses RSA-SHA256 for RSA keys, DSA-SHA256 for DSA keys, and ECDSA-SHA512 for EC keys.

    AM has different default signing algorithm settings for XML signatures, and for query signatures.

    AM determines the correct default query signing algorithm based on the signing key’s algorithm, be it RSA, DSA, or EC. It only falls back to the same defaults for both XML and query signing algorithms when the settings aren’t correctly defined.

After determining the required algorithm, the sender uses their own private key to write the signature on the request. Then, the provider receiving the message uses the public key exposed in the sender’s metadata to validate the signature.

How encryption works

When encrypting SAML v2.0 messages, the sender uses the receiver’s public key (exposed in the receiver’s metadata) to encrypt the request. The receiver decrypts it with its private key.

As with signing, providers also expose in their metadata the algorithms that they can use to encrypt assertion content.

Since SAML v2.0 messages are in XML format, encrypting them requires an additional key that is transported with the message, as explained in the XML Encryption Syntax and Processing Version 1.1 specification. AM refers to those keys as transport keys.

Consider the following example of an encryption/decryption flow:

  1. The IDP generates a random symmetric transport key using the transport key algorithm exposed in the SP’s metadata.

  2. The IDP encrypts the assertion with the transport key.

  3. The IDP encrypts the transport key with the public key of the SP (which is also exposed in its metadata).

  4. The SP decrypts the transport key using its private key. Then, it uses the transport key to decrypt the assertion.

This ensures only this SP can decrypt the message.

Configure the advertised signing and encryption algorithms

  1. Configure the required signing algorithms and digests:

    Hosted IDPs and SPs can advertise the algorithms they can use to sign assertion content. This information appears as part of the provider’s metadata extension.

    Signing/digest algorithm metadata example 
    <Extensions>
 <alg:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
 <alg:SigningMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256"/>
</Extensions>

    • In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

    • On the Assertion Content tab, in the Signing Algorithm drop-down list, select the signing algorithms this provider can use.

      There is no default for this property.

    • On the Assertion Content tab, in the Digest Algorithm drop-down list, select the digest algorithms this provider can use.

      There is no default for this property.

  2. Configure the required encryption algorithms:

    Hosted SPs and IDPs advertise their encryption algorithms so that the remote providers know which ones they should use when sending encrypted data.

    Encryption algorithm metadata example 
    <!-- Enable RSA-OAEP key transport with AES-GCM data encryption: -->
<KeyDescriptor use="encryption">
 <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#rsa-oaep"/>
 <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc11#aes128-gcm"/>
</KeyDescriptor>

    • In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

    • On the Assertion Content tab, in the Encryption Algorithm drop-down list, select the algorithms this provider can use.

      Select one or more AES algorithms from the list to encrypt assertion content, and one or more asymmetric algorithms to encrypt the transport key.

      For assertion encryption algorithms, use AES-GCM rather than the older AES-CBC modes. GCM offers authenticated encryption, which better protects against an attacker tampering with an encrypted assertion. Also sign assertions to make such attacks harder to exploit.

      Assertion Encryption Algorithms
      Algorithm identifier Recommended

      http://www.w3.org/2009/xmlenc11#aes128-gcm

      ✔

      http://www.w3.org/2009/xmlenc11#aes192-gcm

      ✔

      http://www.w3.org/2009/xmlenc11#aes256-gcm

      ✔

      http://www.w3.org/2001/04/xmlenc#aes128-cbc (default)

      http://www.w3.org/2001/04/xmlenc#aes192-cbc

      http://www.w3.org/2001/04/xmlenc#aes256-cbc

      Key Transport Algorithms
      Algorithm identifier Recommended

      http://www.w3.org/2009/xmlenc11#rsa-oaep(1)

      ✔

      http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p (default)

      http://www.w3.org/2001/04/xmlenc#rsa-1_5(2)

      ✖

      (1) When this algorithm is configured, AM uses the Mask Generation Function Algorithm property (Configure > Global Services > Common Federation Configuration) to create the transport key. For a list of supported mask generation function algorithms, refer to Algorithms.

      (2) For security reasons, you should not use this option.

Configure AM to sign SAML v2.0 metadata

Map the am.services.saml2.metadata.signing.RSA secret label to an alias that AM uses to sign exported metadata:

  1. In the AM admin UI, go to Configure > Secret Stores.

  2. Select the Keystore or HSM store where you want to map the secret.

  3. On the Mappings tab, select the am.services.saml2.metadata.signing.RSA secret label.

  4. In the Edit Mapping pane:

    • To edit a mapping, click the pen icon.

    • To add a mapping, enter the alias, and click Add.

    • To delete a mapping, click the cross icon.

  5. Save your changes.

  6. Export the XML-based metadata from your hosted provider to share with other providers in your circle of trust, specifying the sign=true query parameter:

    $ curl \
--output metadata.xml \
"https://openam.example.com:8443/openam/saml2/jsp/exportmetadata.jsp\
?entityid=myHostedProvider\
&sign=true\
&realm=/mySubRealm"

    If you configure your provider in the Top Level Realm, you can omit the realm query parameter.

    The XML output contains a <ds:Signature> element that the remote entity uses to verify the authenticity of the metadata.

Configure AM to sign and encrypt SAML v2.0 assertion content

Note the following important points when configuring signing and encryption of assertion content:

  • Assertions

    HTTP-POST bindings require signed assertions. If the response is not signed, AM defaults to signing the assertion and uses the SP configuration to determine encryption settings.

    You must configure signing secret labels on the IDP, as described in Secret label mappings for SAML v2.0 signing and encryption.

    Failure to configure signing when using HTTP-POST bindings might result in errors such as:

    ERROR: UtilProxySAMLAuthenticatorLookup.retrieveAuthenticationFromCache: Unable to do sso or federation.
com.sun.identity.saml2.common.SAML2Exception: Provider's signing certificate alias is missing.

    or:

    ERROR: SAML2Utils.verifyResponse:Assertion is not signed or signature is not valid.

  • SAML authentication requests

    Signing is recommended to verify the request’s authenticity and when using the ForceAuthn flag.

  • SAML assertion responses

    Signing AND encrypting is recommended because responses can contain user data.

  • SAML logout requests

    Signing is recommended to verify the request’s authenticity.

Configure key rollover by mapping more than one secret to the same secret label. Refer to Map and rotate secrets.

AM provides global default secrets for signing and encrypting SAML v2.0 assertion content with the following secret labels:

  • am.default.applications.federation.entity.providers.saml2.idp.encryption

  • am.default.applications.federation.entity.providers.saml2.idp.signing

  • am.default.applications.federation.entity.providers.saml2.sp.encryption

  • am.default.applications.federation.entity.providers.saml2.sp.signing

If you map these secret labels by realm, every provider of the same role uses the same secrets to sign and encrypt assertion content. For more granularity, you can override these settings and use custom secrets for each hosted provider in the realm:

  1. In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  2. On the Assertion Content tab, in the Secret Label Identifier property, enter a string value to identify the secret labels this provider will use.

    For example, mySamlSecrets.

    How do secret label identifiers work?

    AM uses a secret identifier to know which secret labels are relevant for a provider. You can reuse the identifier that another provider is already using if you want them to share the same secrets.

    When a provider is removed from the AM configuration, AM automatically removes the secret labels related to their identifier, unless they’re being used by another provider.

    If you don’t specify a value for the secret label identifier, AM uses the global default secrets relative to the entity provider’s role, in the realm. If they aren’t mapped, AM searches for the global default secrets in the global secret stores.

  3. Save your changes.

    AM creates two new secret labels, at the realm level, based on the value you specified.

    • am.applications.federation.entity.providers.saml2.mySamlSecrets.signing

    • am.applications.federation.entity.providers.saml2.mySamlSecrets.encryption

  4. If you haven’t configured a secret store in the same realm as the entity provider, create one by following the steps in Secret stores.

  5. Go to Realms > Realm Name > Secret Stores, and select the secret store in which to map the new secret labels.

  6. On the Mappings tab, add mappings for the two custom secret labels.

    Adding mappings for SAML entities at the realm level.

    For information on creating mappings, refer to Map and rotate secrets.

    For information on the types of key pairs and secrets required, refer to Secret label mappings for SAML v2.0 signing and encryption.

  7. In the AM admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  8. On the Assertion Content tab, in the Signing and Encryption section, select the SAML v2.0 elements that AM should sign, and the elements to encrypt.

  9. Save your changes.

    AM now uses the key pairs you configured in the realm’s secret store to sign or encrypt the elements you selected.

    For troubleshooting issues involving encryption, you can enable the openam.saml.decryption.debug.mode advanced property.

    Refer to SAML v2.0 advanced properties.

Certificates and secrets

SAML 2.0 secrets for hosted SP or IDP entities are managed by the secrets API, which lets you rotate certificates using secret mappings. This only applies to hosted entities; certificates for remote entities are derived from SAML 2.0 metadata provided by the third party.

The following certificates are used in SAML 2.0 flows with the corresponding secret mappings.

Certificate AM role Third-party role AM use case Third-party use case Secret

Hosted IdP signing certificate

Hosted IdP

Remote SP

Sign outbound SAML assertions

Validate inbound signed SAML assertion

am.applications.federation.entity.providers.saml2.<secret identifier>.signing(1)

(am.default.applications.federation.entity.providers.saml2.idp.signing)

Hosted IdP encryption certificate

Hosted IdP

Remote SP

Decrypt inbound encrypted SAML requests

Encrypt outbound SAML requests

am.applications.federation.entity.providers.saml2.<secret identifier>.encryption(1)

(am.default.applications.federation.entity.providers.saml2.idp.encryption)

Hosted SP signing certificate

Hosted SP

Remote IdP

Sign outbound SAML requests

Validate inbound signed SAML requests

am.applications.federation.entity.providers.saml2.<secret identifier>.signing(1)

(am.default.applications.federation.entity.providers.saml2.sp.signing)

Hosted SP encryption certificate

Hosted SP

Remote IdP

Decrypt inbound SAML assertions

Encrypt outbound SAML assertions

am.applications.federation.entity.providers.saml2.<secret identifier>.encryption(1)

(am.default.applications.federation.entity.providers.saml2.sp.encryption)

(1) If defined, this secret is used; otherwise the default (in brackets) is used.