<chapter id="server-installation">
    <title>Installation and Configuration of Keycloak Server</title>

    <para>
        The Keycloak Server has two downloadable distributions.
    </para>
    <para>
        <itemizedlist>

            <listitem>
                keycloak-appliance-dist-all-1.0-rc-1-SNAPSHOT.zip
            </listitem>

            <listitem>
                keycloak-war-dist-all-1.0-rc-1-SNAPSHOT.zip
            </listitem>

        </itemizedlist>

    </para>
    <section id="Appliance_install">
        <title>Appliance Install</title>
        <para>
            The
            <literal>keycloak-appliance-dist-all.zip</literal>
            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>
keycloak-appliance-dist-all-1.0-rc-1-SNAPSHOT/
    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-1-SNAPSHOT.zip
        keycloak-eap6-adapter-dist-1.0-rc-1-SNAPSHOT.zip
        keycloak-wildfly-adapter-dist-1.0-rc-1-SNAPSHOT.zip
    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
                url="http://localhost:8080/auth/admin/index.html">
            http://localhost:8080/auth/admin/index.html</ulink>.
            Username: <emphasis>admin</emphasis>
            Password: <emphasis>admin</emphasis>. Keycloak will then prompt you to
            enter in a new password.
        </para>
    </section>
    <section id="WAR_distribution_installation">
        <title>WAR Distribution Installation</title>
        <para>
            The
            <literal>keycloak-war-dist-all.zip</literal>
            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.
        </para>
        <para>
            The directory structure of this distro looks like this:
        </para>
        <para>
<programlisting>
keycloak-war-dist-all-1.0-rc-1-SNAPSHOT/
    deployments/
        auth-server.war/
        keycloak-ds.xml
    configuration/
        keycloak-server.json
        themes/
    adapters/
        keycloak-as7-adapter-dist-1.0-rc-1-SNAPSHOT.zip
        keycloak-eap6-adapter-dist-1.0-rc-1-SNAPSHOT.zip
        keycloak-wildfly-adapter-dist-1.0-rc-1-SNAPSHOT.zip
    examples/
    docs/
</programlisting>
        </para>
        <para>
            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.
        </para>
        <para>
<programlisting>
    $ cd keycloak-war-dist-all-1.0-rc-1-SNAPSHOT
    $ cp -r deployments $JBOSS_HOME/standalone
</programlisting>
        </para>
        <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
                url="http://localhost:8080/auth/admin/index.html">
            http://localhost:8080/auth/admin/index.html</ulink>.
            Username: <emphasis>admin</emphasis>
            Password: <emphasis>admin</emphasis>. Keycloak will then prompt you to
            enter in a new password.
        </para>
    </section>
    <section>
        <title>Configuring the Server</title>
        <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>
                    Configuring keycloak to use a production database.
                </listitem>

                <listitem>
                    Setting up SSL/HTTPS
                </listitem>

                <listitem>
                    Enforcing HTTPS connections
                </listitem>
            </itemizedlist>
        </para>
        <section>
            <title>Database Configuration</title>
            <para>
                The datasource used to store Keycloak data is configured in 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>
                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
                <literal>.../standalone/configuration/standalone.xml</literal> should look like after you've done this:
            </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>
            </datasources>
        </subsystem>
]]>
</programlisting>
            </para>
            <para>
                Besides moving the database config into the central <literal>standalone.xml</literal> 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 <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
                <literal>.../standalone/deployments/auth-server.war/WEB-INF/classes/META-INF/persistence.xml</literal>.
                Please see the <ulink url="http://hibernate.org/orm/documentation/">Hibernate and JPA documentation</ulink> for more information on tweaking the backend datamodel.
            </para>
            <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,
                    as the default dialect may not work correctly. You can setup dialect either by adding property <literal>hibernate.dialect</literal>
                    to the <literal>persistence.xml</literal> file mentioned above or simply by adding system property <literal>hibernate.dialect</literal>
                    with corresponding value. For example, if you are using MS-SQL you can start keycloak with command:
<programlisting><![CDATA[
./standalone.sh -Dhibernate.dialect=org.hibernate.dialect.SQLServer2008Dialect
]]></programlisting>
                    This command will set system property <literal>hibernate.dialect</literal> to value <literal>org.hibernate.dialect.SQLServer2008Dialect</literal>
                    and this one will take precedence over the value from <literal>persistence.xml</literal> file.
                    <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>
        </section>
        <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
                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:

