SAML Signing and Encryption

This section describes how to configure SAML signing and encryption for SAML endpoints in DirX Access. DirX Access supports signing and encryption to protect the protocol messages and assertions exchanged between Identity Providers (IdPs) and Service Providers (SPs) according to the SAML 2.0 specification. These behaviors are configured per SAML endpoint (IdP or SP) and are reflected in runtime behavior.

Goals and Security Properties

SAML signing and encryption address different threats:

  • Signing provides message integrity and authenticity: the receiver can verify that a protocol message or assertion was produced by the expected peer and not modified.

  • Encryption provides confidentiality: sensitive data (e.g., NameID, assertions, attribute statements) is unreadable to intermediaries. Please consider that performance overhead is associated with encryption.

IdP Endpoint

Signing

Signing of SAML Response Protocol Messages

Enable the Do sign (outgoing) SAML response messages configuration element if SP sides require signed SAML Response protocol messages.

  • The signing is performed using the private key specified by the alias in the Signing key alias configuration element.

  • The signature validation on all SP sides is performed based on the trust anchor that is taken from the IdP metadata.

    • The Signature validation certificate aliases configuration element defines what certificate is placed in the IdP metadata.

    • The certificate is placed to the KeyDescriptor use="signing" - KeyInfo tag of the IDPSSODescriptor, AuthnAuthorityDescriptor, PDPDescriptor and AttributeAuthorityDescriptor services.

    • In the case of the DirX Access, the IdP metadata is exposed on the IdP metadata endpoint (e.g., {saml_idp_endpoint_web_application_location}/FederationMetadata/2007-06/FederationMetadata.xml) for transferability to the SP side.

  • To support the certificate path validation on all SP sides and having certificate chain with length greater than 1, the whole chain containing the end-entity certificate is imprinted in the SAML message when allowed by the Do imprint certificates configuration element.

    • The end-entity certificate corresponds to the signing private key and the trust anchor must be a part of the certificate chain. Please see the section with use cases below for more details.

  • There is no enforcement for signed SAML Response messages as mentioned in the SP endpoint metadata.

Signing of SAML Assertions

Enable the Do sign SAML assertion configuration element if the corresponding SPs (according to the SAML assertion consumer service URLs configuration element) requires signed SAML Assertions.

  • The signing is performed using the private key specified by the alias in the Signing key alias configuration element.

  • The signature validation on the corresponding SP sides is performed based on the trust anchor that is taken from the IdP metadata.

  • To support the certificate path validation on the corresponding SP sides, the whole chain containing the end-entity certificate is imprinted in the SAML Assertion when allowed by the Do imprint certificates configuration element.

  • The SP endpoint should also define the requirement for signed SAML assertions in its metadata (the WantAssertionsSigned="true" of the SPSSODescriptor service) and validate the signature.

Signing of SAML Logout Request Protocol Messages

Enable the Do sign (outgoing) SAML request messages configuration element if SP sides require signed SAML Logout Request protocol messages.

  • The signing is performed using the private key specified by the alias in the Signing key alias configuration element.

Encryption

DirX Access supports configuring the following encryption options:

  • Key Encryption Algorithm

    • Defines the algorithm used to encrypt the symmetric key (RSA1_5, RSA_OAEP, RSA_OAEP_11).

  • Key Placement

    • Determines where the encrypted key is placed (INLINE or PEER).

  • Encryption Algorithm

    • Specifies the symmetric encryption algorithm (AES_128_CBC, AES_192_CBC, AES_256_CBC, AES_128_GCM, AES_192_GCM, AES_256_GCM).

These settings apply to encryption of assertions and NameID elements.

Encryption of SAML Assertions (SingleSignOnService)

Enable the Do encrypt SAML assertions configuration element if the SP requires encrypted assertions for the authentication flow.

  • The encryption is performed using the certificate taken from the metadata of the corresponding SP endpoint.

    • The certificate is taken from the KeyDescriptor use="encryption" - KeyInfo tag of the SPSSODescriptor service.

  • In the case of DirX Access, the decryption on the SP side is performed using the corresponding private key specified by the alias in the Decryption key alias configuration element.

  • There is no enforcement for encrypted SAML Assertion mentioned in the SP endpoint metadata.

