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.

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

Service Provider metadata

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.

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.

Endpoint-kind: saml2

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

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.

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

Authentication Request configuration

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.

Force Authentication

The SAML2 Authenticator can indicate that authentication must always be performed. This is controlled by the authenticator’s Force Auth setting. When the value is not sent, the authenticator will NOT include a ForceAuthn attribute in the outbound SAML authentication request, regardless of the client requesting forced authentication or whether a client is configured with a setting to force re-authentication. When the value is set to always, the authenticator will include a ForceAuthn attribute with a value of true in the outbound SAML authentication request, regardless of what is requested or configured for a client. In case of selecting if-requested-by-client, the inclusion of the ForceAuthn attribute is based on whether it was included in the request to Curity, or whether an OAuth client was configured with the option to force re-authentication.


An OAuth client can request forced authentication when using an OpenId Authentication request’s prompt=login parameter to the Authorization endpoint. A Service Provider in the Authentication Profile can request forced authentication using an authentication request’s forceAuthN parameter to the Authentication or Authenticator endpoint.

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 done when ForceAuthn is included in the request, but the AuthnStatement/authnInstant part of the Assertion is used to compare the current time with.

SAML2 dynamic authenticator

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.

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.