Merge pull request #1 from stianst/master

Re-structuring

.gitignore

@@ -1,3 +1,6 @@
+_book
+node_modules
+
 # Intellij
 ###################
 .idea

README.adoc

@@ -1,10 +1,10 @@
 
-Securing Client Applications Guide
+{{book.title}}
-======================
+===========================================
 
 image:images/keycloak_logo.png[alt="Keycloak"]
 
-*Keycloak* _Documentation_ for {{book.versions.swarm}}
+*Keycloak* _Documentation_ for {{book.project.version}}
 
 http://www.keycloak.org
 

SUMMARY.adoc

@@ -1,25 +1,49 @@
-== Securing Client Applications Guide
+= {{book.title}}
-
-//. link:topics/templates/document-attributes.adoc[]
-:imagesdir: images
 
  . link:topics/preface.adoc[Preface]
- . link:topics/Overview.adoc[Overview]
+ . link:topics/overview/overview.adoc[Overview]
- . link:topics/oidc.adoc[OpenID Connect Client Adapters]
+   .. link:topics/overview/what-are-client-adapters.adoc[What are Client Adapters?]
- .. link:topics/jboss-adapter.adoc[JBoss/Wildfly Adapter]
+   .. link:topics/overview/supported-protocols.adoc[Supported Protocols]
- .. link:topics/tomcat-adapter.adoc[Tomcat 6, 7 and 8 Adapters]
+
- .. link:topics/jetty9-adapter.adoc[Jetty 9.x Adapters]
+ . link:topics/oidc/oidc-overview.adoc[OpenID Connect]
- .. link:topics/jetty8-adapter.adoc[Jetty 8.1.x Adapter]
+
- .. link:topics/servlet-filter-adapter.adoc[Java Servlet Filter Adapter]
+   .. link:topics/oidc/java/java-adapters.adoc[Java Adapters]
- .. link:topics/fuse-adapter.adoc[JBoss Fuse and Apache Karaf Adapter]
+      ... link:topics/oidc/java/java-adapter-config.adoc[Java Adapters Config]
- .. link:topics/javascript-adapter.adoc[Javascript Adapter]
+      ... link:topics/oidc/java/jboss-adapter.adoc[JBoss EAP/Wildfly Adapter]
- .. link:topics/spring-boot-adapter.adoc[Spring Boot Adapter]
+      ... link:topics/oidc/java/fuse-adapter.adoc[JBoss Fuse and Apache Karaf Adapter]
- .. link:topics/spring-security-adapter.adoc[Spring Security Adapter]
+      {% if book.community %}
- .. link:topics/installed-applications.adoc[Installed Applications]
+      ... link:topics/oidc/java/tomcat-adapter.adoc[Tomcat 6, 7 and 8 Adapters]
- .. link:topics/logout.adoc[Logout]
+      ... link:topics/oidc/java/jetty9-adapter.adoc[Jetty 9.x Adapters]
- .. link:topics/adapter_error_handling.adoc[Error Handling]
+      ... link:topics/oidc/java/jetty8-adapter.adoc[Jetty 8.1.x Adapter]
- .. link:topics/multi-tenancy.adoc[ Multi Tenancy]
+      ... link:topics/oidc/java/spring-boot-adapter.adoc[Spring Boot Adapter]
- .. link:topics/jaas.adoc[JAAS plugin]
+      ... link:topics/oidc/java/spring-security-adapter.adoc[Spring Security Adapter]
- . link:topics/saml.adoc[SAML Client Adapters]
+      {% endif %}
+      ... link:topics/oidc/java/servlet-filter-adapter.adoc[Java Servlet Filter Adapter]
+      ... link:topics/oidc/java/jaas.adoc[JAAS plugin]
+      ... link:topics/oidc/java/adapter-context.adoc[Keycloak Security Context]
+      ... 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/javascript-adapter.adoc[JavaScript Adapter]
+
+   .. link:topics/oidc/oidc-generic.adoc[Other OpenID Connect libraries]
+
+ . link:topics/saml/saml-overview.adoc[SAML]
+
+
+// . link:topics/oidc.adoc[OpenID Connect Client Adapters]
+
+//
+//
+//{% if book.community %}
+//
+//
+//{% endif %}
+// .. link:topics/installed-applications.adoc[Installed Applications]
+//
+//
+//
+// . link:topics/saml.adoc[SAML Client Adapters]
 
 

book.json

