clints

SUMMARY.adoc

@@ -34,20 +34,25 @@
  .. link:topics/sso-protocols/oidc.adoc[OpenID Connect]
  .. link:topics/sso-protocols/saml.adoc[SAML]
  .. link:topics/sso-protocols/saml-vs-oidc.adoc[OIDC vs. SAML]
+ . link:topics/clients.adoc[Managing Clients]
+ .. link:topics/clients/client-oidc.adoc[OIDC Clients]
+ .. link:topics/clients/client-saml.adoc[SAML Clients]
+ ... link:topics/clients/saml/idp-initiated-login.adoc[IDP Initiated Login]
+ ... link:topics/clients/saml/entity-descriptors.adoc[SAML Entity Descriptors]
+ .. link:topics/clients/client-link.adoc[Client Links]
+ .. link:topics/clients/client-registration.adoc[Client Registration]
+ .. link:topics/clients/service-accounts.adoc[Service Accounts]
+ .. link:topics/clients/protocol-mappers.adoc[Protocol Mappers]
  . link:topics/admin-permissions.adoc[Master Admin Access Control]
  . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
- . link:topics/client-registration.adoc[Client Registration]
  . link:topics/identity-broker.adoc[Identity Broker]
- . link:topics/access-types.adoc[Client Access Types]
  . link:topics/roles.adoc[Roles]
  . link:topics/groups.adoc[Groups]
- . link:topics/service-accounts.adoc[Service Accounts]
  . link:topics/cors.adoc[CORS]
  . link:topics/timeouts.adoc[Cookie settings, Session Timeouts, and Token Lifespans]
  . link:topics/events.adoc[Auditing and Events]
  . link:topics/ldap.adoc[LDAP/AD Integration]
  . link:topics/export-import.adoc[Export and Import]
- . link:topics/saml.adoc[SAML SSO]
  . link:topics/security-vulnerabilities.adoc[Security Vulnerabilities]
  . link:topics/protocol-mappers.adoc[OIDC Token and SAML Assertion Mappings]
  . link:topics/MigrationFromOlderVersions.adoc[Migration from older versions]

book.json

@@ -72,6 +72,10 @@
       "name": "Keycloak Installation and Configuration Guide",
       "link": "https://keycloak.gitbooks.io/server-install-guide/content/"
     },
+    "adapterguide": {
+      "name": "Securing Client Applications Guide",
+      "link": "https://keycloak.gitbooks.io/securing-client-applications-guide/content/"
+    },
     "project": {
       "name": "Keycloak",
       "version": "1.9.3.Final"

topics/access-types.adoc

@@ -1,21 +0,0 @@
-[[_access_types]]
-= Client Access Types
-
-When you create a Client in admin console you may be wondering what the "Access Types" are. 
-
-confidential::
-  Confidential access type is for clients that need to perform a browser login and that you want to require a client secret when they turn an access code into an access token, (see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details).  The advantages of this is that it is a little extra security.
-  Since Keycloak requires you to register valid redirect-uris, I'm not exactly sure what this little extra security is though.
-  :) The disadvantages of this access type is that confidential access type is pointless for pure Javascript clients as anybody could easily figure out your client's secret! 
-
-public::
-  Public access type is for clients that need to perform a browser login and that you feel that the added extra security of confidential access type is not needed.
-  FYI, Pure javascript clients are by nature public. 
-
-bearer-only::
-  Bearer-only access type means that the application only allows bearer token requests.
-  If this is turned on, this application cannot participate in browser logins. 
-
-direct access only::
-  You would also see a "Direct Access Only" switch when creating the Client.
-  This switch is for clients that only use the  <<_direct_access_grants,Direct Access Grant>>                        protocol to obtain access tokens.     

topics/clients.adoc

@@ -1,32 +1,15 @@
-= Clients
-:doctype: book
-:sectnums:
-:toc: left
-:icons: font
-:experimental:
-:sourcedir: .
 
