Merge pull request #4 from stianst/master

Misc

SUMMARY.adoc

@@ -25,9 +25,12 @@
       ... link:topics/oidc/java/adapter_error_handling.adoc[Error Handling]
       ... link:topics/oidc/java/logout.adoc[Logout]
       ... link:topics/oidc/java/multi-tenancy.adoc[Multi Tenancy]
+      ... link:topics/oidc/java/application-clustering.adoc[Application Clustering]
 
    .. link:topics/oidc/javascript-adapter.adoc[JavaScript Adapter]
 
    .. link:topics/oidc/oidc-generic.adoc[Other OpenID Connect libraries]
 
  . link:topics/saml/saml-overview.adoc[SAML]
+
+ . link:topics/client-registration.adoc[Client Registration]

topics/client-registration.adoc

@@ -0,0 +1,157 @@
+== Client Registration
+
+In order for an application or service to utilize {{book.project.name}} it has to register a client in {{book.project.name}}.
+An admin can do this through the admin console (or admin REST endpoints), but clients can also register themselves through the {{book.project.name}} client
+registration service.
+
+The Client Registration Service provides built-in support for {{book.project.name}} Client Representations, OpenID Connect Client Meta Data and SAML Entity Descriptors.
+The Client Registration Service endpoint is `/realms/<realm>/clients-registrations/<provider>`.
+
+The built-in supported `providers` are: 
+
+* default - {{book.project.name}} Client Representation (JSON)
+* install - {{book.project.name}} Adapter Configuration (JSON)
+* openid-connect - OpenID Connect Client Metadata Description (JSON)
+* saml2-entity-descriptor - SAML Entity Descriptor (XML)
+
+The following sections will describe how to use the different providers. 
+
+=== Authentication
+
+To invoke the Client Registration Services you need a token. The token can be a bearer token, an initial access token or a registration access token.
+
+==== Bearer Token
+
+The bearer token can be issued on behalf of a user or a Service Account. The following permissions are required to invoke the endpoints (see link:{{book.adminguide.link}}[{{book.adminguide.name}}] for more details):
+
+* create-client or manage-client - To create clients
+* view-client or manage-client - To view clients
+* manage-client - To update or delete client
+
+If you are using a bearer token to create clients it's recommend to use a token from a Service Account with only the `create-client` role (see link:{{book.adminguide.link}}[{{book.adminguide.name}}] for more details).
+
+==== Initial Access Token
+
+The recommended approach to registering new clients is by using initial access tokens.
+An initial access token can only be used to create clients and has a configurable expiration as well as a configurable limit on how many clients can be created. 
+
+An initial access token can be created through the admin console.
+To create a new initial access token first select the realm in the admin console, then click on `Realm Settings` in the menu on the left, followed by `Initial Access Tokens` in the tabs displayed in the page. 
+
+You will now be able to see any existing initial access tokens. If you have access you can delete tokens that are no longer required. You can only retrieve the
+value of the token when you are creating it. To create a new token click on `Create`. You can now optionally add how long the token should be valid, also how
+many clients can be created using the token. After you click on `Save` the token value is displayed.
+
+It is important that you copy/paste this token now as you won't be able to retrieve it later. If you forget to copy/paste it, then delete the token and create another one.
+
+The token value is used as a standard bearer token when invoking the Client Registration Services, by adding it to the Authorization header in the request.
+For example: 
+
+[source]
+----
+Authorization: bearer eyJhbGciOiJSUz...
+----            
+
+==== Registration Access Token
+
+When you create a client through the Client Registration Service the response will include a registration access token.
+The registration access token provides access to retrieve the client configuration later, but also to update or delete the client.
+The registration access token is included with the request in the same way as a bearer token or initial access token.
+Registration access tokens are only valid once when it's used the response will include a new token. 
+
+If a client was created outside of the Client Registration Service it won't have a registration access token associated with it.
+You can create one through the admin console. This can also be useful if you loose the token for a particular client.
+To create a new token find the client in the admin console and click on `Credentials`. Then click on `Generate registration access token`.
+
+=== {{book.project.name}} Representations
+
+The `default` client registration provider can be used to create, retrieve, update and delete a client.
+It uses {{book.project.name}} Client Representation format which provides support for configuring clients exactly as they can be configured through the admin
+console, including for example configuring protocol mappers.
+
+To create a client create a Client Representation (JSON) then do a HTTP POST to `/realms/<realm>/clients-registrations/default`.
+
+It will return a Client Representation that also includes the registration access token.
+You should save the registration access token somewhere if you want to retrieve the config, update or delete the client later. 
+
+To retrieve the Client Representation then do a HTTP GET to `/realms/<realm>/clients-registrations/default/<client id>`.
+
+It will also return a new registration access token. 
+
+To update the Client Representation then do a HTTP PUT to with the updated Client Representation to:
+`/realms/<realm>/clients-registrations/default/<client id>`.
+
+It will also return a new registration access token. 
+
+To delete the Client Representation then do a HTTP DELETE to:
+`/realms/<realm>/clients-registrations/default/<client id>`
+
+=== {{book.project.name}} Adapter Configuration
+
+The `installation` client registration provider can be used to retrieve the adapter configuration for a client.
+In addition to token authentication you can also authenticate with client credentials using HTTP basic authentication.
+To do this include the following header in the request: 
+
+[source]
+----
+Authorization: basic BASE64(client-id + ':' + client-secret)
+----        
+
+To retrieve the Adapter Configuration then do a HTTP GET to `/realms/<realm>/clients-registrations/install/<client id>`.
+
+No authentication is required for public clients.
+This means that for the JavaScript adapter you can load the client configuration directly from {{book.project.name}} using the above URL.
+
+=== OpenID Connect Dynamic Client Registration
+
+{{book.project.name}} implements https://openid.net/specs/openid-connect-registration-1_0.html[OpenID Connect Dynamic Client Registration], which extends https://tools.ietf.org/html/rfc7591[OAuth 2.0 Dynamic Client Registration Protocol] and https://tools.ietf.org/html/rfc7592[OAuth 2.0 Dynamic Client Registration Management Protocol].
+
+The endpoint to use these specifications to register clients in {{book.project.name}} is `/realms/<realm>/clients-registrations/openid-connect[/<client id>]`.
+
+This endpoints can also be found in the OpenID Connect Discovery endpoint for the realm, `/realms/<realm>/.well-known/openid-configuration`.
+
+=== SAML Entity Descriptors
+
+The SAML Entity Descriptor endpoint only supports using SAML v2 Entity Descriptors to create clients.
+It doesn't support retrieving, updating or deleting clients.
+For those operations the {{book.project.name}} representation endpoints should be used.
+When creating a client a {{book.project.name}} Client Representation is returned with details about the created client, including a registration access token.
+
+To create a client do a HTTP POST with the SAML Entity Descriptor to `/realms/<realm>/clients-registrations/saml2-entity-descriptor`.
+
+=== Example using CURL
+
+The following example creates a client with the clientId `myclient` using CURL. You need to replace `eyJhbGciOiJSUz...` with a proper initial access token or
+bearer token.
+
+[source,bash]
+----
+curl -X POST \
+    -d '{ "clientId": "myclient" }' \
+    -H "Content-Type:application/json" \
+    -H "Authorization: bearer eyJhbGciOiJSUz..." \
+    http://localhost:8080/auth/realms/master/clients-registrations/default
+----
+
+=== Example using Java Client Registration API
+
+The Client Registration Java API makes it easy to use the Client Registration Service using Java.
+To use include the dependency `org.keycloak:keycloak-client-registration-api:>VERSION<` from Maven. 
+
+For full instructions on using the Client Registration refer to the JavaDocs.
+Below is an example of creating a client. You need to replace `eyJhbGciOiJSUz...` with a proper initial access token or bearer token.
+
+[source,java]
+----
+String token = "eyJhbGciOiJSUz...";
+
+ClientRepresentation client = new ClientRepresentation();
+client.setClientId(CLIENT_ID);
+
+ClientRegistration reg = ClientRegistration.create().url("http://localhost:8080/auth/realms/myrealm/clients").build();
+reg.auth(Auth.token(token));
+
+client = reg.create(client);
+
+String registrationAccessToken = client.getRegistrationAccessToken();
+----        

