gitlab conversion script

gitlab-conversion.py

@@ -0,0 +1,103 @@
+import sys, os, re, json, shutil, errno
+
+def transform(root, f, targetdir):
+    full = os.path.join(root, f)
+    print full
+    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')
+    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)
+    output.write(input)
+
+indir = 'topics'
+targetdir = 'target'
+if len(sys.argv) > 1:
+    targetdir = sys.argv[1]
+
+shutil.rmtree(os.path.join(targetdir, 'images'))
+shutil.rmtree(os.path.join(targetdir, 'keycloak-images'))
+shutil.rmtree(os.path.join(targetdir, 'rhsso-images'))
+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)
+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)
+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")
+
+
+
+
+
+
+
+
+

topics/cache.adoc

@@ -1,3 +1,4 @@
+
 == Server Cache Configuration
 
 {{book.project.name}} has two types of caches.  One type of cache sits in front of the database to decrease load on the DB

topics/cache/clear.adoc

@@ -1,3 +1,4 @@
+
 === Clearing Caches at Runtime
 
 To clear the realm or user cache, go to the {{book.project.name}} admin console Realm Settings->Cache Config page.

topics/cache/disable.adoc

@@ -1,3 +1,4 @@
+
 === Disabling Caching
 
 To disable the realm or user cache, you must edit the `keycloak-server.json` file in your distribution.  Where

topics/cache/eviction.adoc

@@ -1,3 +1,4 @@
+
 === Eviction and Expiration
 
 There are multiple different caches configured for {{book.project.name}}.

topics/cache/replication.adoc

@@ -1,3 +1,4 @@
+
 === Replication and Failover
 
 The `sessions`, `offlineSessions` and `loginFailures` caches are the only caches that may perform replication.  Entries are

topics/clustering.adoc

@@ -1,3 +1,4 @@
+
 [[_clustering]]
 == Clustering
 

topics/clustering/booting.adoc

@@ -1,3 +1,4 @@
+
 === Booting the Cluster
 
 Booting {{book.project.name}} in a cluster depends on your <<fake/../../operating-mode.adoc#_operating-mode, operating mode>>

topics/clustering/example.adoc

@@ -1,3 +1,4 @@
+
 === Clustering Example
 
 {{book.project.name}} does come with an out of the box clustering demo that leverages domain mode.  Review the

topics/clustering/load-balancer.adoc

@@ -1,3 +1,4 @@
+
 === Setting Up a Load Balancer
 
 This section only covers configuring the built in load balancer that is discussed in the
@@ -59,7 +60,7 @@ binding needs to point to the host and port of the new host.
 </socket-binding-group>
 ----
 
-=== Master Bind Addresses
+==== Master Bind Addresses
 
 Next thing you'll have to do is to change the `public` and `management` bind addresses for the master host.  Either
 edit the _domain.xml_ file as discussed in the <<fake/../../network/bind-address.adoc#_bind-address, Bind Addresses>> chapter
@@ -70,7 +71,7 @@ or specify these bind addresses on the command line as follows:
 $ domain.sh --host-config=host-master.xml -Djboss.bind.address=192.168.0.2 -Djboss.bind.address.management=192.168.0.2
 ----
 
-=== Host Slave Bind Addresses
+==== Host Slave Bind Addresses
 
 Next you'll have to change the `public`, `management`, and domain controller bind addresses (`jboss.domain.master-address`).  Either edit the
 _host-slave.xml_ file or specify them on the command line as follows:

topics/clustering/multicast.adoc

@@ -1,3 +1,4 @@
+
 === Multicast Network Setup
 
 Out of the box clustering support has a need to for IP Multicast.  Multicast is a network broadcast protocol.  This protocol

topics/clustering/recommended.adoc

@@ -1,3 +1,4 @@
+
 === Recommended Network Architecture
 
 The recommended network architecture for deploying {{book.project.name}} is to set up an HTTP/HTTPS load balancer on

topics/clustering/serialized.adoc

@@ -1,3 +1,4 @@
+
 [[_clustering_db_lock]]
 === Serialized Cluster Startup
 

topics/clustering/troubleshooting.adoc

@@ -1,3 +1,4 @@
+
 === Troubleshooting
 
 Note that when you run cluster, you should see message similar to this in the log of both cluster nodes:
@@ -16,3 +17,6 @@ Default values are UDP port 55200 and multicast port 45688 with multicast addres
 Note that you may need more ports opened if you want to enable additional features like diagnostics for your JGroups stack.
 {{book.project.name}} delegates most of the clustering work to Infinispan/JGroups.
 Please consult the link:{{book.appserver.jgroups.link}}[JGroups] chapter of the {{book.appserver.jgroups.name}}.
+
+
+

topics/database/checklist.adoc

@@ -1,3 +1,4 @@
+
 === RDBMS Setup Checklist
 
 These are the steps you will need to perform to get an RDBMS configured for {{book.project.name}}.

topics/database/datasource.adoc

@@ -1,3 +1,4 @@
+
 === Modify the {{book.project.name}} Datasource
 
 After declaring your JDBC driver, you  have to modify the existing datasource configuration that {{book.project.name}} uses

topics/database/hibernate.adoc

@@ -1,3 +1,4 @@
+
 === Hibernate Configuration
 
 The Hibernate persistence API is already pre-configured out of the box and rarely needs to be changed.

topics/database/jdbc.adoc

@@ -1,3 +1,4 @@
+
 === Package the JDBC Driver
 
 Find and download the JDBC driver JAR for your RDBMS.  Before you can use this driver, you must package it up into a module

topics/installation.adoc

@@ -1,3 +1,4 @@
+
 == Installation
 
 Installing {{book.project.name}} is as simple as downloading it and unzipping it.  This chapter reviews system requirements

topics/installation/directory-structure.adoc

@@ -1,3 +1,4 @@
+
 === Distribution Directory Structure
 
 This chapter walks you through the directory structure of the server distribution.

topics/installation/distribution-files-community.adoc

@@ -1,3 +1,4 @@
+
 === Installing Distribution Files
 
 The Keycloak Server has three downloadable distributions:

topics/installation/distribution-files-product.adoc

@@ -1,3 +1,4 @@
+
 === Installing Distribution Files
 
 The {{book.project.name}} Server is contained in one distribution file:

topics/installation/system-requirements.adoc

@@ -1,3 +1,4 @@
+
 === System Requirements
 
 These are the requirements to run the {{book.project.name}} authentication server:

topics/manage.adoc

@@ -7,7 +7,8 @@ shown how to edit the _standalone.xml_ or _domain.xml_ directly.  This must be d
 Additionally, you may be shown how to apply config changes on a running server using the app server's command line interface ({{books.appserver.name}} CLI).  This chapter discusses
 how you will do this.
 
-=== Start the {{books.appserver.name}} CLI
+
+=== Start the {{book.appserver.name}} CLI
 
 To start the {{books.appserver.name}} CLI, you need to run the `jboss-cli` script.
 

topics/mongo.adoc

@@ -1,3 +1,4 @@
+
 [[_mongo]]
 
 == Mongo DB Setup
@@ -94,6 +95,6 @@ Therefore, a configuration like the following
 ----
 will authenticate the user against the authentication database, but store all keycloak related data in the keycloak database.
 
-==== MongoDB Replica Sets
+=== MongoDB Replica Sets
 
 In order to use a mongo replica set for Keycloak, one has to use URI based configuration, which supports the definition of replica sets out of the box: `mongodb://host1:27017,host2:27017,host3:27017/`.

topics/network.adoc

@@ -1,3 +1,4 @@
+
 [[_network]]
 
 == Network Setup

topics/network/bind-address.adoc

@@ -1,3 +1,4 @@
+
 [[_bind-address]]
 
 === Bind Addresses

topics/network/https.adoc

@@ -1,3 +1,4 @@
+
 === Setting up HTTPS/SSL
 
 WARNING:  {{book.project.name}} is not set up by default to handle SSL/HTTPS.

topics/network/outgoing.adoc

@@ -1,3 +1,4 @@
+
 === Outgoing HTTP Requests
 
 The {{book.project.name}} server often needs to make non-browser HTTP requests to the applications and services it secures.

topics/network/ports.adoc

@@ -1,3 +1,4 @@
+
 [[_ports]]
 
 === Socket Port Bindings

topics/old-installation.adoc

