Merge pull request #2 from keycloak/master

sync to the latest changes

SUMMARY.adoc

@@ -1,9 +1,9 @@
 = {{book.title}}
 
  . link:topics/overview.adoc[Overview]
- .. link:topics/features.adoc[Features]
+ .. link:topics/overview/features.adoc[Features]
- .. link:topics/how.adoc[How Does Security Work?]
+ .. link:topics/overview/how.adoc[How Does Security Work?]
- .. link:topics/concepts.adoc[Core Concepts and Terms]
+ .. link:topics/overview/concepts.adoc[Core Concepts and Terms]
  . link:topics/initialization.adoc[Server Initialization]
  . link:topics/admin-console.adoc[Admin Console]
  .. link:topics/realms/master.adoc[The Master Realm]
@@ -50,7 +50,7 @@
  .. link:topics/roles/realm-client-roles.adoc[Realm and Client Roles]
  .. link:topics/roles/composite.adoc[Composite Roles]
  .. link:topics/roles/user-role-mappings.adoc[User Role Mappings]
- ... link:topics/roles/default-roles.adoc[Default Roles]
+ ... link:topics/roles/user-role-mappings/default-roles.adoc[Default Roles]
  .. link:topics/roles/client-scope.adoc[Client Scope]
  . link:topics/groups.adoc[Groups]
  .. link:topics/groups/groups-vs-roles.adoc[Groups Vs. Roles]
@@ -83,11 +83,24 @@
  .. link:topics/sessions/offline.adoc[Offline Access]
  . link:topics/user-federation.adoc[User Storage Federation]
  .. link:topics/user-federation/ldap.adoc[LDAP/AD Integration]
+ .. link:topics/user-federation/custom.adoc[Custom Providers]
  . link:topics/events.adoc[Auditing and Events]
+ .. link:topics/events/login.adoc[Login Events]
+ .. link:topics/events/admin.adoc[Admin Events]
  . link:topics/export-import.adoc[Export and Import]
  . link:topics/account.adoc[User Account Service]
- . link:topics/security-vulnerabilities.adoc[Security Vulnerabilities]
+ . link:topics/threat.adoc[Threat Model Mitigation]
+ .. link:topics/threat/brute-force.adoc[Password Guess, Brute Force Attacks]
+ .. link:topics/threat/clickjacking.adoc[Clickjacking]
+ .. link:topics/threat/ssl.adoc[SSL/HTTPS Requirement]
+ .. link:topics/threat/csrf.adoc[CSRF]
+ .. link:topics/threat/redirect.adoc[Unspecific Redirect URIs]
+ .. link:topics/threat/compromised-tokens.adoc[Compromised Access and Refresh tokens]
+ .. link:topics/threat/compromised-codes.adoc[Compromised Access Codes]
+ .. link:topics/threat/open-redirect.adoc[Open Redirectors]
+ .. link:topics/threat/password-db-compromised.adoc[Password database compromised]
+ .. link:topics/threat/scope.adoc[Limiting Scope]
+ .. link:topics/threat/sql.adoc[SQL Injection Attacks]
  . link:topics/MigrationFromOlderVersions.adoc[Migration from older versions]
- . link:topics/cors.adoc[CORS]
 
 

topics/MigrationFromOlderVersions.adoc

@@ -1,9 +1,9 @@
-= Migration from older versions
+== Migration from older versions
 
 To upgrade to a new version of Keycloak first download and install the new version of Keycloak.
 You then have to migrate the database, keycloak-server.json, providers, themes and applications from the old version. 
 
-== Migrate database
+=== Migrate database
 
 Keycloak provides automatic migration of the database.
 It's highly recommended that you backup your database prior to upgrading Keycloak. 
@@ -35,86 +35,86 @@ For MongoDB do the same, but for `connectionsMongo`:
 
 When you start the server with this setting your database will automatically be migrated if the database schema has changed in the new version. 
 
-== Migrate keycloak-server.json
+=== Migrate keycloak-server.json
 
 You should copy `standalone/configuration/keycloak-server.json` from the old version to make sure any configuration changes you've done are added to the new installation.
 The version specific section below will list any changes done to this file that you have to do when upgrading from one version to another. 
 
-== Migrate providers
+=== Migrate providers
 
 If you have implemented any SPI providers you need to copy them to the new server.
 The version specific section below will mention if any of the SPI's have changed.
 If they have you may have to update your code accordingly. 
 
-== Migrate themes
+=== Migrate themes
 
 If you have created a custom theme you need to copy them to the new server.
 The version specific section below will mention if changes have been made to themes.
 If there is you may have to update your themes accordingly. 
 
-== Migrate application
+=== Migrate application
 
 If you deploy applications directly to the Keycloak server you should copy them to the new server.
 For any applications including those not deployed directly to the Keycloak server you should upgrade the adapter.
 The version specific section below will mention if any changes are required to applications. 
 
-== Version specific migration
+=== Version specific migration
 
-=== Migrating to 1.9.0
+==== Migrating to 1.9.0
 
-==== Themes and providers directory moved
+===== Themes and providers directory moved
 
 We've moved the themes and providers directories from `standalone/configuration/themes` and `standalone/configuration/providers` to `themes` and `providers` respectively.
 If you have added custom themes and providers you need to move them to the new location.
 You also need to update `keycloak-server.json` as it's changed due to this. 
 
