diff --git a/SUMMARY.adoc b/SUMMARY.adoc index a8f59995e7..701c2ea4d9 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -5,7 +5,7 @@ . link:topics/preface.adoc[Preface] . link:topics/overview.adoc[Overview] - . link:topics/server-installation.adoc[Installation and Configuration of Keycloak Server] + . link:topics/system-requirements.adoc[System Requirements] . link:topics/installation.adoc[Installation and Configuration of Keycloak Server] . link:topics/openshift.adoc[Running Keycloak Server on OpenShift] . link:topics/cache.adoc[Server Cache] diff --git a/SUMMARY.md b/SUMMARY.md deleted file mode 100755 index e0f16866ad..0000000000 --- a/SUMMARY.md +++ /dev/null @@ -1,8 +0,0 @@ -# Summary - - -* [Preface](topics/preface.adoc) - -Test replacement {{book.project.name}} - - diff --git a/topics/clustering.adoc b/topics/clustering.adoc index 130c7c3256..2f644235dd 100755 --- a/topics/clustering.adoc +++ b/topics/clustering.adoc @@ -1,16 +1,4 @@ -= Clustering - -To improve availability and scalability Keycloak can be deployed in a cluster. - -It's fairly straightforward to configure a Keycloak cluster, the steps required are: - -* Configure a shared database -* Configure Infinispan -* Enable realm and user cache invalidation -* Enable distributed user sessions -* Start in HA mode - -== Configure a shared database +[[_clustering]] Keycloak doesn't replicate realms and users, but instead relies on all nodes using the same database. This can be a relational database or Mongo. diff --git a/topics/installation.adoc b/topics/installation.adoc index 021e608749..697f2483e6 100755 --- a/topics/installation.adoc +++ b/topics/installation.adoc @@ -1,7 +1,610 @@ -= Installation +[[_server_installation]] -This chapter shows you how to install Keycloak and walks you through the directory structure of an installation. += Installation and Configuration of Keycloak Server -== Unpackaging Keycloak +== Installation -<<_server_install>> \ No newline at end of file +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 -p +---- +Then restart the server. +For `keycloak-overlay`, please make sure to use: + +[source] +---- +bin/add-user-keycloak.[sh|bat] -r master -u -p +---- + +=== 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] +---- + + + + + + + + +---- + +Find the element `server name="default-server"` (it's a child element of `subsystem xmlns="urn:jboss:domain:undertow:1.0"`) and add: + +[source] +---- + +---- + +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] +---- + + ... + + ... + +---- + +Then add a new `socket-binding` element to the `socket-binding-group` element: + +[source] +---- + + + ... + + ... + +---- + +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] +---- + + + + + + +---- + +`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. diff --git a/topics/installation/getting-files-community.adoc b/topics/installation/getting-files-community.adoc new file mode 100755 index 0000000000..13d2be6ec3 --- /dev/null +++ b/topics/installation/getting-files-community.adoc @@ -0,0 +1,11 @@ += Getting Distribution Files + +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] + + + diff --git a/topics/overview.adoc b/topics/overview.adoc index 64136a69d4..87ab32f51e 100755 --- a/topics/overview.adoc +++ b/topics/overview.adoc @@ -1,10 +1,10 @@ = Guide Overview The purpose of this guide is to walk through the steps that need to be completed prior to booting up the -Keycloak server for the first time. If you just want to test drive Keycloak, it pretty much runs out of the box with its +{{book.project.name}} server for the first time. If you just want to test drive {{book.project.name}}, it pretty much runs out of the box with its own embedded and local-only database. For actual deployments that are going to be run in production you'll need to decide how you want to manage server configuration - at runtime (standalone or domain mode), configure a shared database you will use for Keycloak, set up encryption and HTTPS, - and finally set up Keycloak to run in a cluster. This guide walks through each and every aspect of any pre-boot - decisions and setup you must do prior to deploying Keycloak. + at runtime (standalone or domain mode), configure a shared database for {{book.project.name}} storage, set up encryption and HTTPS, + and finally set up {{book.project.name}} to run in a cluster. This guide walks through each and every aspect of any pre-boot + decisions and setup you must do prior to deploying the server. diff --git a/topics/preface.adoc b/topics/preface.adoc index 46e39e8ae6..3a0cd073cb 100755 --- a/topics/preface.adoc +++ b/topics/preface.adoc @@ -18,4 +18,3 @@ Let's pretend to have an extremely long line that does not fit This one is short ---- -Test if attribute is working {{book.project.name}} \ No newline at end of file diff --git a/topics/server-installation.adoc b/topics/server-installation.adoc deleted file mode 100755 index 697f2483e6..0000000000 --- a/topics/server-installation.adoc +++ /dev/null @@ -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 -p ----- -Then restart the server. -For `keycloak-overlay`, please make sure to use: - -[source] ----- -bin/add-user-keycloak.[sh|bat] -r master -u -p ----- - -=== 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] ----- - - - - - - - - ----- - -Find the element `server name="default-server"` (it's a child element of `subsystem xmlns="urn:jboss:domain:undertow:1.0"`) and add: - -[source] ----- - ----- - -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] ----- - - ... - - ... - ----- - -Then add a new `socket-binding` element to the `socket-binding-group` element: - -[source] ----- - - - ... - - ... - ----- - -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] ----- - - - - - - ----- - -`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. diff --git a/topics/system-requirements.adoc b/topics/system-requirements.adoc new file mode 100755 index 0000000000..2d0ea122cb --- /dev/null +++ b/topics/system-requirements.adoc @@ -0,0 +1,9 @@ += System Requirements + +These are the requirements to run the {{book.project.name}} authentication server: + +* Java 8 JDK +* Network multicast support if you clustering {{book.project.name}}. + +{{book.project.name}} can be clustered without multicast, but this requires a bunch of configuration changes. Please see +the <<_clustering,clustering>> section of this guide for more information. \ No newline at end of file