Encryption of SAML Assertions (AttributeService)

Enable the Do encrypt SAML AttributeStatement elements in (outgoing) messages if the SP side expects encrypted assertions with attribute statements.

  • The encryption is performed using the certificate taken from the metadata of the corresponding SP endpoint.

Encryption of SAML Logout Requests

Enable the Do encrypt SAML NameID elements in (outgoing) messages if the SP side expects encrypted identifier in the Logout Requests (SLO) protocol messages.

  • The encryption is performed using the certificate taken from the metadata of the corresponding SP endpoint.

SP endpoint

Signing

Signing of SAML Authn/Logout Request Protocol Messages

Enable the Do sign (outgoing) SAML request messages if the IdP requires signed SAML Authn/Logout Request protocol messages.

  • The signing is performed using the private key specified by the alias in the Signing key alias configuration element.

  • The signature validation on the IdP side is performed based on the trust anchor that is taken from the corresponding SP metadata.

    • The Signature validation certificate aliases configuration element defines what certificate is placed to the SP metadata.

    • The certificate is placed to the KeyDescriptor use="signing" - KeyInfo tag of the SPSSODescriptor service.

    • The SP metadata is exposed on the SP metadata endpoint (e.g., {saml_sp_endpoint_web_application_location}/FederationMetadata/2007-06/FederationMetadata.xml) for transferability to the IdP side.

  • To support the certificate path validation on the corresponding IdP side, the whole chain starting with the end-entity certificate can be imprinted in the SAML message when allowed by the Do imprint certificates configuration element.

  • The IdP endpoint should also define the requirement for signed SAML Authn Requests in its metadata (the WantAuthnRequestsSigned="true" of the IDPSSODescriptor service) and enforce it.

Accepting only signed SAML assertions (wantAssertionsSigned)

Enable the Do want assertions signed configuration element.

Specifies whether the SP endpoint only accepts signed SAML assertions in the SAML Response messages from the IdP.

  • If enabled, only signed SAML assertions are accepted and the signature is validated based on the trust anchor taken from the IdP metadata.

  • If enabled, the flag is reflected in the SP metadata as WantAssertionsSigned="true" of the SPSSODescriptor service.

  • If disabled, assertions are accepted regardless of the fact if they are signed or not. But if they are signed, the signature is still validated and assertion with invalid signature is rejected.

  • Note that if the signature validation is enabled, you must also set the Signature validation policy to required or optional to enforce the signature validation for signed assertions.

Encryption

Encryption of SAML Logout Requests

Enable the Do encrypt SAML NameID elements in (outgoing) messages if the IdP side expects encrypted identifier in the Logout Requests (SLO) protocol messages.

  • The encryption is performed using the certificate taken from the metadata of the corresponding IdP endpoint.

Accepting only encrypted SAML Assertions

Enable the Do enforce assertion encryption configuration element if the SP side wants to accept only encrypted SAML assertions in the SAML Response messages from the IdP.

  • If enabled, only encrypted SAML assertions are accepted and the decryption is performed using the corresponding private key specified by the alias in the Decryption key alias configuration element.

  • If disabled, both encrypted and unencrypted SAML assertions are accepted.

  • The setting is not reflected in the SP metadata because there is no such standard flag defined for the SPSSODescriptor service.

Use cases

Signing when Certificate Chain of Length 2 or greater

In the most recommended case, the IdP and/or SP side uses end-entity certificate for signing that is followed by one or multiple CA certificates forming the whole certificate chain. Any certificate can be chosen as a trust anchor but this case defines the option when the trust anchor is not the end-entity certificate.

In this case, it is necessary to imprint the certificate chain in the SAML message to support certificate path validation on receiving side.

Configuration