topics/oidc/java/application-clustering.adoc

@@ -0,0 +1,131 @@
+[[_applicationclustering]]
+= Application Clustering
+
+This chapter is focused on clustering support for your own AS7, EAP6 or Wildfly applications, which are secured by Keycloak.
+We support various deployment scenarios according if your application is: 
+
+* stateless or stateful 
+* distributable (replicated http session) or non-distributable and just relying on sticky sessions provided by loadbalancer 
+* deployed on same or different cluster hosts where keycloak servers are deployed     
+
+The situation is a bit tricky as application communicates with Keycloak directly within user's browser (for example redirecting to login screen), but there is also backend (out-of-bound) communication between keycloak and application, which is hidden from end-user and his browser and hence can't rely on sticky sessions. 
+
+NOTE: To enable distributable (replicated) HTTP Sessions in your application, you may need to do some additional steps.
+Usually you need to put tag into `WEB-INF/web.xml` file of your application and possibly do some additional steps to configure underlying cluster cache (In case of Wildfly, the implementation of cluster cache is based on Infinispan). These steps are server specific, so consult documentation of your application server for more details. 
+
+== Stateless token store
+
+By default, the servlet web application secured by Keycloak uses HTTP session to store information about authenticated user account.
+This means that this info could be replicated across cluster and your application will safely survive failover of some cluster node. 
+
+However if you don't need or don't want to use HTTP Session, you may alternatively save all info about authenticated account into cookie.
+This is useful especially if your application is: 
+
+* stateless application without need of HTTP Session, but with requirement to be safe to failover of some cluster node 
+* stateful application, but you don't want sensitive token data to be saved in HTTP session 
+* stateless application relying on loadbalancer, which is not aware of sticky sessions (in this case cookie is your only way)         
+
+To configure this, you can add this line to configuration of your adapter in `WEB-INF/keycloak.json` of your application: 
+[source]
+----
+
+
+"token-store": "cookie"
+----        
+
+Default value of `token-store` is `session`, hence saving data in HTTP session. 
+
+One limitation of cookie store is, that whole info about account is passed in cookie KEYCLOAK_ADAPTER_STATE in each HTTP request.
+Hence it's not the best for network performance.
+Another small limitation is limited support for Single-Sign out.
+It works without issues if you init servlet logout (HttpServletRequest.logout) from this application itself as the adapter will delete the KEYCLOAK_ADAPTER_STATE cookie.
+But back-channel logout initialized from different application can't be propagated by Keycloak to this application with cookie store.
+Hence it's recommended to use very short value of access token timeout (1 minute for example). 
+
+== Relative URI optimization
+
+In many deployment scenarios will be Keycloak and secured applications deployed on same cluster hosts.
+For this case Keycloak already provides option to use relative URI as value of option _auth-server-url_ in `WEB-INF/keycloak.json` . In this case, the URI of Keycloak server is resolved from the URI of current request. 
+
+For example if your loadbalancer is on _https://loadbalancer.com/myapp_ and auth-server-url is _/auth_, then relative URI of Keycloak is resolved to be  _https://loadbalancer.com/auth_ . 
+
+For cluster setup, it may be even better to use option _auth-server-url-for-backend-request_ . This allows to configure that backend requests between Keycloak and your application will be sent directly to same cluster host without additional round-trip through loadbalancer.
+So for this, it's good to configure values in `WEB-INF/keycloak.json` like this: 
+[source]
+----
+
+
+"auth-server-url": "/auth",
+"auth-server-url-for-backend-requests": "http://${jboss.host.name}:8080/auth"
+----        
+
+This would mean that browser requests (like redirecting to Keycloak login screen) will be still resolved relatively to current request URI like _https://loadbalancer.com/myapp_, but backend (out-of-bound) requests between keycloak and your app are sent always to same cluster host with application . 
+
+Note that additionally to network optimization, you may not need "https" in this case as application and keycloak are communicating directly within same cluster host. 
+
+== Admin URL configuration
+
+Admin URL for particular application can be configured in Keycloak admin console.
+It's used by Keycloak server to send backend requests to application for various tasks, like logout users or push revocation policies. 
+
+For example logout of user from Keycloak works like this: 
+
+. User sends logout request from one of applications where he is logged. 
+. Then application will send logout request to Keycloak 
+. Keycloak server logout user in itself, and then it re-sends logout request by backend channel to all applications where user is logged.
+  Keycloak is using admin URL for this.
+  So logout is propagated to all apps.             
+
+You may again use relative values for admin URL, but in cluster it may not be the best similarly like in <<_relative_uri_optimization,previous section>> . 
+
+Some examples of possible values of admin URL are: 
+
+http://${jboss.host.name}:8080/myapp::
+  This is best choice if "myapp" is deployed on same cluster hosts like Keycloak and is distributable.
+  In this case Keycloak server sends logout request to itself, hence no communication with loadbalancer or other cluster nodes and no additional network traffic. 
+
+http://${application.session.host}:8080/myapp::
+  Keycloak will track hosts where is particular HTTP Session served and it will send session invalidation message to proper cluster node.             
+
+[[_registration_app_nodes]]
+== Registration of application nodes to Keycloak
+
+Previous section describes how can Keycloak send logout request to proper application node.
+However in some cases admin may want to propagate admin tasks to all registered cluster nodes, not just one of them.
+For example push new notBefore for realm or application, or logout all users from all applications on all cluster nodes. 
+
+In this case Keycloak should be aware of all application cluster nodes, so it could send event to all of them.
+To achieve this, we support auto-discovery mechanism: 
+
+. Once new application node joins cluster, it sends registration request to Keycloak server 
+. The request may be re-sent to Keycloak in configured periodic intervals 
+. If Keycloak won't receive re-registration request within specified timeout (should be greater than period from point 2) then it automatically unregister particular node 
+. Node is also unregistered in Keycloak when it sends unregistration request, which is usually during node shutdown or application undeployment.
+  This may not work properly for forced shutdown when undeployment listeners are not invoked, so here you need to rely on automatic unregistration from point 3 .         
+
+Sending startup registrations and periodic re-registration is disabled by default, as it's main usecase is just cluster deployment.
+In `WEB-INF/keycloak.json` of your application, you can specify: 
+
+[source]
+----
+"register-node-at-startup": true,
+"register-node-period": 600,
+----                
+which means that registration is sent at startup (accurately when 1st request is served by the application node) and then it's resent each 10 minutes. 
+
+In Keycloak admin console you can specify the maximum node re-registration timeout (makes sense to have it bigger than _register-node-period_ from adapter configuration for particular application). Also you can manually add and remove cluster nodes in admin console, which is useful if you don't want to rely on adapter's automatic registration or if you want to remove stale application nodes, which weren't unregistered (for example due to forced shutdown). 
+
+[[_refresh_token_each_req]]
+== Refresh token in each request
+
+By default, application adapter tries to refresh access token when it's expired (period can be specified as <<_token_timeouts,Access Token Lifespan>>) . However if you don't want to rely on the fact, that Keycloak is able to successfully propagate admin events like logout to your application nodes, then you have possibility to configure adapter to refresh access token in each HTTP request. 
+
+In `WEB-INF/keycloak.json` you can configure: 
+
+[source]
+----
+"always-refresh-token": true
+----        
+
+Note that this has big performance impact.
+It's useful just if performance is not priority, but security is critical and you can't rely on logout and push notBefore propagation from Keycloak to applications. 

