initial move

SUMMARY.adoc

@@ -0,0 +1,14 @@
+== Keycloak Reference Guide
+
+//. link:topics/templates/document-attributes.adoc[]
+:imagesdir: images
+
+ . link:topics/preface.adoc[Preface]
+ . link:topics/Overview.adoc[Overview]
+ . link:topics/server-installation.adoc[Installation and Configuration of Keycloak Server]
+ . link:topics/openshift.adoc[Running Keycloak Server on OpenShift]
+ . link:topics/cache.adoc[Server Cache]
+ . link:topics/clustering.adoc[Clustering]
+ . link:topics/proxy.adoc[Keycloak Security Proxy]
+
+

topics/cache.adoc

@@ -0,0 +1,58 @@
+= Server Cache
+
+By default, Keycloak caches realm metadata and users.
+There are two separate caches, one for realm metadata (realm, application, client, roles, etc...) and one for users.
+These caches greatly improves the performance of the server. 
+
+== Eviction and Expiration
+
+By default the user cache contains a maximum of 10000 entries.
+This is not 10000 users, but 10000 entries in the cache.
+You can change the maximum number of entries by editing the server configuration `standalone.xml` or `standalone-ha.xml`.
+Locate the element `cache-container name="keycloak"` and change the eviction policy for the `users` cache.
+For more information see https://docs.jboss.org/author/display/WFLY10/Infinispan+Subsystem[Infinispan Subsystem documentation]. 
+
+== Disabling Caches
+
+To disable the realm or user cache, you must edit the `keycloak-server.json` file in your distribution.
+Here's what the config looks like initially. 
+
+
+[source]
+----
+
+    "userCache": {
+        "infinispan" : {
+            "enabled": true
+        }
+    },
+
+    "realmCache": {
+        "infinispan" : {
+            "enabled": true
+        }
+    },
+----        
+
+To disable the cache set the enabled field to false for the cache you want to disable: 
+[source]
+----
+
+    "userCache": {
+        "infinispan" : {
+            "enabled": false
+        }
+    },
+
+    "realmCache": {
+        "infinispan" : {
+            "enabled": false
+        }
+    },
+----        
+
+== Clear Caches
+
+To clear the realm or user cache, go to the Keycloak admin console Realm Settings->Cache Config page.
+On this page you can clear the realm cache or the user cache.
+This will clear the caches for all realms and not only the selected realm. 

topics/openshift.adoc

@@ -0,0 +1,44 @@
+[[_openshift]]
+
+= Running Keycloak Server on OpenShift
+
+Keycloak provides a OpenShift cartridge to make it easy to get it running on OpenShift.
+If you don't already have an account or don't know how to create applications go to https://www.openshift.com/        first.
+You can create the Keycloak instance either with the web tool or the command line tool, both approaches are described below. 
+
+WARNING: It's important that immediately after creating a Keycloak instance you open the `Administration Console`            and login to reset the password.
+If this is not done anyone can easily gain admin rights to your Keycloak instance. 
+
+== Create Keycloak instance with the web tool
+
+. Open https://openshift.redhat.com/app/console/applications and click on `Add Application`.
+. Scroll down to the bottom of the page to find the `Code Anything` section.
+. Insert `http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge` into the `URL to a cartridge definition` field and click on `Next`.
+. Fill in the following form and click on `Create Application`. 
+. Click on `Continue to the application overview page`.
+. Under the list of applications you should find your Keycloak instance and the status should be `Started`.
+. Click on it to open the Keycloak servers homepage. 
+
+== Create Keycloak instance with the command-line tool
+
+. Run the following command from a terminal: 
+
+[source]
+----
+rhc app create <APPLICATION NAME> http://cartreflect-claytondev.rhcloud.com/github/keycloak/openshift-keycloak-cartridge
+----	
+            
+. Replace `<APPLICATION NAME>` with the name you want (for example keycloak). 
+
+Once the instance is created the rhc tool outputs details about it.
+Open the returned `URL` in a browser to open the Keycloak servers homepage. 
+
+== Next steps
+
+The Keycloak servers homepage shows the Keycloak logo and `Welcome to Keycloak`.
+There is also a link to the `Administration Console`.
+Open that and log in using username `admin` and password `admin`.
+On the first login you are required to change the password. 
+
+TIP: On OpenShift Keycloak has been configured to only accept requests over https.
+If you try to use http you will be redirected to https. 

