libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

add docbook info on how NameID is calculated

Browse source
This commit is contained in:
Josh Cain 2016-02-05 11:18:02 -06:00
parent e3d64f301d
commit 66cec589f7
1 changed files with 168 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

178
docbook/auth-server-docs/reference/en/en-US/modules/saml.xml
View file

@ -18,15 +18,19 @@
<chapter id="saml"> <chapter id="saml">
<title>SAML SSO</title> <title>SAML SSO</title>
<para> <para>
Keycloak supports SAML 2.0 for registered applications. Both POST and Redirect bindings are supported. You can choose 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 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 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 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. log a JIRA request and we'll schedule it.
</para> </para>
<para> <para>
When you create an application in the admin console, you can choose which protocol the application will log in with. When you create an application in the admin console, you can choose which protocol the application will log in
In the application create screen, choose <literal>saml</literal> from the protocol list. After that there 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: are a bunch of configuration options. Here is a description of each item:
</para> </para>
<para> <para>
@ -45,7 +49,8 @@
<listitem> <listitem>
<para> <para>
SAML login responses may specify the authentication method used (password, etc.) as well as 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. a timestamp of the login. Setting this to on will include that statement in the response
document.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -53,7 +58,8 @@
<term>Multi-valued Roles</term> <term>Multi-valued Roles</term>
<listitem> <listitem>
<para> <para>
If this switch is off, any user role mappings will have a corresponding attribute created for it. 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 If this switch is turn on, only one role attribute will be created, but it will have
multiple values within in. multiple values within in.
</para> </para>
@ -71,7 +77,9 @@
<term>Sign Assertions</term> <term>Sign Assertions</term>
<listitem> <listitem>
<para> <para>
With the <literal>Sign Documents</literal> switch signs the whole document. With this setting With the
<literal>Sign Documents</literal>
switch signs the whole document. With this setting
you just assign the assertions of the document. you just assign the assertions of the document.
</para> </para>
</listitem> </listitem>
@ -98,7 +106,9 @@
<listitem> <listitem>
<para> <para>
Expect that documents coming from a client are signed. Keycloak will validate this signature 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. using the client keys set up in the
<literal>Application Keys</literal>
submenu item.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -106,8 +116,10 @@
<term>Force POST Binding</term> <term>Force POST Binding</term>
<listitem> <listitem>
<para> <para>
By default, Keycloak will respond using the initial SAML binding of the original request. By turning By default, Keycloak will respond using the initial SAML binding of the original request. By
on this switch, you will force Keycloak to always respond using the SAML POST Binding even if the 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. original request was the Redirect binding.
</para> </para>
</listitem> </listitem>
@ -116,9 +128,12 @@
<term>Front Channel Logout</term> <term>Front Channel Logout</term>
<listitem> <listitem>
<para> <para>
If true, this application requires a browser redirect to be able to perform a logout. For example, If true, this application requires a browser redirect to be able to perform a logout. For
the application may require a cookie to be reset which could only be done by a done via a redirect. example,
If this switch is false, then Keycloak will invoke a background SAML request to logout the application. 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -126,7 +141,8 @@
<term>Force Name ID Format</term> <term>Force Name ID Format</term>
<listitem> <listitem>
<para> <para>
If the request has a name ID policy, ignore it and used the value configured in the admin console If the request has a name ID policy, ignore it and used the value configured in the admin
console
under Name ID Format under Name ID Format
</para> </para>
</listitem> </listitem>
@ -136,8 +152,107 @@
<listitem> <listitem>
<para> <para>
Name ID Format for the subject. If no name ID policy is specified in the request or if the 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. Force Name ID Format attribute is true, this value is used. Properties used for each of the
respective formats are defined below.
</para> </para>
<variablelist>
<varlistentry>
<term>username</term>
<listitem>
<para>
Format:
<literal>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</literal>
</para>
<para>
Source:
<literal>UserModel.userName</literal>
property
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>email</term>
<listitem>
<para>
Format:
<literal>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</literal>
</para>
<para>
Source:
<literal>UserModel.email</literal>
property
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>transient</term>
<listitem>
<para>
Format:
<literal>urn:oasis:names:tc:SAML:2.0:nameid-format:transient</literal>
</para>
<para>
Source:<literal>G-$randomUuid</literal>, I.E.
<literal>G-5ef5b38f-864f-41ad-82a0-04ade9139500</literal>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>persistent</term>
<listitem>
<para>
Format:
<literal>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</literal>
</para>
<para>
The persistent identifier will be evaluated in the following order. If one step
does not yield a value, processing will continue on to the next until a value is
found.
</para>
<variablelist>
<varlistentry>
<term>
1) saml.persistent.name.id.for.$clientId
<literal>UserModel</literal> attribute
</term>
<listitem>
<para>
identifier unique to this client/user pair.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
2) saml.persistent.name.id.for.*
<literal>UserModel</literal> attribute
</term>
<listitem>
<para>
user identifier for all clients, unless otherwise overridden by a
$clientId attribute.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
3) G-$randomUuid
</term>
<listitem>
<para>
I.E.<literal>G-5ef5b38f-864f-41ad-82a0-04ade9139500</literal>. If
neither a $clientId or wildcard user attribute is found, a persistent
identifier will be generated for the given client. Note that once this
identifier has been generated, a user attribute with the key
<emphasis>saml.persistent.name.id.for.$clientId</emphasis>
will be persisted and used on all subsequent requests against the given
client.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -146,7 +261,8 @@
<para> <para>
This URL will be used for all SAML requests and responsed directed to the SP. It will be used 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 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 contains the Assertion Consumer Service URL, that will take precedence, but this URL must be
valided
by a registered Valid Redirect URI pattern by a registered Valid Redirect URI pattern
</para> </para>
</listitem> </listitem>
@ -187,7 +303,8 @@
</para> </para>
<para> <para>
For login to work, Keycloak needs to be able to resolve the URL for the Assertion Consumer Service of the SP. If 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 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 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. specify the Assertion Consumer Service URL per binding.
</para> </para>
@ -204,24 +321,35 @@
<section> <section>
<title>SAML Entity Descriptor</title> <title>SAML Entity Descriptor</title>
<para> <para>
If you go into the admin console in the application list menu page you will see an <literal>Import</literal> If you go into the admin console in the application list menu page you will see an
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> <literal>Import</literal>
format described in SAML 2.0. You should review all the information there to make sure everything is set up correctly. 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>
<para> <para>
Each realm has a URL where you can view the XML entity descriptor for the IDP. <literal>root/auth/realms/{realm}/protocol/saml/descriptor</literal> Each realm has a URL where you can view the XML entity descriptor for the IDP.
<literal>root/auth/realms/{realm}/protocol/saml/descriptor</literal>
</para> </para>
</section> </section>
<section> <section>
<title>IDP Initiated Login</title> <title>IDP Initiated Login</title>
<para> <para>
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 IDP Initiated Login is a feature that where you can set up a URL on the Keycloak server that will log you
go to the client page in the admin console of the client you want to set this up for. Specify the <literal>IDP Initiated SSO URL Name</literal>. This is a simple string into a specific application/client. To set this up
with no whitespace in it. After this you can reference your client at the following URL: <literal>root/auth/realms/{realm}/protocol/saml/clients/{url-name}</literal> go to the client page in the admin console of the client you want to set this up for. Specify the<literal>
IDP Initiated SSO URL Name</literal>. This is a simple string
with no whitespace in it. After this you can reference your client at the following URL:
<literal>root/auth/realms/{realm}/protocol/saml/clients/{url-name}</literal>
</para> </para>
<para> <para>
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 If your client requires a special relay state, you can also configure this in the admin console.
<literal>RelayState</literal> query parameter, i.e. : <literal>root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate</literal> Alternatively, you can specify the relay state in a
<literal>RelayState</literal>
query parameter, i.e. :
<literal>root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate</literal>
</para> </para>
</section> </section>
</chapter> </chapter>