topics/oidc/java/java-adapter-config.adoc

@@ -2,11 +2,10 @@
 [[_java_adapter_config]]
 === Java Adapter Config
 
-Each adapter supported by Keycloak can be configured by a simple JSON text file.
+Each Java adapter supported by Keycloak can be configured by a simple JSON file.
 This is what one might look like:
 
-
+[source,json]
-[source]
 ----
 {
   "realm" : "demo",
@@ -36,55 +35,48 @@ This is what one might look like:
 }
 ----
 
-Some of these configuration switches may be adapter specific and some are common across all adapters.
+You can use `${...}` enclosure for system property replacement. For example `${jboss.server.config.dir}` would be replaced by `/path/to/{{book.project.name}}`.
-For Java adapters you can use `${...}` enclosure as System property replacement.
-For example `${jboss.server.config.dir}`.
-Also, you can obtain a template for this config file from the admin console.
-Go to the realm and select the application you want a template for.
-Go to the `Installation` tab and this will provide you with a template that includes the public key of the realm.
-
-Here is a description of each item:
 
+The initial config file can be ontained from the the admin console. This can be done by opening the admin console, select `Clients` from the menu and clicking
+on the corresponding client. Once the page for the client is opened click on the `Installation` tab and select `Keycloak OIDC JSON`.
 
