データベースの設定

リレーショナルデータベースの設定方法の概要

このガイドでは、Keycloakサーバーがリレーショナルデータベースにデータを保存するように設定する方法について説明します。

サポートされているデータベース

サーバーは、さまざまなデータベースを組み込みでサポートしています。利用可能なデータベースを調べるには、db 設定オプションの期待される値を参照してください。次の表に、サポートされているデータベースと、テスト済みのバージョンを示します。

データベースオプション値テスト済みバージョン

データベース	オプション値	テスト済みバージョン
MariaDB Server	`mariadb`	11.4
Microsoft SQL Server	`mssql`	2022
MySQL	`mysql`	8.4
Oracle Database	`oracle`	23.5
PostgreSQL	`postgres`	17
Amazon Aurora PostgreSQL	`postgres`	16.1

MariaDB Server

mariadb

11.4

Microsoft SQL Server

mssql

2022

MySQL

mysql

8.4

Oracle Database

oracle

23.5

PostgreSQL

postgres

Amazon Aurora PostgreSQL

postgres

16.1

デフォルトでは、サーバーは dev-file データベースを使用します。これは、サーバーがデータを永続化するために使用するデフォルトのデータベースであり、開発でのユースケースでのみ存在します。dev-file データベースは本番環境でのユースケースには適していないため、本番環境にデプロイする前に置き換える必要があります。

データベースドライバのインストール

データベースドライバは、Oracle Databaseドライバを除き、Keycloakの一部として同梱されています。

このデータベースに接続する場合は、必要な不足しているドライバを手動でインストールするか、データベースドライバがすでに含まれている別のデータベースに接続する場合は、このセクションをスキップしてください。

Oracle Databaseドライバのインストール

Keycloak用のOracle Databaseドライバをインストールするには

次のいずれかのソースから ojdbc17 および orai18n JARファイルをダウンロードします
1. Zipped JDBC driver and Companion Jars version 23.6.0.24.10 from the Oracleドライバのダウンロードページ。
2. Maven Central経由 (ojdbc17 および orai18n)。
3. 使用中の特定のデータベースについて、データベースベンダーが推奨するインストールメディア。
解凍されたディストリビューションを実行する場合：ojdbc17 および orai18n JARファイルをKeycloakの providers フォルダに配置します

コンテナを実行する場合：カスタムKeycloakイメージをビルドし、JARを providers フォルダに追加します。Operator用のカスタムイメージをビルドする場合、これらのイメージは、Keycloakのすべてのビルド時オプションが設定された最適化されたイメージである必要があります。

Keycloak Operatorで使用でき、Maven CentralからダウンロードしたOracle Database JDBCドライバを含むイメージをビルドするための最小限のContainerfileは、次のようになります

FROM quay.io/keycloak/keycloak:latest
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc17/23.6.0.24.10/ojdbc17-23.6.0.24.10.jar /opt/keycloak/providers/ojdbc17.jar
ADD --chown=keycloak:keycloak --chmod=644 https://repo1.maven.org/maven2/com/oracle/database/nls/orai18n/23.6.0.24.10/orai18n-23.6.0.24.10.jar /opt/keycloak/providers/orai18n.jar
# Setting the build parameter for the database:
ENV KC_DB=oracle
# Add all other build parameters needed, for example enable health and metrics:
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
# To be able to use the image with the Keycloak Operator, it needs to be optimized, which requires Keycloak's build step:
RUN /opt/keycloak/bin/kc.sh build

最適化されたイメージをビルドする方法の詳細については、コンテナでのKeycloakの実行ガイドを参照してください。

次に、次のセクションで説明されているように、データベースの設定を続行します。

データベースの設定

サポートされている各データベースについて、サーバーはデータベースの設定を簡素化するために、いくつかの意見に基づいたデフォルト設定を提供します。データベースホストや認証情報などの主要な設定を提供することで、設定を完了できます。

設定は、build コマンドまたは start コマンドの実行中に設定できます

build コマンドの後に最適化された start コマンドを使用する（推奨）