@@ -0,0 +1,39 @@
+{
+  "gitbook": "2.x.x",
+  "structure": {
+    "readme": "README.adoc"
+  },
+  "plugins": [
+    "toggle-chapters",
+    "ungrey",
+    "splitter"
+  ],
+  "variables": {
+    "title": "Keycloak Securing Client Applications Guide",
+    "community": true,
+    "product": false,
+    "images": "keycloak-images",
+    "appserver": {
+      "name": "Wildfly",
+      "version": "10"
+    },
+    "adminguide": {
+      "name": "Keycloak Administration Guide",
+      "link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/"
+    },
+    "web": {
+      "docs": {
+        "name": "keycloak.org/docs",
+        "link": "http://keycloak.org/docs"
+      },
+      "downloads": {
+        "name": "keycloak.org/downloads",
+        "link": "http://keycloak.org/downloads"
+      }
+    },
+    "project": {
+      "name": "Keycloak",
+      "version": "1.9.5.Final"
+    }
+  }
+}

build.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+cd $(readlink -f `dirname $0`)
+
+python gitlab-conversion.py
+cd target
+asciidoctor master.adoc
+
+xdg-open master.html

gitlab-conversion.py

@@ -0,0 +1,107 @@
+import sys, os, re, json, shutil, errno
+
+def transform(root, f, targetdir):
+    full = os.path.join(root, f)
+    input = open(full, 'r').read()
+    dir = os.path.join(targetdir, root)
+    if not os.path.exists(dir):
+        os.makedirs(dir)
+    output = open(os.path.join(dir, f), 'w')
+    input = applyTransformation(input)
+    output.write(input)
+
+
+def applyTransformation(input):
+    for variable in re.findall(r"\{\{(.*?)\}\}", input):
+        tmp = variable.replace('.', '_')
+        input = input.replace(variable, tmp)
+    input = input.replace('{{', '{').replace('}}', '}')
+    input = re.sub(r"<<fake.+#", "<<", input)
+    for variable in re.findall(r"[ ]*{% if (.*?) %}", input):
+        tmp = variable.replace('.', '_')
+        input = input.replace(variable, tmp)
+    exp = re.compile("[ ]*{% if (.*?) %}(.*?)[ ]*{% endif %}", re.DOTALL)
+    input = re.sub(exp, "ifeval::[{\g<1>}==true]\g<2>endif::[]", input)
+    input = re.sub(r"image:(\.\./)*", "image:", input)
+    input = re.sub(r"image::(\.\./)*", "image::", input)
+    return input
+
+
+indir = 'topics'
+targetdir = 'target'
+if len(sys.argv) > 1:
+    targetdir = sys.argv[1]
+
+shutil.rmtree(os.path.join(targetdir, 'images'), ignore_errors=True)
+shutil.rmtree(os.path.join(targetdir, 'keycloak-images'), ignore_errors=True)
+shutil.rmtree(os.path.join(targetdir, 'rhsso-images'), ignore_errors=True)
+shutil.copytree('images',os.path.join(targetdir, 'images'))
+#shutil.copytree('keycloak-images',os.path.join(targetdir, 'keycloak-images'))
+#shutil.copytree('rhsso-images',os.path.join(targetdir, 'rhsso-images'))
+
+tmp = os.path.join(targetdir, 'topics')
+if not os.path.exists(tmp):
+    os.makedirs(tmp)
+
+# transform files
+for root, dirs, filenames in os.walk(indir):
+    for f in filenames:
+        transform(root,f,targetdir)
+
+# Create master.doc includes
+input = open('SUMMARY.adoc', 'r').read()
+output = open(os.path.join(targetdir, 'master.adoc'), 'w')
+
+output.write("""
+:toc:
+:toclevels: 3
+:numbered:
+
+include::document-attributes.adoc[]
+""")
+
+input = re.sub(r"[ ]*\.+\s*link:(.*)\[(.*)\]", "include::\g<1>[]", input)
+input = applyTransformation(input)
+output.write(input)
+
+# parse book.json file and create document attributes
+with open('book.json') as data_file:
+    data = json.load(data_file)
+
+variables = data['variables']
+
+def makeAttributes(variables, variable, list):
+    for i in variables.keys():
+        if variable is None:
+            tmp = i
+        else:
+            tmp = variable + '_' + i
+        if isinstance(variables[i],dict):
+            makeAttributes(variables[i], tmp, list)
+        elif isinstance(variables[i],bool):
+            boolval = 'false'
+            if variables[i]:
+                boolval = 'true'
+            list.append({tmp: boolval})
+        else:
+            list.append({tmp: str(variables[i])})
+
+
+attributeList = []
+makeAttributes(variables, None, attributeList)
+
+output = open(os.path.join(targetdir, 'document-attributes.adoc'), 'w')
+for attribute in attributeList:
+    for k in attribute.keys():
+        output.write(':book_' + k + ": " + attribute[k] + "\n")
+
+print "Transformation complete!"
+
+
+
+
+
+
+
+
+