+Here is a description of each configuration option:
 
 realm::
   Name of the realm representing the users of your distributed applications and services.
   This is _REQUIRED._
 
 resource::
-  Username of the application.
+  The client-id of the application. Each application has a client-id that is used to identify the application.
-  Each application has a username that is used when the application connects with the Keycloak server to turn an access code into an access token (part of the OAuth 2.0 protocol). This is _REQUIRED._
-
-realm-public-key::
-  PEM format of public key.
-  You can obtain this from the administration console.
   This is _REQUIRED._
 
+realm-public-key::
+  PEM format of the realm public key. You can obtain this from the administration console.
+  This is OPTION._
+
 auth-server-url::
-  The base URL of the Keycloak Server.
+  The base URL of the {{book.project.name}} server. All other {{book.project.name}} pages and REST service endpoints are derived from this. It is usually of the form `https://host:port/auth`.
-  All other Keycloak pages and REST services are derived from this.
+  This is _REQUIRED._
-  It is usually of the form `https://host:port/auth`                        This is _REQUIRED._
 
 ssl-required::
-  Ensures that all communication to and from the Keycloak server from the adapter is over HTTPS.
+  Ensures that all communication to and from the {{book.project.name}} server is over HTTPS.
+  In production this should be set to `all`.
   This is _OPTIONAL_.
   The default value is _external_ meaning that HTTPS is required by default for external requests.
   Valid values are 'all', 'external' and 'none'.
 
 use-resource-role-mappings::
