JBoss.orgCommunity Documentation
The Keycloak Server has two downloadable distributions.
The
keycloak-appliance-dist-all.zip
is quite large, but contains a complete server (backed by Wildfly)
that runs out of the box. The only thing you'll have to enable and configure is SSL. Unzipping it, the
directory layout looks
something like this:
keycloak-appliance-dist-all-1.0-rc-2/ keycloak/ bin/ standalone.sh standalone.bat standalone/deployments/ auth-server.war/ standalone/configuration/ keycloak-server.json themes/ adapters/ keycloak-as7-adapter-dist-1.0-rc-2.zip keycloak-eap6-adapter-dist-1.0-rc-2.zip keycloak-wildfly-adapter-dist-1.0-rc-2.zip examples/ docs/
The
standalone.sh
or
standalone.bat
script is used to start the server.
After executing that, log into the admin console at
http://localhost:8080/auth/admin/index.html.
Username: admin
Password: admin. Keycloak will then prompt you to
enter in a new password.
The
keycloak-war-dist-all.zip
contains
just the bits you need to install keycloak on your favorite web container. We currently only support
installing it on top of an existing JBoss AS 7.1.1, JBoss EAP 6.x, or Wildfly 8 distribution. We may in the
future provide directions on how to install it on another web container like Tomcat or Jetty. If anybody
in the community is interested in pulling this together, please contact us. Its mostly Maven pom work.
The directory structure of this distro looks like this:
keycloak-war-dist-all-1.0-rc-2/ deployments/ auth-server.war/ keycloak-ds.xml configuration/ keycloak-server.json themes/ adapters/ keycloak-as7-adapter-dist-1.0-rc-2.zip keycloak-eap6-adapter-dist-1.0-rc-2.zip keycloak-wildfly-adapter-dist-1.0-rc-2.zip examples/ docs/
After unzipping this file, copy everything in deployments
directory into the
standalone/deployments
of your JBoss or Wildfly distro. Also, copy everything in
configuration
directory into the standalone/configuration
directory.
$ cd keycloak-war-dist-all-1.0-rc-2 $ cp -r deployments $JBOSS_HOME/standalone $ cp -r configuration $JBOSS_HOME/standalone
After these steps you should also install the client adapter as this may contain modules the server needs (like Bouncycastle). You will also need to install the adapter to run the examples on the same server.
After booting up the JBoss or Wildfly distro, you can then make sure it is installed properly by logging into the admin console at http://localhost:8080/auth/admin/index.html. Username: admin 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:
By default, Keycloak uses a relational database to store Keycloak data. This datasource is the .../standalone/deployments/keycloak-ds.xml
file of your Keycloak Server installation if you used Section 3.2, “WAR Distribution Installation” or in .../standalone/configuration/standalone.xml
if you used Section 3.1, “Appliance Install”. File keycloak-ds.xml
is used in WAR
distribution, so that you have datasource available out of the box and you don't need to edit standalone.xml
file.
However a good thing is to always delete the file keycloak-ds.xml
and move its configuration text
into the centrally managed standalone.xml
file.
This will allow you to manage the database connection pool from the Wildfly/JBoss administration console. Here's what
.../standalone/configuration/standalone.xml
should look like after you've done this:
<subsystem xmlns="urn:jboss:domain:datasources:2.0"> <datasources> <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url> <driver>h2</driver> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true"> <connection-url>jdbc:h2:${jboss.server.data.dir}/keycloak;AUTO_SERVER=TRUE</connection-url> <driver>h2</driver> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> <drivers> <driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem>
Besides moving the database config into the central standalone.xml
configuration file
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,
JBoss AS7,
or JBoss EAP 6.x documentation on how to do this.
Keycloak also runs on a Hibernate/JPA backend which is configured in the
standalone/configuration/keycloak-server.json
.
By default the setting is like this:
"connectionsJpa": { "default": { "dataSource": "java:jboss/datasources/KeycloakDS", "databaseSchema": "update" } },
Possible configuration options are:
Allow you to specify name of persistence unit if you want to provide your own persistence.xml file for JPA configuration. If this option is used, then all other configuration options are ignored as you are expected to configure all JPA/DB properties in your own persistence.xml file. Hence you can remove properties "dataSource" and "databaseSchema" in this case.
JNDI name of the dataSource
boolean property to specify if datasource is JTA capable
Value of Hibernate dialect. In most cases you don't need to specify this property as dialect will be autodetected by Hibernate.
Value of database schema (Hibernate property "hibernate.hbm2ddl.auto" ).
Specify whether Hibernate should show all SQL commands in the console (false by default)
Specify whether Hibernate should format SQL commands (true by default)
For more info about Hibernate properties, see Hibernate and JPA documentation .
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).
Table 3.1. Tested databases
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:
"eventsStore": { "provider": "jpa", "jpa": { "exclude-events": [ "REFRESH_TOKEN" ] } }, "realm": { "provider": "jpa" }, "user": { "provider": "${keycloak.user.provider:jpa}" },
to:
"eventsStore": { "provider": "mongo", }, "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:
"connectionsMongo": { "default": { "host": "127.0.0.1", "port": "27017", "db": "keycloak" } }
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.
Accessing the admin console will get these annoying log messages:
WARN [org.jboss.resteasy.core.ResourceLocator] (http-/127.0.0.1:8080-3) Field providers of subresource xxx will not be injected according to spec
These can be ignored by editing standalone.xml of your jboss installation:
<logger category="org.jboss.resteasy.core.ResourceLocator"> <level name="ERROR"/> </logger>
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.
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 does not require SSL.
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
keytool
.
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 the 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:
<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:
<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
Check the Wildfly Undertow documentation for more information on fine tuning the socket connections.
Now that you have a Java keystore with the appropriate certificates, you need to configure your
JBoss EAP6/AS7 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.
<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false"> <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http" redirect-port="443" /> <connector name="https" scheme="https" protocol="HTTP/1.1" socket-binding="https" enable-lookups="false" secure="true"> <ssl name="localhost-ssl" password="secret" protocol="TLSv1" key-alias="localhost" certificate-key-file="${jboss.server.config.dir}/keycloak.jks" /> </connector> ... </subsystem>
Check the JBoss 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.
This is done by editing standalone/configuration/standalone.xml
.
proxy-address-forwarding
and redirect-socket
to the http-listener
element:
<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:
<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 WildFly documentation for more information.
Servlet containers can force browsers and other HTTP clients to use HTTPS. You have to configure this in
.../standalone/deployments/auth-server.war/WEB-INF/web.xml
. All you have to do is
uncomment out the security constraint.
<web-app> ... <security-constraint> <web-resource-collection> <url-pattern>/*</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> </web-app>
In Keycloak, each realm has an "Require SSL" switch that you should turn on. Log into the
adminstration console and set this switch for each realm that Keycloak manages. This switch is on
the Settings>>General
page. While this switch does do similar checks as the security
constraint in web.xml
, it will also force applications and oauth clients to only
register HTTPS based redirect URLs.