topics/oidc/java/adapter-context.adoc

@@ -1,10 +1,4 @@
-= KeycloakSecurityContext
+=== Keycloak Security Context
-:doctype: book
-:sectnums:
-:toc: left
-:icons: font
-:experimental:
-:sourcedir: .
 
 The `KeycloakSecurityContext` interface is available if you need to look at the access token directly.
 This context is also useful if you need to get the encoded access token so you can make additional REST invocations.

topics/oidc/java/adapter_error_handling.adoc

@@ -1,6 +1,6 @@
 
 [[_adapter_error_handling]]
-= Error Handling
+=== Error Handling
 
 Keycloak has some error handling facilities for servlet based client adapters.
 When an error is encountered in authentication, keycloak will call `HttpServletResponse.sendError()`.

topics/oidc/java/fuse-adapter.adoc

@@ -1,6 +1,6 @@
 
 [[_fuse_adapter]]
-= JBoss Fuse and Apache Karaf Adapter
+=== JBoss Fuse and Apache Karaf Adapter
 
 Currently Keycloak supports securing your web applications running inside http://www.jboss.org/products/fuse/overview/[JBoss Fuse]        or http://karaf.apache.org/[Apache Karaf] . It leverages <<_jetty8_adapter,Jetty 8 adapter>> as both JBoss Fuse 6.1 and Apache Karaf 3 are bundled with http://eclipse.org/jetty/[Jetty 8.1 server] under the covers and Jetty is used for running various kinds of web applications. 
 

topics/oidc/java/jaas.adoc

@@ -1,6 +1,6 @@
 
 [[_jaas_adapter]]
-= JAAS plugin
+=== JAAS plugin
 
 It's generally not needed to use JAAS for most of the applications, especially if they are HTTP based, but directly choose one of our adapters.
 However some applications and systems may still rely on pure legacy JAAS solution.

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

@@ -1,20 +1,9 @@
 
-[[_adapter_config]]
+[[_java_adapter_config]]
-
+=== Java Adapter Config
-= Adapters
-
-Keycloak can secure a wide variety of application types.
-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. 
-
-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. 
-
-
-== General Adapter Config
 
 Each adapter supported by Keycloak can be configured by a simple JSON text file.
-This is what one might look like: 
+This is what one might look like:
 
 
 [source]
@@ -45,117 +34,117 @@ This is what one might look like:
    "client-keystore-password" : "geheim",
    "client-key-password" : "geheim"
 }
-----    
+----
 
 Some of these configuration switches may be adapter specific and some are common across all adapters.
 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. 
+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: 
+Here is a description of each item:
 
 
 
 realm::
   Name of the realm representing the users of your distributed applications and services.
-  This is _REQUIRED._                    
+  This is _REQUIRED._
 
 resource::
   Username of 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._                    
+  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._                    
+  This is _REQUIRED._
 
 auth-server-url::
   The base URL of the Keycloak Server.
   All other Keycloak pages and REST services are derived from this.
-  It is usually of the form `https://host:port/auth`                        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.
   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'. 
+  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 false, it will look at the realm level for user role mappings.
   This is _OPTIONAL_.
-  The default value is _false_. 
+  The default value is _false_.
 
 public-client::
   If set to true, the adapter will not send credentials for the client to Keycloak.
-  The default value is _false_. 
+  The default value is _false_.
 
 enable-cors::
   This enables CORS support.
   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_. 
+  The default value is _false_.
 
 cors-max-age::
   If CORS is enabled, this sets the value of the `Access-Control-Max-Age`                        header.
   This is _OPTIONAL_.
-  If not set, this header is not returned in CORS responses. 
+  If not set, this header is not returned in CORS responses.
 
 cors-allowed-methods::
   If CORS is enabled, this sets the value of the `Access-Control-Allow-Methods`                        header.
   This should be a comma-separated string.
   This is _OPTIONAL_.