まず、データベースに接続するために必要な最小限の設定を conf/keycloak.conf で指定できます
```
# The database vendor.
db=postgres

# The username of the database user.
db-username=keycloak

# The password of the database user.
db-password=change_me

# Sets the hostname of the default JDBC URL of the chosen vendor
db-url-host=keycloak-postgres
```
次に、次のコマンドは、設定オプションに基づいて新しい最適化されたサーバーイメージを作成し、サーバーを起動します。
```
bin/kc.[sh|bat] build
bin/kc.[sh|bat] start --optimized
```

start コマンドのみを使用する（--optimized なし）

bin/kc.[sh|bat] start --db postgres --db-url-host keycloak-postgres --db-username keycloak --db-password change_me

上記の例には、データベースに接続するために必要な最小限の設定が含まれていますが、データベースパスワードが公開されるため、推奨されません。少なくともパスワードには、上記のように conf/keycloak.conf、環境変数、またはキーストアを使用してください。

デフォルトのスキーマは keycloak ですが、db-schema 設定オプションを使用して変更できます。

レルムのインポートとエクスポートまたは管理者ブートストラップとリカバリの際にデータベースを設定することも可能です

bin/kc.[sh|bat] import --help
bin/kc.[sh|bat] export --help
bin/kc.[sh|bat] bootstrap-admin --help

詳細については、Keycloakの設定を参照してください。

デフォルトの接続設定の上書き

サーバーは、データベースと通信するための基盤技術としてJDBCを使用します。デフォルトの接続設定が不十分な場合は、db-url 設定オプションを使用してJDBC URLを指定できます。

以下は、PostgreSQLデータベースのサンプルコマンドです。

bin/kc.[sh|bat] start --db postgres --db-url jdbc:postgresql://mypostgres/mydatabase

CLIを使用して ; などの特殊なシェル文字を含むコマンドを呼び出す場合は、文字をエスケープする必要があることに注意してください。そのため、代わりに設定ファイルで設定することをお勧めします。

デフォルトのJDBCドライバの上書き

サーバーは、選択したデータベースに応じてデフォルトのJDBCドライバを使用します。

別のドライバを設定するには、JDBCドライバの完全修飾クラス名で db-driver を設定できます

bin/kc.[sh|bat] start --db postgres --db-driver=my.Driver

設定したドライバに関係なく、デフォルトのドライバは常にランタイムで利用可能です。

本当に必要な場合にのみ、このプロパティを設定してください。たとえば、特定のクラウドデータベースサービス用のJDBCドライバラッパーの機能を利用する場合などです。

データベースのUnicodeサポートの設定

すべてのフィールドのUnicodeサポートは、データベースがVARCHARフィールドとCHARフィールドでUnicode文字セットを使用できるかどうかによって異なります。

これらのフィールドを設定できる場合、Unicodeは機能する可能性が高くなります。通常はフィールド長の犠牲を伴います。
データベースがNVARCHARフィールドとNCHARフィールドでのみUnicodeをサポートしている場合、サーバーのスキーマはVARCHARフィールドとCHARフィールドを広範囲に使用するため、すべてのテキストフィールドのUnicodeサポートは機能しない可能性が高くなります。

データベーススキーマは、次の特別なフィールドでのみUnicode文字列のサポートを提供します

レルム：表示名、HTML表示名、ローカライズテキスト（キーと値）
フェデレーションプロバイダー：表示名
ユーザー：ユーザー名、名、姓、属性名と値
グループ：名前、属性名と値
ロール：名前
オブジェクトの説明

それ以外の場合、文字はデータベースエンコーディングに含まれる文字に制限されます。これは多くの場合8ビットです。ただし、一部のデータベースシステムでは、Unicode文字のUTF-8エンコーディングを有効にし、すべてのテキストフィールドで完全なUnicode文字セットを使用できます。特定のデータベースの場合、この選択により、8ビットエンコーディングでサポートされる最大文字列長よりも短い最大文字列長になる可能性があります。

OracleデータベースのUnicodeサポートの設定

