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.
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.
saml1
/authenticate
/authenticate/saml1
/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.
idp-url
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.
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.
SAMLResponse
For more information on Validation Procedures see Validation section.
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.
idp-entity-id
signature-verification-key
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.
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.
issuer-entity-id
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.
request-options/nameid-format
NameIDPolicy/Format
The ACR value that is included in the SAML Authentication Request’s RequestedAuthnContext is controlled by the authentication-context-class-reference configuration setting.
RequestedAuthnContext
authentication-context-class-reference
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.
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.
issueInstant
saml-clock-skew
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.
AuthnStatement/authnInstant
The following limitations are known about the SAML authenticator
<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>