SAML v2.0 Identity Providers

Keycloak can broker identity providers based on the SAML v2.0 protocol.

Procedure

Click Identity Providers in the menu.
From the Add provider list, select SAML v2.0.

Add identity provider
Enter your initial configuration options. See General IDP Configuration for more information about configuration options. .SAML Config

Configuration Description

Configuration	Description
Service Provider Entity ID	The SAML Entity ID that the remote Identity Provider uses to identify requests from this Service Provider. By default, this setting is set to the realms base URL `<root>/realms/{realm-name}`.
Single Sign-On Service URL	The SAML endpoint that starts the authentication process. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.
Single Logout Service URL	The SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.
Backchannel Logout	Toggle this switch to ON if your SAML IDP supports back channel logout.
NameID Policy Format	The URI reference corresponding to a name identifier format. By default, Keycloak sets it to `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`.
Principal Type	Specifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value can not be set together with 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' NameID Policy Format value.
Principal Attribute	If a Principal type is non-blank, this field specifies the name ("Attribute [Name]") or the friendly name ("Attribute [Friendly Name]") of the identifying attribute.
Allow create	Allow the external identity provider to create a new identifier to represent the principal.
HTTP-POST Binding Response	Controls the SAML binding in response to any SAML requests sent by an external IDP. When OFF, Keycloak uses Redirect Binding.
HTTP-POST Binding for AuthnRequest	Controls the SAML binding when requesting authentication from an external IDP. When OFF, Keycloak uses Redirect Binding.
Want AuthnRequests Signed	When ON, Keycloak uses the realm’s keypair to sign requests sent to the external SAML IDP.
Signature Algorithm	If Want AuthnRequests Signed is ON, the signature algorithm to use.
SAML Signature Key Name	Signed SAML documents sent using POST binding contain the identification of signing key in `KeyName` element, which, by default, contains the Keycloak key ID. External SAML IDPs can expect a different key name. This switch controls whether `KeyName` contains: * `KEY_ID` - Key ID. * `CERT_SUBJECT` - the subject from the certificate corresponding to the realm key. Microsoft Active Directory Federation Services expect `CERT_SUBJECT`. * `NONE` - Keycloak omits the key name hint from the SAML message.
Force Authentication	The user must enter their credentials at the external IDP even when the user is already logged in.
Validate Signature	When ON, the realm expects SAML requests and responses from the external IDP to be digitally signed.
Validating X509 Certificate	The public certificate Keycloak uses to validate the signatures of SAML requests and responses from the external IDP.
Sign Service Provider Metadata	When ON, Keycloak uses the realm’s key pair to sign the SAML Service Provider Metadata descriptor.
Pass subject	Controls if Keycloak forwards a `login_hint` query parameter to the IDP. Keycloak adds this field’s value to the login_hint parameter in the AuthnRequest’s Subject so destination providers can pre-fill their login form.
Attribute Consuming Service Index	Identifies the attribute set to request to the remote IDP. Keycloak automatically adds the attributes mapped in the identity provider configuration to the autogenerated SP metadata document.
Attribute Consuming Service Name	A descriptive name for the set of attributes that are advertised in the autogenerated SP metadata document.

Service Provider Entity ID

The SAML Entity ID that the remote Identity Provider uses to identify requests from this Service Provider. By default, this setting is set to the realms base URL <root>/realms/{realm-name}.

Single Sign-On Service URL

The SAML endpoint that starts the authentication process. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.

Single Logout Service URL

The SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field is specified there.

Backchannel Logout

Toggle this switch to ON if your SAML IDP supports back channel logout.

NameID Policy Format

The URI reference corresponding to a name identifier format. By default, Keycloak sets it to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

Principal Type

Specifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Subject NameID value can not be set together with 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' NameID Policy Format value.

Principal Attribute

If a Principal type is non-blank, this field specifies the name ("Attribute [Name]") or the friendly name ("Attribute [Friendly Name]") of the identifying attribute.

Allow create

Allow the external identity provider to create a new identifier to represent the principal.

HTTP-POST Binding Response

Controls the SAML binding in response to any SAML requests sent by an external IDP. When OFF, Keycloak uses Redirect Binding.

HTTP-POST Binding for AuthnRequest