IdP Side
[{
    "@odata.type": "#net.atos.dirx.access.apprepo.api.config.client.web.saml.SamlIdPEndpoint",
    "dp": "net.atos.dirx.access.apprepo.api.config.client.web.saml.SamlIdPEndpoint",
    "key": "SAML IdP-FEP",
    ...
    "keystore": {
      "keystoreId": {
        "key": "SAML IdP",
        "type": "net.atos.dirx.access.apprepo.api.config.keymanagement.Keystore"
      },
      "keystorePassword": "dirxaccess",
      "signingKeyAlias": "federation-sign",
      "signingPublicKeyAliases": [
          "federation-sign.intermediate.trusted"
      ],
      "signingKeyPassword": "dirxaccess"
    },
    "signResponseMessages": true,
    "imprintCertificates": true,
    "wantRequestMessagesSigned": true,
    "certPathValidationEnabled": true,
    "signatureValidationPolicy": "required",
    "peerSamlMetadataIds": [
        {
            "key": "My-Company SP",
            "type": "net.atos.dirx.access.apprepo.api.config.client.web.saml.SamlMetadata"
        }
    ],
    "ssoServiceSamlAssertionConstructionTemplateIds": [
        {
            "key": "SAML Profile Assertion Template",
            "type": "net.atos.dirx.access.apprepo.api.config.subject.external.saml.SamlAssertionConstructionTemplate"
        }
    ]
},
{
    "@odata.type": "#net.atos.dirx.access.apprepo.api.config.subject.external.saml.SamlAssertionConstructionTemplate",
    "dp": "net.atos.dirx.access.apprepo.api.config.subject.external.saml.SamlAssertionConstructionTemplate",
    "key": "SAML Profile Assertion Template",
    ...
    "signSamlAssertion": true
}]
Shortened SAML IdP keystore content
Keystore type: PKCS12
...
*******************************************
*******************************************
Alias name: federation-sign
Entry type: PrivateKeyEntry
Certificate chain length: 3
Certificate[1]:
Owner: CN=my-server.acme.example, O=DirXAccess
Issuer: CN=my-server.acme.example.intermediate, O=DirXAccess
...
Certificate[2]:
Owner: CN=my-server.acme.example.intermediate, O=DirXAccess
Issuer: CN=DirX Access Certification Authority, O=Acme
...
Certificate[3]:
Owner: CN=DirX Access Certification Authority, O=Acme
Issuer: CN=DirX Access Certification Authority, O=Acme
...
*******************************************
*******************************************
Alias name: federation-sign.intermediate.trusted
Entry type: trustedCertEntry
Owner: CN=my-server.acme.example.intermediate, O=DirXAccess
Issuer: CN=DirX Access Certification Authority, O=Acme
...
Extensions:
BasicConstraints:[
  CA:true
  PathLen:2147483647
]
...
*******************************************
*******************************************
Description

At the IdP side, SAML Response protocol messages and SAML Assertions are signed by the "federation-sign" private key of the key pair which public key is distributed as an X.509 end-entity certificate. The "federation-sign.intermediate.trusted" certificate goes to the SAML IdP metadata to define the trust anchor at SP side.

Signing when Certificate Chain of Length 1 (Self-Signed Certificates)

In the simplest case, the IdP and/or SP side uses self-signed (CA) certificate that is considered as end-entity certificate and trust anchor at the same time.

In this case, there is no need to imprint the certificate chain in SAML messages because the chain length is 1.

Since the fact of the self-signed certificate, the certificate path validation validates the certificate against itself.

Signing when Certificate Chain of Length 1 (Pre-trusted Certificates)

In this still valid, but not recommended, case, the IdP and/or SP side uses end-entity certificate that is also configured as trust anchors at the same time. The end-entity certificate is part of some longer certificate chain and therefore is not self-signed.

In this case, there is no need to imprint the certificate chain in SAML messages because the chain length is 1.

The certificate path validation trivially succeeds on the receiving side because trust anchor is considered to be already trusted and is not part of the certificate path validation.