Signing and Encryption

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 Does Signing Work?

When AM needs to sign a SAML request or response for the consumption of a remote entity provider, it will determine 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 does not 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 cannot be used with the private key configured in the relevant secret ID.

    • Keysize Mismatch - the required key size and actual key size are not equal.

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

  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 will only fall back to the same defaults for both XML and query signing algorithms when the settings are not 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 Does Encryption Work?

In summary, 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 will be 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.

See the following procedures to configure signing and encryption in your environment:

Configuring 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, ForgeRock recommends AES-GCM over 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 will use 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, see Algorithms.

      (2) For security reasons, ForgeRock strongly recommends that you do not use this option.

Configuring AM to Sign and Encrypt SAML v2.0 Assertion Content

Considerations When Configuring Signing and Encryption
Assertions

HTTP-POST bindings require signed assertions.

Failure to enable signing when using HTTP-POST bindings may result in errors such as the following:

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 also when using the ForceAuthn flag.

SAML assertion responses

Signing AND encrypting is recommended, since responses can contain user data.

SAML logout requests

Signing is recommended to verify the request’s authenticity.

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

  2. On the Assertion Content tab, in the [label]# Secret ID Identifier# property, enter a string value to identify the secret IDs this provider will use.

    For example, mySamlSecrets.

    How Do Secret Identifies Work?

    AM uses the secret identifier to know which secret IDs 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 IDs related to their identifier, unless they are being used by another provider.

    If you do not specify a value for the secret ID identifier, AM will use the global default secrets relative to the entity provider’s role, in the realm. If they are not mapped, AM will search for the global default secrets in the global secret stores.

  3. Save your changes.

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

  4. In the AM Admin UI, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  5. 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.

  6. 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.