Controls the SAML binding when requesting authentication from an external IDP. When OFF, Keycloak uses Redirect Binding.

Want AuthnRequests Signed

When ON, Keycloak uses the realm’s keypair to sign requests sent to the external SAML IDP.

Signature Algorithm

If Want AuthnRequests Signed is ON, the signature algorithm to use.

SAML Signature Key Name

Signed SAML documents sent using POST binding contain the identification of signing key in KeyName element, which, by default, contains the Keycloak key ID. External SAML IDPs can expect a different key name. This switch controls whether KeyName contains: * KEY_ID - Key ID. * CERT_SUBJECT - the subject from the certificate corresponding to the realm key. Microsoft Active Directory Federation Services expect CERT_SUBJECT. * NONE - Keycloak omits the key name hint from the SAML message.

Force Authentication

The user must enter their credentials at the external IDP even when the user is already logged in.

Validate Signature

When ON, the realm expects SAML requests and responses from the external IDP to be digitally signed.

Validating X509 Certificate

The public certificate Keycloak uses to validate the signatures of SAML requests and responses from the external IDP.

Sign Service Provider Metadata

When ON, Keycloak uses the realm’s key pair to sign the SAML Service Provider Metadata descriptor.

Pass subject

Controls if Keycloak forwards a login_hint query parameter to the IDP. Keycloak adds this field’s value to the login_hint parameter in the AuthnRequest’s Subject so destination providers can pre-fill their login form.

Attribute Consuming Service Index

Identifies the attribute set to request to the remote IDP. Keycloak automatically adds the attributes mapped in the identity provider configuration to the autogenerated SP metadata document.

Attribute Consuming Service Name

A descriptive name for the set of attributes that are advertised in the autogenerated SP metadata document.

You can import all configuration data by providing a URL or a file pointing to the SAML IDP entity descriptor of the external IDP. If you are connecting to a Keycloak external IDP, you can import the IDP settings from the URL <root>/realms/{realm-name}/protocol/saml/descriptor. This link is an XML document describing metadata about the IDP. You can also import all this configuration data by providing a URL or XML file pointing to the external SAML IDP’s entity descriptor to connect to.

Requesting specific AuthnContexts

Identity Providers facilitate clients specifying constraints on the authentication method verifying the user identity. For example, asking for MFA, Kerberos authentication, or security requirements. These constraints use particular AuthnContext criteria. A client can ask for one or more criteria and specify how the Identity Provider must match the requested AuthnContext, exactly, or by satisfying other equivalents.

You can list the criteria your Service Provider requires by adding ClassRefs or DeclRefs in the Requested AuthnContext Constraints section. Usually, you need to provide either ClassRefs or DeclRefs, so check with your Identity Provider documentation which values are supported. If no ClassRefs or DeclRefs are present, the Identity Provider does not enforce additional constraints.

Table 1. Requested AuthnContext Constraints
Configuration	Description
Comparison	The method the Identity Provider uses to evaluate the context requirements. The available values are `Exact`, `Minimum`, `Maximum`, or `Better`. The default value is `Exact`.
AuthnContext ClassRefs	The AuthnContext ClassRefs describing the required criteria.
AuthnContext DeclRefs	The AuthnContext DeclRefs describing the required criteria.

SP Descriptor

When you access the provider’s SAML SP metadata, look for the Endpoints item in the identity provider configuration settings. It contains a SAML 2.0 Service Provider Metadata link which generates the SAML entity descriptor for the Service Provider. You can download the descriptor or copy its URL and then import it into the remote Identity Provider.

This metadata is also available publicly by going to the following URL:

http[s]://{host:port}/realms/{realm-name}/broker/{broker-alias}/endpoint/descriptor

Ensure you save any configuration changes before accessing the descriptor.

Send subject in SAML requests

By default, a social button pointing to a SAML Identity Provider redirects the user to the following login URL:

http[s]://{host:port}/realms/${realm-name}/broker/{broker-alias}/login

Adding a query parameter named login_hint to this URL adds the parameter’s value to SAML request as a Subject attribute. If this query parameter is empty, Keycloak does not add a subject to the request.

Enable the "Pass subject" option to send the subject in SAML requests.