-  If not set, this header is not returned in CORS responses. 
+  If not set, this header is not returned in CORS responses.
 
 cors-allowed-headers::
   If CORS is enabled, this sets the value of the `Access-Control-Allow-Headers`                        header.
   This should be a comma-separated string.
   This is _OPTIONAL_.
-  If not set, this header is not returned in CORS responses. 
+  If not set, this header is not returned in CORS responses.
 
 bearer-only::
   This tells the adapter to only do bearer token authentication.
   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_. 
+  The default value is _false_.
 
 enable-basic-auth::
   This tells the adapter to also support basic authentication.
   If this option is enabled, then _secret_ must also be provided.
   This is _OPTIONAL_.
-  The default value is _false_. 
+  The default value is _false_.
 
 expose-token::
   If `true`, an authenticated browser client (via a Javascript HTTP invocation) can obtain the signed access token via the URL `root/k_query_bearer_token`.
   This is _OPTIONAL_.
-  The default value is _false_. 
+  The default value is _false_.
 
 credentials::
   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.
   Currently only `password`                        is supported.
-  This is _REQUIRED_. 
+  This is _REQUIRED_.
 
 connection-pool-size::
   Adapters will make separate HTTP invocations to the Keycloak Server to turn an access code into an access token.
   This config option defines how many connections to the Keycloak Server should be pooled.
   This is _OPTIONAL_.
-  The default value is `20`. 
+  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.
   While convenient,  this setting is not recommended as you will not be verifying the host name of the Keycloak Server.
   This is _OPTIONAL_.
-  The default value is `false`. 
+  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.
   This is not a recommended.
   This seting may be useful in test environments This is _OPTIONAL_.
-  The default value is `false`. 
+  The default value is `false`.
 
 truststore::
   This setting is for Java adapters.
@@ -166,55 +155,55 @@ truststore::
   This is what the trustore does.
   The keystore contains one or more trusted host certificates or certificate authorities.
   You can create this truststore by extracting the public certificate of the Keycloak server's SSL keystore.
-  This is _OPTIONAL_                        if `ssl-required`                        is `none`                        or `disable-trust-manager`                        is `true`. 
+  This is _OPTIONAL_                        if `ssl-required`                        is `none`                        or `disable-trust-manager`                        is `true`.
 
 truststore-password::
   Password for the truststore keystore.
-  This is _REQUIRED_                        if `truststore`                        is set. 
+  This is _REQUIRED_                        if `truststore`                        is set.
 
 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 Java keystore file.
   This keystore contains client certificate for two-way SSL when the adapter makes HTTPS requests to the Keycloak server.
-  This is _OPTIONAL_. 
+  This is _OPTIONAL_.
 
 client-keystore-password::
   _Not supported yet, but we will support in future versions._                        Password for the client keystore.
-  This is _REQUIRED_                        if `client-keystore`                        is set. 
+  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.
-  This is _REQUIRED_                        if `client-keystore`                        is set. 
+  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. 
+  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.
-  More info in <<_refresh_token_each_req,Refresh token in each 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 just in cluster (See <<_registration_app_nodes,Registration of application nodes to Keycloak>>)
 
 register-node-period::
   Period for re-registration adapter to Keycloak.
   Useful in cluster.
-  See <<_registration_app_nodes,Registration of application nodes to Keycloak>> for details. 
+  See <<_registration_app_nodes,Registration of application nodes to Keycloak>> 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 <<_stateless_token_store,Stateless token store>> for details.
 
 principal-attribute::
   OpenID Connection ID Token attribute to populate the UserPrincipal name with.
   If token attribute is null, defaults to `sub`.
-  Possible values are `sub`, `preferred_username`, `email`, `name`, `nickname`, `given_name`, `family_name`. 
+  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 default value is _false_.     
+  The default value is _false_.

topics/oidc/java/java-adapters.adoc

@@ -0,0 +1 @@
+== Java Adapters

topics/oidc/java/jboss-adapter.adoc

@@ -1,6 +1,6 @@
 
 [[_jboss_adapter]]
-= JBoss/Wildfly Adapter
+=== JBoss/Wildfly Adapter
 
 To be able to secure WAR apps deployed on JBoss AS 7.1.1, JBoss EAP 6.x, or Wildfly, you must install and configure the Keycloak Subsystem.
 You then have two options to secure your WARs.
