magのOSS備忘録

使ったOSSソフトウェアについて書いていきます。

CentOS Stream 8にKeycloakをインストールする

本記事の目標

本記事では、CentOS Stream 8にKeycloakをインストールして動作させるまでを扱う。
Keycloak自体の設定は扱わない。

目次

実行環境

以下の実行環境を扱う。

  • CentOS Stream 8
  • Keycloak 15.0.1
  • OpenJDK 11 (11.0.12.0.7-0.el8_4)
  • PostgreSQL 12.7

Keycloakの持つ管理情報は、デフォルトで使用されるH2 DatabaseではなくPostgreSQLに保持させる。

システム構成はアプリケーションサーバー、およびデータベースサーバーで、それぞれ別のOS上で動作させる。IPアドレスは以下の通りとする。

なお、簡略化のためSELinux、firewalldは停止させておく。

データベースサーバーの構築

データベースサーバーにはPostgreSQLを使用する。

PostgreSQL Yum Repository登録

dnfコマンドでPostgreSQLがインストールできるように、DNFにPostgreSQL Yum Repositoryを登録する。

dnf install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

PostgreSQLのインストール

CentOS Streamでは、DNFのモジュール機能を使用して複数のバージョンのPostgreSQLを切り替えることができる。 ただし、psqlコマンドを使用したときにno version information available (required by psql)のようなメッセージが表示されるため(2021/8/12現在)、モジュール機能は使用しない。

dnf module disable postgresql
dnf install postgresql12-server

psqlコマンドなどのmanを見れるようにしておく。
以下のように/etc/man_db.confを編集する。

  MANDATORY_MANPATH                     /usr/man
  MANDATORY_MANPATH                     /usr/share/man
  MANDATORY_MANPATH                     /usr/local/share/man
+ MANDATORY_MANPATH                     /usr/pgsql-12/share/man
  #---------------------------------------------------------
  # set up PATH to MANPATH mapping
  # ie. what man tree holds man pages for what binary directory.

PostgreSQLの初期設定

PostgreSQLの初期データベースを作成する。
データベースのエンコーディングにはUTF8を指定し、ロケールは設定しない。 KeycloakではUnicode文字列が使用可能であるが、データベース側の設定もUTF8になっている必要がある。
https://www.keycloak.org/docs/latest/server_installation/#postgresql-database

export PGSETUP_INITDB_OPTIONS="--encoding=UTF8 --no-locale"
postgresql-12-setup initdb

設定ファイルの編集

postgresql.confの編集

ここでは待ち受けるIPアドレスと、ログに関する設定のみを変更している。
設定ファイルは/var/lib/pgsql/12/data/postgresql.confにある。

 # - Connection Settings -
 
-#listen_addresses = 'localhost'                # what IP address(es) to listen on;
+listen_addresses = '192.168.1.3,127.0.0.1'            # what IP address(es) to listen on;
                                        # comma-separated list of addresses;
                                        # defaults to 'localhost'; use '*' for all
                                        # (change requires restart)

 # These are only used if logging_collector is on:
-log_directory = 'log'                  # directory where log files are written,
+log_directory = '/var/log/postgresql'  # directory where log files are written,
                                        # can be absolute or relative to PGDATA
-log_filename = 'postgresql-%a.log'     # log file name pattern,
+log_filename = 'postgresql-%Y%m%d.log' # log file name pattern,
                                        # can include strftime() escapes
 #log_file_mode = 0600                  # creation mode for log files,
                                        # begin with 0 to use octal notation

 #debug_print_rewritten = off
 #debug_print_plan = off
 #debug_pretty_print = on
-#log_checkpoints = off
-#log_connections = off
-#log_disconnections = off
-#log_duration = off
+log_checkpoints = on
+log_connections = on
+log_disconnections = on
+log_duration = on
 #log_error_verbosity = default         # terse, default, or verbose messages
 #log_hostname = off
 log_line_prefix = '%m [%p] '           # special values:

-log_timezone = 'America/New_York'
+log_timezone = 'Asia/Tokyo'

-timezone = 'America/New_York'
+timezone = 'Asia/Tokyo'

pg_hba.confの編集

ここでは、postgresql.confで設定した待ち受けるIPアドレスへの接続許可設定を追加する。
Keycloakから接続するデータベース名と接続に使用するユーザ名は、それぞれkeycloakとしておく。
設定ファイルは/var/lib/pgsql/12/data/pg_hba.confにある。

 # IPv4 local connections:
 host    all             all             127.0.0.1/32            ident
+# IPv4 remote connections:
+host    keycloak        keycloak        192.168.1.0/24          md5
 # IPv6 local connections:

ログディレクトリの作成

postgresql.confで設定したログディレクトリを作成する。
CentOSの流儀に合わせてログは/var/log配下にまとめる。

mkdir -p /var/log/postgresql
chown postgres:postgres /var/log/postgresql
chmod 750 /var/log/postgresql

PostgreSQLの起動

systemctl enable postgresql-12
systemctl start postgresql-12

Keycloakの管理情報用のDB作成

Keycloakの管理情報用のDBとして、以下の表のように設定する。

項目
データベース名 keycloak
ユーザ名 keycloak
パスワード ※keycloakとしておく
スキーマ keycloak

psqlコマンドで、postgresユーザとしてPostgreSQLにログインし、以下のコマンドでデータベースなどを作成する。

CREATE DATABASE keycloak;
CREATE USER keycloak;
\password keycloak
\c keycloak
CREATE SCHEMA keycloak;
GRANT ALL PRIVILEGES ON SCHEMA keycloak TO keycloak;

アプリケーションサーバーの構築

OpenJDKのインストール

CentOS Stream 8が提供しているOpenJDKをインストールする。 インストールはDNFを使用し、以下のように実行する。

dnf install java-11-openjdk

インストール後の結果は、以下ように実行してメッセージが表示されればよい。

# java -version
openjdk version "11.0.12" 2021-07-20 LTS
OpenJDK Runtime Environment 18.9 (build 11.0.12+7-LTS)
OpenJDK 64-Bit Server VM 18.9 (build 11.0.12+7-LTS, mixed mode, sharing)

Keycloakの取得

以下のURLからKeycloakを取得する。
KeycloakはWildFly上のアプリケーションとして提供されるため、取得した圧縮したファイルにはWildFlyが同梱されている。
/opt配下にインストールする。

cd /opt
wget https://github.com/keycloak/keycloak/releases/download/15.0.1/keycloak-15.0.1.zip
tar zxvf keycloak-15.0.1.tar.gz             
ln -s keycloak-15.0.1 keycloak              

PostgreSQLJDBC Driver設定

Keycloakのドキュメントに従い、PostgreSQLJDBC Driverをダウンロード、および設定を行う。
Server Installation and Configuration Guide

PostgreSQLJDBC Driverは以下から取得する。
PostgreSQL JDBC Download

この記事を執筆した時点(2021/8/12)では、最新版がpostgresql-42.2.23.jarとなっていたため、このバージョンに合わせて設定を記載する。

cd /opt/keycloak/modules/system/layers/keycloak/org/
mkdir -p postgresql/main
wget https://jdbc.postgresql.org/download/postgresql-42.2.23.jar

設定ファイルはmodule.xmlという名称で作成し、内容は以下の通り。

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="org.postgresql">

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

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

最終的に、以下のようにファイルが格納されていればよい。

/opt/keycloak/modules/system/layers/keycloak/org/postgresql/main/postgresql-42.2.23.jar
/opt/keycloak/modules/system/layers/keycloak/org/postgresql/main/module.xml

設定ファイルの編集

standalone.xmlの編集

Keycloakでは以下の冗長構成を選択することが可能である。

詳細は下記を参照。
Server Installation and Configuration Guide

今回はスタンドアローン・モードを使用する。
スタンドアローン・モードの場合、設定ファイルはstandalone.xmlを使用することになり、standalone/configuration/配下に格納されている。
設定する内容としては、ログ出力設定と管理情報の保存先(PostgreSQL)設定となる。

@@ -114,7 +114,6 @@
             <root-logger>
                 <level name="INFO"/>
                 <handlers>
<!-- デーモンとして動作させるため、コンソールへのログ出力は抑止。 -->
-                    <handler name="CONSOLE"/>
                     <handler name="FILE"/>
                 </handlers>
             </root-logger>
@@ -137,18 +136,24 @@
                         <password>sa</password>
                     </security>
                 </datasource>
<!-- 記載してあるKeycloakDSの記載を削除する -->
-                <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>
<!-- KeycloakDSをPostgreSQLに接続する設定に変更したものを追記。 -->
<!-- ユーザ名やパスワードはPostgreSQLで設定したものを使用する -->
+                <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true">
+                    <connection-url>jdbc:postgresql://192.168.1.3/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="h2" module="com.h2database.h2">
                         <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
                     </driver>
<!-- PostgreSQL JDBC Driverの設定を追加 -->
+                    <driver name="postgresql" module="org.postgresql">
+                        <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
+                    </driver>
                 </drivers>
             </datasources>
         </subsystem>
@@ -471,6 +476,7 @@
                         <property name="initializeEmpty" value="true"/>
                         <property name="migrationStrategy" value="update"/>
                         <property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
