189 lines
9.4 KiB
XML
Executable file
189 lines
9.4 KiB
XML
Executable file
<chapter id="saml">
|
|
<title>SAML SSO</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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 <literal>saml</literal> from the protocol list. After that there
|
|
are a bunch of configuration options. Here is a description of each item:
|
|
</para>
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>Include AuthnStatement</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Multi-valued Roles</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Sign Documents</term>
|
|
<listitem>
|
|
<para>
|
|
When turned on, Keycloak will sign the document using the realm's private key.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Sign Assertions</term>
|
|
<listitem>
|
|
<para>
|
|
With the <literal>Sign Documents</literal> switch signs the whole document. With this setting
|
|
you just assign the assertions of the document.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Signature Algorithm</term>
|
|
<listitem>
|
|
<para>
|
|
Choose between a variety of algorithms for signing SAML documents.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Encrypt Assertions</term>
|
|
<listitem>
|
|
<para>
|
|
Encrypt assertions in SAML documents with the realm's private key. The AES algorithm is used
|
|
with a key size of 128 bits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Client Signature Required</term>
|
|
<listitem>
|
|
<para>
|
|
Expect that documents coming from a client are signed. Keycloak will validate this signature
|
|
using the client keys set up in the <literal>Application Keys</literal> submenu item.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Force POST Binding</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Front Channel Logout</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Force Name ID Format</term>
|
|
<listitem>
|
|
<para>
|
|
If the request has a name ID policy, ignore it and used the value configured in the admin console
|
|
under Name ID Format
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Name ID Format</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Master SAML Processing URL</term>
|
|
<listitem>
|
|
<para>
|
|
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
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Assertion Consumer Service POST Binding URL</term>
|
|
<listitem>
|
|
<para>
|
|
POST Binding URL for the Assertion Consumer Service.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Assertion Consumer Service Redirect Binding URL</term>
|
|
<listitem>
|
|
<para>
|
|
Redirect Binding URL for the Assertion Consumer Service.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Logout Service POST Binding URL</term>
|
|
<listitem>
|
|
<para>
|
|
POST Binding URL for the Logout Service.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>Logout Service Redirect Binding URL</term>
|
|
<listitem>
|
|
<para>
|
|
Redirect Binding URL for the Logout Service.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<section>
|
|
<title>SAML Entity Descriptor</title>
|
|
<para>
|
|
If you go into the admin console in the application list menu page you will see an <literal>Import</literal>
|
|
button. If you click on that you can import SAML Service Provider definitions using the <ulink url="http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf">Entity Descriptor</ulink>
|
|
format described in SAML 2.0. You should review all the information there to make sure everything is set up correctly.
|
|
</para>
|
|
<para>
|
|
Each realm has a URL where you can view the XML entity descriptor for the IDP. <literal>root/realms/{realm}/protocol/saml/descriptor</literal>
|
|
</para>
|
|
</section>
|
|
</chapter>
|