-  If set to true, the adapter will look inside the token for application level role mappings for the user.
+  If set to true, the adapter will look inside the token for application level role mappings for the user. If false, it will look at the realm level for user role mappings.
-  If false, it will look at the realm level for user role mappings.
   This is _OPTIONAL_.
   The default value is _false_.
 
 public-client::
   If set to true, the adapter will not send credentials for the client to Keycloak.
+  This is _OPTIONAL_.
   The default value is _false_.
 
 enable-cors::
-  This enables CORS support.
+  This enables CORS support. It will handle CORS preflight requests. It will also look into the access token to determine valid origins.
-  It will handle CORS preflight requests.
-  It will also look into the access token to determine valid origins.
   This is _OPTIONAL_.
   The default value is _false_.
 
@@ -106,14 +98,12 @@ cors-allowed-headers::
   If not set, this header is not returned in CORS responses.
 
 bearer-only::
-  This tells the adapter to only do bearer token authentication.
+  This should be set to _true_ for services. If enabled the adapter will not attempt to authenticate users, but only verify bearer tokens.
-  That is, it will not do OAuth 2.0 redirects, but only accept bearer tokens through the `Authorization`                        header.
   This is _OPTIONAL_.
   The default value is _false_.
 
 enable-basic-auth::
-  This tells the adapter to also support basic authentication.
+  This tells the adapter to also support basic authentication. If this option is enabled, then _secret_ must also be provided.
-  If this option is enabled, then _secret_ must also be provided.
   This is _OPTIONAL_.
   The default value is _false_.
 
@@ -123,9 +113,8 @@ expose-token::
   The default value is _false_.
 
 credentials::
-  Specify the credentials of the application.
+  Specify the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type.
-  This is an object notation where the key is the credential type and the value is the value of the credential type.
+  Currently `password` and `jwt` is supported.
-  Currently only `password`                        is supported.
   This is _REQUIRED_.
 
 connection-pool-size::
@@ -135,22 +124,22 @@ connection-pool-size::
   The default value is `20`.
 
 disable-trust-manager::
-  If the Keycloak Server requires HTTPS and this config option is set to `true`                        you do not have to specify a truststore.
+  If the {{book.project.name}} server requires HTTPS and this config option is set to `true` you do not have to specify a truststore.
-  While convenient,  this setting is not recommended as you will not be verifying the host name of the Keycloak Server.
+  This setting should only be used during development and *never* in production as it will disable verification of SSL certificates.
   This is _OPTIONAL_.
   The default value is `false`.
 
 allow-any-hostname::
-  If the Keycloak Server requires HTTPS and this config option is set to `true`                        the Keycloak Server's certificate is validated via the truststore, but host name validation is not done.
+  If the {{book.project.name}} server requires HTTPS and this config option is set to `true` the Keycloak Server's certificate is validated via the truststore,
-  This is not a recommended.
+  but host name validation is not done.
+  This setting should only be used during development and *never* in production as it will disable verification of SSL certificates.
   This seting may be useful in test environments This is _OPTIONAL_.
   The default value is `false`.
 
 truststore::