-Keycloak provides support for managing Clients. 
+== Managing Clients
+
+Clients are entities that can request authentication of a user.  Clients come in two forms.
+he first type of client is an application that wants
+to participate in single-sign-on.  These clients just want {{book.project.name}} to provide security for them.  The other type
+of client is one that is requesting an access token so that it can invoke on other services on behalf of the authenticated user.
+This section discusses various aspects around configuring clients and various ways to do it.
+
+W
+
 
-== Client Config
 
-Keycloak supports flexible configuration of Clients. 
-
-=== Redirect Endpoint
-
-For scenarios where one wants to link from one client to another, Keycloak provides a special redirect endpoint: `/realms/realm_name/clients/client_id/redirect`. 
-
-If a client accesses this endpoint via an `HTTP GET` request, Keycloak returns the configured base URL for the provided Client and Realm in the form of an `HTTP 307` (Temporary Redirect) via the response's `Location` header. 
-
-Thus, a client only needs to know the Realm name and the Client ID in order to link to them.
-This indirection helps avoid hard-coding client base URLs. 
-
-As an example, given the realm `master` and the client-id `account`: 
-
-[source]
-----
-http://keycloak-host:keycloak-port/auth/realms/master/clients/account/redirect
-----               
-Would temporarily redirect to: http://keycloak-host:keycloak-port/auth/realms/master/account
 
 

topics/clients/client-link.adoc

@@ -0,0 +1,32 @@
+= Clients
+:doctype: book
+:sectnums:
+:toc: left
+:icons: font
+:experimental:
+:sourcedir: .
+
+Keycloak provides support for managing Clients. 
+
+== Client Config
+
+Keycloak supports flexible configuration of Clients. 
+
+=== Redirect Endpoint
+
+For scenarios where one wants to link from one client to another, Keycloak provides a special redirect endpoint: `/realms/realm_name/clients/client_id/redirect`. 
+
+If a client accesses this endpoint via an `HTTP GET` request, Keycloak returns the configured base URL for the provided Client and Realm in the form of an `HTTP 307` (Temporary Redirect) via the response's `Location` header. 
+
+Thus, a client only needs to know the Realm name and the Client ID in order to link to them.
+This indirection helps avoid hard-coding client base URLs. 
+
+As an example, given the realm `master` and the client-id `account`: 
+
+[source]
+----
+http://keycloak-host:keycloak-port/auth/realms/master/clients/account/redirect
+----               
+Would temporarily redirect to: http://keycloak-host:keycloak-port/auth/realms/master/account
+
+

topics/clients/client-oidc.adoc