<programlisting><![CDATA[
"audit": {
  "provider": "jpa",
  "jpa": {
    "exclude-events": [ "REFRESH_TOKEN" ]
  }
},

"model": {
  "provider": "jpa"
},
]]></programlisting>

                to:

                <programlisting><![CDATA[
"audit": {
  "provider": "mongo",
  "mongo": {
    "exclude-events": [ "REFRESH_TOKEN" ],
    "host": "<hostname>",
    "port": <port>,
    "user": "<user>",
    "password": "<password>",
    "db": "<db name>"
  }
},

"model": {
  "provider": "mongo",
  "mongo": {
    "host": "<hostname>",
    "port": <port>,
    "user": "<user>",
    "password": "<password>",
    "db": "<db name>"
  }
},
]]></programlisting>

                All configuration options are optional. Default values for host and port are localhost and 27017. If
                user and password are not specified Keycloak will connect unauthenticated to your MongoDB. Finally, default
                values for db are keycloak for the model, and keycloak-audit for audit.

                If you switch to Mongo model, it could be a good idea to remove RDBMS related stuff from your distribution to reduce startup time and memory footprint.
                To do it, you need to:
                <itemizedlist>
                    <listitem>Comment/remove datasource <literal>KeycloakDS</literal> from <literal>standalone/configuration/standalone.xml</literal> or <literal>standalone/deployments/keycloak-ds.xml</literal></listitem>
                    <listitem>Remove file <literal>standalone/deployments/auth-server.war/WEB-INF/classes/META-INF/persistence.xml</literal></listitem>
                </itemizedlist>
            </para>
        </section>

        <section>
            <title>AS7/EAP6.x Logging</title>
            <para>
                Accessing the admin console will get these annoying log messages:
            </para>
<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>

            <para>
                These can be ignored by editing standalone.xml of your jboss installation:
            </para>
<programlisting>
<![CDATA[
    <logger category="org.jboss.resteasy.core.ResourceLocator">
        <level name="ERROR"/>
    </logger>
]]>
</programlisting>
        </section>
        <section>
            <title>SSL/HTTPS Setup</title>
            <warning>
                <para>
                    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.
                </para>
            </warning>

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

            <section>
                <title>Enable SSL on Keycloak</title>
                <para>
                    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>
                </para>
                <section>
                    <title>Creating the Certificate and Java Keystore</title>
                    <para>
                        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.
                    </para>
                    <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>
                    <para>
                        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.
                    </para>
                    <para>
                        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>
                    </para>
                    <para>
                        Find the element <literal>&lt;server name="default-server"&gt;</literal> (it's a child element of <literal>&lt;subsystem xmlns="urn:jboss:domain:undertow:1.0"&gt;</literal>) and add:
                        <programlisting><![CDATA[<https-listener name="https" socket-binding="https" security-realm="UndertowRealm"/>
    ]]></programlisting>
                    </para>
                    <para>
                        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.
                    </para>
                </section>
                <section>
                    <title>Installing the keystore to JBoss EAP6/AS7</title>
                    <para>
                        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.
                    </para>
                    <para>
<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>
                    </para>
                    <para>
                        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.
                    </para>
                </section>
            </section>

            <section>
                <title>Enable SSL on a Reverse Proxy</title>
                <para>
                    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
                    <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.
                    This is done by editing <literal>standalone/configuration/standalone.xml</literal>.
                </para>
                First add <literal>proxy-address-forwarding</literal> and <literal>redirect-socket</literal> to the <literal>http-listener</literal>
                element:
                <para>
<programlisting><![CDATA[<subsystem xmlns="urn:jboss:domain:undertow:1.1">
    ...
    <http-listener name="default" socket-binding="http" proxy-address-forwarding="true" redirect-socket="proxy-https"/>
    ...
</subsystem>
]]></programlisting>
                Then add a new <literal>socket-binding</literal> element to the <literal>socket-binding-group</literal> element:
<programlisting><![CDATA[
<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>
]]></programlisting>
                </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>Enforce HTTPS For Server Connections</title>
                <para>
                    Servlet containers can force browsers and other HTTP clients to use HTTPS.  You have to configure this in
                    <literal>.../standalone/deployments/auth-server.war/WEB-INF/web.xml</literal>.  All you have to do is
                    uncomment out the security constraint.
                </para>
                <para>
 <programlisting><![CDATA[<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>]]></programlisting>
                </para>
            </section>

            <section>
                <title>Enforce HTTPS at Realm Level</title>
                <para>
                    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 <literal>Settings>>General</literal> page.  While this switch does do similar checks as the security
                    constraint in <literal>web.xml</literal>, it will also force applications and oauth clients to only
                    register HTTPS based redirect URLs.
                </para>
            </section>
        </section>

    </section>
</chapter>
