115 lines
6 KiB
Text
115 lines
6 KiB
Text
|
[[_saml]]
|
||
|
|
= SAML SSO
|
||
|
|
|
||
|
|
Keycloak supports 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.
|
||
|
|
We do not yet support logout via redirects.
|
||
|
|
All logouts happen via a background POST binding request to the application that will be logged out.
|
||
|
|
We do not support SAML 1.1 either.
|
||
|
|
If you want support for either of those, please log a JIRA request and we'll schedule it.
|
||
|
|
|
||
|
|
When you create an application in the admin console, you can choose which protocol the application will log in with.
|
||
|
|
In the application create screen, choose `saml` from the protocol list.
|
||
|
|
After that there are a bunch of configuration options.
|
||
|
|
Here is a description of each item:
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
Client ID::
|
||
|
|
This value must match the issuer value sent with AuthNRequests.
|
||
|
|
Keycloak will pull the issuer from the Authn SAML request and match it to a client by this value.
|
||
|
|
|
||
|
|
Include AuthnStatement::
|
||
|
|
SAML login responses may specify the authentication method used (password, etc.) as well as a timestamp of the login.
|
||
|
|
Setting this to on will include that statement in the response document.
|
||
|
|
|
||
|
|
Multi-valued Roles::
|
||
|
|
If this switch is off, any user role mappings will have a corresponding attribute created for it.
|
||
|
|
If this switch is turn on, only one role attribute will be created, but it will have multiple values within in.
|
||
|
|
|
||
|
|
Sign Documents::
|
||
|
|
When turned on, Keycloak will sign the document using the realm's private key.
|
||
|
|
|
||
|
|
Sign Assertions::
|
||
|
|
With the `Sign Documents` switch signs the whole document.
|
||
|
|
With this setting you just assign the assertions of the document.
|
||
|
|
|
||
|
|
Signature Algorithm::
|
||
|
|
Choose between a variety of algorithms for signing SAML documents.
|
||
|
|
|
||
|
|
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.
|
||
|
|
Keycloak will validate this signature using the client keys set up in the `Application Keys` submenu item.
|
||
|
|
|
||
|
|
Force POST Binding::
|
||
|
|
By default, Keycloak will respond using the initial SAML binding of the original request.
|
||
|
|
By turning on this switch, you will force Keycloak 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 by a done via a redirect.
|
||
|
|
If this switch is false, then Keycloak 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.
|
||
|
|
|
||
|
|
Master SAML Processing URL::
|
||
|
|
This URL will be used for all SAML requests and responsed 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 valided 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.
|
||
|
|
|
||
|
|
For login to work, Keycloak needs to be able to resolve the URL for the Assertion Consumer Service of the SP.
|
||
|
|
If you are relying on the SP to provide this URL in the login request, then you must register valid redirect uri patterns so that this URL can be validated.
|
||
|
|
You can set the Master SAML Processing URL as well, or alternatively, you can specify the Assertion Consumer Service URL per binding.
|
||
|
|
|
||
|
|
For logout to work, you must specify a Master SAML Processing URL, or the Loging Service URL for the binding you want Keycloak to use.
|
||
|
|
|
||
|
|
One thing to note is that roles are not treated as a hierarchy.
|
||
|
|
So, any role mappings will just be added to the role attributes in the SAML document using their basic name.
|
||
|
|
So, if you have multiple application roles you might have name collisions.
|
||
|
|
You can use the Scope Mapping menu item to control which role mappings are set in the response.
|
||
|
|
|
||
|
|
== SAML Entity Descriptor
|
||
|
|
|
||
|
|
If you go into the admin console in the application list menu page you will see an `Import` button.
|
||
|
|
If you click on that you can import SAML Service Provider definitions using the http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf[Entity Descriptor
|
||
|
|
] format described in SAML 2.0.
|
||
|
|
You should review all the information there to make sure everything is set up correctly.
|
||
|
|
|
||
|
|
Each realm has a URL where you can view the XML entity descriptor for the IDP. `root/auth/realms/{realm}/protocol/saml/descriptor`
|
||
|
|
|
||
|
|
== IDP Initiated Login
|
||
|
|
|
||
|
|
IDP Initiated Login is a feature that where you can set up a URL on the Keycloak server that will log you into a specific application/client.
|
||
|
|
To set this up go to the client page in the admin console of the client you want to set this up for.
|
||
|
|
Specify the``
|
||
|
|
IDP Initiated SSO URL Name``.
|
||
|
|
This is a simple string with no whitespace in it.
|
||
|
|
After this you can reference your client at the following URL: `root/auth/realms/{realm}/protocol/saml/clients/{url-name}`
|
||
|
|
|
||
|
|
If your client requires a special relay state, you can also configure this in the admin console.
|
||
|
|
Alternatively, you can specify the relay state in a `RelayState` query parameter, i.e.
|
||
|
|
: `root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate`
|