@@ -0,0 +1,132 @@
+
+=== OIDC Clients
+
+<<fake/../../sso-protocols/oidc.adoc#_oidc,OpenID Connect>> is the preferred protocol to secure applications.  It was designed from the ground up to be web friendly
+and works best with HTML5/Javascript applications.
+
+To create a OIDC client go to the `Clients` left menu item.  On this page you'll see a `create` button on the right.
+
+.Clients
+image:../../{{book.images}}/clients.png[]
+
+This will bring you to the `Add Client` page.
+
+
+.Add Client
+image:../../{{book.images}}/add-client-oidc.png[]
+
+Enter in the `Client ID` of the client.  This should be a simple string
+alpha-numeric string that will be used in requests and in the {{book.project.name}} database to identity the client.
+Next select `openid-connect` in the `Client Protocol` drop down box.
+Ignore the `Client Template` listbox for now,
+we'll go over that later in this chapter.
+Finally enter in the base URL of your
+application in the `Root URL` field and click `Save`.  This will create the client and bring you to the client `Settings`
+tab.
+
+.Client Settings
+image:../../{{book.images}}/client-settings-oidc.png[]
+
+Let's walk through each configuration item on this page.
+
+*Client ID*
+
+This specifies an alpha-numeric string that will be used as the client identifier for OIDC requests.
+
+*Name*
+
+This is the display name for the client whenever it is displayed in a {{book.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:{{book.developerguide.link}}[{{book.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.  {{book.project.name}} provides the same functionality.
+
+*Access Type*
+
+This defines the type of the OIDC client.
+
+_confidential_::
+  Confidential access type is for clients that need to perform a browser login and that you want to require a client secret when they turn an access code into an access token,
+  (see http://tools.ietf.org/html/rfc6749#section-4.1.3[Access Token Request] in the OAuth 2.0 spec for more details).  The advantages of this is that it is a little extra security.
+  Since {{book.project.name}} requires you to register valid redirect-uris, we're not exactly sure what this little extra security is though.
+  :) The disadvantages of this access type is that confidential access type is pointless for pure Javascript clients as anybody could easily figure out your client's secret!
+
+_public_::
+  Public access type is for clients that need to perform a browser login and that you feel that the added extra security of confidential access type is not needed.
+  FYI, Pure javascript clients are by nature public.
+
+_bearer-only_::
+  Bearer-only access type means that the application only allows bearer token requests.
+  If this is turned on, this application cannot participate in browser logins.
+
+_dire*Root URL*
+
+     If {{book.project.name}} uses any configured relative URLs, this value is prepended to them.
+
+     *Valid Redirect URIs*
+
+     This is a required 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!
+     Only wildcards, * ,are allowed at the end of of a URI, i.e. http://host.com/*
+
+     You should take extra precautions when registering valid redirect URI patterns as if you make
+     them too general you are vulnerable to attacks.  See <<fake/../../security-vulnerabilities.adoc#_unspecific-redirect-uris, Security Vulnerabilities>> chapter
+     for more information.
+
+     *Base URL*
+
+     If {{book.project.name}} needs to link to the client, this URL would be used.
+
+ct access only_::
+  This switch is for clients that only use the  <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Direct Access Grant>> protocol to obtain access tokens.
+
+*Standard Flow Enabled*
+
+If this is on, clients are allowed to use the OIDC <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Authorization Code Flow>>.
+
+*Implicit Flow Enabled*
+
+If this is on, clients are allowed to use the OIDC <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Implicit Flow>>.
+
+*Direct Grants Enabled*
+
+If this is on, clients are allowed to use the OIDC <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows,Direct Grants>>.
+
+*Admin URL*
+
+For {{book.project.name}} specific client adapters, this is the callback endpoint for the client.  The {{book.project.name}}
+server will use this URI to make callbacks like pushing revocation policies, performing backchannel logout, and other
+administrative operations.  For {{book.project.name}} servlet adapters, this can be the root URL of the servlet application.
+See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
+
+*Web Origins*
+
+This setting is related to browser Javascript making cross-domain XHR HTTP requests to your application.  It is central
+place to maintain a list
+of domains that are allowed to make link:http://www.w3.org/TR/cors/[CORS] requests to your application.  This information is stuffed in the
+access token.  {{book.project.name}} specific client adapters can make use of this token information to decide whether to allow
+a CORS request to process.  See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
+
+Enter in a base URL 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!
+
+
+
+
+
+
+
+
+
+

topics/clients/client-saml.adoc

@@ -0,0 +1,125 @@
+
+=== SAML Clients
+
+{{book.project.name}} supports <<fake/../../sso-protocols/saml.adoc#_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:../../{{book.images}}/clients.png[]
+
+This will bring you to the `Add Client` page.
+
+
+.Add Client
+image:../../{{book.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.
+Ignore the `Client Template` listbox for now,
+we'll go over that later in this chapter.
+Finally enter in the `Client SAML Endpoint` URL.  Enter the
+URL you want the {{book.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.
+application in the `Root URL` field and click `Save`.  This will create the client and bring you to the client `Settings`
+tab.
+
+.Client Settings
+image:../../{{book.images}}/client-settings-saml.png[]
+
+
+
+Client ID::
+  This value must match the issuer value sent with AuthNRequests.
+  {{book.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 {{book.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:{{book.developerguide.link}}[{{book.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.  {{book.project.name}} provides the same functionality.
+
+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. 
+
+Sign Documents::
+  When turned on, Keycloak will sign the document using the realm's private key. 
+
+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.
+
+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.
+  {{book.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, {{book.project.name}} will respond using the initial SAML binding of the original request.
+  By turning on this switch, you will force {{book.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 by a done via a redirect.
+  If this switch is false, then {{book.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. 
+
+Root URL::
+  If {{book.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!
+  Only wildcards, * ,are allowed at the end of of a URI, i.e. http://host.com/*.  This field is used when the exact SAML
+  endpoints are not registered and {{book.project.name}} is pull the Assertion Consumer URL from the request.
+
+Base URL::
+  If {{book.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 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.     
+
+

topics/clients/protocol-mappers.adoc

@@ -6,7 +6,7 @@ Keycloak allows you to define what exactly is transferred.
 You can hardcode roles, claims and custom attributes.
 You can pull user metadata into a token or assertion.
 You can rename roles.
-Basicall you have a lot of control of what exactly goes back to the client. 
+Basically you have a lot of control of what exactly goes back to the client.
 
 Within the admin console, if you go to an application you've registered, you'll see a "Mappers" sub-menu item.
 This is the place where you can control how a OIDC ID Token, Access Token, and SAML login response assertions look like.

topics/clients/saml/entity-descriptors.adoc

@@ -0,0 +1,13 @@
+
+==== SAML Entity Descriptors
+
+Instead of manually registering a SAML 2.0 client, you can import it via a standard SAML Entity Descriptor XML file.
+There is an `Import` option on the Add Client page.
+
+.Add Client
+image:../../../{{book.images}}/add-client-saml.png[]
+
+Click the `Select File` button and load your entity descriptor file.  You should review all the information there to make sure everything is set up correctly.
+
+Some SAML client adapters like _mod-auth-mellon_ need the XML Entity Descriptor for the IDP.  You can obtain this by
+going to this public URL:  `root/auth/realms/{realm}/protocol/saml/descriptor`

topics/clients/saml/idp-initiated-login.adoc

@@ -0,0 +1,12 @@
+
+==== 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.
+In the `Settings` tab for your client, you need to 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 on the `Settings` tab in the `IDP Initiated SSO Relay State` field.
+Alternatively, browsers can specify the relay state in a `RelayState` query parameter, i.e.
+`root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate`.
+

topics/saml.adoc

@@ -1,114 +0,0 @@
-[[_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`        

topics/security-vulnerabilities.adoc

@@ -1,10 +1,10 @@
-= Security Vulnerabilities
+== Security Vulnerabilities
 
 This chapter discusses possible security vulnerabilities Keycloak could have, how Keycloak mitigates those vulnerabilities, and what steps you need to do to configure Keycloak to mitigate some vulnerabilities.
 A good list of potential vulnerabilities and what security implementations should do to mitigate them can be found in the http://tools.ietf.org/html/rfc6819[OAuth 2.0 Threat Model] document put out by the IETF.
 Many of those vulnerabilities are discussed here. 
 
-== SSL/HTTPS Requirement
+=== SSL/HTTPS Requirement
 
 If you do not use SSL/HTTPS for all communication between the Keycloak auth server and the clients it secures you will be very vulnerable to man in the middle attacks.
 OAuth 2.0/OpenID Connect uses access tokens for security.
@@ -21,7 +21,7 @@ It checks the DNS domain name against the server's certificate.
 In production you should make sure that each of your client adapters is configured to use a truststore.
 Otherwise you are vulnerable to DNS man in the middle attacks. 
 
-== CSRF Attacks
+=== CSRF Attacks
 
 Cross-site request forgery (CSRF) is a web-based attack whereby HTTP requests are transmitted from a user that the web site trusts or has authenticated (e.g., via HTTP redirects or HTML forms).  Any site that uses cookie based authentication is vulnerable for these types of attacks.
 These attacks are mitigated by matching a state cookie against a posted form or query parameter. 
@@ -38,7 +38,7 @@ The only part of Keycloak that really falls into CSRF is the user account manage
 To mitigate this Keycloak sets a state cookie and also embeds the value of this state cookie within hidden form fields or query parameters in action links.
 This query or form parameter is checked against the state cookie to verify that the call was made by the user. 
 
-== Clickjacking
+=== Clickjacking
 
 With clickjacking, a malicious site loads the target site in a transparent iFrame overlaid on top of a set of dummy buttons that are carefully constructed to be placed directly under important buttons on the target site.
 When a user clicks a visible button, they are actually clicking a button (such as an "Authorize" button) on the hidden page.
@@ -47,9 +47,17 @@ An attacker can steal a user's authentication credentials and access their resou
 By default, every response by Keycloak sets some specific browser headers that can prevent this from happening specifically http://tools.ietf.org/html/rfc7034[X-FRAME_OPTIONS] and http://www.w3.org/TR/CSP/[Content-Security-Policy].
 You should take a look at both of these headers.
 In the admin console you can specify the values these headers will have.
-By default, Keycloak only sets up a same-origin policy for iframes. 
+By default, Keycloak only sets up a same-origin policy for iframes.
 
-== Compromised Access Codes
+[[_unspecific-redirect-uris]]
+=== Unspecific Redirect URIs
+
+For the <<fake/../sso-protocols/oidc.adoc#_oidc-auth-flows,Authorization Code Flow>>, if you register redirect URIs that
+are too general, then it would be possible for a rogue client to impersonate a different client that has a broader scope
+of access.  This could happen for instance if two clients live under the same domain.  So, its a good idea to make your
+registered redirect URIs as specific as feasible.
+
+=== Compromised Access Codes
 
 It would be very hard for an attacker to compromise Keycloak access codes.
 Keycloak generates a cryptographically strong random value for its access codes so it would be very hard to guess an access token.
@@ -59,7 +67,7 @@ This value should be really short.
 Like a seconds.
 Just long enough for the client to make the request to turn the code into an token. 
 
-== Compromised access and refresh tokens
+=== Compromised access and refresh tokens
 
 There's a few things you can do to mitigate access tokens and refresh tokens from being stolen.
 Most importantly is to enforce SSL/HTTPS communication between Keycloak and its clients and applications.
@@ -70,7 +78,7 @@ If an access token or refresh token is compromised, the first thing you should d
 This will enforce that any tokens issued prior to that date are now invalid.
 You can also disable specific applications, clients, and users if you feel that any one of those entities is completely compromised. 
 
-== Open redirectors
+=== Open redirectors
 
 An attacker could use the end-user authorization endpoint and the redirect URI parameter to abuse the authorization server as an open redirector.
 An open redirector is an endpoint using a parameter to automatically redirect a user agent to the location specified by the parameter value without any validation.

topics/sso-protocols/oidc.adoc

@@ -1,3 +1,4 @@
+[[_oidc]]
 
 === Open ID Connect
 
@@ -19,6 +20,8 @@ is digitally signed by the realm.  The client can make REST invocations on remot
 extracts the _access token_, verifies the signature of the token, then decides based on access information within the token whether or not to process
 the request.
 
+[[_oidc-auth-flows]]
+
 ==== OIDC Auth Flows
 
 OIDC has different ways for a client or application to authenticate a user and receive an _identity_ and _access_ token.  Which

topics/sso-protocols/saml.adoc

@@ -1,3 +1,4 @@
+[[_saml]]
 
 === SAML