Keycloak Server has three downloadable distributions. keycloak-&project.version;.[zip|tar.gz] - Standalone server keycloak-overlay-&project.version;.[zip|tar.gz] - Installer for WildFly or JBoss EAP keycloak-demo-&project.version;.[zip|tar.gz] - Development bundle including WildFly, Keycloak, examples and documentation

For production and for non-JavaEE developers we recommend using the standalone Keycloak server. All you need to do is to download keycloak-&project.version;.zip or keycloak-&project.version;.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: keycloak-&project.version;/bin/standalone.sh or: keycloak-&project.version;/bin/standalone.bat Once the server is started log into the admin console at http://localhost:8080/auth/admin/index.html (username: admin and password: admin). Keycloak will then prompt you to enter in a new password.

Keycloak can be installed into an existing WildFly 9.0.0.Final server. To do this download keycloak-overlay-&project.version;.zip or keycloak-overlay-&project.version;.tar.gz. Once downloaded extract into the root directory of your WildFly installation. To start WildFly with Keycloak run: <WILDFLY_HOME>/bin/standalone.sh --server-config=standalone-keycloak.xml or: <WILDFLY_HOME>/bin/standalone.bat --server-config=standalone-keycloak.xml Once the server is started log into the admin console at http://localhost:8080/auth/admin/index.html (username: admin and password: admin). Keycloak will then prompt you to enter in a new password.

Same procedure as WildFly 9.0.0.Final, but download keycloak-overlay-eap6-&project.version;.zip or keycloak-overlay-eap6-&project.version;.tar.gz.

The demo bundle contains everything you need to get started with Keycloak including documentation and examples. To install it first download keycloak-demo-&project.version;.zip or keycloak-demo-&project.version;.tar.gz. Once downloaded extract it inside keycloak-demo-&project.version; you'll find keycloak which contains a full WildFly 9.0.0.Final 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: keycloak-&project.version;/bin/standalone.sh or: keycloak-&project.version;/bin/standalone.bat Once the server is started log into the admin console at http://localhost:8080/auth/admin/index.html (username: admin and password: admin). Keycloak will then prompt you to enter in a new password.

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

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 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: 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) schema Specify the database schema to use

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 in some cases, you must manually set the proper dialect, as the default dialect may not work correctly. You can setup dialect by adding property driverDialect to the keycloak-server.json into connectionsJpa section (see above). Database JDBC driver Hibernate Dialect H2 1.3.161 H2 1.3.161 auto MySQL 5.5 MySQL Connector/J 5.1.25 auto PostgreSQL 9.2 JDBC4 Postgresql Driver, Version 9.3-1100 auto Oracle 11g R1 Oracle JDBC Driver v11.1.0.7 auto Microsoft SQL Server 2012 Microsoft SQL Server JDBC Driver 4.0.2206.100 org.hibernate.dialect.SQLServer2008Dialect Sybase ASE 15.7 JDBC(TM)/7.07 ESD #5 (Build 26792)/P/EBF20686 auto

Keycloak provides 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: to: And at the end of the file add the snippet like this where you can configure details about your Mongo database: 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 Mongo documentation for details about those options and their default values. Alternatively, you can configure MongoDB using a MongoDB 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 will authenticate the user against the authentication database, but store all keycloak related data in the keycloak database.

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/.

Keycloak provides a JSON file based model implementation, which means that your identity data will be saved in a flat JSON text file instead of traditional RDBMS. The performance of this implementaion is likely to be slower because it reads and writes the entire file with each call to the Keycloak REST API. But it is very useful in development to see exactly what is being saved. It is not recommended for production. Note that this only applies to realm and user data. There is currently no file implementation for event persistence. So you will need to use JPA or Mongo for that. To configure Keycloak to use file persistence open standalone/configuration/keycloak-server.json in your favourite editor. Change the realm and user providers and disable caching. Change: to: You can also change the location of the data file by adding a connectionsFile snippet: All configuration options are optional. Default value for directory is ${jboss.server.data.dir}. Default file name is keycloak-model.json.

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: 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. max-pooled-per-route How many connections can be pooled per host. disable-trust-manager If true, HTTPS server certificates are not verified. If you set this to false, you must configure a truststore. disable-cookies true by default. When set to true, this will disable any cookie caching. 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. truststore The value is the file path to a Java keystore file. If you prefix the path with classpath:, then the truststore will be obtained from the deployment's classpath instead. 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-password Password for the truststore keystore. This is REQUIRED if truststore is set. 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.

Keycloak is not set up by default to handle SSL/HTTPS in either the war distribution or appliance. 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.

First enable SSL on Keycloak or on a reverse proxy in front of Keycloak. Then configure the Keycloak Server to enforce HTTPS connections.

The following things need to be done Generate a self signed or third-party signed certificate and import it into a Java keystore using keytool. Enable Wildfly to use this certificate and turn on SSL/HTTPS.

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.

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. $ 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 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: $ 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: -----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: $ keytool -import -keystore keycloak.jks -file root.crt -alias root Last step is import your new CA generated certificate to your keystore: $ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer

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: ]]> Find the element <server name="default-server"> (it's a child element of <subsystem xmlns="urn:jboss:domain:undertow:1.0">) and add: ]]> Check the Wildfly Undertow documentation for more information on fine tuning the socket connections.

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.

Open standalone/configuration/standalone.xml in your favorite editor. First add proxy-address-forwarding and redirect-socket to the http-listener element: ... ... ]]> Then add a new socket-binding element to the socket-binding-group element: ... ... ]]> Check the WildFly documentation for more information.

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. A Keycloak subsystem can be defined in zero or more of those profiles. To enable Keycloak for a server profile edit domain/configuration/domain.xml. To the extensions element add the Keycloak extension: ... ]]> Then you need to add the server to the required server profiles. By default WildFly starts two servers in the main-server-group which uses the full profile. To add Keycloak for this profile add the Keycloak subsystem to the profile element with name full: ... true auth ]]> To configure the server copy standalone/configuration/keycloak-server.json to domain/servers/<SERVER NAME>/configuration. The configuration should be identical for all servers in a group. Follow the Clustering section of the documentation to configure Keycloak for clustering. In domain mode it doesn't make much sense to not configure Keycloak in cluster mode. 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 and Themes sections for more information on how to do this.

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. ]]> 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:. 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.