PingOne Advanced Identity Cloud

Sign and encrypt messages

By default, IdPs and SPs do not sign or encrypt SAML 2.0 messages.

Although this is useful for test and demo environments, secure your production and production-like environments with keys.

For information on how to create and configure keys for signing and encryption in Advanced Identity Cloud, refer to TLS, secrets, signing, trust, and encryption

How signing works

When Advanced Identity Cloud 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. Advanced Identity Cloud 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, Advanced Identity Cloud 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 Advanced Identity Cloud is unable to find a suitable key, it does not sign the element, and displays an error.

    Possible reasons that Advanced Identity Cloud might 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, Advanced Identity Cloud uses the default algorithm settings.

  5. Advanced Identity Cloud examines the configured signing key type, and uses RSA-SHA256 for RSA keys, DSA-SHA256 for DSA keys, and ECDSA-SHA512 for EC keys.

    Advanced Identity Cloud has different default signing algorithm settings for XML signatures, and for query signatures.

    Advanced Identity Cloud determines the correct default query signing algorithm based on the signing key’s algorithm: RSA, DSA, or EC.

    Advanced Identity Cloud reverts to the same defaults for XML and query signing algorithms only if 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 encryption works

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

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

Because SAML 2.0 messages are in XML format, the encryption requires an additional key to be transported with the message, as explained in the XML Encryption Syntax and Processing Version 1.1 specification. Advanced Identity Cloud 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.

  5. The SP uses the transport key to decrypt the assertion.

This scenario ensures only this SP can decrypt the message.

The following sections explore these topics in detail.

Configure the advertised signing and encryption algorithms

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.

Configure the required signing algorithms and digests:

  1. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  2. In Assertion Content > Signing and Encryption > Secret ID And Algorithms:

    • In the Signing Algorithm list, select the signing algorithms this provider can use.

    • In the Digest Algorithm list, select the digest algorithms this provider can use.

      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>

      There is no default for these properties.

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

Configure the required encryption algorithms:

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

    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>

    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 protects better against an attacker tampering with an encrypted assertion. Also sign assertions to make such attacks harder to exploit.

    Table 1. 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

    Table 2. Key transport algorithms
    Algorithm Identifier Recommended

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

    ✔

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

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

    ✖

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

Configure Advanced Identity Cloud to sign and encrypt SAML 2.0 assertion content

Advanced Identity Cloud can sign and encrypt the SAML 2.0 assertion content with the following caveats:

Assertions

HTTP-POST bindings require signed assertions.

Failure to enable signing when using HTTP-POST bindings can 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 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.

To configure signing and encryption:

  1. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

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

    For example, mySamlSecrets.

    How secret identifiers work:

    • Advanced Identity Cloud using a 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 Advanced Identity Cloud configuration, Advanced Identity Cloud 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, Advanced Identity Cloud will use the global default secrets relative to the entity provider’s role, in the realm. If they are not mapped, Advanced Identity Cloud will search for the global default secrets in the global secret stores.

  3. Save your changes.

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

  4. Under Native Consoles > Access Management, go to Applications > Federation > Entity Providers > Hosted Entity Provider.

  5. On the Assertion Content tab, in the Signing and Encryption section, select the SAML 2.0 elements that Advanced Identity Cloud should sign and the elements to encrypt.

  6. Save your changes.

    Advanced Identity Cloud now uses the key pairs you configured. For more information on how to create and configure keys for signing and encryption in Advanced Identity Cloud, refer to TLS, secrets, signing, trust, and encryption.