@@ -9,7 +9,7 @@ Alternatively, you don't have to crack open your WARs at all and can apply Keycl
 Both methods are described in this section. 
 
 [[_jboss_adapter_installation]]
-== Adapter Installation
+==== Adapter Installation
 
 Adapters are no longer included with the appliance or war distribution.
 Each adapter is a separate download on the Keycloak download site.
@@ -144,7 +144,7 @@ public class CustomerService {
 
 We hope to improve our integration in the future so that you don't have to specify the @SecurityDomain annotation when you want to propagate a keycloak security context to the EJB tier. 
 
-== Required Per WAR Configuration
+==== Required Per WAR Configuration
 
 This section describes how to secure a WAR directly by adding config and editing files within your WAR package. 
 
@@ -206,7 +206,7 @@ Here's an example pulled from one of the examples that comes distributed with Ke
 </web-app>
 ----        
 
-== Securing WARs via Keycloak Subsystem
+==== Securing WARs via Keycloak Subsystem
 
 You do not have to crack open a WAR to secure it with Keycloak.
 Alternatively, you can externally secure it via the Keycloak Adapter Subsystem.

topics/oidc/java/jetty8-adapter.adoc

@@ -1,13 +1,13 @@
 
 [[_jetty8_adapter]]
-= Jetty 8.1.x Adapter
+=== Jetty 8.1.x Adapter
 
 Keycloak has a separate adapter for Jetty 8.1.x that you will have to install into your Jetty installation.
 You then have to provide some extra configuration in each WAR you deploy to Jetty.
 Let's go over these steps. 
 
 [[_jetty8_adapter_installation]]
-== Adapter Installation
+==== Adapter Installation
 
 Adapters are no longer included with the appliance or war distribution.Each adapter is a separate download on the Keycloak download site.
 They are also available as a maven artifact. 
@@ -40,7 +40,7 @@ Edit start.ini and add keycloak to the options
 OPTIONS=Server,jsp,jmx,resources,websocket,ext,plus,annotations,keycloak
 ----        
 
-== Required Per WAR Configuration
+==== Required Per WAR Configuration
 
 Enabling Keycloak for your WARs is the same as the Jetty 9.x adapter.
 Our 8.1.x adapter supports both keycloak.json and the jboss-web.xml advanced configuration.

topics/oidc/java/jetty9-adapter.adoc

@@ -1,13 +1,13 @@
 
 [[_jetty9_adapter]]
-= Jetty 9.x Adapters
+=== Jetty 9.x Adapters
 
 Keycloak has a separate adapter for Jetty 9.1.x and Jetty 9.2.x that you will have to install into your Jetty installation.
 You then have to provide some extra configuration in each WAR you deploy to Jetty.
 Let's go over these steps. 
 
 [[_jetty9_adapter_installation]]
-== Adapter Installation
+==== Adapter Installation
 
 Adapters are no longer included with the appliance or war distribution.Each adapter is a separate download on the Keycloak download site.
 They are also available as a maven artifact. 
@@ -34,7 +34,7 @@ $ java -jar $JETTY_HOME/start.jar --add-to-startd=keycloak
 ----        
 
 [[_jetty9_per_war]]
-== Required Per WAR Configuration
+==== Required Per WAR Configuration
 
 This section describes how to secure a WAR directly by adding config and editing files within your WAR package. 
 

topics/oidc/java/logout.adoc

@@ -1,5 +1,5 @@
 
-= Logout
+=== Logout
 
 There are multiple ways you can logout from a web application.
 For Java EE servlet containers, you can call HttpServletRequest.logout(). For any other browser application, you can point the browser at the url `http://auth-server/auth/realms/{realm-name}/tokens/logout?redirect_uri=encodedRedirectUri`.

topics/oidc/java/multi-tenancy.adoc

@@ -1,5 +1,5 @@
 
-= Multi Tenancy
+=== Multi Tenancy
 
 Multi Tenancy, in our context, means that one single target application (WAR) can be secured by a single (or clustered) Keycloak server, authenticating its users against different realms.
 In practice, this means that one application needs to use different `keycloak.json` files.

topics/oidc/java/servlet-filter-adapter.adoc

@@ -1,5 +1,5 @@
 
-= Java Servlet Filter Adapter
+=== Java Servlet Filter Adapter
 
 If you want to use Keycloak with a Java servlet application that doesn't have an adapter for that servlet platform, you can opt to use the servlet filter adapter that Keycloak has.
 This adapter works a little differently than the other adapters.

topics/oidc/java/spring-boot-adapter.adoc

@@ -1,11 +1,11 @@
 
-= Spring Boot Adapter
+=== Spring Boot Adapter
 
 To be able to secure Spring Boot apps you must add the Keycloak Spring Boot adapter JAR to your app.
 You then have to provide some extra configuration via normal Spring Boot configuration (`application.properties`).  Let's go over these steps. 
 
 [[_spring_boot_adapter_installation]]
-== Adapter Installation
+==== Adapter Installation
 
 The Keycloak Spring Boot adapter takes advantage of Spring Boot's autoconfiguration so all you need to do is add the Keycloak Spring Boot adapter JAR to your project.
 Depending on what container you are using with Spring Boot, you also need to add the appropriate Keycloak container adapter.
@@ -29,7 +29,7 @@ If you are using Maven, add the following to your pom.xml (using Tomcat as an ex
 ----        
 
 [[_spring_boot_adapter_configuration]]
-== Required Spring Boot Adapter Configuration
+==== Required Spring Boot Adapter Configuration
 
 This section describes how to configure your Spring Boot app to use Keycloak. 
 

topics/oidc/java/spring-security-adapter.adoc

@@ -1,5 +1,5 @@
 
-= Spring Security Adapter
+=== Spring Security Adapter
 
 To secure an application with Spring Security and Keycloak, add this adapter as a dependency to your project.
 You then have to provide some extra beans in your Spring Security configuration file and add the Keycloak security filter to your pipeline. 
@@ -7,7 +7,7 @@ You then have to provide some extra beans in your Spring Security configuration
 Unlike the other Keycloak Adapters, you should not configure your security in web.xml.
 However, keycloak.json is still required. 
 
-== Adapter Installation
+==== Adapter Installation
 
 Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle build. 
 
@@ -23,11 +23,11 @@ Add Keycloak Spring Security adapter as a dependency to your Maven POM or Gradle
 </dependency>
 ----        
 
-== Spring Security Configuration
+==== Spring Security Configuration
 
 The Keycloak Spring Security adapter takes advantage of Spring Security's flexible security configuration syntax. 
 
-=== Java Configuration
+===== Java Configuration
 
 Keycloak provides a KeycloakWebSecurityConfigurerAdapter as a convenient base class for creating a http://docs.spring.io/spring-security/site/docs/4.0.x/apidocs/org/springframework/security/config/annotation/web/WebSecurityConfigurer.html[WebSecurityConfigurer]                instance.
 The implementation allows customization by overriding methods.
@@ -78,7 +78,7 @@ You must provide a session authentication strategy bean which should be of type
 Spring Security's `SessionFixationProtectionStrategy` is currently not supported because it changes the session identifier after login via Keycloak.
 If the session identifier changes, universal log out will not work because Keycloak is unaware of the new session identifier. 
 
-=== XML Configuration
+===== XML Configuration
 
 While Spring Security's XML namespace simplifies configuration, customizing the configuration can be a bit verbose. 
 
@@ -148,13 +148,13 @@ While Spring Security's XML namespace simplifies configuration, customizing the
 </beans>
 ----            
 
-== Multi Tenancy
+==== Multi Tenancy
 
 The Keycloak Spring Security adapter also supports multi tenancy.
 Instead of injecting `AdapterDeploymentContextFactoryBean` with the path to `keycloak.json` you can inject an implementation of the `KeycloakConfigResolver` interface.
 More details on how to implement the `KeycloakConfigResolver` can be found in <<_multi_tenancy>>. 
 
-== Naming Security Roles
+==== Naming Security Roles
 
 Spring Security, when using role-based authentication, requires that role names start with `ROLE_`.
 For example, an administrator role must be declared in Keycloak as `ROLE_ADMIN` or similar, not simply `ADMIN`. 
@@ -163,7 +163,7 @@ The class `org.keycloak.adapters.springsecurity.authentication.KeycloakAuthentic
 Use, for example, `org.springframework.security.core.authority.mapping.SimpleAuthorityMapper` to insert the `ROLE_` prefix and convert the role name to upper case.
 The class is part of Spring Security Core module. 
 
-== Client to Client Support
+==== Client to Client Support
 
 To simplify communication between clients, Keycloak provides an extension of Spring's `RestTemplate` that handles bearer token authentication for you.
 To enable this feature your security configuration must add the `KeycloakRestTemplate` bean.
@@ -227,7 +227,7 @@ public class RemoteProductService implements ProductService {
 }
 ----        
 
-== Spring Boot Configuration
+==== Spring Boot Configuration
 
 Spring Boot attempts to eagerly register filter beans with the web application context.
 Therefore, when running the Keycloak Spring Security adapter in a Spring Boot environment, it may be necessary to add two ``FilterRegistrationBean``s to your security configuration to prevent the Keycloak filters from being registered twice. 

topics/oidc/java/tomcat-adapter.adoc

@@ -1,13 +1,13 @@
 
 [[_tomcat_adapter]]
-= Tomcat 6, 7 and 8 Adapters
+=== Tomcat 6, 7 and 8 Adapters
 
 To be able to secure WAR apps deployed on Tomcat 6, 7 and 8 you must install the Keycloak Tomcat 6, 7 or 8 adapter into your Tomcat installation.
 You then have to provide some extra configuration in each WAR you deploy to Tomcat.
 Let's go over these steps. 
 
 [[_tomcat_adapter_installation]]
-== Adapter Installation
+==== Adapter Installation
 
 Adapters are no longer included with the appliance or war distribution.
 Each adapter is a separate download on the Keycloak download site.
@@ -28,7 +28,7 @@ $ unzip keycloak-tomcat7-adapter-dist.zip
 $ unzip keycloak-tomcat8-adapter-dist.zip
 ----    
 
-== Required Per WAR Configuration
+==== Required Per WAR Configuration
 
 This section describes how to secure a WAR directly by adding config and editing files within your WAR package. 
 

topics/oidc/javascript-adapter.adoc

@@ -1,5 +1,5 @@
 
-= Javascript Adapter
+== Javascript Adapter
 
 The Keycloak Server comes with a Javascript library you can use to secure HTML/Javascript applications.
 This library is referenceable directly from the keycloak server.

topics/oidc/oidc-generic.adoc

@@ -1,23 +1,46 @@
+== Other OpenID Connect libraries
 
-= Installed Applications
+OAuth2 https://tools.ietf.org/html/rfc6749
+OpenID Connect http://openid.net/connect/
 
-Keycloak provides two special redirect uris for installed applications. 
+
+=== Endpoints
+
+TODO
+
+=== Flows
+
+==== Authorization Grant
+
+==== Implicit
+
+==== Resource Owner Password Credentials
+
+==== Client Credentials
+
+=== Redirect URIs
+
+Keycloak provides two special redirect uris for installed applications.
 
 [[_installed_applications_url]]
-== Installed Applications url
+==== Installed Applications url
 
-http://localhost 
+http://localhost
 
 This returns the code to a web server on the client as a query parameter.
 Any port number is allowed.
-This makes it possible to start a web server for the installed application on any free port number without requiring changes in the `Admin Console`. 
+This makes it possible to start a web server for the installed application on any free port number without requiring changes in the `Admin Console`.
 
 [[_installed_applications_urn]]
-== Installed Applications urn
+==== Installed Applications urn
 
-`urn:ietf:wg:oauth:2.0:oob` 
+`urn:ietf:wg:oauth:2.0:oob`
 
 If its not possible to start a web server in the client (or a browser is not available) it is possible to use the special `urn:ietf:wg:oauth:2.0:oob` redirect uri.
 When this redirect uri is used Keycloak displays a page with the code in the title and in a box on the page.
 The application can either detect that the browser title has changed, or the user can copy/paste the code manually to the application.
-With this redirect uri it is also possible for a user to use a different device to obtain a code to paste back to the application. 
+With this redirect uri it is also possible for a user to use a different device to obtain a code to paste back to the application.
+
+=== Session Management
+
+=== Dynamic Client Registration

topics/oidc/oidc-overview.adoc

@@ -0,0 +1,8 @@
+== OpenID Connect
+
+Keycloak can secure a wide variety of application types.
+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.
+
+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/preface.adoc

@@ -1,4 +1,4 @@
-= Preface
+== Preface
 
 In some of the example listings, what is meant to be displayed on one line does not fit inside the available page width.These lines have been broken up. A '\' at the end of a line means that a break has been introduced to fit in the page, with the following lines indented.
 So: 

topics/saml/saml-overview.adoc

@@ -0,0 +1 @@
+== SAML