Oracleデータベースでは、データベースがVARCHARフィールドとCHARフィールドでUnicodeサポート付きで作成された場合、Unicode文字がサポートされます。たとえば、データベース文字セットとしてAL32UTF8を設定した場合などです。この場合、JDBCドライバは特別な設定を必要としません。

データベースがUnicodeサポートなしで作成された場合、特別なフィールドでUnicode文字をサポートするようにJDBCドライバを設定する必要があります。2つのプロパティを設定します。これらのプロパティは、システムプロパティまたは接続プロパティとして設定できることに注意してください。

oracle.jdbc.defaultNChar を true に設定します。
オプションで、oracle.jdbc.convertNcharLiterals を true に設定します。

これらのプロパティおよびパフォーマンスへの影響の詳細については、Oracle JDBCドライバの構成ドキュメントを参照してください。

Microsoft SQL ServerデータベースのUnicodeサポート

Microsoft SQL Serverデータベースの場合、Unicode文字は特別なフィールドでのみサポートされます。データベースは特別な設定を必要としません。

JDBCドライバの sendStringParametersAsUnicode プロパティは、パフォーマンスを大幅に向上させるために false に設定する必要があります。このパラメータがないと、Microsoft SQL Serverはインデックスを使用できなくなる可能性があります。

MySQLデータベースのUnicodeサポートの設定

MySQLデータベースでは、CREATE DATABASEコマンドを使用するときに、データベースがVARCHARフィールドとCHARフィールドでUnicodeサポート付きで作成された場合、Unicode文字がサポートされます。

utf8mb4文字セットは、utf8文字セットのストレージ要件が異なるため、サポートされていないことに注意してください。詳細については、MySQLのドキュメントを参照してください。その状況では、特別なフィールド以外のフィールドの長さ制限は適用されません。これは、列がバイト数ではなく文字数を収容するように作成されるためです。データベースのデフォルト文字セットがUnicodeストレージを許可しない場合、特別なフィールドのみがUnicode値を格納できます。

MySQLサーバーを起動します。
JDBCドライバの設定で、「JDBC接続設定」を見つけます。
次の接続プロパティを追加します：characterEncoding=UTF-8

PostgreSQLデータベースのUnicodeサポートの設定

PostgreSQLデータベースでは、データベース文字セットがUTF8の場合にUnicodeがサポートされます。Unicode文字は、特別なフィールド以外のフィールドのフィールド長を短縮することなく、任意のフィールドで使用できます。JDBCドライバは特別な設定を必要としません。文字セットは、PostgreSQLデータベースが作成されるときに決定されます。

次のSQLコマンドを入力して、PostgreSQLクラスタのデフォルト文字セットを確認します。
```
show server_encoding;
```
デフォルトの文字セットがUTF 8でない場合は、次のようなコマンドを使用して、UTF8をデフォルトの文字セットとしてデータベースを作成します
```
create database keycloak with encoding 'UTF8';
```

Amazon Aurora PostgreSQLの準備

Amazon Aurora PostgreSQLを使用する場合、「Amazon Web Services JDBC Driver」は、Multi-AZセットアップでライターインスタンスが変更されたときのデータベース接続の転送などの追加機能を提供します。このドライバはディストリビューションの一部ではないため、使用する前にインストールする必要があります。

このドライバをインストールするには、次の手順を実行します

解凍されたディストリビューションを実行する場合：「Amazon Web Services JDBC Driver」のリリースページからJARファイルをダウンロードし、Keycloakの providers フォルダに配置します。
コンテナを実行する場合：カスタムKeycloakイメージをビルドし、JARを providers フォルダに追加します。

Keycloak Operatorで使用できるイメージをビルドするための最小限のContainerfileは、次のようになります
```
FROM quay.io/keycloak/keycloak:latest
ADD --chmod=0666 https://github.com/awslabs/aws-advanced-jdbc-wrapper/releases/download/2.3.1/aws-advanced-jdbc-wrapper-2.3.1.jar /opt/keycloak/providers/aws-advanced-jdbc-wrapper.jar
```
最適化されたイメージをビルドする方法の詳細については、「コンテナでのKeycloakの実行」ガイドを参照してください。また、Keycloak Operatorで最適化されたイメージと最適化されていないイメージを実行する方法については、「カスタムKeycloakイメージの使用」ガイドを参照してください。
次のパラメータでKeycloakを実行するように設定します

