2014-01-13 01:57:31 +00:00
<chapter id= "server-installation" >
<title > Installation and Configuration of Keycloak Server</title>
<para >
The Keycloak Server has two downloadable distributions.
</para>
<para >
<itemizedlist >
<listitem >
2014-09-02 11:22:15 +00:00
keycloak-appliance-dist-all-&project.version; .zip
2014-01-13 01:57:31 +00:00
</listitem>
<listitem >
2014-09-02 11:22:15 +00:00
keycloak-war-dist-all-&project.version; .zip
2014-01-13 01:57:31 +00:00
</listitem>
</itemizedlist>
</para>
2014-02-19 14:03:32 +00:00
<section id= "Appliance_install" >
2014-01-13 01:57:31 +00:00
<title > Appliance Install</title>
<para >
The
2014-09-03 08:13:05 +00:00
<literal > keycloak-appliance-dist-all-&project.version; .zip</literal>
2014-01-13 01:57:31 +00:00
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:
</para>
<para >
<programlisting >
2014-09-02 11:22:15 +00:00
keycloak-appliance-dist-all-&project.version; /
2014-01-13 01:57:31 +00:00
keycloak/
bin/
standalone.sh
standalone.bat
standalone/deployments/
2014-05-27 11:05:35 +00:00
auth-server.war/
standalone/configuration/
keycloak-server.json
themes/
2014-01-13 01:57:31 +00:00
adapters/
2014-09-02 11:22:15 +00:00
keycloak-as7-adapter-dist-&project.version; .zip
keycloak-eap6-adapter-dist-&project.version; .zip
keycloak-wildfly-adapter-dist-&project.version; .zip
2014-01-13 01:57:31 +00:00
examples/
docs/
</programlisting>
</para>
<para >
The
<literal > standalone.sh</literal>
or
<literal > standalone.bat</literal>
script is used to start the server.
After executing that, log into the admin console at<ulink
2014-05-28 13:31:33 +00:00
url="http://localhost:8080/auth/admin/index.html">
http://localhost:8080/auth/admin/index.html</ulink> .
2014-03-12 16:57:30 +00:00
Username: <emphasis > admin</emphasis>
Password: <emphasis > admin</emphasis> . Keycloak will then prompt you to
2014-01-13 01:57:31 +00:00
enter in a new password.
</para>
</section>
2014-02-19 14:03:32 +00:00
<section id= "WAR_distribution_installation" >
2014-01-13 01:57:31 +00:00
<title > WAR Distribution Installation</title>
<para >
The
2014-09-03 08:13:05 +00:00
<literal > keycloak-war-dist-all-&project.version; .zip</literal>
2014-01-13 01:57:31 +00:00
contains
just the bits you need to install keycloak on your favorite web container. We currently only support
2014-11-04 13:30:53 +00:00
installing it on top of an existing Wildfly 8, JBoss EAP 6.x or JBoss AS 7.1.1 distribution. We may in the
2014-01-13 01:57:31 +00:00
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.
</para>
<para >
The directory structure of this distro looks like this:
</para>
<para >
<programlisting >
2014-09-02 11:22:15 +00:00
keycloak-war-dist-all-&project.version; /
2014-01-13 01:57:31 +00:00
deployments/
auth-server.war/
keycloak-ds.xml
2014-05-27 11:05:35 +00:00
configuration/
keycloak-server.json
themes/
2014-01-13 01:57:31 +00:00
adapters/
2014-09-02 11:22:15 +00:00
keycloak-as7-adapter-dist-&project.version; .zip
keycloak-eap6-adapter-dist-&project.version; .zip
keycloak-wildfly-adapter-dist-&project.version; .zip
2014-01-13 01:57:31 +00:00
examples/
docs/
</programlisting>
</para>
<para >
2014-05-27 11:05:35 +00:00
After unzipping this file, copy everything in <literal > deployments</literal> directory into the
<literal > standalone/deployments</literal> of your JBoss or Wildfly distro. Also, copy everything in
<literal > configuration</literal> directory into the <literal > standalone/configuration</literal> directory.
2014-01-13 01:57:31 +00:00
</para>
<para >
<programlisting >
2014-09-02 11:22:15 +00:00
$ cd keycloak-war-dist-all-&project.version;
2014-01-13 01:57:31 +00:00
$ cp -r deployments $JBOSS_HOME/standalone
2014-08-07 08:32:26 +00:00
$ cp -r configuration $JBOSS_HOME/standalone
2014-01-13 01:57:31 +00:00
</programlisting>
</para>
2014-08-14 15:01:04 +00:00
<para >
After these steps you should also <link linkend= 'jboss-adapter-installation' > install the client adapter</link>
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.
</para>
2014-01-13 01:57:31 +00:00
<para >
After booting up the JBoss or Wildfly distro, you can then make sure it is installed properly
by logging into the admin console at<ulink
2014-05-28 13:31:33 +00:00
url="http://localhost:8080/auth/admin/index.html">
http://localhost:8080/auth/admin/index.html</ulink> .
2014-03-12 16:57:30 +00:00
Username: <emphasis > admin</emphasis>
Password: <emphasis > admin</emphasis> . Keycloak will then prompt you to
2014-01-13 01:57:31 +00:00
enter in a new password.
</para>
2014-11-03 16:05:00 +00:00
<para >
2014-11-04 13:30:53 +00:00
If you have Keycloak on JBoss AS 7.1.1 <link linkend= "as7-specifics" > these steps</link> .
2014-11-03 16:05:00 +00:00
</para>
2014-01-13 01:57:31 +00:00
</section>
2014-11-02 21:46:41 +00:00
<section id= "subsystem_installation" >
<title > Subsystem Installation</title>
<para >
For WildFly installations, the Keycloak server is not deployed from the /deployments directory. Instead, the Keycloak
subsystem module contains the Keycloak server and it is controlled by the subsystem. If you are using the
appliance install, this subsystem is already present and a Keycloak server is pre-defined in the subsytem declaration.
</para>
</section>
2014-01-13 01:57:31 +00:00
<section >
2014-10-06 11:58:22 +00:00
<title id= "configure-server" > Configuring the Server</title>
2014-01-13 01:57:31 +00:00
<para >
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:
<itemizedlist >
<listitem >
2014-09-03 08:13:05 +00:00
Configuring Keycloak to use a production database.
2014-01-13 01:57:31 +00:00
</listitem>
<listitem >
Setting up SSL/HTTPS
</listitem>
<listitem >
Enforcing HTTPS connections
</listitem>
</itemizedlist>
</para>
<section >
2014-08-19 19:10:32 +00:00
<title > Relational Database Configuration</title>
2014-01-13 01:57:31 +00:00
<para >
2014-09-03 08:13:05 +00:00
By default, Keycloak uses a relational database to store Keycloak data. This datasource is the <literal > standalone/deployments/keycloak-ds.xml</literal>
file of your Keycloak Server installation if you used <xref linkend= "WAR_distribution_installation" /> or in <literal > standalone/configuration/standalone.xml</literal>
2014-02-19 14:03:32 +00:00
if you used <xref linkend= "Appliance_install" /> . File <literal > keycloak-ds.xml</literal> is used in WAR
distribution, so that you have datasource available out of the box and you don't need to edit <literal > standalone.xml</literal> file.
However a good thing is to always delete the file <literal > keycloak-ds.xml</literal> and move its configuration text
into the centrally managed <literal > standalone.xml</literal> file.
This will allow you to manage the database connection pool from the Wildfly/JBoss administration console. Here's what
2014-09-03 08:13:05 +00:00
<literal > standalone/configuration/standalone.xml</literal> should look like after you've done this:
2014-01-13 01:57:31 +00:00
</para>
<para >
<programlisting > < ![CDATA[
<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>
2014-09-03 08:13:05 +00:00
</datasources>
</subsystem>
2014-01-13 01:57:31 +00:00
]]>
</programlisting>
</para>
<para >
Besides moving the database config into the central <literal > standalone.xml</literal> configuration file
2014-02-18 10:36:58 +00:00
you might want to use a better relational database for Keycloak like PostgreSQL or MySQL. You might also
2014-01-13 01:57:31 +00:00
want to tweak the configuration settings of the datasource. Please see the <ulink url= "https://docs.jboss.org/author/display/WFLY8/DataSource+configuration" > Wildfly</ulink> ,
<ulink url= "https://docs.jboss.org/author/display/AS71/DataSource+configuration" > JBoss AS7</ulink> ,
or <ulink url= "https://docs.jboss.org/author/display/AS71/DataSource+configuration" > JBoss EAP 6.x</ulink> documentation on how to do this.
</para>
<para >
Keycloak also runs on a Hibernate/JPA backend which is configured in the
2014-08-07 10:23:46 +00:00
<literal > standalone/configuration/keycloak-server.json</literal> .
By default the setting is like this:
<programlisting > < ![CDATA[
"connectionsJpa": {
"default": {
"dataSource": "java:jboss/datasources/KeycloakDS",
"databaseSchema": "update"
}
},
]]></programlisting>
Possible configuration options are:
<variablelist >
<varlistentry >
<term > dataSource</term>
<listitem >
<para >
JNDI name of the dataSource
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > jta</term>
<listitem >
<para >
boolean property to specify if datasource is JTA capable
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > driverDialect</term>
<listitem >
<para >
Value of Hibernate dialect. In most cases you don't need to specify this property as dialect will be
autodetected by Hibernate.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > databaseSchema</term>
<listitem >
<para >
Value of database schema (Hibernate property "hibernate.hbm2ddl.auto" ).
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > showSql</term>
<listitem >
<para >
Specify whether Hibernate should show all SQL commands in the console (false by default)
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > formatSql</term>
<listitem >
<para >
Specify whether Hibernate should format SQL commands (true by default)
</para>
</listitem>
</varlistentry>
2014-09-03 08:13:05 +00:00
<varlistentry >
<term > unitName</term>
<listitem >
<para >
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.
</para>
</listitem>
</varlistentry>
2014-08-07 10:23:46 +00:00
</variablelist>
For more info about Hibernate properties, see <ulink url= "http://hibernate.org/orm/documentation/" > Hibernate and JPA documentation</ulink> .
2014-01-13 01:57:31 +00:00
</para>
2014-02-19 15:16:15 +00:00
<section >
<title > Tested databases</title>
<para >
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,
2014-08-07 10:23:46 +00:00
as the default dialect may not work correctly. You can setup dialect by adding property <literal > driverDialect</literal>
to the <literal > keycloak-server.json</literal> into <literal > connectionsJpa</literal> section (see above).
2014-02-19 15:16:15 +00:00
<table frame= 'all' > <title > Tested databases</title>
<tgroup cols= '3' align= 'left' colsep= '1' rowsep= '1' >
<thead >
<row >
<entry > Database</entry>
<entry > JDBC driver</entry>
<entry > Hibernate Dialect</entry>
</row>
</thead>
<tbody >
<row >
<entry > H2 1.3.161</entry>
<entry > H2 1.3.161</entry>
<entry > auto</entry>
</row>
<row >
<entry > MySQL 5.5</entry>
<entry > MySQL Connector/J 5.1.25</entry>
<entry > auto</entry>
</row>
<row >
<entry > PostgreSQL 9.2</entry>
<entry > JDBC4 Postgresql Driver, Version 9.3-1100</entry>
<entry > auto</entry>
</row>
<row >
<entry > Oracle 11g R1</entry>
<entry > Oracle JDBC Driver v11.1.0.7</entry>
<entry > auto</entry>
</row>
<row >
<entry > Microsoft SQL Server 2012</entry>
<entry > Microsoft SQL Server JDBC Driver 4.0.2206.100</entry>
<entry > org.hibernate.dialect.SQLServer2008Dialect</entry>
</row>
<row >
<entry > Sybase ASE 15.7</entry>
<entry > JDBC(TM)/7.07 ESD #5 (Build 26792)/P/EBF20686</entry>
<entry > auto</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
2014-01-13 01:57:31 +00:00
</section>
2014-02-19 16:43:11 +00:00
<section >
<title > MongoDB based model</title>
<para >
Keycloak provides <ulink url= "http://www.mongodb.com" > MongoDB</ulink> based model implementation, which means that your identity data will be saved
2014-05-27 11:05:35 +00:00
in MongoDB instead of traditional RDBMS. To configure Keycloak to use Mongo open <literal > standalone/configuration/keycloak-server.json</literal>
in your favourite editor, then change:
2014-02-19 16:43:11 +00:00
<programlisting > < ![CDATA[
2014-08-27 10:41:40 +00:00
"eventsStore": {
2014-08-07 10:23:46 +00:00
"provider": "jpa",
"jpa": {
"exclude-events": [ "REFRESH_TOKEN" ]
}
2014-05-27 11:05:35 +00:00
},
2014-08-07 10:23:46 +00:00
"realm": {
"provider": "jpa"
},
"user": {
"provider": "${keycloak.user.provider:jpa}"
2014-05-27 11:05:35 +00:00
},
2014-02-19 16:43:11 +00:00
]]></programlisting>
2014-05-27 11:05:35 +00:00
to:
<programlisting > < ![CDATA[
2014-08-27 10:41:40 +00:00
"eventsStore": {
2014-08-07 10:23:46 +00:00
"provider": "mongo",
2014-09-03 08:13:05 +00:00
"mongo": {
"exclude-events": [ "REFRESH_TOKEN" ]
}
2014-05-27 11:05:35 +00:00
},
2014-08-07 10:23:46 +00:00
"realm": {
"provider": "mongo"
2014-05-27 11:05:35 +00:00
},
2014-08-07 10:23:46 +00:00
"user": {
"provider": "mongo"
2014-09-03 08:13:05 +00:00
},
2014-02-19 16:43:11 +00:00
]]></programlisting>
2014-05-27 11:05:35 +00:00
2014-08-07 10:23:46 +00:00
And at the end of the file add the snippet like this where you can configure details about your Mongo database:
<programlisting > < ![CDATA[
"connectionsMongo": {
"default": {
"host": "127.0.0.1",
"port": "27017",
2014-10-30 10:09:21 +00:00
"db": "keycloak",
"connectionsPerHost": 100
2014-08-07 10:23:46 +00:00
}
}
]]></programlisting>
2014-05-27 11:05:35 +00:00
2014-08-07 10:23:46 +00:00
All configuration options are optional. Default values for host and port are localhost and 27017. Default name of database
is <literal > keycloak</literal> . You can also specify properties <literal > user</literal> and <literal > password</literal>
if you want authenticate against your MongoDB. If user and password are not specified, Keycloak will connect
unauthenticated to your MongoDB.
2014-02-19 16:43:11 +00:00
</para>
2014-10-30 10:09:21 +00:00
<para > Finally there is set of optional configuration options, which can be used to specify connection-pooling capabilities of Mongo client. Supported int options are:
<literal > connectionsPerHost</literal> , <literal > threadsAllowedToBlockForConnectionMultiplier</literal> , <literal > maxWaitTime</literal> , <literal > connectTimeout</literal>
<literal > socketTimeout</literal> . Supported boolean options are: <literal > socketKeepAlive</literal> , <literal > autoConnectRetry</literal> .
Supported long option is <literal > maxAutoConnectRetryTime</literal> . See <ulink url= "http://api.mongodb.org/java/2.11.4/com/mongodb/MongoClientOptions.html" > Mongo documentation</ulink>
for details about those options and their default values.
</para>
2014-02-19 16:43:11 +00:00
</section>
2014-05-27 11:05:35 +00:00
2014-11-03 16:05:00 +00:00
<section id= "as7-specifics" >
2014-11-04 13:30:53 +00:00
<title > AS7 specifics</title>
2014-05-05 22:50:41 +00:00
<para >
2014-11-04 13:30:53 +00:00
If you have Keycloak on JBoss AS 7.1.1 you need to do few other things in order to have Keycloak up and running. This includes:
2014-11-03 16:05:00 +00:00
<orderedlist >
<listitem >
<para >
Remove or comment the element from file <literal > KEYCLOAK_HOME/standalone/deployments/auth-server.war/WEB-INF/jboss-deployment-structure.xml</literal> .
<programlisting > < ![CDATA[
<exclude-subsystems >
<subsystem name= "webservices" />
</exclude-subsystems>
]]></programlisting>
</para>
</listitem>
<listitem >
<para >
Then either:
</para>
<para >
<itemizedlist >
<listitem >
<para >
Disable webservices extension and subsystem by remove (or comment) both in <literal > KEYCLOAK_HOME/standalone/configuration/standalone.xml</literal> .
</para>
</listitem>
<listitem >
<para >
If you want to use webservices subsystem, the alternative is to remove 2 JAR files
<literal > KEYCLOAK_HOME/standalone/deployments/auth-server.war/WEB-INF/lib/keycloak-saml-protocol-&project.version; .jar</literal>
and <literal > KEYCLOAK_HOME/standalone/deployments/auth-server.war/WEB-INF/lib/picketlink-federation-&picketlink.version; .jar</literal>
but note that <link linkend= "saml" > SAML</link> won't work.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</orderedlist>
2014-05-05 22:50:41 +00:00
</para>
2014-11-03 16:05:00 +00:00
<section >
<title > AS7/EAP6.x Logging</title>
<para >
Accessing the admin console will get these annoying log messages:
</para>
2014-05-05 22:50:41 +00:00
<programlisting >
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
</programlisting>
2014-11-03 16:05:00 +00:00
<para >
These can be ignored by editing standalone.xml of your jboss installation:
</para>
2014-05-05 22:50:41 +00:00
<programlisting >
< ![CDATA[
<logger category= "org.jboss.resteasy.core.ResourceLocator" >
<level name= "ERROR" />
</logger>
]]>
</programlisting>
2014-11-03 16:05:00 +00:00
</section>
2014-05-05 22:50:41 +00:00
</section>
2014-11-03 16:05:00 +00:00
2014-09-19 15:03:08 +00:00
<section id= "ssl_modes" >
2014-08-20 18:37:15 +00:00
<title > SSL/HTTPS Requirement/Modes</title>
2014-01-13 01:57:31 +00:00
<warning >
<para >
Keycloak is not set up by default to handle SSL/HTTPS in either the
2014-06-18 08:59:23 +00:00
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.
2014-01-13 01:57:31 +00:00
</para>
</warning>
2014-08-20 18:37:15 +00:00
<para >
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.
</para>
<para >
Keycloak has 3 SSL/HTTPS modes which you can set up in the admin console under the Settings->Login page
and the <literal > Require SSL</literal> select box. Each adapter config should mirror this server-side
setting. See adapter config section for more details.
<variablelist >
<varlistentry >
<term > external</term>
<listitem >
<para >
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.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > none</term>
<listitem >
<para >
Keycloak does not require SSL.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > all</term>
<listitem >
<para >
Keycloak requires SSL for all IP addresses.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section >
<title > SSL/HTTPS Setup</title>
2014-01-13 01:57:31 +00:00
2014-06-18 08:59:23 +00:00
<para >
First enable SSL on Keycloak or on a reverse proxy in front of Keycloak. Then configure the Keycloak Server to enforce HTTPS connections.
2014-01-13 01:57:31 +00:00
</para>
2014-06-18 08:59:23 +00:00
2014-01-13 01:57:31 +00:00
<section >
2014-06-18 08:59:23 +00:00
<title > Enable SSL on Keycloak</title>
2014-01-13 01:57:31 +00:00
<para >
2014-06-18 08:59:23 +00:00
The following things need to be done
<itemizedlist >
<listitem >
Generate a self signed or third-party signed certificate and import it into a Java keystore
using <literal > keytool</literal> .
</listitem>
<listitem >
Enable JBoss or Wildfly to use this certificate and turn on SSL/HTTPS.
</listitem>
</itemizedlist>
2014-01-13 01:57:31 +00:00
</para>
<section >
2014-06-18 08:59:23 +00:00
<title > Creating the Certificate and Java Keystore</title>
2014-01-13 01:57:31 +00:00
<para >
2014-06-18 08:59:23 +00:00
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.
2014-01-13 01:57:31 +00:00
</para>
2014-06-18 08:59:23 +00:00
<section >
<title > Self Signed Certificate</title>
<para >
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 <literal > keytool</literal> utility that comes with the Java jdk.
</para>
<para >
<programlisting >
$ 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
</programlisting>
</para>
<para >
You should answer the <literal > What is your first and last name?</literal> question with
the DNS name of the machine you're installing the server on. For testing purposes,
<literal > localhost</literal> should be used. After executing this command, the
<literal > keycloak.jks</literal> file will be generated in the same directory as you executed
the <literal > keytool</literal> command in.
</para>
<para >
If you want a third-party signed certificate, but don't have one, you can obtain one for free
at <ulink url= "http://cacert.org" > cacert.org</ulink> . You'll have to do a little set up first
before doing this though.
</para>
<para >
The first thing to do is generate a Certificate Request:
<programlisting >
$ keytool -certreq -alias yourdomain -keystore keycloak.jks > keycloak.careq
</programlisting>
</para>
<para >
Where <literal > yourdomain</literal> is a DNS name for which this certificate is generated for.
Keytool generates the request:
<programlisting >
-----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-----
</programlisting>
</para>
<para >
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:
<programlisting >
$ keytool -import -keystore keycloak.jks -file root.crt -alias root
</programlisting>
</para>
<para >
Last step is import your new CA generated certificate to your keystore:
<programlisting >
$ keytool -import -alias yourdomain -keystore keycloak.jks -file your-certificate.cer
</programlisting>
</para>
</section>
</section>
<section >
<title > Installing the keystore to WildFly</title>
2014-01-13 01:57:31 +00:00
<para >
2014-06-18 08:59:23 +00:00
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 <literal > standalone/configuration</literal> .
Then you need to edit <literal > standalone/configuration/standalone.xml</literal> to enable SSL/HTTPS.
2014-01-13 01:57:31 +00:00
</para>
<para >
2014-06-18 08:59:23 +00:00
To the <literal > security-realms</literal> element add:
<programlisting > <![CDATA[<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> ]]></programlisting>
2014-01-13 01:57:31 +00:00
</para>
<para >
2014-06-18 08:59:23 +00:00
Find the element <literal > < server name="default-server"> </literal> (it's a child element of <literal > < subsystem xmlns="urn:jboss:domain:undertow:1.0"> </literal> ) and add:
<programlisting > <![CDATA[<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
]]></programlisting>
2014-01-13 01:57:31 +00:00
</para>
<para >
2014-06-18 08:59:23 +00:00
Check the <ulink url= "https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration" > Wildfly Undertow</ulink> documentation for more information on fine tuning the socket connections.
2014-01-13 01:57:31 +00:00
</para>
2014-06-18 08:59:23 +00:00
</section>
<section >
<title > Installing the keystore to JBoss EAP6/AS7</title>
2014-01-13 01:57:31 +00:00
<para >
2014-06-18 08:59:23 +00:00
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 <literal > standalone/configuration</literal> .
Then you need to edit <literal > standalone/configuration/standalone.xml</literal> to enable SSL/HTTPS.
2014-01-13 01:57:31 +00:00
</para>
<para >
2014-06-18 08:59:23 +00:00
<programlisting > <![CDATA[<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> ]]></programlisting>
2014-01-13 01:57:31 +00:00
</para>
<para >
2014-06-18 08:59:23 +00:00
Check the <ulink url= "https://docs.jboss.org/author/display/AS71/SSL+setup+guide" > JBoss</ulink> documentation for more information on fine tuning the socket connections.
2014-01-13 01:57:31 +00:00
</para>
</section>
</section>
2014-06-18 08:59:23 +00:00
2014-01-13 01:57:31 +00:00
<section >
2014-06-18 08:59:23 +00:00
<title > Enable SSL on a Reverse Proxy</title>
2014-01-20 17:46:33 +00:00
<para >
2014-06-18 08:59:23 +00:00
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 <literal > X-Forwarded-For</literal> and
<literal > X-Forwarded-Proto</literal> headers on the requests made to Keycloak. Next you need to enable
2014-06-18 10:08:06 +00:00
<literal > proxy-address-forwarding</literal> 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.
2014-01-20 17:46:33 +00:00
</para>
2014-10-29 13:02:16 +00:00
<section >
<title > WildFly</title>
<para >
Open <literal > standalone/configuration/standalone.xml</literal> in your favorite editor.
</para>
<para >
First add <literal > proxy-address-forwarding</literal> and <literal > redirect-socket</literal> to
the <literal > http-listener</literal> element:
2014-06-18 08:59:23 +00:00
<programlisting > <![CDATA[<subsystem xmlns="urn:jboss:domain:undertow:1.1">
...
2014-10-29 13:02:16 +00:00
<http-listener name= "default" socket-binding= "http"
proxy-address-forwarding="true" redirect-socket="proxy-https"/>
2014-06-18 08:59:23 +00:00
...
</subsystem>
2014-06-18 10:08:06 +00:00
]]></programlisting>
2014-10-29 13:02:16 +00:00
</para>
<para >
Then add a new <literal > socket-binding</literal> element to the <literal > socket-binding-group</literal> element:
2014-06-18 10:08:06 +00:00
<programlisting > < ![CDATA[
2014-10-29 13:02:16 +00:00
<socket-binding-group name= "standard-sockets" default-interface= "public"
port-offset="${jboss.socket.binding.port-offset:0}">
2014-06-18 10:08:06 +00:00
...
<socket-binding name= "proxy-https" port= "443" />
...
</socket-binding-group>
2014-02-18 10:36:58 +00:00
]]></programlisting>
2014-10-29 13:02:16 +00:00
</para>
<para >
Check the <ulink url= "https://docs.jboss.org/author/display/WFLY8/Undertow+(web)+subsystem+configuration" > WildFly</ulink> documentation for more information.
</para>
</section>
<section >
<title > AS7/EAP</title>
<para >
Open <literal > standalone/configuration/standalone.xml</literal> in your favorite editor.
</para>
<para >
You need to add <literal > redirect-port</literal> to http <literal > connector</literal> element and
add the <literal > RemoteIpValve</literal> valve:
<programlisting > < ![CDATA[
<subsystem xmlns= "urn:jboss:domain:web:1.5"
default-virtual-server="default-host" native="false">
<connector name= "http" protocol= "HTTP/1.1" scheme= "http"
socket-binding="http"
redirect-port="443"/>
<virtual-server name= "default-host" enable-welcome-root= "true" >
<alias name= "localhost" />
<alias name= "example.com" />
</virtual-server>
<valve name= "remoteipvalve" module= "org.jboss.as.web"
class-name="org.apache.catalina.valves.RemoteIpValve">
<param param-name= "protocolHeader" param-value= "x-forwarded-proto" />
</valve>
</subsystem>
]]></programlisting>
</para>
</section>
2014-01-13 01:57:31 +00:00
</section>
2014-06-18 08:59:23 +00:00
2014-01-13 01:57:31 +00:00
</section>
</section>
2014-11-02 21:46:41 +00:00
<section >
<title > Configuring Servers from the Subsystem</title>
<para >
If you are using WildFly, the Keycloak server is deployed and configured from the Keycloak subsystem. This makes provisioning simpler in a domain environment.
It also allows you to create more than one Keycloak server instance inside a single WildFly instance. And, you can upload providers, themes, and
server configurations without disturbing Keycloak's auth-server.war.
</para>
<section >
<title > Manually Creating A Server</title>
<para >
A Keycloak server can be declared by editing standalone.xml or domain.xml.
</para>
<para >
<programlisting > < ![CDATA[
<server xmlns= "urn:jboss:domain:1.4" >
<profile >
<subsystem xmlns= "urn:jboss:domain:keycloak:1.0" >
<auth-server name= "keycloak-1" >
<enabled > true</enabled>
<web-context > auth</web-context>
</auth-server>
<auth-server name= "keyclaok-2" >
<enabled > false</enabled>
<web-context > auth2</web-context>
</auth-server>
</subsystem>
</profile>
]]>
</programlisting>
</para>
<warning >
<para >
2014-11-05 13:30:03 +00:00
If you create more than one Keycloak server, you will need to use CLI to fully configure each instance. At the least,
you will need to run the <link linkend= "uploading-extra-config" > update-server-config</link> operation.
2014-11-02 21:46:41 +00:00
</para>
</warning>
</section>
<section >
<title > Using CLI and CLI GUI with the Keycloak Subsystem</title>
<para >
Servers can also be added/removed or enabled/disabled at runtime using the <ulink url= "https://developer.jboss.org/wiki/CommandLineInterface" > CLI</ulink> or
<ulink url= "https://developer.jboss.org/wiki/AGUIForTheCommandLineInterface" > CLI GUI</ulink> tool. These are tools that ship with WildFly and also with
the Keycloak Appliance installation. See <ulink url= "https://developer.jboss.org/wiki/CommandLineInterface" > CLI</ulink> or
2014-11-05 13:30:03 +00:00
<ulink url= "https://developer.jboss.org/wiki/AGUIForTheCommandLineInterface" > CLI GUI</ulink> documentation to learn more about how to start the tools,
issue commands, and create CLI scripts.
2014-11-02 21:46:41 +00:00
</para>
<para >
2014-11-05 13:30:03 +00:00
To start CLI with the Keycloak Appliance install:
2014-11-02 21:46:41 +00:00
<programlisting > < ![CDATA[
cd <APPLIANCE_INSTALL_DIR > /keycloak/bin
./jboss-cli.sh --gui
or
./jboss.cli.bat --gui]]>
</programlisting>
<note > Your Keycloak server must be running to start in --gui mode.</note>
</para>
<section >
<title > Basic CLI Commands</title>
<para >
Command to add a server in CLI:
<programlisting > < ![CDATA[
/subsystem=keycloak/auth-server=my-auth-server/:add(web-context=my-auth, enabled=true)]]>
</programlisting>
Because "enabled=true", a new Keycloak server will be immediately deployed. By default "enabled" is set to false.
</para>
<para >
Command to remove a server in CLI:
<programlisting > < ![CDATA[
/subsystem=keycloak/auth-server=my-auth-server/:remove]]>
</programlisting>
The Keycloak server will be immediately deleted and undeployed.
</para>
<para >
Command to enable or disable a server in CLI:
<programlisting > < ![CDATA[
/subsystem=keycloak/auth-server=foo/:write-attribute(name=enabled,value=true)]]>
</programlisting>
The Keycloak server will be immediately deployed or undeployed, but not deleted.
</para>
</section>
<section id= "uploading-extra-config" >
2014-11-05 13:30:03 +00:00
<title > Uploading extra configuration using CLI</title>
2014-11-02 21:46:41 +00:00
<para >
The WildFly Keycloak subsystem allows you to upload keycloak-server.json, provider jars, and theme jars to a Keycloak server instance. The
2014-11-05 13:30:03 +00:00
CLI operations for this are "update-server-config" and "add-provider". You may use plain or CLI scripts for these operations. The following
examples are shown using <ulink url= "https://developer.jboss.org/wiki/AGUIForTheCommandLineInterface" > CLI GUI</ulink> for clarity.
2014-11-02 21:46:41 +00:00
</para>
<para >
To use a new keycloak-server.json file for your server, find your server under the Keycloak subsystem. Then right-click the server,
select "update-server-config", and upload your file.
</para>
<para >
<imagedata fileref= "images/update-server-config-select.png" />
</para>
<para >
<imagedata fileref= "images/update-server-config-dialog.png" />
</para>
<warning >
<para >
If you use the update-server-config operation, you should delete or rename < WILDFLY_HOME> /standalone/configuration/keycloak-server.json.
Otherwise, all Keycloak server instances will use this file instead of your uploaded file.
</para>
</warning>
<para >
To upload a new provider jar or theme jar to your server, find your server under the Keycloak subsystem. Then right-click the server,
select "add-provider", and upload your file.
</para>
<para >
<imagedata fileref= "images/add-provider-select.png" />
</para>
<para >
<imagedata fileref= "images/add-provider-dialog.png" />
</para>
</section>
</section>
<section >
<title > Adding a Keycloak server in Domain Mode</title>
<para >
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.
</para>
<para >
In the example below, a Keycloak server named "foo" is defined in the "full" profile. The "full" profile is assigned to the "main-server-group".
Every WildFly instance that belongs to "main-server-group" will get an identically configured deployment of the "foo" Keycloak server.
2014-11-05 13:30:03 +00:00
</para>
<para >
All operations discussed earlier are valid for a Keycloak server in a domain. You can enable/disable, upload new keyclaok-server.json, and add provider jars.
In the following example, any changes that are made to the "foo" server will be automatically propogated to every instance in "main-server-group".
</para>
<para >
2014-11-02 21:46:41 +00:00
<imagedata fileref= "images/domain-mode.png" />
</para>
</section>
</section>
2014-01-13 01:57:31 +00:00
</chapter>
