178 lines
8.4 KiB
Text
178 lines
8.4 KiB
Text
[[_client-saml-configuration]]
|
|
=== SAML Clients
|
|
|
|
{project_name} supports <<_saml,SAML 2.0>> for registered applications.
|
|
Both POST and Redirect bindings are supported.
|
|
You can choose to require client signature validation and can have the server sign and/or encrypt responses as well.
|
|
|
|
To create a SAML client go to the `Clients` left menu item. On this page you'll see a `Create` button on the right.
|
|
|
|
.Clients
|
|
image:{project_images}/clients.png[]
|
|
|
|
This will bring you to the `Add Client` page.
|
|
|
|
|
|
.Add Client
|
|
image:{project_images}/add-client-saml.png[]
|
|
|
|
Enter in the `Client ID` of the client. This is often a URL and will be the expected `issuer` value in SAML requests sent
|
|
by the application. Next select `saml` in the `Client Protocol` drop down box.
|
|
Finally enter in the `Client SAML Endpoint` URL. Enter the
|
|
URL you want the {project_name} server to send SAML requests and responses to. Usually applications have only one URL for processing SAML requests.
|
|
If your application has different URLs for its bindings, don't worry, you can fix this in the `Settings` tab of the client.
|
|
Click `Save`. This will create the client and bring you to the client `Settings`
|
|
tab.
|
|
|
|
.Client Settings
|
|
image:{project_images}/client-settings-saml.png[]
|
|
|
|
|
|
|
|
Client ID::
|
|
This value must match the issuer value sent with AuthNRequests.
|
|
{project_name} will pull the issuer from the Authn SAML request and match it to a client by this value.
|
|
|
|
Name::
|
|
This is the display name for the client whenever it is displayed in a {project_name} UI screen. You can localize
|
|
the value of this field by setting up a replacement string value i.e. $\{myapp}. See the link:{developerguide_link}[{developerguide_name}]
|
|
for more information.
|
|
|
|
Description::
|
|
This specifies the description of the client. This can also be localized.
|
|
|
|
Enabled::
|
|
If this is turned off, the client will not be allowed to request authentication.
|
|
|
|
Consent Required::
|
|
If this is on, then users will get a consent page which asks the user if they grant access to that application. It will also
|
|
display the metadata that the client is interested in so that the user knows exactly what information the client is getting access to.
|
|
If you've ever done a social login to Google, you'll often see a similar page. {project_name} provides the same functionality.
|
|
|
|
Include AuthnStatement::
|
|
SAML login responses may specify the authentication method used (password, etc.) as well as timestamps of the login and the session expiration.
|
|
This is enabled by default, which means that `AuthStatement` element will be included in login responses. Note that setting this to off
|
|
would prevent the client from determining the maximum session length which could result into never expiring client session.
|
|
|
|
Force Artifact Binding::
|
|
When turned on, this will force {project_name} to send artifact messages instead of SAML messages via _POST_ and _Redirect_,
|
|
even when the client has not asked for the binding during login. This must be set if _Artifact_ binding is to be used with
|
|
Idp-initiated login. To use artifact messages also during logout, it is necessary to also configure `Logout Service Redirect Binding URL`.
|
|
|
|
Sign Documents::
|
|
When turned on, {project_name} will sign the document using the realm's private key.
|
|
|
|
Optimize REDIRECT signing key lookup::
|
|
When turned on, the SAML protocol messages will include {project_name}
|
|
native extension that contains a hint with signing key ID. When the SP
|
|
understands this extension, it can use it for signature validation instead of
|
|
attempting to validate signature with all known keys. This option only applies to
|
|
REDIRECT bindings where the signature is transferred in query parameters where
|
|
there is no place with this information in the signature information
|
|
(contrary to POST binding messages where key ID is always included in
|
|
document signature). Currently this is relevant to situations where both
|
|
IDP and SP are provided by {project_name} server and adapter. This
|
|
option is only relevant when `Sign Documents` is switched on.
|
|
|
|
Sign Assertions::
|
|
The `Sign Documents` switch signs the whole document.
|
|
With this setting the assertion is also signed and embedded within the SAML XML Auth response.
|
|
|
|
Signature Algorithm::
|
|
Choose between a variety of algorithms for signing SAML documents.
|
|
|
|
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 vendors 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`).
|
|
|
|
Canonicalization Method::
|
|
Canonicalization method for XML signatures.
|
|
|
|
Encrypt Assertions::
|
|
Encrypt assertions in SAML documents with the realm's private key.
|
|
The AES algorithm is used with a key size of 128 bits.
|
|
|
|
Client Signature Required::
|
|
Expect that documents coming from a client are signed.
|
|
{project_name} will validate this signature using the client public key or cert set up in the `SAML Keys` tab.
|
|
|
|
Force POST Binding::
|
|
By default, {project_name} will respond using the initial SAML binding of the original request.
|
|
By turning on this switch, you will force {project_name} to always respond using the SAML POST Binding even if the original request was the Redirect binding.
|
|
|
|
Front Channel Logout::
|
|
If true, this application requires a browser redirect to be able to perform a logout.
|
|
For example, the application may require a cookie to be reset which could only be done via a redirect.
|
|
If this switch is false, then {project_name} will invoke a background SAML request to logout the application.
|
|
|
|
Force Name ID Format::
|
|
If the request has a name ID policy, ignore it and used the value configured in the admin console under Name ID Format
|
|
|
|
Name ID Format::
|
|
Name ID Format for the subject.
|
|
If no name ID policy is specified in the request or if the Force Name ID Format attribute is true, this value is used.
|
|
Properties used for each of the respective formats are defined below.
|
|
You can change the attribute used by the NameID Mapper.
|
|
|
|
|===
|
|
|Name ID Format|Properties/Attributes Used|Example
|
|
|
|
|username (unspecified)
|
|
|Username Property
|
|
|example_user
|
|
|
|
|email
|
|
|Email Property
|
|
|example_user@example.com
|
|
|
|
|persistent
|
|
|saml.persistent.name.id.for.$clientId Attribute
|
|
|G-6e2a1050-0fc0-479b-bf6e-29cd3ccb373b
|
|
|
|
|transient
|
|
|property and attribute values are not used
|
|
|G-bfb85c10-57d7-4331-81bc-52f104599d79
|
|
|
|
|===
|
|
|
|
Root URL::
|
|
If {project_name} uses any configured relative URLs, this value is prepended to them.
|
|
|
|
Valid Redirect URIs::
|
|
This is an optional field. Enter in a URL pattern and click the + sign to add. Click the - sign next to URLs you want to remove.
|
|
Remember that you still have to click the `Save` button!
|
|
Wildcards (*) are only allowed at the end of a URI, i.e. $$http://host.com/*$$. This field is used when the exact SAML
|
|
endpoints are not registered and {project_name} is pulling the Assertion Consumer URL from the request.
|
|
|
|
Base URL::
|
|
If {project_name} needs to link to the client, this URL would be used.
|
|
|
|
Master SAML Processing URL::
|
|
This URL will be used for all SAML requests and the response will be directed to the SP.
|
|
It will be used as the Assertion Consumer Service URL and the Single Logout Service URL.
|
|
If a login request contains the Assertion Consumer Service URL, that will take precedence, but this URL must be validated by a registered Valid Redirect URI pattern
|
|
|
|
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.
|
|
|
|
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.
|