SAML

Important

The SAML authenticator is deprecated since version 7.6. Please use the SAML2 authenticator instead.

The SAML authenticator can be used to relay authentication to an external SAML Identity Provider. This plugin supports a basic set of most commonly used SAML features, and is by no means intended to act like a Federation Service whatsoever. Still the request- and response-handling are tweakable to be able to integrate in many common scenarios.

Paths

The SAML authenticator is mounted on the Authentication endpoint with the subpath of its ID. So if an authenticator with the ID saml1 is configured and the Authentication endpoint is configured to have the path /authenticate then the path of the SAML authenticator is found under /authenticate/saml1 or /authenticate/saml1/index.

The protocol bindings that are implemented with the SAML authenticator, are limited to send AuthnRequest-messages using the HTTP-Redirect binding method, and to receive Response-messages using the HTTP-POST binding method.

When making a GET-request to the saml-endpoint, a new AuthnRequest-message is constructed from the authentication request context of the Authentication profile, and the user is redirected to the configured idp-url, carrying the SAML message in the QueryString.

When a POST-request is made to the saml-endpoint, it is expected to carry a SAMLResponse-parameter in its form-body. This message must be a response to a previously sent SAML AuthnRequest in the same session.

Because no user interaction is required in this flow, there are no user interface- or template customizations available for this authenticator.

Endpoint-kind: saml

SubPath Method Template Description
index (/) GET n/a The index (/) redirects with an AuthnRequest to the SAML Identity Provider URL
POST n/a The index (/) processes the response from the SAML Identity Provider

Validation Scripts

While the SAML authenticator supports Validation Procedures, the request model of the saml-endpoint is limited in its capabilities of receiving parameters. The GET on the saml-endpoint doesn’t take any input, and the POST on the saml endpoint requires a SAMLResponse parameter in the request-body.

For more information on Validation Procedures see Validation section.

Configuration

To successfully complete a message exchange between the SAML authenticator as Service Provider (SP) and the remote system as Identity Provider (IDP), some basic configuration is required, while there are also a number of optional settings that can be made to customize the behaviour of the authenticator.

It is required to introduce the IDP to the SAML authenticator, by providing the idp-entity-id and the idp-url where authentication requests are sent to. To be able to verify the digital signatures in a Response messages from the IDP, a signature-verification-key must point to the keystore that contains the IDP’s signing certificate.

Response signing requirements

By default, the Response-message from the IDP must have an Assertion that is signed. It is also possible to require the Response-message to be signed. These requirements can be configured independent from each other. The same certificate is used to verify both a Response signature as well as an Assertion signature.

Authentication Request configuration

An Authentication Request is constructed with the Server’s ID as SAML EntityID in the message. It is however possible to override the EntityID with a configured issuer-entity-id value. By default, the SAML AuthnRequest is not signed when it is sent. If a signing keystore is configured, it is used to include a digital signature on the AuthnRequest message.

If a specific NameID-format must be requested, this can be configured in the request-options/nameid-format setting of the SAML authenticator. A configured setting will be included in the NameIDPolicy/Format element of the SAML AuthnRequest-message.

ACR in Authentication Request

The ACR value that is included in the SAML Authentication Request’s RequestedAuthnContext is controlled by the authentication-context-class-reference configuration setting.

By default, whenever a client or Service Provider to the Authentication Service includes a value for acr in the request, this value is also included in the SAML request. This requires the ACR of the SAML authenticator to be aligned with the Authentication Context Class Reference at the Remote IDP. The authenticator can also be configured to supply an explicit value or to not include any value.

Timestamp validation

SAML Response messages are validated on their freshness. Whenever a SAML Response-message is received, its issue instant (issueInstant) value is compared to the Server’s current time. To be considered valid, the issue instant may only differ 60 seconds (both in the future as well as past) from the current timestamp. This clock skew setting can be custom specific by setting the saml-clock-skew configuration setting.

The same kind of timestamp validation is a done when ForceAuthn is included in the request, but the AuthnStatement/authnInstant part of the Assertion is used to compare the current time with.

Known limitations

The following limitations are known about the SAML authenticator

  • Only one Assertion is supported in a SAML Response. If the IDP returns multiple Assertions, the message is accepted, but only the first Assertion is used. Other Assertions are discarded completely.
  • No encryption is supported, nor on the messages, the assertions or attribute statements.

Configuration Example

<authenticator>
    <id>saml1</id>
    <saml xmlns="https://curity.se/ns/conf/authenticators/saml">
        <idp-entity-id>https://idp.example.com/</idp-entity-id>
        <idp-url>https://idp.example.com/saml2/sso/web</idp-url>
        <signature-verification-key>example-idp-signature-verification-key</signature-verification-key>
        <request-options>
            <nameid-format>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</nameid-format>
        </request-options>
        <wants-response-signed>true</wants-response-signed>
        <wants-assertion-signed>true</wants-assertion-signed>
        <request-signing-key>default-signing-key</request-signing-key>
    </saml>
</authenticator>