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.

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.

    Tip

    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.

    Note

    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.

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. 

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

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

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

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

    Remote providers must specify the encryption method defined by Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0. For example:

    <KeyDescriptor use="encryption">
    <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#rsa-oaep"/>
    <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
</KeyDescriptor>

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

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

      If unspecified, the provider uses the following algorithms:

      • http://www.w3.org/2001/04/xmlenc#aes128-cbc, for assertions.

      • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p, for the transport key.

Configuring AM to Sign SAML v2.0 Metadata

You can configure the am.services.saml2.metadata.signing.RSA secret ID with an alias that AM uses to sign exported metadata.

Perform the following steps to map the alias:

  1. In the AM console, 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 ID.

  4. In the Edit Mapping pane:

    1. To edit a mapping, click the pen icon.

    2. To add a mapping, enter the alias, and then click the Add button.

    3. 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 can use to verify the authenticity of the metadata.

Configuring 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 IDs on the identity provider. For more information, see Secret ID Mappings for SAML v2.0 Signing and Encryption.

    Failure to configure signing when using HTTP-POST bindings might 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, because responses can contain user data.

  • SAML logout requests

    Signing is recommended to verify the request's authenticity.

Tip

Configure key rollover by mapping more than one secret to the same secret ID. See "Mapping and Rotating Secrets".

AM provides global default secrets for signing and encrypting SAML v2.0 assertion content, in the following secret IDs:

  • 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 configure these secret IDs by realm, every provider of the same role will use the same secrets to sign and encrypt assertion content. To allow for more granularity, AM lets you override these settings and use custom secrets for each hosted provider in the realm:

  1. In the AM console, 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.

    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:

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

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

  4. (Optional) If you have not configured a secret store in the same realm as the entity provider, create one by following the steps in "Configuring Secret Stores".

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

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

    Adding mappings for SAML entities at the realm level.

    For information on creating mappings, see "Mapping and Rotating Secrets".

    For information on the types of key pairs and secrets required, see Secret ID Mappings for SAML v2.0 Signing and Encryption.

  7. In the AM console, 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.

    Tip

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

    See "SAML v2.0 Advanced Properties".

Read a different version of :