Keycloak

Keycloak
is an identity management solution implemented in Java that can be used as an authentication backend for many different applications.
This article or section is out of date.
Reason:
Keycloak 17 has a new configuration file format.
[1]
(Discuss in
Talk:Keycloak#New configuration file format
)
Installation
Install the
keycloak
package.
Running
Start/enable
keycloak.service
. In the default configuration, it will start in standalone mode which is not recommended for production environments but will be used in this article for the sake of simplicity.
By default, Keycloak is available on
http://127.0.0.1:8080/
and
https://127.0.0.1:8443/
.
Note
Prior to Keycloak 18.0.0, the endpoints were
http://127.0.0.1:8080/auth/
and
https://127.0.0.1:8443/auth/
respectively
Creating an admin user
As per
upstream instructions
, you have two ways to create the initial Keycloak admin user one is connecting to keycloak through
http://localhost:8080
and the second is to add environment variables for username and password for the first launch.
To do the latter,
override the unit
:
/etc/systemd/system/keycloak.service.d/admin.conf
[Service]
Environment="KEYCLOAK_ADMIN=admin"
Environment="KEYCLOAK_ADMIN_PASSWORD=securepassword"
Reload the systemd daemon
, then
restart
the
keycloak.service
.
Afterwards, make sure to delete the override and
daemon-reload
again, as Keycloak will refuse to start up with the environment variables defined when the account already exists.
Configuration
The default standalone configuration can be found at
/etc/keycloak/standalone.xml
.
Any changes you make to this file while the server is running will not take effect and may even be overwritten by the server. Either stop the service beforehand, use the command line scripting or use the web console of WildFly.
The ports used by the service can found in that file, albeit in a slightly unusual format:
/etc/keycloak/standalone.xml
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
        <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
        <socket-binding name="http" port="${jboss.http.port:8080}"/>
        <socket-binding name="https" port="${jboss.https.port:8443}"/>   
        <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="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>
H2 configuration
Keycloak's
standalone.xml
file is preconfigured with two
h2
datasources. One is "ExampleDS", and can be safely removed. The other is "KeycloakDS" and is used to store Keycloak's configuration. (
jboss.home.dir
refers to
/opt/keycloak
in the Keycloak package)
Example configuration parts for the H2 file-based database:
/etc/keycloak/standalone.xml
<subsystem xmlns="urn:jboss:domain:datasources:5.0">
            <datasources>
                <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}">
                    <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" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}">
                    <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>
   ...
            <default-bindings context-service="java:jboss/ee/concurrency/context/default" datasource="java:jboss/datasources/KeycloakDS" managed-executor-service="java:jboss/ee/concurrency/executor/default" managed-scheduled-executor-service="java:jboss/ee/concurrency/scheduler/default" managed-thread-factory="java:jboss/ee/concurrency/factory/default"/>
PostgreSQL configuration
The official Arch Linux Keycloak package already comes with inbuilt PostgreSQL support.
Example configuration parts for PostgreSQL:
/etc/keycloak/standalone.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" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}">
                    <connection-url>jdbc:postgresql://localhost:5432/keycloak</connection-url>
                    <driver>postgresql</driver>
                    <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>
   ...
            <default-bindings context-service="java:jboss/ee/concurrency/context/default" datasource="java:jboss/datasources/KeycloakDS" managed-executor-service="java:jboss/ee/concurrency/executor/default" managed-scheduled-executor-service="java:jboss/ee/concurrency/scheduler/default" managed-thread-factory="java:jboss/ee/concurrency/factory/default"/>
Keycloak Prometheus metrics
Install the
keycloak-metrics-spi
package. To enable the metrics listener endpoint
/opt/keycloak/bin/kcadm.sh config credentials --server
http://localhost:8080/auth
--realm master --user $KEYCLOAK_ADMIN --password $KEYCLOAK_PASS
 /opt/keycloak/bin/kcadm.sh update events/config -s "eventsEnabled=true" -s "adminEventsEnabled=true" -s "eventsListeners+=metrics-listener"
The config command creates a kcadm.config file in the .keycloak directory of the user who runs the command. As contains an access token, it is recommend to remove the file after
rm /home/$USER/.keycloak/kcadm.config
After restarting the metrics are available via
http://localhost:8080/auth/realms/master/metrics
External links
Configuring Keycloak with Postgres
Official Keycloak documentation