keycloak-scim/server_admin/topics/identity-broker/saml.adoc

=== SAML v2.0 Identity Providers

{project_name} can broker identity providers based on the SAML v2.0 protocol.

To begin configuring an SAML v2.0 provider, go to the `Identity Providers` left menu item
and select `SAML v2.0` from the `Add provider` drop down list.  This will bring you to the `Add identity provider` page.

.Add Identity Provider
image:{project_images}/saml-add-identity-provider.png[]

The initial configuration options on this page are described in <<_general-idp-config, General IDP Configuration>>.
You must define the SAML configuration options as well.  They basically describe the SAML IDP you are communicating with.

.SAML Config
|===
|Configuration|Description

|Service Provider Entity ID
|This is a required field and specifies the SAML Entity ID that the remote Identity Provider will use to identify requests coming from this Service Provider. By default it is set to the realm base URL `<root>/auth/realms/{realm-name}`.

|Single Sign-On Service URL
|This is a required field and specifies the SAML endpoint to start the authentication process.  If your SAML IDP publishes an IDP entity descriptor, the value of
 this field will be specified there.

|Single Logout Service URL
|This is an optional field that specifies the SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of
 this field will be specified there.
 
|Backchannel Logout
|Enable if your SAML IDP supports backchannel logout.

|NameID Policy Format
|Specifies the URI reference corresponding to a name identifier format. Defaults 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 Principal is set to either "Attribute [Name]" or "Attribute [Friendly Name]", this field will specify the name or the friendly name of the identifying attribute, respectively.

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

|HTTP-POST Binding Response
|When this realm responds to any SAML requests sent by the external IDP, which SAML binding should be used?  If set to `off`, then the Redirect Binding will be used.

|HTTP-POST Binding for AuthnRequest
|When this realm requests authentication from the external SAML IDP, which SAML binding should be used?  If set to `off`, then the Redirect Binding will be used.

|Want AuthnRequests Signed
|If true, it will use the realm's keypair to sign requests sent to the external SAML IDP.

|Signature Algorithm
|If `Want AuthnRequests Signed` is on, then you can also pick the signature algorithm to use.

|SAML Signature Key Name
|Signed SAML documents sent via POST binding contain identification of signing key in `KeyName`
 element. This by default contains {project_name} key ID. However various external SAML IDPs might
 expect a different key name or no key name at all. This switch controls whether `KeyName`
 contains key ID (option `KEY_ID`), subject from certificate corresponding to the realm key
 (option `CERT_SUBJECT` - expected for instance by Microsoft Active Directory Federation
 Services), or that the key name hint is completely omitted from the SAML message (option `NONE`).

|Force Authentication
|Indicates that the user will be forced to enter their credentials at the external IDP even if they are already logged in.

|Validate Signature
|Whether or not the realm should expect that SAML requests and responses from the external IDP to be digitally signed.  It is highly recommended you turn this on!

|Validating X509 Certificate
|The public certificate that will be used to validate the signatures of SAML requests and responses from the external IDP.

|Sign Service Provider Metadata
|If true, it will use the realm's keypair to sign the <<_identity_broker_saml_sp_descriptor, SAML Service Provider Metadata descriptor>>.

|Pass subject
|Whether or not a `login_hint` query parameter should be forwarded to the IDP. When provided, this login_hint parameter is added to AuthnRequest's Subject. This allows destination providers to prefill their login form. When no login_hint is provided, nothing is forwarded as an AuthnRequest Subject.
|===


You can also import all this configuration data by providing a URL or file that points to the SAML IDP entity descriptor of the external IDP.
If you are connecting to a {project_name} external IDP, you can import the IDP settings from the URL `<root>/auth/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 that points to the entity descriptor of the external SAML IDP you want to connect to.

[[_identity_broker_saml_requested_authncontext]]
==== Requesting specific AuthnContexts
Some Identity Providers let the clients specify particular constraints on the authentication method used to verify the user identity (such as asking for MFA, Kerberos authentication, security requirements, and so on). These constraints are specified using particular AuthnContext criteria. A client can ask for one or more criteria and also specify how the Identity Provider should match the requested AuthnContext - exactly, or by satisfying same-or-better equivalents.

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

.Requested AuthnContext Constraints
|===
|Configuration|Description

|Comparison
|The comparison method the Identity Provider should use to evaluate the context requirements. Available values are `Exact`, `Minimum`, `Maximum` or `Better`. Default value is `Exact`.

|AuthnContext ClassRefs
|One or more AuthnContext ClassRefs that describe the required criteria.

|AuthnContext DeclRefs
|One or more AuthnContext DeclRefs that describe the required criteria.
|===

[[_identity_broker_saml_sp_descriptor]]
==== SP Descriptor

If you need to access the provider's SAML SP metadata, look for the `Endpoints` item in the identity provider configuration settings. It contains a link called 
`SAML 2.0 Service Provider Metadata` that generates the SAML entity descriptor for the Service Provider. You can either download it or copy its URL and then import it in the remote Identity Provider.

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

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

Make sure to save any configuration changes before accessing the descriptor or they will not be reflected in the metadata.

[[_identity_broker_saml_login_hint]]
==== Send Subject in SAML requests

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

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

Adding a query parameter named `login_hint` to this URL will add its value to SAML request as a Subject attribute. When this query parameter is absent or left empty, no subject will be added to the request.

"Pass subject" option must be enabled.