From 66cec589f715471279db8b86ced1efa52962f3a3 Mon Sep 17 00:00:00 2001 From: Josh Cain Date: Fri, 5 Feb 2016 11:18:02 -0600 Subject: [PATCH] add docbook info on how NameID is calculated --- .../reference/en/en-US/modules/saml.xml | 208 ++++++++++++++---- 1 file changed, 168 insertions(+), 40 deletions(-) diff --git a/docbook/auth-server-docs/reference/en/en-US/modules/saml.xml b/docbook/auth-server-docs/reference/en/en-US/modules/saml.xml index ded8f64794..d6c93fa864 100755 --- a/docbook/auth-server-docs/reference/en/en-US/modules/saml.xml +++ b/docbook/auth-server-docs/reference/en/en-US/modules/saml.xml @@ -18,16 +18,20 @@ 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 + 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: + 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: @@ -35,7 +39,7 @@ Client ID - This value must match the issuer value sent with AuthNRequests. Keycloak will pull the issuer + 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. @@ -45,7 +49,8 @@ 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. @@ -53,7 +58,8 @@ Multi-valued Roles - 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 multiple values within in. @@ -71,7 +77,9 @@ Sign Assertions - With the Sign Documents switch signs the whole document. With this setting + With the + Sign Documents + switch signs the whole document. With this setting you just assign the assertions of the document. @@ -88,7 +96,7 @@ Encrypt Assertions - Encrypt assertions in SAML documents with the realm's private key. The AES algorithm is used + Encrypt assertions in SAML documents with the realm's private key. The AES algorithm is used with a key size of 128 bits. @@ -97,8 +105,10 @@ 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. + 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. @@ -106,8 +116,10 @@ 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 + 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. @@ -116,9 +128,12 @@ 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. + 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. @@ -126,7 +141,8 @@ Force Name ID Format - 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 @@ -135,18 +151,118 @@ 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. + 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. + + + username + + + Format: + urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified + + + Source: + UserModel.userName + property + + + + + email + + + Format: + urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress + + + Source: + UserModel.email + property + + + + + transient + + + Format: + urn:oasis:names:tc:SAML:2.0:nameid-format:transient + + + Source:G-$randomUuid, I.E. + G-5ef5b38f-864f-41ad-82a0-04ade9139500 + + + + + persistent + + + Format: + urn:oasis:names:tc:SAML:2.0:nameid-format:persistent + + + 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. + + + + + 1) saml.persistent.name.id.for.$clientId + UserModel attribute + + + + identifier unique to this client/user pair. + + + + + + 2) saml.persistent.name.id.for.* + UserModel attribute + + + + user identifier for all clients, unless otherwise overridden by a + $clientId attribute. + + + + + + 3) G-$randomUuid + + + + I.E.G-5ef5b38f-864f-41ad-82a0-04ade9139500. 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 + saml.persistent.name.id.for.$clientId + will be persisted and used on all subsequent requests against the given + client. + + + + + + + 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 + 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 @@ -186,9 +302,10 @@ - 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 + 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. @@ -196,32 +313,43 @@ 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 + 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 Entity Descriptor - format described in SAML 2.0. You should review all the information there to make sure everything is set up correctly. + 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 + 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 + 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} + 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 + 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