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. 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.
Force Auth
ForceAuthn
always
true
if-requested-by-client
Note
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.
prompt=login
forceAuthN
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.
The SAML2 authenticator can be configured to use HTTP Artifact binding to resolve the response from the IDP. When configured, the SAML Authenticator can receive a unique one-time reference to the message (called an artifact) during the authentication flow. The artifact is then exchanged using secure back-channel SOAP binding utilizing the configured HTTP Client and Artifact Resolution URL.
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.
One notable thing for creating dynamic configuration for the SAML2 authenticator (i.e. creating the delegate SAML2 authenticator configuration), is the decryption key. In order to configure a decryption key, you need to do two things:
The keystore password is configured as shared-delegate-authenticator-settings/keystore-password on the Dynamic Authenticator.
shared-delegate-authenticator-settings/keystore-password
The keystore itself must be a (password protected, in other words, an encrypted) PKCS8 private key, or it must be a base64-encoded, possibly password-protected, PKCS12 keystore. The PKCS12 keystore can contain multiple entries, but for the sake of using it as keystore for the dynamic authenticator, it must contain a private key and a certificate or public key. If multiple entries exist in the keystore, the first entry will be used.
The keystore can only be configured on a delegate authenticator, the configuration setting is called assertion-decryption-keystore.
assertion-decryption-keystore
Note that the keystore is used to generate the metadata, and if a certificate must show up in the SAML2 authenticator’s metadata, the keystore must be provided as a PKCS12 keystore that includes the certificate.
Also note that the keystore password is set on a dynamic authenticator, which implies that all keystores in the federation that the dynamic authenticator represents, are protected with the same password. Different dynamic authenticators, representing different federations, can use different passwords.
See the Dynamic Authenticator section for more information.
The following limitations are known about the SAML authenticator