-  This setting is for Java adapters.
+  The value is the file path to a keystore file.
-  The value is the file path to a Java keystore file.
   If you prefix the path with `classpath:`, then the truststore will be obtained from the deployment's classpath instead.
-  Used for outgoing HTTPS communications to the Keycloak server.
+  Used for outgoing HTTPS communications to the {{book.project.name}} server.
   Client making HTTPS requests need a way to verify the host of the server they are talking to.
   This is what the trustore does.
   The keystore contains one or more trusted host certificates or certificate authorities.
@@ -159,45 +148,39 @@ truststore::
 
 truststore-password::
   Password for the truststore keystore.
-  This is _REQUIRED_                        if `truststore`                        is set.
+  This is _REQUIRED_ if `truststore` is set and the truststore requires a password.
 
 client-keystore::
-  _Not supported yet, but we will support in future versions._                        This setting is for Java adapters.
+  This is the file path to a keystore file.
-  This is the file path to a Java keystore file.
+  This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the {{book.project.name}} server.
-  This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the Keycloak server.
   This is _OPTIONAL_.
 
 client-keystore-password::
-  _Not supported yet, but we will support in future versions._                        Password for the client keystore.
+  Password for the client keystore.
   This is _REQUIRED_ if `client-keystore` is set.
 
 client-key-password::
-  _Not supported yet, but we will support in future versions._                        Password for the client's key.
+  Password for the client's key.
   This is _REQUIRED_ if `client-keystore` is set.
 
-auth-server-url-for-backend-requests::
-  Alternative location of auth-server-url used just for backend requests.
-  It must be absolute URI.
-  Useful especially in cluster (see <<_relative_uri_optimization,Relative URI Optimization>>) or if you would like to use _https_ for browser requests but stick with _http_ for backend requests etc.
-
 always-refresh-token::
-  If _true_, Keycloak will refresh token in every request.
+  If _true_, the adapter will refresh token in every request.
-  More info in <<_refresh_token_each_req,Refresh token in each request>> .
 
 register-node-at-startup::
   If _true_, then adapter will send registration request to Keycloak.
-  It's _false_                        by default and useful just in cluster (See <<_registration_app_nodes,Registration of application nodes to Keycloak>>)
+  It's _false_ by default and useful only when application is clustered.
+  See link:application-clustering.html[Application Clustering] for details
 
 register-node-period::
   Period for re-registration adapter to Keycloak.
-  Useful in cluster.
+  Useful when application is clustered.
-  See <<_registration_app_nodes,Registration of application nodes to Keycloak>> for details.
+  See link:application-clustering.html[Application Clustering] for details
 
 token-store::
   Possible values are _session_ and _cookie_.
   Default is _session_, which means that adapter stores account info in HTTP Session.
   Alternative _cookie_ means storage of info in cookie.
-  See <<_stateless_token_store,Stateless token store>> for details.
+  See link:application-clustering.html[Application Clustering] for details
 
 principal-attribute::
   OpenID Connection ID Token attribute to populate the UserPrincipal name with.
@@ -205,5 +188,5 @@ principal-attribute::
   Possible values are `sub`, `preferred_username`, `email`, `name`, `nickname`, `given_name`, `family_name`.
 
 turn-off-change-session-id-on-login::
-  The session id is changed by default on a successful login on some platforms to plug a security attack vector (Tomcat 8, Jetty9, Undertow/Wildfly).  Change this to true if you want to turn this off This is _OPTIONAL_.
+  The session id is changed by default on a successful login on some platforms to plug a security attack vector.  Change this to true if you want to turn this off This is _OPTIONAL_.
   The default value is _false_.

topics/oidc/java/java-adapters.adoc

@@ -1 +1,6 @@
 == Java Adapters
+
+{{book.project.name}} comes with a range of different adapters for Java application. Selecting the correct adapter depends on the target platform.
+
+All Java adapters share a set of common configuration options described in the link:java-adapter-config.html[Java Adapters Config] chapter. There are also
+a few more chapters that are relevant to all Java adapters.

topics/oidc/oidc-overview.adoc

@@ -1,8 +1,4 @@
 == OpenID Connect
 