@@ -1,610 +0,0 @@
-[[_server_installation]]
-
-= Installation and Configuration of Keycloak Server
-
-== Installation
-
-Keycloak Server has three downloadable distributions.
-To run the Keycloak server you need to have Java 8 already installed. 
-
-* keycloak-.[zip|tar.gz]
-* keycloak-overlay-.[zip|tar.gz]
-* keycloak-demo-.[zip|tar.gz]        
-
-[[_server_install]]
-=== Install Standalone Server
-
-For production and for non-JavaEE developers we recommend using the standalone Keycloak server.
-All you need to do is to download `keycloak-.zip` or  `keycloak-.tar.gz`, unpackage and start to have a Keycloak server up and running. 
-
-To install first download either the zip or tar.gz and extract.
-Then start by running either: 
-
-[source]
-----
-keycloak-/bin/standalone.sh
-----                
-or: 
-
-[source]
-----
-keycloak-/bin/standalone.bat
-----            
-
-[[_overlay_install]]
-=== Install on existing WildFly or JBoss EAP 
-
-Keycloak can be installed into an existing installations of WildFly  or JBoss EAP . To do this download `keycloak-overlay-.zip` or `keycloak-overlay-.tar.gz`.
-Once downloaded extract into the root directory of your installation. 
-
-To add Keycloak to existing standalone.xml server config run: 
-
-[source]
-----
-
-bin/jboss-cli.sh --file=bin/keycloak-install.cli
----- 
-To add Keycloak to existing standalone-ha.xml server config run: 
-
-[source]
-----
-
-bin/jboss-cli.sh --file=bin/keycloak-install-ha.cli
-----
-If you want to add Keycloak to a different server config edit `keycloak-install.cli` or `keycloak-install-ha.cli` and change the name of the server config. 
-
-=== Install Development Bundle
-
-The demo bundle contains everything you need to get started with Keycloak including documentation and examples.
-To install it first download `keycloak-demo-.zip` or `keycloak-demo-.tar.gz`.
-Once downloaded extract it inside `keycloak-demo-` you'll find `keycloak` which contains a full WildFly  server with Keycloak Server and Adapters included.
-You'll also find `docs` and `examples` which contains everything you need to get started developing applications that use Keycloak. 
-
-To start WildFly with Keycloak run: 
-
-[source]
-----
-keycloak-/bin/standalone.sh
----- 
-or: 
-
-[source]
-----
-keycloak-/bin/standalone.bat
-----            
-
-== Configuring the Server
-
-Although the Keycloak Server is designed to run out of the box, there's some things you'll need to configure before you go into production.
-Specifically: 
-
-* Configuring Keycloak to use a production database
-* Setting up SSL/HTTPS
-* Enforcing HTTPS connections        
-
-=== Admin User
-
-To access the admin console to configure Keycloak you need an account to login.
-There is no built in user, instead you have to first create an admin account.
-This can done either by opening http://localhost:8080/auth                (creating a user through the browser can only be done through localhost) or you can use the add-user script from the command-line. 
-
-The `add-user` script creates a temporary file with the details of the user, which are imported at startup.
-To add a user with this script run: 
-
-[source]
-----
-
-bin/add-user.[sh|bat] -r master -u <username> -p <password>
-----
-Then restart the server. 
-For `keycloak-overlay`, please make sure to use: 
-
-[source]
-----
-bin/add-user-keycloak.[sh|bat] -r master -u <username> -p <password>
-----            
-
-=== Relational Database Configuration
-
-You might want to use a better relational database for Keycloak like PostgreSQL or MySQL.
-You might also want to tweak the configuration settings of the datasource.
-Please see the https://docs.jboss.org/author/display/WFLY8/DataSource+configuration[Wildfly]                documentation on how to do this. 
-
-Keycloak runs on a Hibernate/JPA backend which is configured in the `standalone/configuration/keycloak-server.json`.
-By default the setting is like this: 
-
-[source]
-----
-"connectionsJpa": {
-    "default": {
-        "dataSource": "java:jboss/datasources/KeycloakDS",
-        "databaseSchema": "update"
-    }
-},
-----
-Possible configuration options are: 
-
-dataSource::
-  JNDI name of the dataSource 
-
-jta::
-  boolean property to specify if datasource is JTA capable 
-
-driverDialect::
-  Value of Hibernate dialect.
-  In most cases you don't need to specify this property as dialect will be autodetected by Hibernate. 
-
-databaseSchema::
-  Specify if schema should be updated or validated.
-  Valid values are "update" and "validate" ("update is default). 
-
-showSql::
-  Specify whether Hibernate should show all SQL commands in the console (false by default) 
-
-formatSql::
-  Specify whether Hibernate should format SQL commands (true by default) 
-
-globalStatsInterval::
-  Will log global statistics from Hibernate about executed DB queries and other things.
-  Statistics are always reported to server log at specified interval (in seconds) and are cleared after each report. 
-
-schema::
-  Specify the database schema to use             
-
-===== Tested databases
-
-Here is list of RDBMS databases and corresponding JDBC drivers, which were tested with Keycloak.
-Note that Hibernate dialect is usually set automatically according to your database, but you have possibility to override if default dialect doesn't work correctly.
-You can setup dialect by adding property `driverDialect` to the `keycloak-server.json` into `connectionsJpa` section (see above). 
-
-.Tested databases
-[cols="1,1,1", frame="all", options="header"]
-|===
-| Database
-| JDBC driver
-| Hibernate Dialect
-
-
-
-
-
-
-|===                
-
-=== MongoDB based model
-
-Keycloak provides http://www.mongodb.com[MongoDB] based model implementation, which means that your identity data will be saved in MongoDB instead of traditional RDBMS.
-To configure Keycloak to use Mongo open `standalone/configuration/keycloak-server.json` in your favourite editor, then change:  
-
-[source]
-----
-
-"eventsStore": {
-    "provider": "jpa",
-    "jpa": {
-        "exclude-events": [ "REFRESH_TOKEN" ]
-    }
-},
-
-"realm": {
-    "provider": "jpa"
-},
-
-"user": {
-    "provider": "${keycloak.user.provider:jpa}"
-},
-----
-to:  
-
-[source]
-----
-
-"eventsStore": {
-    "provider": "mongo",
-    "mongo": {
-        "exclude-events": [ "REFRESH_TOKEN" ]
-    }
-},
-
-"realm": {
-    "provider": "mongo"
-},
-
-"user": {
-    "provider": "mongo"
-},
-----                
-And at the end of the file add the snippet like this where you can configure details about your Mongo database: 
-
-[source]
-----
-
-"connectionsMongo": {
-    "default": {
-        "host": "127.0.0.1",
-        "port": "27017",
-        "db": "keycloak",
-        "connectionsPerHost": 100,
-        "databaseSchema": "update"
-    }
-}
-----                
-All configuration options are optional.
-Default values for host and port are localhost and 27017.
-Default name of database is `keycloak` . You can also specify properties `user` and `password` if you want authenticate against your MongoDB.
-If user and password are not specified, Keycloak will connect unauthenticated to your MongoDB. 
-
-Finally there is set of optional configuration options, which can be used to specify connection-pooling capabilities of Mongo client.
-Supported int options are: `connectionsPerHost`, `threadsAllowedToBlockForConnectionMultiplier`, `maxWaitTime`, `connectTimeout` `socketTimeout`.
-Supported boolean options are: `socketKeepAlive`, `autoConnectRetry`.
-Supported long option is `maxAutoConnectRetryTime`.
-See http://api.mongodb.org/java/2.11.4/com/mongodb/MongoClientOptions.html[Mongo documentation]                for details about those options and their default values. 
-
-Alternatively, you can configure MongoDB using a MongoDB http://docs.mongodb.org/manual/reference/connection-string/[connection URI].
-In this case, you define all information concerning the connection and authentication within the URI, as described in the MongoDB documentation.
-Please note that the database specified within the URI is only used for authentication.
-To change the database used by keycloak you have to set `db` property as before.
-Therefore, a configuration like the following
- 
-[source]
-----
-
-"connectionsMongo": {
-    "default": {
-        "uri": "mongodb://user:password@127.0.0.1/authentication",
-        "db": "keycloak"
-    }
-}
-----                
-will authenticate the user against the authentication database, but store all keycloak related data in the keycloak database.
- 
-==== MongoDB Replica Sets
-
-In order to use a mongo replica set for Keycloak, one has to use URI based configuration, which supports the definition of replica sets out of the box: `mongodb://host1:27017,host2:27017,host3:27017/`. 
-
-=== Outgoing Server HTTP Requests
-
-Keycloak server needs to invoke on remote HTTP endpoints to do things like backchannel logouts and other management functions.
-Keycloak maintains a HTTP client connection pool which has various configuration settings you can specify before boot time.
-This is configured in the `standalone/configuration/keycloak-server.json`.
-By default the setting is like this: 
-
-[source]
-----
-
-"connectionsHttpClient": {
-    "default": {}
-},
-----                
-Possible configuration options are: 
-
-establish-connection-timeout-millis::
-  Timeout for establishing a socket connection. 
-
-socket-timeout-millis::
-  If an outgoing request does not receive data for this amount of time, timeout the connection. 
-
-connection-pool-size::
-  How many connections can be in the pool (128 by default). 
-
-max-pooled-per-route::
-  How many connections can be pooled per host (64 by default). 
-
-connection-ttl-millis::
-  Maximum connection time to live in milliseconds.
-  Not set by default. 
-
-max-connection-idle-time-millis::
-  Maximum time the connection might stay idle in the connection pool (900 seconds by default). Will start background cleaner thread of Apache HTTP client.
-  Set to -1 to disable this checking and the background thread. 
-
-disable-cookies::
-  `true` by default.
-  When set to true, this will disable any cookie caching. 
-
-client-keystore::
-  This is the file path to a Java keystore file.
-  This keystore contains client certificate for two-way SSL. 
-
-client-keystore-password::
-  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.
-  This is _REQUIRED_ if `client-keystore` is set.             
-
-[[_truststore]]
-=== Securing Outgoing Server HTTP Requests
-
-When Keycloak connects out to remote HTTP endpoints over secure https connection, it has to validate the other server's certificate in order to ensure it is connecting to a trusted server.
-That is necessary in order to prevent man-in-the-middle attacks. 
-
-How certificates are validated is configured in the `standalone/configuration/keycloak-server.json`.
-By default truststore provider is not configured, and any https connections fall back to standard java truststore configuration as described in https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[
-            Java's JSSE Reference Guide] - using `javax.net.ssl.trustStore system property`, otherwise `cacerts` file that comes with java is used. 
-
-Truststore is used when connecting securely to identity brokers, LDAP identity providers, when sending emails, and for backchannel communication with client applications.
-Some of these facilities may - in case when no trusted certificate is found in your configured truststore - fallback to using the JSSE provided truststore.
-The default JavaMail API implementation used to send out emails behaves in this way, for example. 
-
-You can add your truststore configuration by using the following template:  
-
-[source]
-----
-
-"truststore": {
-    "file": {
-        "file": "path to your .jks file containing public certificates",
-        "password": "password",
-        "hostname-verification-policy": "WILDCARD",
-        "disabled": false
-    }
-}
-----            
-
-Possible configuration options are:  
-
-file::
-  The value is the file path to a Java keystore file.
-  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.
-  Truststore file should only contain public certificates of your secured hosts.
-  This is _REQUIRED_ if `disabled` is not true. 
-
-password::
-  Password for the truststore.
-  This is _REQUIRED_ if `disabled` is not true. 
-
-hostname-verification-policy::
-  `WILDCARD` by default.
-  For HTTPS requests, this verifies the hostname of the server's certificate.
-   `ANY` means that the hostname is not verified. `WILDCARD` Allows wildcards in subdomain names i.e.
-  *.foo.com. `STRICT` CN must match hostname exactly. 
-
-disabled::
-  If true (default value), truststore configuration will be ignored, and certificate checking will fall back to JSSE configuration as described.
-  If set to false, you must configure `file`, and `password` for the truststore.             
-
-You can use _keytool_ to create a new truststore file and add trusted host certificates to it:  
-
-[source]
-----
-
-$ keytool -import -alias HOSTDOMAIN -keystore truststore.jks -file host-certificate.cer
-----            
-
-[[_ssl_modes]]
-=== SSL/HTTPS Requirement/Modes
-
-WARNING: Keycloak is not set up by default to handle SSL/HTTPS.
-It is highly recommended that you either enable SSL on the Keycloak server itself or on a reverse proxy in front of the Keycloak server. 
-
-Keycloak can run out of the box without SSL so long as you stick to private IP addresses like localhost, 127.0.0.1, 10.0.x.x, 192.168.x.x, and 172..16.x.x.
-If you try to access Keycloak from a non-IP adress you will get an error. 
-
-Keycloak has 3 SSL/HTTPS modes which you can set up in the admin console under the Settings->Login page and the `Require SSL` select box.
-Each adapter config should mirror this server-side setting.
-See adapter config section for more details. 
-
-external::
-  Keycloak can run out of the box without SSL so long as you stick to private IP addresses like localhost, 127.0.0.1, 10.0.x.x, 192.168.x.x, and 172..16.x.x.
-  If you try to access Keycloak from a non-IP adress you will get an error. 
-
-none::
-  Keycloak does not require SSL. 
-
-all::
-  Keycloak requires SSL for all IP addresses.             
-
-=== SSL/HTTPS Setup
-
-First enable SSL on Keycloak or on a reverse proxy in front of Keycloak.
-Then configure the Keycloak Server to enforce HTTPS connections. 
-
-==== Enable SSL on Keycloak
-
-The following things need to be done 
-
-* keytool
-* Enable Wildfly to use this certificate and turn on SSL/HTTPS.                
-
-===== Creating the Certificate and Java Keystore
-
-In order to allow HTTPS connections, you need to obtain a self signed or third-party signed certificate and import it into a Java keystore before you can enable HTTPS in the web container you are deploying the Keycloak Server to. 
-
-====== Self Signed Certificate
-
-In development, you will probably not have a third party signed certificate available to test a Keycloak deployment so you'll need to generate a self-signed on.
-Generate one is very easy to do with the `keytool` utility that comes with the Java jdk. 
-
-
-[source]
-----
-
-$ keytool -genkey -alias localhost -keyalg RSA -keystore keycloak.jks -validity 10950
-    Enter keystore password: secret
-    Re-enter new password: secret
-    What is your first and last name?
-    [Unknown]:  localhost
-    What is the name of your organizational unit?
-    [Unknown]:  Keycloak
-    What is the name of your organization?
-    [Unknown]:  Red Hat
-    What is the name of your City or Locality?
-    [Unknown]:  Westford
-    What is the name of your State or Province?
-    [Unknown]:  MA
-    What is the two-letter country code for this unit?
-    [Unknown]:  US
-    Is CN=localhost, OU=Keycloak, O=Test, L=Westford, ST=MA, C=US correct?
-    [no]:  yes
-----                        
-
-You should answer `What is your first and last name ?` question with the DNS name of the machine you're installing the server on.
-For testing purposes, `localhost` should be used.
-After executing this command, the `keycloak.jks` file will be generated in the same directory as you executed the `keytool` command in. 
-
-If you want a third-party signed certificate, but don't have one, you can obtain one for free at http://cacert.org[cacert.org].
-You'll have to do a little set up first before doing this though. 
-
-The first thing to do is generate a Certificate Request: 
-
-[source]
-----
-
-$ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq
-----                        
-
-Where `yourdomain` is a DNS name for which this certificate is generated for.
-Keytool generates the request: 
-
-[source]
-----
-
------BEGIN NEW CERTIFICATE REQUEST-----
-MIIC2jCCAcICAQAwZTELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAk1BMREwDwYDVQQHEwhXZXN0Zm9y
-ZDEQMA4GA1UEChMHUmVkIEhhdDEQMA4GA1UECxMHUmVkIEhhdDESMBAGA1UEAxMJbG9jYWxob3N0
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr7kck2TaavlEOGbcpi9c0rncY4HhdzmY
-Ax2nZfq1eZEaIPqI5aTxwQZzzLDK9qbeAd8Ji79HzSqnRDxNYaZu7mAYhFKHgixsolE3o5Yfzbw1
-29Rvy+eUVe+WZxv5oo9wolVVpdSINIMEL2LaFhtX/c1dqiqYVpfnvFshZQaIg2nL8juzZcBjj4as
-H98gIS7khql/dkZKsw9NLvyxgJvp7PaXurX29fNf3ihG+oFrL22oFyV54BWWxXCKU/GPn61EGZGw
-Ft2qSIGLdctpMD1aJR2bcnlhEjZKDksjQZoQ5YMXaAGkcYkG6QkgrocDE2YXDbi7GIdf9MegVJ35
-2DQMpwIDAQABoDAwLgYJKoZIhvcNAQkOMSEwHzAdBgNVHQ4EFgQUQwlZJBA+fjiDdiVzaO9vrE/i
-n2swDQYJKoZIhvcNAQELBQADggEBAC5FRvMkhal3q86tHPBYWBuTtmcSjs4qUm6V6f63frhveWHf
-PzRrI1xH272XUIeBk0gtzWo0nNZnf0mMCtUBbHhhDcG82xolikfqibZijoQZCiGiedVjHJFtniDQ
-9bMDUOXEMQ7gHZg5q6mJfNG9MbMpQaUVEEFvfGEQQxbiFK7hRWU8S23/d80e8nExgQxdJWJ6vd0X
-MzzFK6j4Dj55bJVuM7GFmfdNC52pNOD5vYe47Aqh8oajHX9XTycVtPXl45rrWAH33ftbrS8SrZ2S
-vqIFQeuLL3BaHwpl3t7j2lMWcK1p80laAxEASib/fAwrRHpLHBXRcq6uALUOZl4Alt8=
------END NEW CERTIFICATE REQUEST-----
-----                        
-
-Send this ca request to your CA.
-The CA will issue you a signed certificate and send it to you.
-Before you import your new cert, you must obtain and import the root certificate of the CA.
-You can download the cert from CA (ie.: root.crt) and import as follows: 
-
-[source]
-----
-
-$ keytool -import -keystore keycloak.jks -file root.crt -alias root
-----                        
-
-Last step is import your new CA generated certificate to your keystore: 
-
-[source]
-----
-
-$ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer
-----                        
-
-===== Installing the keystore to WildFly
-
-Now that you have a Java keystore with the appropriate certificates, you need to configure your Wildfly installation to use it.
-First step is to move the keystore file to a directory you can reference in configuration.
-I like to put it in `standalone/configuration`.
-Then you need to edit `standalone/configuration/standalone.xml` to enable SSL/HTTPS. 
-
-To the `security-realms` element add: 
-
-[source]
-----
-
-<security-realm name="UndertowRealm">
-    <server-identities>
-        <ssl>
-            <keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="secret" />
-        </ssl>
-    </server-identities>
-</security-realm>
-----                    
-
-Find the element `server name="default-server"` (it's a child element of `subsystem xmlns="urn:jboss:domain:undertow:1.0"`) and add: 
-
-[source]
-----
-<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
-----                    
-
-Check the https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration[Wildfly Undertow] documentation for more information on fine tuning the socket connections. 
-
-==== Enable SSL on a Reverse Proxy
-
-Follow the documentation for your web server to enable SSL and configure reverse proxy for Keycloak.
-It is important that you make sure the web server sets the `X-Forwarded-For` and `X-Forwarded-Proto` headers on the requests made to Keycloak.
-Next you need to enable `proxy-address-forwarding` on the Keycloak http connector.
-Assuming that your reverse proxy doesn't use port 8443 for SSL you also need to configure what port http traffic is redirected to. 
-
-===== Configure WildFly
-
-. Open `standalone/configuration/standalone.xml` in your favorite editor. 
-
-. First add `proxy-address-forwarding` and `redirect-socket` to the `http-listener` element: 
-
-[source]
-----
-<subsystem xmlns="urn:jboss:domain:undertow:1.1">
-    ...
-    <http-listener name="default" socket-binding="http"
-        proxy-address-forwarding="true" redirect-socket="proxy-https"/>
-    ...
-</subsystem>
-----                    
-
-Then add a new `socket-binding` element to the `socket-binding-group` element: 
-
-[source]
-----
-
-<socket-binding-group name="standard-sockets" default-interface="public"
-    port-offset="${jboss.socket.binding.port-offset:0}">
-    ...
-    <socket-binding name="proxy-https" port="443"/>
-    ...
-</socket-binding-group>
-----                    
-
-Check the https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration[WildFly] documentation for more information. 
-
-== Keycloak server in Domain Mode
-
-In domain mode, you start the server with the "domain" command instead of the "standalone" command.
-In this case, the Keycloak subsystem is defined in domain/configuration/domain.xml instead of standalone/configuration.standalone.xml.
-Inside domain.xml, you will see more than one profile.
-The Keycloak subsystem is defined for all initial profiles. 
-
-THe server is also added to server profiles.
-By default two servers are started in the main-server-group which uses the full profile. 
-
-You need to make sure `domain/servers/SERVER NAME/configuration` is identical for all servers in a group. 
-
-To deploy custom providers and themes you should deploys these as modules and make sure the modules are available to all servers in the group.
-See <<_providers,Providers>> and <<_themes,Themes>> sections for more information on how to do this. 
-
-== Installing Keycloak Server as Root Context
-
-The Keycloak server can be installed as the default web application.
-In doing so, the server can be referenced at `http://mydomain.com/` instead of `http://mydomain.com/auth`. 
-
-To do this, add the `default-web-module` attribute in the Undertow subystem in standalone.xml. 
-
-[source]
-----
-
-<subsystem xmlns="urn:jboss:domain:undertow:2.0">
-    <server name="default-server">
-        <host name="default-host" alias="localhost" default-web-module="keycloak-server.war">
-            <location name="/" handler="welcome-content"/>
-        </host>
-----        
-
-`keycloak-server.war` is the runtime name of the Keycloak server application.
-Note that the WAR file does not exist as a file.
-If its name changes (ie. `keycloak-server.war`) in the future, find its new name from the Keycloak log entry with `runtime-name:`. 
-
-
-
-NOTE: If you have run your server before altering the root context, your database will contain references to the old /auth context. Your clients may also have incorrect references.
-To fix this on the server side, you will need to export your database to json, make corrections, and then import.
-Client-side `keycloak.json` files will need to be updated manually as well.

topics/openshift.adoc

@@ -1,3 +1,4 @@
+
 [[_openshift]]
 
 == Running Keycloak Server on OpenShift

topics/operating-mode.adoc

@@ -1,3 +1,4 @@
+
 [[_operating_mode]]
 
 == Choosing an Operating Mode

topics/operating-mode/domain.adoc

@@ -1,3 +1,4 @@
+
 [[_domain-mode]]
 === Domain Clustered Mode
 
@@ -72,7 +73,7 @@ The `auth-server-standalone` profile is a non-clustered setup.  The `auth-server
 
 If you scroll down further, you'll see various `socket-binding-groups` defined.
 
-.socket-binding-grous
+.socket-binding-groups
 [source,xml]
 ----
     <socket-binding-groups>
@@ -86,7 +87,8 @@ If you scroll down further, you'll see various `socket-binding-groups` defined.
         <socket-binding-group name="load-balancer-sockets" default-interface="public">
            ...
         </socket-binding-group>
-    </socket-binding-groups>----
+    </socket-binding-groups>
+----
 
 
 This config defines the default port mappings for various connectors that are opened with each

topics/operating-mode/standalone-ha.adoc

@@ -1,3 +1,4 @@
+
 [[_standalone-ha-mode]]
 
 === Standalone Clustered Mode

topics/operating-mode/standalone.adoc

@@ -1,3 +1,4 @@
+
 [[_standalone-mode]]
 === Standalone Mode
 

topics/overview.adoc

@@ -1,3 +1,4 @@
+
 == Guide Overview
 
 The purpose of this guide is to walk through the steps that need to be completed prior to booting up the

topics/overview/recommended-reading.adoc

@@ -1,3 +1,4 @@
+
 === Recommended Additional External Documentation
 
 {{book.project.name}} is built upon a derivative of the {{book.appserver.name}} Application Server and projects embedded

topics/proxy.adoc

@@ -1,3 +1,4 @@
+
 [[_proxy]]
 == Keycloak Security Proxy
 
@@ -147,7 +148,7 @@ adapter-config::
   Same configuration as any other keycloak adapter.
   See <<_adapter_config,Adapter Config>>                                        
 
-===== Constraint Config
+==== Constraint Config
 
 Next under each application you can define one or more constraints in the `constraints` array attribute.
 A constraint defines a URL pattern relative to the base-path.