JBoss.orgCommunity Documentation

Chapter 3. Installation and Configuration of Keycloak Server

3.1. Appliance Install
3.2. WAR Distribution Installation
3.3. Configuring the Server
3.3.1. Relational Database Configuration
3.3.2. MongoDB based model
3.3.3. JSON File based model
3.3.4. EAP6.x Logging
3.3.5. SSL/HTTPS Requirement/Modes
3.3.6. SSL/HTTPS Setup
3.4. Adding Keycloak server in Domain Mode

The Keycloak Server has two downloadable distributions.

The keycloak-appliance-dist-all-1.2.0.Beta1.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.2.0.Beta1/
    keycloak/
        bin/
            standalone.sh
            standalone.bat
            standalone/configuration/
                keycloak-server.json
                themes/
    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-1.2.0.Beta1.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 Wildfly 8 or JBoss EAP 6.x 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.2.0.Beta1/
    deployments/
        auth-server.war/
        keycloak-ds.xml
    configuration/
        keycloak-server.json
        themes/
    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.2.0.Beta1
    $ cp -r deployments $JBOSS_HOME/standalone/deployments
    $ cp -r configuration $JBOSS_HOME/standalone/configuration

After these steps you MUST then download and 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.

You can no longer run Keycloak on JBoss AS 7.1.1. You must run on EAP 6.x or Wildfly.

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

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:

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

Value of database schema (Hibernate property "hibernate.hbm2ddl.auto" ).

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)

unitName

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.

For more info about Hibernate properties, see Hibernate and JPA documentation .

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",
    "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:

"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 Mongo documentation for details about those options and their default values.

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:

"realm": {
    "provider": "jpa"
},

"user": {
    "provider": "jpa"
},
    
"userSessions": {
    "provider" : "mem"
},
    
"realmCache": {
    "provider": "mem"
},

"userCache": {
    "provider": "mem",
    "mem": {
        "maxSize": 20000
    }
},

to:

"realm": {
    "provider": "file"
},

"user": {
    "provider": "file"
},
                    
"userSessions": {
    "provider" : "mem"
},
                    
"realmCache": {
    "provider": "none"
},

"userCache": {
    "provider": "none",
},

You can also change the location of the data file by adding a connectionsFile snippet:

"connectionsFile": {
   "default" : {
        "directory": "/mydirectory",
        "fileName": "myfilename.json"
    }
}

All configuration options are optional. Default value for directory is ${jboss.server.data.dir}. Default file name is keycloak-model.json.

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 JBoss or 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
    

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.

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:

<extensions>
    ...
    <extension module="org.keycloak.keycloak-subsystem"/>
</extensions>

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:

<profile name="full">
    ...
    <subsystem xmlns="urn:jboss:domain:keycloak:1.0">
        <auth-server name="main-auth-server">
            <enabled>true</enabled>
            <web-context>auth</web-context>
        </auth-server>
    </subsystem>

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.