db-url

aws-wrapper を通常のPostgreSQL JDBC URLに挿入すると、jdbc:aws-wrapper:postgresql://... のようなURLになります。

db-driver

AWS JDBCラッパーを使用するには、software.amazon.jdbc.Driver に設定します。

MySQLサーバーの準備

MySQL 8.0.30以降、MySQLは、明示的なプライマリキーなしで作成されたInnoDBテーブルに対して、生成された非表示のプライマリキーをサポートしています（詳細についてはこちら）。この機能が有効になっている場合、データベーススキーマの初期化と移行は、エラーメッセージ Multiple primary key defined (1068) で失敗します。Keycloakをインストールまたはアップグレードする前に、MySQLサーバー構成でパラメータ sql_generate_invisible_primary_key を OFF に設定して無効にする必要があります。

クラスタ構成でのデータベースロックタイムアウトの変更

クラスタノードは同時に起動できるため、データベースアクションに余分な時間がかかります。たとえば、起動中のサーバーインスタンスは、データベースの移行、インポート、または初回初期化を実行する場合があります。データベースロックは、クラスタノードが同時に起動するときに、起動アクションが互いに競合するのを防ぎます。

このロックの最大タイムアウトは900秒です。ノードがこのロックをタイムアウトよりも長く待機すると、起動は失敗します。デフォルト値を変更する必要性は低いですが、次のコマンドを入力して変更できます

bin/kc.[sh|bat] start --spi-dblock-jpa-lock-wait-timeout 900

XAトランザクションをサポートするデータベースベンダーの使用

Keycloakはデフォルトで非XAトランザクションと適切なデータベースドライバを使用します。

ドライバが提供するXAトランザクションサポートを使用する場合は、次のコマンドを入力します

bin/kc.[sh|bat] build --db=<vendor> --transaction-xa-enabled=true

Keycloakは、ベンダーに適したJDBCドライバを自動的に選択します。

Azure SQLやMariaDB Galeraなど、一部のベンダーはXAトランザクションメカニズムをサポートまたは依存していません。

XAリカバリはデフォルトで有効になっており、トランザクションログを格納するためにファイルシステムの場所 KEYCLOAK_HOME/data/transaction-logs を使用します。

コンテナ化された環境でXAトランザクションを有効にしても、そのパスに安定したストレージが利用可能でない限り、XAリカバリは完全にサポートされません。

migrationStrategyのJPAプロバイダー設定オプションの設定

JPA migrationStrategy（manual/update/validate）を設定するには、次のようにJPAプロバイダーを設定する必要があります

connections-jpa SPIの quarkus プロバイダーの migration-strategy の設定

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual

DB初期化用のSQLファイルも取得する場合は、この追加のSPI initializeEmpty（true/false）を追加する必要があります

connections-jpa SPIの quarkus プロバイダーの initialize-empty の設定

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-initialize-empty=false

同様に、migrationExportを特定のファイルと場所にポイントします

connections-jpa SPIの quarkus プロバイダーの migration-export の設定

bin/kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>

詳細については、データベースの移行ドキュメントを確認してください。

データベースの設定

サポートされているデータベース

データベースドライバのインストール

Oracle Databaseドライバのインストール

データベースの設定

デフォルトの接続設定の上書き

デフォルトのJDBCドライバの上書き

データベースのUnicodeサポートの設定

OracleデータベースのUnicodeサポートの設定

Microsoft SQL ServerデータベースのUnicodeサポート

MySQLデータベースのUnicodeサポートの設定

PostgreSQLデータベースのUnicodeサポートの設定

Amazon Aurora PostgreSQLの準備

MySQLサーバーの準備

クラスタ構成でのデータベースロックタイムアウトの変更

XAトランザクションをサポートするデータベースベンダーの使用

migrationStrategyのJPAプロバイダー設定オプションの設定

関連オプション