159 lines
9.4 KiB
Text
159 lines
9.4 KiB
Text
|
|
[[_client-saml-configuration]]
|
|
= Creating a SAML client
|
|
[role="_abstract"]
|
|
{project_name} supports <<_saml,SAML 2.0>> for registered applications.
|
|
POST and Redirect bindings are supported. You can choose to require client signature validation. You can have the server sign and/or encrypt responses as well.
|
|
|
|
.Procedure
|
|
. Click *Clients* in the menu.
|
|
. Click *Create client* to go to the *Create client* page.
|
|
. Set *Client type* to *SAML*.
|
|
+
|
|
.Create client
|
|
image:images/add-client-saml.png[]
|
|
|
|
. Enter the *Client ID* of the client. This is often a URL and is the expected *issuer* value in SAML requests sent by the application.
|
|
|
|
. Click *Save*. This action creates the client and brings you to the *Settings* tab.
|
|
|
|
The following sections describe each setting on this tab.
|
|
|
|
== Settings tab
|
|
|
|
The *Settings* tab includes many options to configure this client.
|
|
|
|
.Client settings
|
|
image:images/client-settings-saml.png[]
|
|
|
|
=== General settings
|
|
|
|
*Client ID*:: The alphanumeric ID string that is used in OIDC requests and in the {project_name} database to identify the client. This value must match the issuer value sent with AuthNRequests. {project_name} pulls the issuer from the Authn SAML request and match it to a client by this value.
|
|
|
|
*Name*:: The name for the client in a {project_name} UI screen. To localize
|
|
the name, set up a replacement string value. For example, a string value such as $\{myapp}. See the link:{developerguide_link}[{developerguide_name}] for more information.
|
|
|
|
*Description*:: The description of the client. This setting can also be localized.
|
|
|
|
// *Enabled*:: When set to *On*, the client can request authentication.
|
|
|
|
*Always Display in Console*:: Always list this client in the Account Console even if this user does not have an active session.
|
|
|
|
=== Access Settings
|
|
|
|
*Root URL*:: When {project_name} uses a configured relative URL, this value is prepended to the URL.
|
|
|
|
*Home URL*:: If {project_name} needs to link to a client, this URL is used.
|
|
|
|
*Valid Redirect URIs*:: Enter a URL pattern and click the + sign to add. Click the - sign to remove. Click *Save* to save these changes.
|
|
Wildcards values are allowed only at the end of a URL. For example, http://host.com/*$$.
|
|
This field is used when the exact SAML endpoints are not registered and {project_name} pulls the Assertion Consumer URL from a request.
|
|
|
|
*IDP-Initiated SSO URL name*:: URL fragment name to reference client when you want to do IDP Initiated SSO. Leaving this empty will disable IDP Initiated SSO. The URL you will reference from your browser will be: _server-root_/realms/{realm}/protocol/saml/clients/{client-url-name}
|
|
|
|
*IDP Initiated SSO Relay State*:: Relay state you want to send with SAML request when you want to do IDP Initiated SSO.
|
|
|
|
*Master SAML Processing URL*:: This URL is used for all SAML requests and the response is directed to the SP. It is used as the Assertion Consumer Service URL and the Single Logout Service URL.
|
|
+
|
|
If login requests contain the Assertion Consumer Service URL then those login requests will take precedence. This URL must be validated by a registered Valid Redirect URI pattern.
|
|
|
|
=== SAML capabilities
|
|
|
|
*Name ID Format*:: The Name ID Format for the subject. This format is used if no name ID policy is specified in a request, or if the Force Name ID Format attribute is set to ON.
|
|
|
|
*Force Name ID Format*:: If a request has a name ID policy, ignore it and use the value configured in the Admin Console under *Name ID Format*.
|
|
|
|
*Force POST Binding*:: By default, {project_name} responds using the initial SAML binding of the original request. By enabling *Force POST Binding*, {project_name} responds using the SAML POST binding even if the original request used the redirect binding.
|
|
|
|
*Force artifact binding*:: If enabled, response messages are returned to the client through the SAML ARTIFACT binding system.
|
|
|
|
*Include AuthnStatement*:: SAML login responses may specify the authentication method used, such as password, as well as timestamps of the login and the session expiration.
|
|
*Include AuthnStatement* is enabled by default, so that the *AuthnStatement* element will be included in login responses. Setting this to OFF prevents clients from determining the maximum session length, which can create client sessions that do not expire.
|
|
|
|
*Include OneTimeUse Condition*:: If enable, a OneTimeUse Condition is included in login responses.
|
|
|
|
*Optimize REDIRECT signing key lookup*:: When set to ON, the SAML protocol messages include the {project_name} native extension. This extension contains a hint with the signing key ID. The SP uses the extension for signature validation instead of attempting to validate the signature using keys.
|
|
+
|
|
This option applies to REDIRECT bindings where the signature is transferred in query parameters and this information is not found in the signature information. This is contrary to POST binding messages where key ID is always included in document signature.
|
|
+
|
|
This option is used when {project_name} server and adapter provide the IDP and SP. This option is only relevant when *Sign Documents* is set to ON.
|
|
|
|
=== Signature and Encryption
|
|
|
|
*Sign Documents*:: When set to ON, {project_name} signs the document using the realms private key.
|
|
|
|
*Sign Assertions*:: The assertion is signed and embedded in the SAML XML Auth response.
|
|
|
|
*Signature Algorithm*:: The algorithm used in signing SAML documents. Note that `SHA1` based algorithms are deprecated and may be removed in a future release.
|
|
We recommend the use of some more secure algorithm instead of `*_SHA1`. Also, with `*_SHA1` algorithms, verifying signatures
|
|
do not work if the SAML client runs on Java 17 or higher.
|
|
|
|
*SAML Signature Key Name*:: Signed SAML documents sent using POST binding contain the identification of the signing key in the *KeyName* element. This action can be controlled by the *SAML Signature Key Name* option. This option controls the contents of the *Keyname*.
|
|
+
|
|
--
|
|
* *KEY_ID* The *KeyName* contains the key ID. This option is the default option.
|
|
* *CERT_SUBJECT* The *KeyName* contains the subject from the certificate corresponding to the realm key. This option is expected by Microsoft Active Directory Federation Services.
|
|
* *NONE* The *KeyName* hint is completely omitted from the SAML message.
|
|
--
|
|
+
|
|
*Canonicalization Method*:: The canonicalization method for XML signatures.
|
|
|
|
=== Login settings
|
|
|
|
*Login theme*:: A theme to use for login, OTP, grant registration, and forgotten password pages.
|
|
|
|
*Consent required*:: If enabled, users have to consent to client access.
|
|
+
|
|
For client-side clients that perform browser logins. As it is not possible to ensure that secrets can be kept safe with client-side clients, it is important to restrict access by configuring correct redirect URIs.
|
|
|
|
*Display client on screen*:: This switch applies if *Consent Required* is *Off*.
|
|
* _Off_
|
|
+
|
|
The consent screen will contain only the consents corresponding to configured client scopes.
|
|
|
|
* _On_
|
|
+
|
|
There will be also one item on the consent screen about this client itself.
|
|
|
|
*Client consent screen text*:: Applies if *Consent required* and *Display client on screen* are enabled. Contains the text that will be on the consent screen about permissions for this client.
|
|
|
|
=== Logout settings
|
|
|
|
*Front channel logout*:: If *Front Channel Logout* is enabled, the application requires a browser redirect to perform a logout. For example, the application may require a cookie to be reset which could only be done via a redirect. If *Front Channel Logout* is disabled, {project_name} invokes a background SAML request to log out of the application.
|
|
|
|
== Keys tab
|
|
|
|
*Encrypt Assertions*:: Encrypts the assertions in SAML documents with the realms private key. The AES algorithm uses a key size of 128 bits.
|
|
|
|
*Client Signature Required*:: If *Client Signature Required* is enabled, documents coming from a client are expected to be signed. {project_name} will validate this signature using the client public key or cert set up in the `Keys` tab.
|
|
|
|
*Allow ECP Flow*:: If true, this application is allowed to use SAML ECP profile for authentication.
|
|
|
|
== Advanced tab
|
|
|
|
This tab has many fields for specific situations. Some fields are covered in other topics. For details on other fields, click the question mark icon.
|
|
|
|
=== Fine Grain SAML Endpoint Configuration
|
|
|
|
*Logo URL*:: URL that references a logo for the Client application.
|
|
|
|
*Policy URL*:: URL that the Relying Party Client provides to the End-User to read about how the profile data will be used.
|
|
|
|
*Terms of Service URL*:: URL that the Relying Party Client provides to the End-User to read about the Relying Party's terms of service.
|
|
|
|
*Assertion Consumer Service POST Binding URL*:: POST Binding URL for the Assertion Consumer Service.
|
|
|
|
*Assertion Consumer Service Redirect Binding URL*:: Redirect Binding URL for the Assertion Consumer Service.
|
|
|
|
*Logout Service POST Binding URL*:: POST Binding URL for the Logout Service.
|
|
|
|
*Logout Service Redirect Binding URL*:: Redirect Binding URL for the Logout Service.
|
|
|
|
*Logout Service Artifact Binding URL*:: _Artifact_ Binding URL for the Logout Service. When set together with the `Force Artifact Binding` option, _Artifact_ binding is forced for both login and logout flows. _Artifact_ binding is not used for logout unless this property is set.
|
|
|
|
*Logout Service SOAP Binding URL*:: Redirect Binding URL for the Logout Service. Only applicable if *back channel logout* is used.
|
|
|
|
*Artifact Binding URL*:: URL to send the HTTP artifact messages to.
|
|
|
|
*Artifact Resolution Service*:: URL of the client SOAP endpoint where to send the `ArtifactResolve` messages to.
|
|
|