topics/preface.adoc

@@ -0,0 +1,20 @@
+= 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: 
+
+[source]
+----
+Let's pretend to have an extremely \
+long line that \
+does not fit
+This one is short
+----         
+Is really: 
+
+[source]
+----
+Let's pretend to have an extremely long line that does not fit
+This one is short
+----      
+

topics/proxy.adoc

@@ -0,0 +1,238 @@
+[[_proxy]]
+= Keycloak Security Proxy
+
+Keycloak has an HTTP(S) proxy that you can put in front of web applications and services where it is not possible to install the keycloak adapter.
+You can set up URL filters so that certain URLs are secured either by browser login and/or bearer token authentication.
+You can also define role constraints for URL patterns within your applications. 
+
+== Proxy Install and Run
+
+Download the keycloak proxy distribution from the Keycloak download pages and unzip it. 
+[source]
+----
+
+$ unzip keycloak-proxy-dist.zip
+----        
+
+To run it you must have a proxy config file (which we'll discuss in a moment). 
+[source]
+----
+
+$ java -jar bin/launcher.jar [your-config.json]
+----        
+
+If you do not specify a path to the proxy config file, the launcher will look in the current working directory for the file named `proxy.json`        
+
+== Proxy Configuration
+
+Here's an example configuration file. 
+[source]
+----
+
+{
+    "target-url": "http://localhost:8082",
+    "send-access-token": true,
+    "bind-address": "localhost",
+    "http-port": "8080",
+    "https-port": "8443",
+    "keystore": "classpath:ssl.jks",
+    "keystore-password": "password",
+    "key-password": "password",
+    "applications": [
+        {
+            "base-path": "/customer-portal",
+            "error-page": "/error.html",
+            "adapter-config": {
+                "realm": "demo",
+                "resource": "customer-portal",
+                "realm-public-key": "MIGfMA0GCSqGSIb",
+                "auth-server-url": "http://localhost:8081/auth",
+                "ssl-required" : "external",
+                "principal-attribute": "name",
+                "credentials": {
+                    "secret": "password"
+                }
+            }
+            ,
+            "constraints": [
+                {
+                    "pattern": "/users/*",
+                    "roles-allowed": [
+                        "user"
+                    ]
+                },
+                {
+                    "pattern": "/admins/*",
+                    "roles-allowed": [
+                        "admin"
+                    ]
+                },
+                {
+                    "pattern": "/users/permit",
+                    "permit": true
+                },
+                {
+                    "pattern": "/users/deny",
+                    "deny": true
+                }
+            ]
+        }
+    ]
+}
+----        
+
+=== Basic Config
+
+The basic configuration options for the server are as follows: 
+
+target-url::
+  The URL this server is proxying _REQUIRED._. 
+
+send-access-token::
+  Boolean flag.
+  If true, this will send the access token via the KEYCLOAK_ACCESS_TOKEN header to the proxied server. _OPTIONAL._.
+  Default is false. 
+
+bind-address::
+  DNS name or IP address to bind the proxy server's sockets to. _OPTIONAL._.
+  The default value is _localhost_                        
+
+http-port::
+  Port to listen for HTTP requests.
+  If you do not specify this value, then the proxy will not listen for regular HTTP requests. _OPTIONAL._. 
+
+https-port::
+  Port to listen for HTTPS requests.
+  If you do not specify this value, then the proxy will not listen for HTTPS requests. _OPTIONAL._. 
+
+keystore::
+  Path to a Java keystore file that contains private key and certificate for the server to be able to handle HTTPS requests.
+  Can be a file path, or, if you prefix it with `classpath:`                            it will look for this file in the classpath. _OPTIONAL._.
+  If you have enabled HTTPS, but have not defined a keystore, the proxy will auto-generate a self-signed certificate and use that. 
+
+buffer-size::
+  HTTP server socket buffer size.
+  Usually the default is good enough. _OPTIONAL._. 
+
+buffers-per-region::
+  HTTP server socket buffers per region.
+  Usually the default is good enough. _OPTIONAL._. 
+
+io-threads::
+  Number of threads to handle IO.
+  Usually default is good enough.
+   _OPTIONAL._.
+  The default is the number of available processors * 2. 
+
+worker-threads::
+  Number of threads to handle requests.
+  Usually the default is good enough. _OPTIONAL._.
+  The default is the number of available processors * 16.         
+
+=== Application Config
+
+Next under the `applications` array attribute, you can define one or more applications per host you are proxying. 
+
+base-path::
+  The base context root for the application.
+  Must start with '/' _REQUIRED._. 
+
+error-page::
+  If the proxy has an error, it will display the target application's error page relative URL _OPTIONAL._.
+  This is a relative path to the base-path.
+  In the example above it would be `/customer-portal/error.html`. 
+
+adapter-config::
+  _REQUIRED._.
+  Same configuration as any other keycloak adapter.
+  See <<_adapter_config,Adapter 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.
+You can deny, permit, or require authentication for a specific URL pattern.
+You can specify roles allowed for that path as well.
+More specific constraints will take precedence over more general ones. 
+
+pattern::
+  URL pattern to match relative to the base-path of the application.
+  Must start with '/' _REQUIRED._.
+  You may only have one wildcard and it must come at the end of the pattern.
+  Valid `/foo/bar/*` and  `/foo/*.txt`                                    Not valid: `/*/foo/*`. 
+
+roles-allowed::
+  Array of strings of roles allowed to access this url pattern. _OPTIONAL._. 
+
+methods::
+  Array of strings of HTTP methods that will exclusively match this pattern and HTTP request. _OPTIONAL._. 
+
+excluded-methods::
+  Array of strings of HTTP methods that will be ignored when match this pattern. _OPTIONAL._. 
+
+deny::
+  Deny all access to this URL pattern. _OPTIONAL._. 
+
+permit::
+  Permit all access without requiring authentication or a role mapping. _OPTIONAL._. 
+
+permit-and-inject::
+  Permit all access, but inject the headers, if user is already authenticated._OPTIONAL._. 
+
+authenticate::
+  Require authentication for this pattern, but no role mapping. _OPTIONAL._.                 
+
+=== Header Names Config
+
+Next under the list of applications you can override the defaults for the names of the header fields injected by the proxy (see Keycloak Identity Headers). This mapping is optional. 
+
+keycloak-subject::
+  e.g.
+  MYAPP_USER_ID 
+
+keycloak-username::
+  e.g.
+  MYAPP_USER_NAME 
+
+keycloak-email::
+  e.g.
+  MYAPP_USER_EMAIL 
+
+keycloak-name::
+  e.g.
+  MYAPP_USER_ID 
+
+keycloak-access-token::
+  e.g.
+  MYAPP_ACCESS_TOKEN             
+
+== Keycloak Identity Headers
+
+When forwarding requests to the proxied server, Keycloak Proxy will set some additional headers with values from the OIDC identity token it received for authentication. 
+
+KEYCLOAK_SUBJECT::
+  User id.
+  Corresponds to JWT `sub` and will be the user id Keycloak uses to store this user. 
+
+KEYCLOAK_USERNAME::
+  Username.
+  Corresponds to JWT `preferred_username`                        
+
+KEYCLOAK_EMAIL::
+  Email address of user if set. 
+
+KEYCLOAK_NAME::
+  Full name of user if set. 
+
+KEYCLOAK_ACCESS_TOKEN::
+  Send the access token in this header if the proxy was configured to send it.
+  This token can be used to make bearer token requests.             Header field names can be configured using a map of `header-names` in configuration file: 
+[source]
+----
+
+{
+    "header-names" {
+        "keycloak-subject": "MY_SUBJECT"
+    }
+}
+----        

topics/server-installation.adoc

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