Installation and Configuration of Keycloak Server

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

Database Configuration The datasource used to store Keycloak data is configured in the .../standalone/deployments/keycloak-ds.xml file of your Keycloak Server installation. A good thing to delete this file and move its configuration text into the centrally managed .../standalone/configuration/standalone.xml file. This will allow you to manage the database connection pool from the Wildfly/JBoss adminstration console. Here's what .../standalone/configuration/standalone.xml should look like after you've done this:

jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE

jdbc:h2:${jboss.server.data.dir}/keycloak;AUTO_SERVER=TRUE

org.h2.jdbcx.JdbcDataSource

]]> Besides moving the database config into the central standalone.xml configuration file you might want to use a better relational database for Keycloak like Oracle or something. 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/deployments/auth-server.war/WEB-INF/classes/META-INF/persistence.xml. Please see the Hibernate and JPA documentation for more information on tweaking the backend datamodel.

SSL/HTTPS Setup Keycloak is not set up by default to handle SSL/HTTPS in either the war distribution or appliance. It is highly recommended that you enable it! 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. Configure the Keycloak Server to enforce HTTPS connections.

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

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

Installing the keystore to JBoss AS7 Now that you have a Java keystore with the appropriate certificates, you need to configure your JBoss 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. ... ]]> Check the JBoss documentation for more information on fine tuning the socket connections.

Enforce HTTPS For Server Connections 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. ...

CONFIDENTIAL

]]>

Enforce HTTPS at Realm Level 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.