The SAML2 authenticator can be used to act as a SAML Service Provider and 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 SAML2 authenticator is a newer version of the SAML authenticator. It is recommended to use the SAML2 authenticator over the SAML authenticator, as support for the latter one will be dropped in the future.
The SAML2 authenticator is mounted on the Authentication endpoint with the subpath of its ID. So if an authenticator with the ID saml2 is configured and the Authentication endpoint is configured to have the path /authenticate then the path of the SAML2 authenticator is found under /authenticate/saml2.
saml2
/authenticate
/authenticate/saml2
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 can be a response to a previously sent SAML AuthnRequest in the same session, but the SAML2 authenticator also supports unsolicited responses (i.e. a Response that does not refer to any previous AuthnRequest).
Because no user interaction is required in this flow, there are no user interface or template customizations available for this authenticator.
The SAML2 authenticator publishes its Service Provider metadata on the anonymous endpoint of the authenticator, under the /metadata subpath. For example, if an authenticator with ID my-saml2-authenticator is configured on an authentication profile that has the anonymous endpoint mapped on /authenticate/anonymous, then the metadata is published on the path /authenticate/anonymous/my-saml2-authenticator/metadata.
/metadata
my-saml2-authenticator
/authenticate/anonymous
/authenticate/anonymous/my-saml2-authenticator/metadata
When used as a dynamic authenticator the metadata endpoint expects the federation id to be passed in the query parameter (fid). When the federation id is not provided the default value is used. For example, the request for metadata with federation ID test-federation-id and dynamic authenticator ID my-saml2-dynamic-authenticator, (configured on an authentication profile that has the anonymous endpoint mapped on /authenticate/anonymous), will be the following /authenticate/anonymous/my-saml2-dynamic-authenticator/metadata?fid=test-federation-id.
fid
default
test-federation-id
my-saml2-dynamic-authenticator
/authenticate/anonymous/my-saml2-dynamic-authenticator/metadata?fid=test-federation-id
While the SAML2 authenticator supports Validation Procedures, the request model of the saml2-endpoint is limited in its capabilities of receiving parameters. The GET on the saml2-endpoint doesn’t take any input, and the POST on the saml2-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 SAML2 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 of a Response message or Assertion that was received from an 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 full Response message to be signed. These requirements can be configured independently of 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 configured Issuer Entity ID as SAML EntityID in the message. By default, the SAML AuthnRequest is not signed when it is sent. However, when a Request 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.
request-options/nameid-format
NameIDPolicy/Format
The SAML2 Authenticator can indicate that authentication must always be performed. This is controlled by the authenticator’s Force Auth setting. By default, it is not sent. Configuration allows you to always ask for Force Authentication, or to have it controlled on a per-request basis. The latter will allow an OpenId Connect client to ask for prompt=login, which would result in the SAML Authenticator’s AuthnRequest message to include forced authentication.
Force Auth
prompt=login
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 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 SAML2 Authenticator can be used as a dynamic authenticator. This means that its configuration can be sourced from different places than from the configuration settings.
See the Dynamic Authenticator section for more information.
The following limitations are known about the SAML authenticator