-==== Adapter Subsystems only bring in dependencies if keycloak is on
+===== Adapter Subsystems only bring in dependencies if keycloak is on
 
 Previously, if you had installed our saml or oidc keycloak subsystem adapters into Wildfly or JBoss EAP, we would automatically include Keycloak client jars into EVERY application irregardless if you were using Keycloak or not.
 These libraries are now only added to your deployment if you have keycloak authentication turned on for that adapter (via the subsystem, or auth-method in web.xml 
 
-==== Client Registration service endpoints moved
+===== Client Registration service endpoints moved
 
 The Client Registration service endpoints have been moved from `{realm}/clients` to `{realm}/clients-registrations`. 
 
-==== Session state parameter in authentication response renamed
+===== Session state parameter in authentication response renamed
 
 In the OpenID Connect authentication response we used to return the session state as `session-state` this is not correct according to the specification and has been renamed to `session_state`. 
 
-==== Deprecated OpenID Connect endpoints
+===== Deprecated OpenID Connect endpoints
 
 In 1.2 we deprecated a number of endpoints that where not consistent with the OpenID Connect specifications, these have now been removed.
 This also applies to the validate token endpoints that was replaced with the new introspect endpoint in 1.8. 
 
-==== Updates to theme templates
+===== Updates to theme templates
 
 Feedback in template.ftl has been moved and format has changed slightly. 
 
-==== Module and Source Code Re-org
+===== Module and Source Code Re-org
 
 Most of our modules and source code have been consolidated into two maven modules:  keycloak-server-spi and keycloak-services.
 SPI interfaces are in server-spi, implementations are in keycloak-services.
 All JPA dependent modules have been consolidated under keycloak-model-jpa.
 Same goes with mongo and infinispan under modules keycloak-model-mongo and keycloak-model-infinispan. 
 
-==== For adapters, session id changed after login
+===== For adapters, session id changed after login
 
 To plug a security attack vector, for platforms that support it (Tomcat 8, Undertow/Wildfly, Jetty 9), the keycloak oidc and saml adapters will change the session id after login.
 You can turn off this behavior check adapter config switches. 
 
-==== SAML SP Client Adapter Changes
+===== SAML SP Client Adapter Changes
 
 Keycloak SAML SP Client Adapter now requires a specific endpoint, `/saml` to be registered with your IDP. 
 
-=== Migrating to 1.8.0
+==== Migrating to 1.8.0
 
-==== Admin account
+===== Admin account
 
 In previous releases we shipped with a default admin user with a default password, this has now been removed.
 If you are doing a new installation of 1.8 you will have to create an admin user as a first step.
 This can be done easily by following the steps in <<_create_admin_user,Admin User>>. 
 
-==== OAuth2 Token Introspection
+===== OAuth2 Token Introspection
 
 In order to add more compliance with OAuth2 specification, we added a new endpoint for token introspection.
 The new endpoint can reached at `/realms/{realm}/protocols/openid-connect/token/introspect` and it is solely based on `RFC-7662.`                
@@ -126,9 +126,9 @@ The new token introspection URL can now be obtained from OpenID Connect Provider
 There you will find a claim with name `token_introspection_endpoint` within the response.
 Only `confidential clients` are allowed to invoke the new endpoint, where these clients will be usually acting as a resource server and looking for token metadata in order to perform local authorization checks. 
 
-=== Migrating to 1.7.0.CR1
+==== Migrating to 1.7.0.CR1
 
-==== Direct access grants disabled by default for clients
+===== Direct access grants disabled by default for clients
 
 In order to add more compliance with OpenID Connect specification, we added flags into admin console to Client Settings page, where you can enable/disable various kinds of OpenID Connect/OAuth2 flows (Standard flow, Implicit flow, Direct Access Grants, Service Accounts). As part of this, we have `Direct Access Grants` (corresponds to OAuth2 `Resource Owner Password Credentials Grant`) disabled by default for new clients. 
 
@@ -139,7 +139,7 @@ We also added builtin client `admin-cli` to each realm.
 This client has `Direct Access Grants` enabled.
 So if you're using Admin REST API or Keycloak admin-client, you should update your configuration to use `admin-cli` instead of `security-admin-console` as the latter one doesn't have direct access grants enabled anymore by default. 
 
-==== Option 'Update Profile On First Login' moved from Identity provider to Review Profile authenticator
+===== Option 'Update Profile On First Login' moved from Identity provider to Review Profile authenticator
 
 In this version, we added `First Broker Login`, which allows you to specify what exactly should be done when new user is logged through Identity provider (or Social provider), but there is no existing Keycloak user yet linked to the social account.
 As part of this work, we added option `First Login Flow` to identity providers where you can specify the flow and then you can configure this flow under `Authentication` tab in admin console. 
@@ -147,22 +147,22 @@ As part of this work, we added option `First Login Flow` to identity providers w
 We also removed the option `Update Profile On First Login` from the Identity provider settings and moved it to the configuration of `Review Profile` authenticator.
 So once you specify which flow should be used for your Identity provider (by default it's `First Broker Login` flow), you go to `Authentication` tab, select the flow and then you configure the option under `Review Profile` authenticator. 
 
-==== Element 'form-error-page' in web.xml not supported anymore
+===== Element 'form-error-page' in web.xml not supported anymore
 
 form-error-page in web.xml will no longer work for client adapter authentication errors.
 You must define an error-page for the various HTTP error codes.
 See documentation for more details if you want to catch and handle adapter error conditions. 
 
-==== IdentityProviderMapper changes
+===== IdentityProviderMapper changes
 
 There is no change in the interface itself or method signatures.
 However there is some change in behaviour.
 We added `First Broker Login` flow in this release and the method `IdentityProviderMapper.importNewUser` is now called after `First Broker Login` flow is finished.
 So if you want to have any attribute available in `Review Profile` page, you would need to use the method `preprocessFederatedIdentity` instead of `importNewUser` . You can set any attribute by invoke `BrokeredIdentityContext.setUserAttribute` and that will be available on `Review profile` page. 
 
-=== Migrating to 1.6.0.Final
+==== Migrating to 1.6.0.Final
 
-==== Option that refresh tokens are not reusable anymore
+===== Option that refresh tokens are not reusable anymore
 
 Old versions of Keycloak allowed reusing refresh tokens multiple times.
 Keycloak still permits this, but also have an option `Revoke refresh token` to disallow it.
@@ -171,7 +171,7 @@ When a refresh token is used to obtain a new access token a new refresh token is
 When option is enabled, then this new refresh token should be used next time the access token is refreshed.
 It won't be possible to reuse old refresh token multiple times. 
 
-==== Some packages renamed
+===== Some packages renamed
 
 We did a bit of restructure and renamed some packages.
 It is mainly about renaming internal packages of util classes.
@@ -179,7 +179,7 @@ The most important classes used in your application ( for example AccessToken or
 However there is slight chance that you will be affected and will need to update imports of your classes.
 For example if you are using multitenancy and KeycloakConfigResolver, you will be affected as for example class HttpFacade was moved to different package - it is `org.keycloak.adapters.spi.HttpFacade` now. 
 
-==== Persisting user sessions
+===== Persisting user sessions
 
 We added support for offline tokens in this release, which means that we are persisting "offline" user sessions into database now.
 If you are not using offline tokens, nothing will be persisted for you, so you don't need to care about worse performance for more DB writes.
@@ -193,9 +193,9 @@ However in all cases, you will need to update `standalone/configuration/keycloak
 ----                    
 If you want sessions to be persisted in Mongo instead of classic RDBMS, use provider `mongo` instead. 
 
-=== Migrating to 1.5.0.Final
+==== Migrating to 1.5.0.Final
 
-==== Realm and User cache providers
+===== Realm and User cache providers
 
 Infinispan is now the default and only realm and user cache providers.
 In non-clustered mode a local Infinispan cache is used.
@@ -203,7 +203,7 @@ We've also removed our custom in-memory cache and the no cache providers.
 If you have realmCache or userCache set in keycloak-server.json to mem or none please remove these.
 As Infinispan is the only provider there's no longer any need for the realmCache and userCache objects so these can be removed. 
 
-==== Uses Session providers
+===== Uses Session providers
 
 Infinispan is now the default and only user session provider.
 In non-clustered mode a local Infinispan cache is used.
@@ -214,38 +214,38 @@ As Infinispan is the only provider there's no longer any need for the userSessio
 For anyone that wants to achieve increased durability of user sessions this can be achieved by configuring the user session cache with more than one owner or use a replicated cache.
 It's also possible to configure Infinispan to persist caches, although that would have impacts on performance. 
 
-==== Contact details removed from registration and account management
+===== Contact details removed from registration and account management
 
 In the default theme we have now removed the contact details from the registration page and account management.
 The admin console now lists all the users attributes, not just contact specific attributes.
 The admin console also has the ability to add/remove attributes to a user.
 If you want to add contact details, please refer to the address theme included in the examples. 
 
-=== Migrating to 1.3.0.Final
+==== Migrating to 1.3.0.Final
 
-==== Direct Grant API always enabled
+===== Direct Grant API always enabled
 
 In the past Direct Grant API (or Resource Owner Password Credentials) was disabled by default and there was an option on a realm to enable it.
 The Direct Grant API is now always enabled and the option to enable/disable for a realm is removed. 
 
-==== Database changed
+===== Database changed
 
 There are again few database changes.
 Remember to backup your database prior to upgrading. 
 
-==== UserFederationProvider changed
+===== UserFederationProvider changed
 
 There are few minor changes in UserFederationProvider interface.
 You may need to sync your implementation when upgrade to newer version and upgrade few methods, which has changed signature.
 Changes are really minor, but were needed to improve performance of federation. 
 
-==== WildFly 9.0.0.Final
+===== WildFly 9.0.0.Final
 
 Following on from the distribution changes that was done in the last release the standalone download of Keycloak is now based on WildFly 9.0.0.Final.
 This als affects the overlay which can only be deployed to WildFly 9.0.0.Final or JBoss EAP 6.4.0.GA.
 WildFly 8.2.0.Final is no longer supported for the server. 
 
-==== WildFly, JBoss EAP and JBoss AS7 adapters
+===== WildFly, JBoss EAP and JBoss AS7 adapters
 
 There are now 3 separate adapter downloads for WildFly, JBoss EAP and JBoss AS7: 
 
@@ -259,9 +259,9 @@ Make sure you grab the correct one.
 You also need to update standalone.xml as the extension module and subsystem definition has changed.
 See <<_jboss_adapter_installation,Adapter Installation>> for details. 
 
-=== Migrating from 1.2.0.Beta1 to 1.2.0.RC1
+==== Migrating from 1.2.0.Beta1 to 1.2.0.RC1
 
-==== Distribution changes
+===== Distribution changes
 
 Keycloak is now available in 3 downloads: standalone, overlay and demo bundle.
 The standalone is intended for production and non-JEE developers.
@@ -270,40 +270,40 @@ Finally we have a demo (or dev) bundle that is aimed at developers getting start
 This bundle contains a WildFly server, with Keycloak server and adapter included.
 It also contains all documentation and examples. 
 
-==== Database changed
+===== Database changed
 
 This release contains again a number of changes to the database.
 The biggest one is Application and OAuth client merge.
 Remember to backup your database prior to upgrading. 
 
-==== Application and OAuth client merge
+===== Application and OAuth client merge
 
 Application and OAuth clients are now merged into `Clients`.
 The UI of admin console is updated and database as well.
 Your data from database should be automatically updated.
 The previously set Applications will be converted into Clients with `Consent required` switch off and OAuth Clients will be converted into Clients with this switch on. 
 
-=== Migrating from 1.1.0.Final to 1.2.0.Beta1
+==== Migrating from 1.1.0.Final to 1.2.0.Beta1
 
-==== Database changed
+===== Database changed
 
 This release contains a number of changes to the database.
 Remember to backup your database prior to upgrading. 
 
-==== `iss` in access and id tokens
+===== `iss` in access and id tokens
 
 The value of `iss` claim in access and id tokens have changed from `realm name` to `realm url`.
 This is required by OpenID Connect specification.
 If you're using our adapters there's no change required, other than if you've been using bearer-only without specifying `auth-server-url` you have to add it now.
 If you're using another library (or RSATokenVerifier) you need to make the corresponding changes when verifying `iss`. 
 
-==== OpenID Connect endpoints
+===== OpenID Connect endpoints
 
 To comply with OpenID Connect specification the authentication and token endpoints have been changed to having a single authentication endpoint and a single token endpoint.
 As per-spec `response_type` and `grant_type` parameters are used to select the required flow.
 The old endpoints (`/realms/{realm}/protocols/openid-connect/login`, `/realms/{realm}/protocols/openid-connect/grants/access`, `/realms/{realm}/protocols/openid-connect/refresh`, `/realms/{realm}/protocols/openid-connect/access/codes)` are now deprecated and will be removed in a future version. 
 
-==== Theme changes
+===== Theme changes
 
 The layout of themes have changed.
 The directory hierarchy used to be `type/name` this is now changed to `name/type`.
@@ -314,7 +314,7 @@ If you deployed themes as a JAR in the past you had to create a custom theme loa
 This has been simplified to only requiring a plain text file (`META-INF/keycloak-themes.json`) to describe the themes included in a JAR.
 See the <<_themes,themes>> section in the docs for more information. 
 
-==== Claims changes
+===== Claims changes
 
 Previously there was `Claims` tab in admin console for application and OAuth clients.
 This was used to configure which attributes should go into access token for particular application/client.
@@ -323,7 +323,7 @@ This was removed and replaced with <<_mappers,Protocol mappers>>, which are more
 You don't need to care about migration of database from previous version.
 We did migration scripts for both RDBMS and Mongo, which should ensure that claims configured for particular application/client will be converted into corresponding protocol mappers (Still it's safer to backup DB before migrating to newer version though). Same applies for exported JSON representation from previous version. 
 
-==== Social migration to identity brokering
+===== Social migration to identity brokering
 
 We refactored social providers SPI and replaced it with <<_identity_broker,identity brokering SPI>>, which is more flexible.
 The `Social` tab in admin console is renamed to `Identity Provider` tab. 
@@ -336,13 +336,13 @@ You can first go to the Keycloak admin console and copy Redirect URI from the pa
 Then you can simply paste this as allowed Redirect URI to the admin console of 3rd party provider (IE.
 Facebook admin console). 
 
-=== Migrating from 1.1.0.Beta2 to 1.1.0.Final
+==== Migrating from 1.1.0.Beta2 to 1.1.0.Final
 
 * WEB-INF/lib
 +`standalone/configuration/providers`<<_providers,+providers>>
 
 
-=== Migrating from 1.1.0.Beta1 to 1.1.0.Beta2
+==== Migrating from 1.1.0.Beta1 to 1.1.0.Beta2
 
 * Adapters are now a separate download.  They are not included in appliance and war distribution.  We have too many now and the distro
   is getting bloated.
@@ -355,26 +355,26 @@ Facebook admin console).
   For AS7 only, the extension module name is org.keycloak.keycloak-as7-subsystem.
 * Server installation is no longer supported on AS7.  You can still use AS7 as an application client.
 
-=== Migrating from 1.0.x.Final to 1.1.0.Beta1
+==== Migrating from 1.0.x.Final to 1.1.0.Beta1
 
 * RealmModel JPA and Mongo storage schema has changed
 * UserSessionModel JPA and Mongo storage schema has changed as these interfaces have been refactored
 * Upgrade your adapters, old adapters are not compatible with Keycloak 1.1.  We interpreted JSON Web Token and OIDC ID Token specification incorrectly.  'aud'
   claim must be the client id, we were storing the realm name in there and validating it.
 
-=== Migrating from 1.0 RC-1 to RC-2
+==== Migrating from 1.0 RC-1 to RC-2
 
 * A lot of info level logging has been changed to debug. Also, a realm no longer has the jboss-logging audit listener by default.
   If you want log output when users login, logout, change passwords, etc. enable the jboss-logging audit listener through the admin console.
 
-=== Migrating from 1.0 Beta 4 to RC-1
+==== Migrating from 1.0 Beta 4 to RC-1
 
 * logout REST API has been refactored.  The GET request on the logout URI does not take a session_state
   parameter anymore.  You must be logged in in order to log out the session.
   You can also POST to the logout REST URI.  This action requires a valid refresh token to perform the logout.
   The signature is the same as refresh token minus the grant type form parameter.  See documentation for details.
 
-=== Migrating from 1.0 Beta 1 to Beta 4
+==== Migrating from 1.0 Beta 1 to Beta 4
 
 * LDAP/AD configuration is changed.  It is no longer under the "Settings" page.  It is now under
   Users->Federation.  Add Provider will show you an "ldap" option.
@@ -392,7 +392,7 @@ Facebook admin console).
 * Format of JSON file for importing realm data was changed. Now role mappings is available under the JSON record of particular
   user.
 
-=== Migrating from 1.0 Alpha 4 to Beta 1
+==== Migrating from 1.0 Alpha 4 to Beta 1
 
 * DB Schema has changed.  We have added export of the database to Beta 1, but not the ability to import
   the database from older versions. This will be supported in future releases.
@@ -405,7 +405,7 @@ Facebook admin console).
 * JavaScript adapter
 * Session Timeout
 
-=== Migrating from 1.0 Alpha 2 to Alpha 3
+==== Migrating from 1.0 Alpha 2 to Alpha 3
 
 * SkeletonKeyToken, SkeletonKeyScope, SkeletonKeyPrincipal, and SkeletonKeySession have been renamed to:
   AccessToken, AccessScope, KeycloakPrincipal, and KeycloakAuthenticatedSession respectively.
@@ -415,7 +415,7 @@ Facebook admin console).
   attempt to invoke a refresh on the auth server using a saved refresh token.
 * Subject in AccessToken has been changed to the User ID.
 
-=== Migrating from 1.0 Alpha 1 to Alpha 2
+==== Migrating from 1.0 Alpha 1 to Alpha 2
 
 * DB Schema has changed.  We don't have any data migration utilities yet as of Alpha 2.
 * JBoss and Wildfly adapters are now installed via a JBoss/Wildfly subsystem.  Please review the adapter

topics/authentication/kerberos.adoc

@@ -64,8 +64,8 @@ Keytab file `/tmp/http.keytab` will need to be accessible on the host where {{bo
 ==== Setup and configuration of {{book.project.name}} server
 
 You need to install a kerberos client on your machine.  This is also platform dependent.
-If you are on Fedora, Ubuntu or RHEL, you can install package `freeipa-client`, which contains Kerberos client and bunch of other stuff.
+If you are on Fedora, Ubuntu or RHEL, you can install the package `freeipa-client`, which contains a Kerberos client and bunch of other utilities.
-Configure kerberos client (on linux it's in file `/etc/krb5.conf` ). You need to put your Kerberos realm and at least configure the Http domains your server will be running on.
+Configure kerberos client (on linux it's in file `/etc/krb5.conf` ). You need to put your Kerberos realm and at least configure the HTTP domains your server will be running on.
 For the example realm MYDOMAIN.ORG you may configure `domain_realm` section like this: 
 
 [source]
@@ -77,33 +77,43 @@ For the example realm MYDOMAIN.ORG you may configure `domain_realm` section like
    
 Next you need to export the keytab file with the HTTP principal and make sure the file is accessible to the process under which {{book.project.name}} server is running.
 For production, it's ideal if it's readable just by this process and not by someone else.
-For MIT Kerberos example above, we already exported keytab to `/tmp/http.keytab` . If your KDC and {{book.project.name}} are running on same host, you have file already available.
+For MIT Kerberos example above, we already exported keytab to `/tmp/http.keytab` . If your KDC and {{book.project.name}} are running on same host,
+you have that file already available.
 
-Next you need to run the {{book.project.name}} server and configure SPNEGO/Kerberos authentication in {{book.project.name}} admin console.
+===== Enable SPNEGO Processing
-{{book.project.name}} supports Kerberos authentication through <<_user_federation,Federation provider SPI>> . We have 2 federation providers with Kerberos authentication support:
 
-Kerberos::
+{{book.project.name}} does not have SPNEGO protocol support turned on by default.  So, you have to go to the <<fake/../../authentication/flows.adoc#_authentication-flows, browser flow>>
-  This provider is useful if you want to authenticate with Kerberos `NOT` backed by aLDAP server.
+and enable `Kerberos`.
-  In this case, users are usually created in the {{book.project.name}} database after first successful SPNEGO/Kerberos login
-  and they may need to update profile after first login, as Kerberos protocol itself doesn't provision any data like first name, last name or email.
 
-LDAP::
+.browser flow
-  This provider is useful if you want to authenticate with Kerberos backed by LDAP server.
+image:../../{{book.images}}/browser-flow.png[]
-  In this case, data about users are provisioned from LDAP server after successful Kerberos authentication.
 
-Finally you may need to check the Kerberos authenticator correctly configured.
+Switch the `Kerbros` requirement from _disabled_ to either _alternative_ or _required_.  _Alternative_ basically means that Kerberos is optional.  If
-You can go to `Authentication` tab in admin console and select `Browser` flow.
+the user's browser hasn't been configured to work with SPNEGO/Kerberos, then {{book.project.name}} will fall back to the regular login screens.  If you set the requirement
-Here you will see `Kerberos` authenticator, which is used by {{book.project.name}} for SPNEGO handshake with client (exchange `Negotiate` header etc.).
+to _required_ then all users must have Kerberos enabled for their browser.
-By default it's disabled, so {{book.project.name}} doesn't ask for the Negotiate header, however once you configured federation provider in previous step,
-it's automatically switched to _alternative_.
-You should make sure that it is switched to _alternative_.
 
-image:../../{{book.images}}/kerberos-browser-flow.png[]
+===== Configure Kerberos User Storage Federation Provider
 
-_Alternative_ means that {{book.project.name}} tries to ask the browser for Negotiate header, but if it's not available,
+Now that the SPNEGO protocol is turned on at the authentication server, you'll need to configure how {{book.project.name}} interprets the Kerberos ticket.
-it will continue on to next authenticator (which usually means displaying username/password form to user).
+This is done through <fake/../../user-federation.adoc#_user-storage-federation,User Storage Federation>>. We have 2 different federation providers with Kerberos authentication support.
-You can switch the Kerberos authentication type to _required_ if you want to enforce login with kerberos ticket and not allow any fallback to the username/password form.
 
+If you want to authenticate with Kerberos backed by an LDAP server, you have to first configure the <<fake/../../user-federation/ldap.adoc#_ldap, LDAP Federation Provider>>.
+If you look at the configuration page for your LDAP provider you'll see a `Kerberos Integration` section.
+
+.LDAP Kerberos Integration
+image:../../{{book.images}}/ldap-kerberos.png[]
+
+Turning on the switch `Allow Kerberos authentication` will make {{book.project.name}} use the Kerberos principal to lookup information about the user so that it can
+be imported into the {{book.project.name}} environment.
+
+If your Kerberos solution is not backed by an LDAP server, you have to use the `Kerberos` User Storage Federation Provider.  Go to the `User Federation`
+left menu item and select `Kerberos` from the right `Add provider` select box.
+
+.Kerberos User Storage Provider
+image:../../{{book.images}}/kerberos-provider.png[]
+
+This provider simply parses the Kerberos ticket for principal information and does a small import into the local {{book.project.name}} database.
+User profile information like first name, last name, and email are not provisioned.  Just simple user principal information.
 
 ==== Setup and configuration of client machines
 

topics/authentication/password-policies.adoc

@@ -1,3 +1,4 @@
+[[_password-policies]]
 
 === Password Policies
 

topics/clients/client-oidc.adoc

@@ -85,7 +85,7 @@ 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
+them too general you are vulnerable to attacks.  See <<fake/../../threat/redirect.adoc#_unspecific-redirect-uris, Threat Model Mitigation>> chapter
 for more information.
 
 *Base URL*
@@ -113,13 +113,19 @@ See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more informa
 
 *Web Origins*
 
-This setting is related to browser Javascript making cross-domain XHR HTTP requests to your application.  It is central
+This option centers around link:http://www.w3.org/TR/cors/[CORS] which stands for Cross-Origin Resource Sharing.
-place to maintain a list
+If executing browser Javascript tries to make an AJAX HTTP request to a server whose domain is different than the one the
-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
+Javascript code came from, then the request uses the CORS.
-access token.  {{book.project.name}} specific client adapters can make use of this token information to decide whether to allow
+The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed.
-a CORS request to process.  See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
+This protocol exists to protect against XSS, CSRF and other Javascript-based attacks.
 
-Enter in a base URL and click the + sign to add.  Click the - sign next to URLs you want to remove.
+{{book.project.name}} has support for validated CORS requests.  The way it works is that the domains listed in the
+`Web Origins` setting for the client are embedded within the access token sent to the client application.  The client
+application can then use this information to decide whether or not to allow a CORS request to be invoked on it.  This is
+an extension to the OIDC protocol so only {{book.project.name}} client adapters support this feature.
+See link:{{book.adapterguide.link}}[{{book.adapterguide.name}}] for more information.
+
+To fill in the `Web Origins` data, 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-registration.adoc

@@ -24,7 +24,7 @@ The token can be a standard bearer token, a initial access token or a registrati
 ===== Bearer Token
 
 The bearertoken can be issued on behalf of a user or a Service Account.
-The following permissions are required to invoke the endpoints (see <<_admin_permissions,Admin Permissions>> for more details): 
+The following permissions are required to invoke the endpoints (see <<fake/../../admin-console-permissions.adoc#_admin_permissions,Admin Permissions>> for more details):
 
 * create-client
 +`manage-client`
@@ -32,7 +32,8 @@ The following permissions are required to invoke the endpoints (see <<_admin_per
 +`manage-client`
 * manage-client                
 
-If you are using a regular bearer token to create clients we recommend using a token from on behalf of a Service Account with only the `create-client` role. See the <<fake/../../clients/oidc/service-accounts.adoc#_service_accounts,Service Accounts>> section for more details.
+If you are using a regular bearer token to create clients we recommend using a token from on behalf of a Service Account with only the `create-client` role.
+See the <<fake/../../clients/oidc/service-accounts.adoc#_service_accounts,Service Accounts>> section for more details.
 
 ===== Initial Access Token
 

topics/clients/protocol-mappers.adoc

@@ -34,7 +34,7 @@ Consent::
 Consent Text::
   If your client requires consent and the `Consent` switch is on, this is the text that will be displayed by the user.
   The value for this text is localizable by specifying a substitution variable with `$\{var-name}}` strings.  The
-  localized value is then configured within property files in your theme.  See the link:{{book.developerguide.link}}[book.developerguide.name]
+  localized value is then configured within property files in your theme.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
   for more information on localization.
 
 Most OIDC mappers also allow you to control where the claim gets put.  You can opt to include or exclude the claim from both the
@@ -43,7 +43,7 @@ _id_ and _access_ tokens by fiddling with the `Add to ID token` and `Add to acce
 Finaly, you can also add other mapper types.  if you go back to the `Mappers` tab, click the `Create` button.
 
 .Add Mapper
-image:../../{{book.images}}/add-mapper[]
+image:../../{{book.images}}/add-mapper.png[]
 
 Pick a `Mapper Type` from the list box.  If you hover over the tooltip, you'll see a description of what that mapper type does.
 Different config parameters will appear for different mapper types.

topics/cors.adoc

@@ -1,47 +0,0 @@
-= CORS
-
-CORS stands for Cross-Origin Resource Sharing.
-If executing browser Javascript tries to make an AJAX HTTP request to a server's whose domain is different than the one the Javascript code came from, then the request uses the http://www.w3.org/TR/cors/[CORS protocol].
-The server must handle CORS requests in a special way, otherwise the browser will not display or allow the request to be processed.
-This protocol exists to protect against XSS and other Javascript-based attacks.
-Keycloak has support for validated CORS requests. 
-
-Keycloak's CORS support is configured per client.
-You specify the allowed origins in the client's configuration page in the admin console.
-You can add as many you want.
-The value must be what the browser would send as a value in the `Origin` header.
-For example `http://example.com`        is what you must specify to allow CORS requests from `example.com`.
-When an access token is created for the client, these allowed origins are embedded within the token.
-On authenticated CORS requests, your application's Keycloak adapter will handle the CORS protocol and validate the `Origin`        header against the allowed origins embedded in the token.
-If there is no match, then the request is denied. 
-
-To enable CORS processing in your application's server, you must set the `enable-cors` setting to `true` in your <<_adapter_config,adapter's configuration file>>.
-When this setting is enabled, the Keycloak adapter will handle all CORS preflight requests.
-It will validate authenticated requests (protected resource requests), but will let unauthenticated requests (unprotected resource requests) pass through. 
-
-== Handling CORS Yourself
-
-This section is for Java developers securing servlet-based applications using our servlet adapter. 
-
-If you don't like our CORS support you can handle it yourself in a filter or something.
-One problem you will encounter is that our adapter will may trigger for any CORS preflight OPTIONS requests to blindly secured URLs.
-This will result in 302 redirection or 401 responses for the preflight OPTIONS request.
-To workaround this problem, you must modify your web.xml security constraints to let OPTIONS requests through 
-[source]
-----
-
-<security-constraint>
-     <web-resource-collection>
-         <web-resource-name>wholesale</web-resource-name>
-         <url-pattern>/*</url-pattern>
-         <http-method>GET</http-method>
-         <http-method>POST</http-method>
-         <http-method>PUT</http-method>
-         <http-method>DELETE</http-method>
-     </web-resource-collection>
-...
-</security-constraint>
-----        
-
-The above security constraint will secure all URLs, but only on GET, POST, PUT, and DELETE calls.
-OPTIONS requests will be let through. 

topics/events.adoc

@@ -1,84 +1,7 @@
-= Auditing and Events
+== Auditing and Events
 
-Keycloak provides an Events SPI that makes it possible to register listeners for user related events, for example user logins.
+{{book.project.name}} provides a rich set of auditing capabilities.  Every single login action can be recorded and stored in
-There are two interfaces that can be implemented, the first is a pure listener, the second is a events store which listens for events, but is also required to store events.
+the database and reviewed in the Admin Console.  All admin actions can also be recorded and reviewed.  There is also a Listener SPI
-An events store provides a way for the admin and account management consoles to view events. 
+in which plugins can listen for these events and perform some action.  Built in ones include a simple log file and the ability
+to send an email if an event occurs.
 
-== Event types
-
-Login events: 
-
-* Login - A user has logged in
-* Register - A user has registered
-* Logout - A user has logged out
-* Code to Token - An application/client has exchanged a code for a token
-* Refresh Token - An application/client has refreshed a token        
-
-Account events: 
-
-* Social Link - An account has been linked to a social provider
-* Remove Social Link - A social provider has been removed from an account
-* Update Email - The email address for an account has changed
-* Update Profile - The profile for an account has changed
-* Send Password Reset - A password reset email has been sent
-* Update Password - The password for an account has changed
-* Update TOTP - The TOTP settings for an account has changed
-* Remove TOTP - TOTP has been removed from an account
-* Send Verify Email - A email verification email has been sent
-* Verify Email - The email address for an account has been verified        
-
-For all events there is a corresponding error event. 
-
-== Event Listener
-
-Keycloak comes with an Email Event Listener and a JBoss Logging Event Listener.
-The Email Event Listener sends an email to the users account when an event occurs.
-The JBoss Logging Event Listener writes to a log file when an events occurs. 
-
-The Email Event Listener only supports the following events at the moment: 
-
-* Login Error
-* Update Password
-* Update TOTP
-* Remove TOTP            
-
-You can exclude one or more events by editing `standalone/configuration/keycloak-server.json` and adding for example: 
-
-[source]
-----
-"eventsListener": {
-    "email": {
-        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
-    }
-}
-----        
-
-== Event Store
-
-Event Store listen for events and is expected to persist the events to make it possible to query for them later.
-This is used by the admin console and account management to view events.
-Keycloak includes providers to persist events to JPA and Mongo. 
-
-You can specify events to include or exclude by editing `standalone/configuration/keycloak-server.json`, and adding for example: 
-
-[source]
-----
-"eventsStore": {
-    "jpa": {
-        "exclude-events": [ "LOGIN", "REFRESH_TOKEN", "CODE_TO_TOKEN" ]
-    }
-}
-----        
-
-== Configure Events Settings for Realm
-
-To enable persisting of events for a realm you first need to make sure you have a event store provider registered for Keycloak.
-By default the JPA event store provider is registered.
-Once you've done that open the admin console, select the realm you're configuring, select `Events`.
-Then click on `Config`.
-You can enable storing events for your realm by toggling `Save Events` to ON.
-You can also set an expiration on events.
-This will periodically delete events from the database that are older than the specified time. 
-
-To configure listeners for a realm on the same page as above add one or more event listeners to the `Listeners` select box.
-This will allow you to enable any registered event listeners with the realm. 

topics/events/admin.adoc

@@ -0,0 +1,37 @@
+
+=== Admin Events
+
+Any action an admin performs within the admin console can be recorded for auditing purposes.
+The Admin Console performs administrative functions by invoking on the {{book.project.name}} REST interface.  {{book.project.name}}
+audits the admin APIs be storing these REST invocations.  These REST invocations can then be viewed in the Admin Console.
+
+To enable auditing of Admin actions, go to the `Events` left menu item and select the `Config` tab.
+
+.Event Configuration
+image:../../{{book.images}}/login-events-config.png[]
+
+In the `Admin Events Settings` section, turn on the `Save Events` switch.
+
+.Admin Event Configuration
+image:../../{{book.images}}/admin-events-settings.png[]
+
+The `Include Representation` switch will include any JSON document that is sent to the admin REST API when they are being
+invoked upon.  This allows you to view exactly what an admin has done, but can lead to a lot of information stored in the
+database.  The `Clear admin events` button allows you to wipe out the current information stored.
+
+To view the admin events go to the `Admin Events` tab.
+
+.Admin Events
+image:../../{{book.images}}/admin-events.png[]
+
+If the `Details` column has a `Representation` box, you can click on that to view the JSON that was sent with that operation.
+
+.Admin Representation
+image:../../{{book.images}}/admin-events-representation.png[]
+
+You can also filter for the events you are interested in by clicking the `Filter` button.
+
+.Admin Event Filter
+image:../../{{book.images}}/admin-events-filter.png[]
+
+

topics/events/login.adoc

@@ -0,0 +1,107 @@
+
+=== Login Events
+
+Login events occur for things like when a user logs in successfully, when somebody enters in a bad password, when a user account
+is updated.  Really every single event that happens to a user can be recorded and viewed.  By default, no events are stored
+or are viewable in the Admin Console.  Only error events are logged to the console and the server's log file.  To start
+persisting  you'll need to enable storage.  Go to the `Events` left menu item and select the `Config` tab.
+
+.Event Configuration
+image:../../{{book.images}}/login-events-config.png[]
+
+To start storing events you'll need to turn the `Save Events` switch to on under the `Login Events Settings`.
+
+.Save Events
+image:../../{{book.images}}/login-events-settings.png[]
+
+The `Saved Types` field allows you to specify which event types you want to store in the event store.  The `Clear events`
+button allows you to delete all the events in the database. The `Expiration` file allows you to specify how long you want
+to keep events stored for.  Once you've enabled storage of login events and decided on you settings, don't forget to click
+the `Save` button on the button of this page.
+
+To view events, go to the `Login Events` tab.
+
+.Login Events
+image:../../{{book.images}}/login-events.png[]
+
+As you can see, there's a lot of information stored and, if you are storing every event, there's a lot of events stored for
+each login action.  The `Filter` button on this page allows you to filter which events you are actually interested in.
+
+.Login Event Filter
+image:../../{{book.images}}/login-events-filter.png[]
+
+In this screenshot, we're filtering only `Login` events.  Clicking the `Update` button runs the filter.
+
+
+==== Event Types
+
+Login events:
+
+* Login - A user has logged in
+* Register - A user has registered
+* Logout - A user has logged out
+* Code to Token - An application/client has exchanged a code for a token
+* Refresh Token - An application/client has refreshed a token
+
+Account events:
+
+* Social Link - An account has been linked to a social provider
+* Remove Social Link - A social provider has been removed from an account
+* Update Email - The email address for an account has changed
+* Update Profile - The profile for an account has changed
+* Send Password Reset - A password reset email has been sent
+* Update Password - The password for an account has changed
+* Update TOTP - The TOTP settings for an account has changed
+* Remove TOTP - TOTP has been removed from an account
+* Send Verify Email - A email verification email has been sent
+* Verify Email - The email address for an account has been verified
+
+For all events there is a corresponding error event.
+
+==== Event Listener
+
+Event listeners listen for events and perform an action based on that event.  There are two built in
+ones that come with {{book.project.name}}: Logging Event Listener and an Email Event Listener.
+
+The Logging Event Listener writes to a log file whenever an error event occurs and is enabled by default.
+Here's an example log message:
+
+----
+11:36:09,965 WARN  [org.keycloak.events] (default task-51) type=LOGIN_ERROR, realmId=master,
+                    clientId=myapp,
+                    userId=19aeb848-96fc-44f6-b0a3-59a17570d374, ipAddress=127.0.0.1,
+                    error=invalid_user_credentials, auth_method=openid-connect, auth_type=code,
+                    redirect_uri=http://localhost:8180/myapp,
+                    code_id=b669da14-cdbb-41d0-b055-0810a0334607, username=admin
+----
+
+This logging is very useful if you want to use a tool like Fail2Ban to detect if there is a hacker bot somewhere that
+is trying to guess user passwords.  You can parse the log file for `LOGIN_ERROR` and pull out the IP Address, feed this information
+into Fail2Ban so that it do what it does to prevent attacks.
+
+The Email Event Listener sends an email to the users account when an event occurs.
+The Email Event Listener only supports the following events at the moment:
+
+* Login Error
+* Update Password
+* Update TOTP
+* Remove TOTP
+
+To enable the Email Listener go to the `Config` tab and click on the `Event Listeners` field.  This will show a drop down list box
+where you can select email.
+
+You can exclude one or more events by editing the `keycloak-server.json` that comes with your distribution and adding for example:
+
+[source]
+----
+"eventsListener": {
+    "email": {
+        "exclude-events": [ "UPDATE_TOTP", "REMOVE_TOTP" ]
+    }
+}
+----
+
+See the link:{{book.installguide.link}}[{{book.installguide.name}}] for more details on where the `keycloak-server.json` file lives.
+
+
+

topics/export-import.adoc

@@ -1,24 +1,27 @@
 [[_export_import]]
-= Export and Import
 
-== Startup export/import
+== Export and Import
 
-Export/import is useful especially if you want to migrate your whole Keycloak database from one environment to another or migrate to different database (For example from MySQL to Oracle). You can trigger export/import at startup of Keycloak server and it's configurable with System properties right now.
+{{book.project.name}} has the ability export and import the entire database.
-The fact it's done at server startup means that no-one can access Keycloak UI or REST endpoints and edit Keycloak database on the fly when export or import is in progress.
+This can be especially useful if you want to migrate your whole {{book.project.name}} database from one environment to another
-Otherwise it could lead to inconsistent results. 
+or migrate to different database (for example from MySQL to Oracle). Export and import
+is triggered at server boot time  and it's parameters are past in via Java System properties.
+Its important to note that because import and export happens at server startup, that no other actions should be taken on the server
+or the database while this happens.
 
 You can export/import your database either to: 
 
 * Directory on local filesystem
-* Single JSON file on your filesystem            When importing using the "dir" strategy, note that the files need to follow the naming convention specified below.
+* Single JSON file on your filesystem
+
+When importing using the directory strategy, note that the files need to follow the naming convention specified below.
 If you are importing files which were previously exported, the files already follow this convention. 
 
 * {REALM_NAME}-realm.json, such as "acme-roadrunner-affairs-realm.json" for the realm named "acme-roadrunner-affairs"
 * {REALM_NAME}-users-{INDEX}.json, such as "acme-roadrunner-affairs-users-0.json" for the first users file of the realm named "acme-roadrunner-affairs"        
 
-If you import to Directory, you can specify also the number of users to be stored in each JSON file.
+If you export to a directory, you can also specify the number of users that will be stored in each JSON file.
 So if you have very large amount of users in your database, you likely don't want to import them into single file as the file might be very big.
-Processing of each file is done in separate transaction as exporting/importing all users at once could also lead to memory issues. 
 
 To export into unencrypted directory you can use: 
 
@@ -54,7 +57,6 @@ Other available options are:
 -Dkeycloak.migration.usersExportStrategy::
   can be used to specify for Directory providers to specify where to import users.
   Possible values are:
-
   * DIFFERENT_FILES - Users will be exported into more different files according to maximum number of users per file. This is default value
   * SKIP - exporting of users will be skipped completely
   * REALM_FILE - All users will be exported to same file with realm (So file like "foo-realm.json" with both realm data and users)
@@ -68,7 +70,6 @@ Possible values are:
   is used during import.
   It can be used to specify how to proceed if realm with same name already exists in the database where you are going to import data.
   Possible values are:
-
   * IGNORE_EXISTING - Ignore importing if realm of this name already exists
   * OVERWRITE_EXISTING - Remove existing realm and import it again with new data from JSON file.
      If you want to fully migrate one environment to another and ensure that the new environment will contain same data
@@ -82,7 +83,7 @@ Examples:
 * -Dkeycloak.import=/tmp/realm1.json
 * -Dkeycloak.import=/tmp/realm1.json,/tmp/realm2.json        
 
-== Admin console export/import
+=== Admin console export/import
 
 Import of most resources can be performed from the admin console.
 Exporting resources will be supported in future versions. 

topics/groups/default-groups.adoc

@@ -2,7 +2,7 @@
 ==== Default Groups
 
 Default groups allow you to automatically assign group membership whenever any new user is created or imported through
-<<fake/../../../user-federation.adoc#_user-federation, User Federation>> or <<fake/../../../identity-broker.adoc_identity-broker, Identity Brokering>>.
+<<fake/../../user-federation.adoc#_user-storage-federation, User Storage Federation>> or <<fake/../../identity-broker.adoc#_identity-brokering, Identity Brokering>>.
 To specify _default groups go to the `Groups` left menu item, and click the `Default Groups` tab.
 
 .Default Roles

topics/overview/concepts.adoc

@@ -1,7 +1,7 @@
 
 === Core Concepts and Terms
 
-There are some key concepts and terms you should be aware of before attempting to use {{book.project.name} to secure your web applications
+There are some key concepts and terms you should be aware of before attempting to use {{book.project.name}} to secure your web applications
 and REST services.
 
 users::

topics/realms/master.adoc

@@ -10,5 +10,6 @@ It is recommended that you do not use the _master_ realm to manage the users and
 as a place for _super_ admins to create and manage the realms in your system.  This keeps things clean and organized.
 
 It is possible to disable the _master_ realm and define admin accounts at each individual new realm you create.  Each realm has its own
-dedicated Admin Console that you can log into with local accounts.  This guide talks more about this in the <<fake/../../managing-realms.adoc#_managing_realms, Managing Realms>>
+dedicated Admin Console that you can log into with local accounts.  This guide talks more about this in the
+<<fake/../../admin-console-permissions/per-realm.adoc#_per_realm_admin_permissions, Dedicated Realm Admin Consoles>>
 chapter.

topics/realms/ssl.adoc

@@ -1,3 +1,4 @@
+[[_ssl-mode]]
 
 === SSL Mode
 

topics/roles/realm-client-roles.adoc

@@ -12,8 +12,8 @@ and hit the `Save` button.
 .Add Role
 image:../../{{book.images}}/role.png[]
 
-The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}}` strings.
+The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}` strings.
-The localized value is then configured within property files in your theme.  See the link:{{book.developerguide.link}}[book.developerguide.name]
+The localized value is then configured within property files in your theme.  See the link:{{book.developerguide.link}}[{{book.developerguide.name}}]
 for more information on localization.  If a client requires user _consent_, this description string will be displayed on the
 consent page for the user.
 

topics/security-vulnerabilities.adoc

@@ -1,138 +0,0 @@
-== 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
-
-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.
-Without SSL/HTTPS, attackers can sniff your network and obtain an access token.
-Once they have an access token they can do any operation that the token has been given permission for. 
-
-Keycloak has <<_ssl_modes,three modes for SSL/HTTPS>>.
-SSL can be hard to set up, so out of the box, Keycloak allows non-HTTPS communication over private IP addresses like localhost, 192.168.x.x, and other private IP addresses.
-In production, you should make sure SSL is enabled and required across the board. 
-
-On the adapter/client side, Keycloak allows you to turn off the SSL trust manager.
-The trust manager ensures identity the client is talking to.
-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
-
-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. 
-
-OAuth 2.0 login specification requires that a state cookie be used and matched against a transmitted state parameter.
-Keycloak fully implements this part of the specification so all logins are protected. 
-
-The Keycloak adminstration console is a pure Javascript/HTML5 application that makes REST calls to the backend Keycloak admin API.
-These calls all require bearer token authentication and are made via Javascript Ajax calls.
-CSRF does not apply here.
-The admin REST API can also be configured to validate CORS origins as well. 
-
-The only part of Keycloak that really falls into CSRF is the user account management pages.
-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
-
-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.
-An attacker can steal a user's authentication credentials and access their resources. 
-
-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.
-
-[[_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.
-An access code can only be turned into an access token once so it can't be replayed.
-In the admin console you can specify how long an access token is valid for.
-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
-
-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.
-Short lifespans (minutes) for access tokens allows Keycloak to check the validity of a refresh token.
-Making sure refresh tokens always stay private to the client and are never transmitted ever is very important as well. 
-
-If an access token or refresh token is compromised, the first thing you should do is go to the admin console and push a not-before revocation policy to all applications.
-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
-
-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.
-An attacker could utilize a user's trust in an authorization server to launch a phishing attack. 
-
-Keycloak requires that all registered applications and clients register at least one redirection uri pattern.
-Any time a client asks Keycloak to perform a redirect (on login or logout for example), Keycloak will check the redirect uri vs.
-the list of valid registered uri patterns.
-It is important that clients and applications register as specific a URI pattern as possible to mitigate open redirector attacks. 
-
-== Password guess: brute force attacks
-
-A brute force attack happens when an attacker is trying to guess a user's password.
-Keycloak has some limited brute force detection capabilities.
-If turned on, a user account will be temporarily disabled if a threshold of login failures is reached.
-The downside of this is that this makes Keycloak vulnerable to denial of service attacks.
-Eventually we will expand this functionality to take client IP address into account when deciding whether to block a user. 
-
-Another thing you can do to prevent password guessing is to point a tool like http://fail2ban.org[Fail2Ban] to the Keycloak server's log file.
-Keycloak logs every login failure and client IP address that had the failure. 
-
-In the admin console, per realm, you can set up a password policy to enforce that users pick hard to guess passwords.
-A password has to match all policies.
-The password policies that can be configured are hash iterations, length, digits, lowercase, uppercase, special characters, not username, regex patterns, password history and force expired password update.
-Force expired password update policy forces or requires password updates after specified span of time.
-Password history policy  restricts a user from resetting his password to N old expired passwords.
-Multiple regex patterns can be specified.
-If there's more than one regex added, password has to match all fully.
-Increasing number of Hash Iterations (n) does not worsen anything (and certainly not the cipher) and it greatly increases the  resistance to dictionary attacks.
-However the drawback to increasing n is that it has some cost (CPU usage, energy, delay) for  the legitimate parties.
-Increasing n also slightly increases the odds that a random password gives the same result as the right  password due to hash collisions, and is thus a false but accepted password; however that remains very unlikely, in the order of  n*[1/(2^256)] for practical values of n, and can be entirely ignored in practice.
-Keycloak also uses PBKDF2 internally to  cryptographically derive passwords to refine and improve the ratio of cost between attacker and legitimate parties.
-Good practice is to pay attention to the time complexity of hash_password and hash; then increase n as much as tolerable in  the situation(s) at hand and and revise parameters such as n every few years to account for time complexity trade off. 
-
-Finally, the best way to mitigate against brute force attacks is to require user to set up a one-time-password (OTP). 
-
-== Password database compromised
-
-Keycloak does not store passwords in raw text.
-It stores a hash of them.
-Because of performance reasons, Keycloak only hashes passwords once.
-While a human could probably never crack a hashed password, it is very possible that a computer could.
-The security community suggests around 20,000 (yes thousand!) hashing iterations to be done to each password.
-This number grows every year due to increasing computing power (It was 1000 12 years ago). The problem with this is that password hashing is a huge performance hit as each login would require the entered password to be hashed that many times and compared to the stored hash.
-So, its up to the admin to configure the password hash iterations.
-This can be done in the admin console password policy configuration.
-Again, the default value is 1 as we thought it might be more important for Keycloak to scale out of the box.
-There's a lot of other measures admins can do to protect their password databases. 
-
-== SQL Injection attacks
-
-At this point in time, there is no knowledge of any SQL injection vulnerabilities in Keycloak 
-
-== Limiting Scope
-
-Using the `Scope` menu in the admin console for clients, you can control exactly which role mappings will be included within the token sent back to the client application.
-This allows you to limit the scope of permissions given to the client which is great if the client isn't very trusted and is known to not being very careful with its tokens. 

topics/threat.adoc

@@ -0,0 +1,8 @@
+== Threat Model Mitigation
+
+This chapter discusses possible security vulnerabilities any authentication server could have and how {{book.project.name}}
+mitigates those 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. 
+

topics/threat/brute-force.adoc

@@ -0,0 +1,35 @@
+
+=== Password guess: brute force attacks
+
+A brute force attack happens when an attacker is trying to guess a user's password.
+{{book.project.name}} has some limited brute force detection capabilities.
+If turned on, a user account will be temporarily disabled if a threshold of login failures is reached.
+To enable this feature go to the `Realm Settings` left menu item, click on the `Security Defenses` tab, then additional
+go to the `Brute Force Detection` sub-tab.
+
+.Brute Force Detection
+image:../../{{book.images}}/brute-force.png[]
+
+The way this works is that if there are `Max Login Failures` during a period of `Failure Reset Time`,
+the account is temporarily disabled for the `Wait Increment` multiplied by the number of failures over the max.  After
+`Failure Reset Time` is reached all failures are wiped clean.  The `Max Wait` is the maximum amount of time
+an account can be disabled for.  Another preventitive measure is that if there is subsequent login failures for one
+account that are too quick for a human to initiate the account will be disabled then.  This is controlled by the
+`Quick Login Check Milli Seconds` value.  So, if there are two login failures for the same account within that value,
+the account will be disabled for `Minimum Quick Login Wait`.
+
+The downside of {{book.project.name}} brute force detection is that the server becomes vulnerble to denial of service attacks.
+An attacker can simply try to guess passwords for as many accounts it knows and these account will be disabled.  Eventually
+Eventually we will expand this functionality to take client IP address into account when deciding whether to block a user.
+
+A better option might be a tool like http://fail2ban.org[Fail2Ban].  You can point this service at the {{book.project.name}} server's log file.
+{{book.project.name}} logs every login failure and client IP address that had the failure.  Fail2Ban can be used to modify
+firewalls after it detects an attack to block connections from specific IP addresses.
+
+==== Password Policies
+
+Another things you should do to prevent password guess is to have a complex enough password policy to ensure that
+users pick hard to guess passwords.  See the <<fake/../../authentication/password-policies.adoc#_password-policies, Password Policies>> chapter for more details.
+
+The best way to prevent password guessing though is to set up the server to use a one-time-password (OTP).
+

topics/threat/clickjacking.adoc

@@ -0,0 +1,19 @@
+
+=== 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 a "login" button) on the hidden page.
+An attacker can steal a user's authentication credentials and access their resources.
+
+By default, every response by {{book.project.name}} 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 the definition of both of these headers as there is a lot of fine-grain browser access you can control
+with these headers.
+In the admin console you can specify the values these headers will have.  Go to the `Realm Settings` left menu item and
+click the `Security Defenses` tab and make sure you are on the `Headers` sub-tab.
+
+image:../../{{book.images}}/security-headers.png[]
+
+By default, {{book.project.name}} only sets up a _same-origin_ policy for iframes.
+

topics/threat/compromised-codes.adoc

@@ -0,0 +1,9 @@
+
+=== Compromised Access Codes
+
+For the <<fake/../../sso-protocols/oidc.adoc#_oidc-auth-flows, OIDC Auth Code Flow>>, t would be very hard for an attacker to compromise {{book.project.name}} access codes.
+{{book.project.name}} generates a cryptographically strong random value for its access codes so it would be very hard to guess an access token.
+An access code can only be used once to obtain an access token.
+In the admin console you can specify how long an access token is valid for on the <<fake/../../sessions/timeouts.adoc#_timeouts, timeouts page>>.
+This value should be really short, as short as a few seconds and just long enough for the client to make the request to obtain a token from the code.
+

topics/threat/compromised-tokens.adoc

@@ -0,0 +1,18 @@
+
+=== Compromised Access and Refresh tokens
+
+There's a few things you can do to mitigate access tokens and refresh tokens from being stolen.
+The most important thing is to enforce SSL/HTTPS communication between {{book.project.name}} and its clients and applications.
+This might seem like a no-brainer, but since {{book.project.name}} does not have SSL enabled by default, many naive admins
+might not realize they have to do this.
+
+Another thing you can do to mitigate leaked access tokens is to shorten their lifespans.  You can specify this
+within the <<fake/../../sessions/timeouts.adoc#_timeouts, timeouts page>>.
+Short lifespans (minutes) for access tokens for clients and applications to refresh their access tokens after a short amount of time.
+If an admin detects a leak, they can logout all user sessions to invalidate these referesh tokens or set up a revocation policy.
+Making sure refresh tokens always stay private to the client and are never transmitted ever is very important as well.
+
+If an access token or refresh token is compromised, the first thing you should do is go to the admin console and push a not-before revocation policy to all applications.
+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.
+

topics/threat/csrf.adoc

@@ -0,0 +1,18 @@
+
+=== 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 with(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.
+
+OAuth 2.0 login specification requires that a state cookie be used and matched against a transmitted state parameter.
+{{book.project.name}} fully implements this part of the specification so all logins are protected.
+
+The {{book.project.name}} Adin Consnole is a pure Javascript/HTML5 application that makes REST calls to the backend {{book.project.name}} admin REST API.
+These calls all require bearer token authentication and are made via Javascript Ajax calls.
+CSRF does not apply here.
+The admin REST API can also be configured to validate the CORS origins as well.
+
+The only part of {{book.project.name}} that really falls into CSRF is the user account management pages.
+To mitigate this {{book.project.name}} 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.

topics/threat/open-redirect.adoc

@@ -0,0 +1,12 @@
+
+=== 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.
+An attacker could utilize a user's trust in an authorization server to launch a phishing attack.
+
+Keycloak requires that all registered applications and clients register at least one redirection uri pattern.
+Any time a client asks {{book.project.name}} to perform a redirect (on login or logout for example), {{book.project.name}} will check the redirect uri vs.
+the list of valid registered uri patterns.
+It is important that clients and applications register as specific a URI pattern as possible to mitigate open redirector attacks.
+

topics/threat/password-db-compromised.adoc

@@ -0,0 +1,9 @@
+
+=== Password database compromised
+
+{{book.project.name}} does not store passwords in raw text.
+It stores a hash of them using the PBKDF2 algorithm.  It actually uses
+a default of 20,000 hasing iterations!  This is the security community's recommended number of iterations.
+This can be a rather large performance hit on your system as PBKDF2, by design, gobbles up a significant amount of CPU.
+It is up to you to decide how serious you want to be to protect your password database.
+

topics/threat/redirect.adoc

@@ -0,0 +1,9 @@
+
+[[_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.
+

topics/threat/scope.adoc

@@ -0,0 +1,8 @@
+
+=== Limiting Scope
+
+By default, each new client applications has an unlimited scope.  This means that every access token that is created
+for that client will contain all the permissions the user has.  If the client gets compromised and the access token
+is leaked, then each system that the user has permission to access is now also compromised.  It is highly suggested
+that you limit the roles an access token is assigned by using the <<fake/../../roles/client-scope.adoc#_client-scope, Scope menu>> for each client.
+

topics/threat/sql.adoc

@@ -0,0 +1,5 @@
+
+=== SQL Injection Attacks
+
+At this point in time, there is no knowledge of any SQL injection vulnerabilities in {{book.project.name}}.
+

topics/threat/ssl.adoc

@@ -0,0 +1,19 @@
+
+=== SSL/HTTPS Requirement
+
+If you do not use SSL/HTTPS for all communication between the {{book.project.name}} 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.
+Without SSL/HTTPS, attackers can sniff your network and obtain an access token.
+Once they have an access token they can do any operation that the token has been given permission for.
+
+Keycloak has <<fake/../../realms/ssl.adoc#_ssl_modes,three modes for SSL/HTTPS>>.
+SSL can be hard to set up, so out of the box, {{book.project.name}} allows non-HTTPS communication over private IP addresses like
+localhost, 192.168.x.x, and other private IP addresses.
+In production, you should make sure SSL is enabled and required across the board.
+
+On the adapter/client side, {{book.project.name}} allows you to turn off the SSL trust manager.
+The trust manager ensures identity the client is talking to.
+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.
+

topics/user-federation.adoc

@@ -1,3 +1,4 @@
+[[_user-storage-federation]]
 
 == User Storage Federation
 
@@ -18,3 +19,13 @@ Some federation plugins may only import the username into {{book.project.name}}
 Some plugins might want to import credentials directly into {{book.project.name}} storage and let {{book.project.name}} handle credential validation.
 Others might want to handle credential validation themselves.
 The goal of the User Storage Federation SPI is to support all of these scenarios.
+
+=== Adding a Provider
+
+To add a storage provider go to the `User Federation` left menu item in the Admin Console.
+
+.User Federation
+image:../{{book.images}}/user-federation.png[]
+
+On the right side, there is a `Add Provider` list box.  Choose the provider you want to add and you will be brought to the configuration page of that provider.
+

topics/user-federation/custom.adoc

@@ -0,0 +1,6 @@
+
+=== Custom Providers
+
+{{book.project.name}} does have a private SPI for User Storage Federation that you can use to write your own custom providers.
+There is no commercial support for this yet.  You can find some documentation for this in our link:https://keycloak.gitbooks.io/server-developer-guide/content/[community documentation].
+This SPI is slated for a major rewrite before commercial support will be provided.

topics/user-federation/ldap.adoc

@@ -1,5 +1,6 @@
+[[_ldap]]
 
-=== LDAP and Active Directory Plugin
+=== LDAP and Active Directory
 
 {{book.project.name}} comes with a built-in LDAP/AD plugin.
 By default, it is set up only to import username, email, first and last name, but you are free to configure additional <<_ldap_mappers,mappers>>
@@ -7,13 +8,15 @@ and add more attributes or delete the default ones.
 It supports password validation via LDAP/AD protocols and different user metadata synchronization modes.
 To configure a federated LDAP store go to the Admin Console.
 Click on the `User Federation` left menu option.
-When you get to this page there is an "Add Provider" select box.
+When you get to this page there is an `Add Provider` select box.
 You should see _ldap_ within this list.
 Selecting _ldap_ will bring you to the ldap configuration page.
 
 ==== Edit Mode
 
-Edit mode defines various synchronization options with your LDAP store depending on what privileges you have. 
+Users, through the <<fake/../../account.adoc#_account-service, User Account Service, and admins through the Admin Console
+have the ability to modify user metadata.  Depending on your setup you may or may not have LDAP update privileges.  The
+`Edit Mode` configuration option defines the edit policy you have with your LDAP store.t privileges you have.
 
 READONLY::
   Username, email, first and last name and other mapped attributes will be unchangeable.
@@ -25,7 +28,8 @@ WRITABLE::
 
 UNSYNCED::
   Any changes to username, email, first and last name, and passwords will be stored in {{book.project.name}} local storage.
-  It is up to you to figure out how to synchronize back to LDAP.             
+  It is up to you to figure out how to synchronize back to LDAP. This allows {{book.project.name}} deployments to support
+  updates of user metadata on a read-only LDAP server.
 
 ==== Other config options
 
@@ -67,7 +71,7 @@ LDAP Federation Provider will automatically take care of synchronization (import
 As users log in, the LDAP Federation provider will import the LDAP user
 into then {{book.project.name}} database and then authenticate against the LDAP password. This is the only time users will be imported.
 If you go to the `Users` left menu item in the Admin Consoel and click the `View all users` button, you will only see those LDAP users that
-have been authenticated at least once by {{book.project.name}}.  It is implemented this way so that admins don't accidently try and import a huge LDAP DB of users.
+have been authenticated at least once by {{book.project.name}}.  It is implemented this way so that admins don't accidentally try and import a huge LDAP DB of users.
 
 If you want to sync all LDAP users into the {{book.project.name}} database, you may configure and enable the `Sync Settings` of the LDAP provider you configured.
 There are 2 types of sychronization:

topics/users/impersonation.adoc

@@ -23,5 +23,5 @@ in as the user being impersonated.  If the admin and user are not in the same re
 be logged in as the user in that user's realm.  In both cases, the browser will be redirected to the impersonated user's User Accoutn Management
 page.
 
-Any user with the realm's `impersonation` role can impersonate a user.  Please see the <<fake/../../admin-permissions.adoc#_admin-permissions,Admin Permissions>> chapter
+Any user with the realm's `impersonation` role can impersonate a user.  Please see the <<fake/../../admin-console-permissions.adoc#_admin_permissions,Admin Console Access Control>> chapter
 for more details on assigning administration permissions.

topics/users/required-actions.adoc

@@ -27,7 +27,7 @@ action name.  Also remember to click the `Save` button after you've decided what
 ==== Default Required Actions
 
 You can also specify required actions that will be added to an account whenever a new user is created, i.e. through the `Add User` button the user
-list screen, or via the <<fake/../../registration.adoc#_registration, user registration>> link on the login page.  To specify
+list screen, or via the <<fake/../../users/user-registration.adoc#_user-registration, user registration>> link on the login page.  To specify
 the default required actions go to the `Authentication` left menu item and click on the `Required Actions` tab.
 
 .Default Required Actions

topics/users/user-registration.adoc

@@ -1,3 +1,4 @@
+[[_user-registration]]
 
 === User Registration