-Keycloak can secure a wide variety of application types.
+This section describes how you can secure applications and services with OpenID Connect using either {{book.project.name}} adapters or generic OpenID Connect
-This section defines which application types are supported and how to configure and install them so that you can use Keycloak to secure your applications.
+Resource Provider libraries.
-
-These client adapters use an extension of the OpenID Connect protocol (a derivate of OAuth 2.0). This extension provides support for clustering, backchannel logout, and other non-standard adminstrative functions.
-The Keycloak project also provides a separate, standalone, generic, SAML client adapter.
-But that is describe in a separate document and has a different download.

topics/overview/supported-protocols.adoc

@@ -1,2 +1,58 @@
 [[_supported_protocols]]
 == Supported Protocols
+
+=== OpenID Connect
+
+link:http://openid.net/connect/[Open ID Connect] (OIDC) is an authentication protocol that is an extension of link:https://tools.ietf.org/html/rfc6749[OAuth 2.0].
+While OAuth 2.0 is only a framework for building authorization protocols and is mainly incomplete, OIDC is a full-fledged authentication and authorization
+protocol.  OIDC also makes heavy use of the link:https://jwt.io[Json Web Token] (JWT) set of standards.  These standards define a
+identity token JSON format and ways to digitally sign and encrypt that data in a compact and web-friendly way.
+
+There is really two types of use cases when using OIDC.  The first is an application that asks the {{book.project.name}} server to authenticate
+a user for them.  After a successful login, the application will receive an _identity token_ and an _access token_.  The _identity token_
+contains information about the user such as username, email, and other profile information.  The _access token_ is digitally signed by
+the realm and contains access information (like user role mappings) that the application can use to determine what resources the user
+is allowed to access on the application.
+
+The second type of use cases is that of a client that wants to gain access to remote services.  In this case, the client asks {{book.project.name}}
+to obtain an _access token_ it can use to invoke on other remote services on behalf of the user.  {{book.project.name}} authenticates the user
+then asks the user for consent to grant access to the client requesting it.  The client then receives the _access token_.  This _access token_
+is digitally signed by the realm.  The client can make REST invocations on remote services using this _access token_.  The REST service
+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.
+
+=== SAML 2.0
+
+link://https://saml.org/fill/this/in[SAML 2.0] is a similar specification to OIDC but a lot older and more mature.  It has its roots in SOAP and the plethora
+of WS-* specifications so it tends to be a bit more verbose than OIDC.  SAML 2.0 is primarily an authentication protocol
+that works by exchanging XML documents between the authentication server and the application.  XML signatures and encryption
+is used to verify requests and responses.
+
+In {{book.project.name}} SAML serves two types of use cases: browser applications and REST invocations.
+
+There is really two types of use cases when using SAML.  The first is an application that asks the {{book.project.name}} server to authenticate
+a user for them.  After a successful login, the application will receive an XML document that contains
+something called a SAML assertion that specify various attributes about the user.  This XML document is digitally signed by
+the realm and contains access information (like user role mappings) that the application can use to determine what resources the user
+is allowed to access on the application.
+
+The second type of use cases is that of a client that wants to gain access to remote services.  In this case, the client asks {{book.project.name}}
+to obtain an SAML assertion it can use to invoke on other remote services on behalf of the user.
+
+=== OIDC vs. SAML
+
+Choosing between OIDC and SAML is not just a matter of using a newer, sexier protocol (OIDC) instead of the old, mature, dinosaur (SAML).
+{{book.project.name}} has chosen OIDC as the protocol we use to both recommend and write all our extensions on top of.
+SAML tends to be a bit more verbose than OIDC.
+
+Beyond verbosity of exchanged data, if you compare the specifications you'll find that OIDC was designed to work with the
+web while SAML was retrofitted to work on top of the web.  For example,
+OIDC is also much better suited for HTML5/JavaScript applications because it is
+much much simpler to implement on the client side than SAML.  Since tokens are in the JSON format,
+they can be directly consumed by JavaScript.  Also, you'll find many nice little switches and features that
+make implementing security in your web applications easier.  For example, check out the iframe trick that the specification
+uses to easily determine if a user is still logged in or not.
+
+SAML has its uses though.  As you see the OIDC specifications evolve you see they implement more and more features that
+SAML has had for years.  What we often see is that people pick SAML over OIDC because of the perception that it is more mature
+and also because they already have existing applications that are secured by it.