<!-- スキーマを指定。PostgreSQLで設定したものを使用する -->
+                        <property name="schema" value="keycloak"/>
                     </properties>
                 </provider>
             </spi>

keycloak.confの編集

docs/contrib/scripts/systemdに、WildFlyをsystemd経由で起動するためのスクリプト、設定ファイルのひな形が格納されている。
また、簡単な手順がREADMEに記載されているため、このファイルに従ってKeycloak向けのsystemdの設定を行う。

mkdir /etc/keycloak
cp -a /opt/keycloak/docs/contrib/scripts/systemd/wildfly.conf /etc/keycloak/keycloak.conf

keycloak.confに記載する内容は以下の通り。
WILDFLY_HOMEとJAVA_OPTSを追記している。

# Home directory
WILDFLY_HOME=/opt/keycloak

# The configuration you want to run
WILDFLY_CONFIG=standalone.xml

# The mode you want to run
WILDFLY_MODE=standalone

# The address to bind to
WILDFLY_BIND=192.168.1.3

# JAVA_OPTS
JAVA_OPTS="-Xms512m -Xmx1024m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=org.jboss.byteman -Djava.awt.headless=true -Djboss.server.log.dir=/var/log/keycloak"

WILDFLY_HOMEはKeycloakをインストールしたディレクトリを指定するが、デフォルトでは/opt/wildflyを参照するようになっている。

JAVA_OPTSはWildFlyのコンフィグファイルであるbin/standalone.confで設定されるが、編集するファイルを少なくするため、本ファイルに追記している。設定内容はbin/standalone.confに記載されているものをコピーしたのと、ログディレクトリを指定するため、-Djboss.server.log.dir=/var/log/keycloakを追記している。

起動スクリプト(launch.sh)の編集

keycloak.confと同様に、Keycloakが用意している起動スクリプトを利用する。

cp -a /opt/keycloak/docs/contrib/scripts/systemd/launch.sh /opt/keycloak/bin/
chmod +x /opt/keycloak/bin/launch.sh

実行ユーザの作成

Keycloakをデーモンとして実行するときのOSのユーザを作成する。

groupadd -r keycloak
useradd -r -g keycloak -d /opt/keycloak -s /sbin/nologin keycloak

ログディレクトリの作成

JAVA_OPTSで設定したログディレクトリを作成する。
CentOSの流儀に合わせてログは/var/log配下にまとめる。

mkdir -p /var/log/keycloak                  
chown -R keycloak:keycloak /var/log/keycloak

管理ユーザの作成

Keycloak上で操作を行うための管理ユーザを作成する。
以下のスクリプトで作成が可能で、ユーザ名、パスワードは任意の値が設定できる。

./add-user-keycloak.sh -r master -u admin -p password

systemdのserviceファイル作成

keycloak.confと同様に、Keycloakが用意しているserviceファイルのひな形をベースとして使用する。

[Unit]
Description=The Keycloak Application Server
After=syslog.target network.target

[Service]
Type=idle
Environment=LAUNCH_JBOSS_IN_BACKGROUND=1
EnvironmentFile=-/etc/keycloak/keycloak.conf
User=keycloak
Group=keycloak
LimitNOFILE=102642
PermissionsStartOnly=true
ExecStartPre=/usr/bin/mkdir -p /var/run/keycloak
ExecStartPre=/usr/bin/chown -R keycloak:keycloak /var/run/keycloak
PIDFile=/var/run/keycloak/keycloak.pid
ExecStart=/opt/keycloak/bin/launch.sh $WILDFLY_MODE $WILDFLY_CONFIG $WILDFLY_BIND
StandardOutput=null
ExecStopPost=/usr/bin/rm -rf /var/run/keycloak

[Install]
WantedBy=multi-user.target

Keycloakが提供するものからの変更点で、注意する部分は以下の箇所。
CentOS Stream 8では/var/run配下はシステム停止時に削除されるため、サービス起動時にディレクトリを作成するように設定している。

PermissionsStartOnly=true
ExecStartPre=/usr/bin/mkdir -p /var/run/keycloak
ExecStartPre=/usr/bin/chown -R keycloak:keycloak /var/run/keycloak
ExecStopPost=/usr/bin/rm -rf /var/run/keycloak

Keycloakの起動

chown -R keycloak:keycloak /opt/keycloak
systemctl daemon-reload
systemctl enable keycloak.service
systemctl start keycloak.service

Keycloakの管理画面へのアクセス

以下のURLへアクセスするとKeycloakの管理画面が表示される。
ログインに使用するのは、管理ユーザの作成で作成したユーザである。

https://192.168.1.3:8443/auth

参考