# Keycloak basic setup

## Getting Keycloak
Download keycloak from [here](https://www.keycloak.org/downloads.html) and install according to the instructions.

## Postgres (for example)
Keycloak comes with its own embedded H2 database. We're going to configure some degree of prod realism by using postgres.
Download postgres from [here](https://www.postgresql.org/download/) and install according to the instructions.

### Configuring Postgres
We'll initially create the **keycloak** database owned by the **keycloak** user.

## Configuring Keycloak

### Database
1. Copy the [postgresql jdbc driver](https://jdbc.postgresql.org/download.html) to **$keycloak_home/modules/system/layers/keycloak/org/postgresql/main**

2. Under **$keycloak_home/modules/system/layers/keycloak/org/postgresql/main** add a file called **module.xml** with the following content (NOTE: change as appropriate if the driver jar has a different name):
    ```xml
    <?xml version="1.0" ?>
    <module xmlns="urn:jboss:module:1.3" name="org.postgresql">

        <resources>
            <resource-root path="postgresql-42.2.5.jar"/>
        </resources>

        <dependencies>
            <module name="javax.api"/>
            <module name="javax.transaction.api"/>
        </dependencies>
    </module>
    ```

3. Under **$keycloak_home/standalone/configuration/standalone.xml**, configure the database subsystem with the postgresql details as follows (NOTE: postgresql is assumed to be listening of port 5432):
```xml
<subsystem xmlns="urn:jboss:domain:datasources:5.0">
    <datasources>
        <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
            <connection-url>jdbc:postgresql://localhost:5432/keycloak</connection-url>
            <driver>postgresql</driver>
            <pool>
                <max-pool-size>20</max-pool-size>
            </pool>
            <security>
                <user-name>keycloak</user-name>
                <password>keycloak</password>
            </security>
        </datasource>
        <drivers>
            <driver name="postgresql" module="org.postgresql">
                <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
            </driver>
        </drivers>
    </datasources>
</subsystem>
```

### Network
We'll run keycloak on alternative ports, so update **$keycloak_home/standalone/configuration/standalone.xml** as follows:
```xml
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    <socket-binding name="management-http" interface="management" port="${jboss.management.http.port:9990}"/>
    <socket-binding name="management-https" interface="management" port="${jboss.management.https.port:9993}"/>
    <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
    <socket-binding name="http" port="${jboss.http.port:9070}"/>
    <socket-binding name="https" port="${jboss.https.port:9443}"/>
    <socket-binding name="txn-recovery-environment" port="4712"/>
    <socket-binding name="txn-status-manager" port="4713"/>
    <outbound-socket-binding name="mail-smtp">
        <remote-destination host="localhost" port="25"/>
    </outbound-socket-binding>
</socket-binding-group>
```

### Running keycloak
You can run keyclock in standalone mode using **$keycloak_home/bin/standalone.sh** (**keycloak_home\bin\standalone.bat**)

### Keycloak realm configuration example
To configure a new realm in keycloak:
1. Login as an administrator
2. On the top left is the realm selector that also allows you to create a new realm - click **Add realm**
3. Specify the name, click **Create** and you've got a new realm

Under a realm, we need to configure clients (applications) that will make use of keycloak for authentication and authorisation, typically using Open Id Connect, but SAML is available as well.

### [Setting up SSL/HTTPS](#keycloak-ssl)
This is outlined [here](https://www.keycloak.org/docs/latest/server_installation/index.html#setting-up-https-ssl). By default, keycloak is setup to listen on https using a self-signed certificate.

You'll have to change any of the client setting configurations to use https for valid redirect URIs and so on.

#### Keycloak connect and self signed certificates
[Keycloak Connect](https://github.com/keycloak/keycloak-nodejs-connect) makes use of the standard node.js https library for tls. The node library doesn't play well with self-signed certificates. The following sections cover some options:

##### Get a certificate signed by a CA - you'll do this in production. The example below uses our own rootCA and signs the keycloak server certificate:
1. Get or generate a new root CA key and certificate

    ```
    openssl genrsa -out rootCA.key 2048
    openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem
    ```

2. Generate a server key and certificate signing request, then sign to get our server certificate:

    ```
    openssl req -nodes -newkey rsa:2048 -keyout server.key -out server.csr
    openssl x509 -req -days 365 -in server.csr -CA rootCA.pem -CAkey rootCA.key -set_serial 01 -out server.crt
    ```

3. Import the root certificate using keytool

    ```
    keytool -import -keystore keycloak.jks -file rootCA.pem -alias root
    ```

4. Generate a server certificate and private key package

    ```
    openssl pkcs12 -export -in server.crt -inkey server.key -name localhost -out server.p12
    ```

5. Import the server certificate and private key package using keytool

    ```
    keytool -importkeystore -deststorepass keycloak -destkeystore keycloak.jks -srckeystore server.p12 -srcstoretype PKCS12
    ```

6. Configure the keystore (this is specific to standalone mode)

    - Copy keycloak.jks to $keycloak_home/standalone/configuration

    - Modify $keycloak_home/standalone/configuration/standalone.xml

        ```xml
        <security-realm name="ApplicationRealm">
            <server-identities>
                <ssl>
                    <keystore path="keycloak.jks" relative-to="jboss.server.config.dir" keystore-password="keycloak" alias="localhost" key-password="keycloak"/>
                </ssl>
            </server-identities>
            <authentication>
                <local default-user="$local" allowed-users="*" skip-group-loading="true"/>
                <properties path="application-users.properties" relative-to="jboss.server.config.dir"/>
            </authentication>
            <authorization>
                <properties path="application-roles.properties" relative-to="jboss.server.config.dir"/>
            </authorization>
        </security-realm>
        ```


7. We'll have to add the additional root CA certificate to node's extra ca certificates

    - On windows:

        ```
        set NODE_EXTRA_CA_CERTS=/path/to/rootCA.pem
        ```

    - On unix:

        ```
        export NODE_EXTRA_CA_CERTS=/path/to/rootCA.pem
        ```