--- title: "Keycloakのデータベース設定と使い方｜PostgreSQL接続・対応DB・バックアップから権限モデルまで" url: "https://www.issoh.co.jp/tech/details/3293/" published: 2024-08-06 updated: 2026-10-15 categories: ["セキュリティ"] publisher: "株式会社一創" --- # Keycloakのデータベース設定と使い方｜PostgreSQL接続・対応DB・バックアップから権限モデルまで Keycloakはレルム・ユーザー・クライアントの設定をすべてデータベースに保存します。起動直後に使われるのは開発専用のdev-fileで、本番ではPostgreSQLなど外部のDBへ切り替える作業が前提です。この記事では、26.8系の公式ドキュメントをもとに、起動と初期管理者の作成、対応データベースと版、Docker ComposeでPostgreSQLへつなぐ設定例、接続プール・TLS・バックアップの決め方を手順で示します。後半ではロール・グループ・属性による権限モデルと、外部DB構成を採用する条件まで扱います。 ## まとめ：Keycloakの起動とDB設定で最初に押さえる5つの判断ポイント - **起動コマンドは`bin/kc.sh start-dev`**（Windowsは`bin\kc.bat start-dev`）。`standalone.sh`は旧ディストリビューションのもので現行版には存在しません。 - **前提はOpenJDK 25**。公式のGetting Startedが明示しています。 - **既定の管理者ユーザーは存在しません**。`http://localhost:8080/`を開いて表示されるフォームで自分で作成します。admin/adminでは入れません。 - **start-devは本番で使えません**。開発モードは検証向けの既定値で動くため、本番はビルドと明示的な設定を伴う`start`で起動します。 - **既定のDBはdev-fileで、本番では外部DBが必須**。第一候補はPostgreSQL（26.8系で14〜18系をサポート）で、バックアップの対象もこのDBです。 2026年10月15日時点の最新安定版は[GitHub Releases](https://github.com/keycloak/keycloak/releases)で26.8.1（10月13日公開）です。26系はリリース間隔が短く、9月だけでも26.7.4と26.7.5が出ています。記事やドキュメントを参照するときは対象バージョンを必ず確認してください。 ## Keycloakの起動と初期設定｜ZIP版start-devから管理者作成までの手順 ZIP配布版で試す場合の手順です。[公式のGetting Started（OpenJDK版）](https://www.keycloak.org/getting-started/getting-started-zip)はOpenJDK 25のインストールを前提にしています。配布物を展開したら、次のコマンドで開発モードを起動します。 ### ZIP配布版のstart-dev起動とstandalone.shが見つからない理由 ``` # Linux / macOS bin/kc.sh start-dev # Windows bin\kc.bat start-dev ``` ここで`standalone.sh`を探しても見つかりません。KeycloakはWildFlyベースからQuarkusベースへ移行しており、**起動スクリプトの名前も設定の仕組みも別物になっています。**古い記事の手順が動かない原因はほぼこれです。設定は`conf/keycloak.conf`、`KC_`で始まる環境変数、コマンドラインオプションの3経路で渡します。 ### 初期管理者ユーザーの作成とbootstrap-adminによる一時管理者の発行 起動したら`http://localhost:8080/`にアクセスします。公式ドキュメントは「Keycloak has no default admin user.」と明記しており、**初期管理者は存在しません。**最初のアクセスで表示されるフォームにユーザー名とパスワードを入力して作成します。 作成後、管理コンソールは`http://localhost:8080/admin`です。ルートURLと管理コンソールのURLが分かれている点も、旧版から変わった部分です。 コンテナや自動構築ではフォームを開けないため、環境変数`KC_BOOTSTRAP_ADMIN_USERNAME`と`KC_BOOTSTRAP_ADMIN_PASSWORD`で一時管理者を作ります。[管理者のブートストラップと復旧のガイド](https://www.keycloak.org/server/bootstrap-admin-recovery)によれば、この値が使われるのはmasterレルムがまだ無い初回起動時だけです。作られたアカウントは一時的な扱いで、恒久的な管理者を用意したら手で削除します。管理者を失ったときは、全ノードを止めて`bin/kc.sh bootstrap-admin user`で作り直せます。 ### start-devを本番へ持ち込まない理由とstartコマンドとの設定差 `start-dev`は名前のとおり開発用です。HTTPSの強制やキャッシュ、データベース接続といった本番向けの設定が省略されており、そのまま本番に出すとセキュリティと性能の両面で問題になります。**本番では設定を確定させたうえで通常の`start`を使い、外部データベースとHTTPSを明示的に構成してください。**本番化の確認項目は[Configuring Keycloak for production](https://www.keycloak.org/server/configuration-production)にまとまっています。 ## Keycloakがデータベースに保存するデータと既定のdev-fileを本番で使えない理由 Keycloakの設定はファイルではなくデータベースに入ります。DBの扱いを決めることは、認証基盤そのものの保全方針を決めることと同じです。 ### レルム・ユーザー・クライアントからセッションまでDBに入る保存範囲 [公式のデータベース設定ガイド](https://www.keycloak.org/server/db)は冒頭で、DBの役割を「ユーザー・クライアント・レルムのデータを保存する」と定義しています。さらに同ガイドはDBに入る機密情報として、ハッシュ化されたパスワード、クライアントの認証情報、トークン署名に使うレルムの鍵を挙げ、保存時の暗号化を推奨しています。 26系では永続化されたユーザーセッションやイベントもDBのテーブルに書かれます。[26.8.0のリリースノート](https://www.keycloak.org/docs/latest/release%5Fnotes/index.html)では、ブルートフォース検知によるログイン失敗の記録も既定でDB保存に変わり、ロック中のユーザーはクラスタを再起動してもロックが続くようになりました。**DBを失うと、設定だけでなくログイン状態とロック状態まで失います。** ### 既定のdev-fileデータベースが検証専用とされる根拠と失われる設定 何も指定しないとKeycloakは`dev-file`というファイル型の組み込みDBを使います。公式ガイドは「開発用途のためだけに存在し、本番デプロイ前に置き換える必要がある」と書いています。[全設定オプションの一覧](https://www.keycloak.org/server/all-config)でも、本番モードでの`dev-file`既定値は非推奨扱いです。 **組み込みDBのまま運用すると、コンテナやプロセスの再作成でレルム・ユーザー・クライアントの設定が失われます。**ボリュームを付ければ残せますが、複数ノードで共有できず、バックアップとレプリケーションの道具も揃いません。 ## Keycloakが対応するデータベース一覧とバージョン別のサポート範囲（26.8系時点） `db`オプションに指定する値と、公式ガイドが掲げるテスト済み版・サポート版の対応です（2026年10月15日時点・26.8.1のドキュメント）。 | データベース | db の値 | テスト済み版 | サポート版 | | ------------------------ | -------- | ------ | -------------- | | PostgreSQL | postgres | 18 | 18.x〜14.x | | Amazon Aurora PostgreSQL | postgres | 17.5 | 17.x〜15.x | | MySQL | mysql | 8.4 | 8.4・8.0（LTS） | | MariaDB Server | mariadb | 11.8 | 11.8〜10.6（LTS） | | Microsoft SQL Server | mssql | 2022 | 2022・2019 | | Oracle Database | oracle | 23.5 | 23.x・19c | | Azure SQL Database | mssql | latest | latest | このほかEnterpriseDB AdvancedとAzure SQL Managed Instanceが載っています。表の範囲を外れる版は、Hibernateの方言が動作を許しても「サポート外の構成」と明記されています。 ### PostgreSQLを第一候補にする理由とOracleだけドライバ追加が要る点 新規構築ならPostgreSQLを選びます。サポート版の幅が最も広く、Aurora PostgreSQLやKubernetes上のCloudNativePGまで公式ガイドが手順を持っているためです。書き込み先がプライマリに限られるよう、Keycloakは標準ドライバの`targetServerType`を自動で`primary`に設定します。リードレプリカを立てても、Keycloakの接続先は常に書き込み可能なインスタンスです。 JDBCドライバは同梱されますが、Oracle Databaseだけは例外です。`ojdbc17`と`orai18n`のJARを`providers`フォルダへ置くか、コンテナならカスタムイメージに組み込みます。社内標準がOracleでも、ドライバ管理とイメージ再ビルドの手間を受け入れられるかで判断が分かれます。 ## Docker ComposeでKeycloakとPostgreSQLをつなぐ設定と確認 手元で外部DB構成を再現する最小の定義です。本番の形に近い状態で、レルムがDBに書かれることを確認できます。 ### compose.yamlでPostgreSQL 18とKeycloakを同時起動する定義 ``` services: postgres: image: postgres:18 environment: POSTGRES_DB: keycloak POSTGRES_USER: keycloak POSTGRES_PASSWORD: change_me volumes: - pgdata:/var/lib/postgresql healthcheck: test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"] interval: 5s retries: 10 keycloak: image: quay.io/keycloak/keycloak:26.8.1 command: start-dev environment: KC_DB: postgres KC_DB_URL_HOST: postgres KC_DB_URL_DATABASE: keycloak KC_DB_USERNAME: keycloak KC_DB_PASSWORD: change_me KC_BOOTSTRAP_ADMIN_USERNAME: tmpadm KC_BOOTSTRAP_ADMIN_PASSWORD: change_me ports: - "127.0.0.1:8080:8080" depends_on: postgres: condition: service_healthy volumes: pgdata: ``` `docker compose up -d`で起動します。ボリュームの付け先が`/var/lib/postgresql`なのは、PostgreSQL 18の公式イメージでデータの置き場所が変わったためです。17系までの`/var/lib/postgresql/data`のまま書くと、名前付きボリュームが使われずデータが匿名ボリュームへ逃げます。経緯は[Docker PostgreSQL構築の手順｜18で変わったボリューム位置とcompose定義・initdb初期化](https://www.issoh.co.jp/tech/details/16976/)で詳しく扱っています。`healthcheck`と`condition: service_healthy`は、DBの準備前にKeycloakが接続を試みて起動に失敗するのを防ぐための記述です。 起動後にテーブルが作られたか確かめます。 ``` docker compose exec postgres psql -U keycloak -d keycloak -c "\dt" | head -n 15 docker compose exec postgres psql -U keycloak -d keycloak -c "SELECT name, enabled FROM realm;" ``` 2つ目のSQLで`master`が返れば、レルムの設定は外部DBに書かれています。 ### keycloak.confとbuildで本番向けのDB接続を固める手順 公式ガイドが推奨するのは、設定ファイルで接続先を決め、`build`で構成を確定させてから`start --optimized`で起動する流れです。`--db-password`をコマンドラインに書く例も載っていますが、パスワードがプロセス一覧に残るため推奨されていません。 ``` # conf/keycloak.conf db=postgres db-url-host=db.internal.example.com db-url-database=keycloak db-username=keycloak # パスワードは環境変数 KC_DB_PASSWORD で渡す db-pool-max-size=40 db-tls-mode=verify-server db-tls-trust-store-file=/opt/keycloak/conf/db-ca.pem hostname=https://auth.example.com # 構成を確定させてから起動する bin/kc.sh build bin/kc.sh start --optimized ``` JDBC URLを丸ごと指定したい場合は`db-url`を使います。こちらを指定すると`db-url-host`などの個別オプションは無視されます。 ### 文字コードUTF8でのデータベース作成とdb-schemaによるスキーマ指定 DBを先に用意する場合は文字コードを最初に決めます。公式ガイドが示すPostgreSQLの作成例です。 ``` CREATE DATABASE keycloak ENCODING 'UTF8' LC_COLLATE 'en_US.utf8' LC_CTYPE 'en_US.utf8'; ``` MySQLとMariaDBなら`utf8mb4`、Oracleなら`AL32UTF8`が推奨です。日本語のユーザー名やグループ名を扱うなら、ここで外すと後から直せません。26.8.0からは起動時にDBの文字コードを検査し、UTF-8でなければ警告を出します。 スキーマは既定でDBのデフォルトスキーマが使われ、`db-schema`で変更できます。Keycloak用の接続ユーザーには、テーブル作成とスキーマ移行に必要な権限を持たせるのが前提です。PostgreSQLでは、アップグレード時の行数見積もりのために`pg_class`と`pg_namespace`へのSELECT権限も求められます。ロールの切り方は[PostgreSQLのロールと権限設計｜CREATE ROLEの属性とGRANT・既定権限の決め方](https://www.issoh.co.jp/tech/details/16984/)が参考になります。 ## Keycloak DBの接続プール・TLS・タイムアウトを本番運用に合わせる設定値 接続できた後に効いてくるのが、接続数の上限と通信の保護です。既定値のまま本番へ出すと、ノードを増やした時点で破綻する項目があります。 ### db-pool-max-size既定100をDBの接続上限から逆算して決める考え方 Keycloakの接続プールの上限`db-pool-max-size`は既定で100です（[全設定オプション](https://www.keycloak.org/server/all-config)）。一方、PostgreSQLの[max\_connections](https://www.postgresql.org/docs/current/runtime-config-connection.html)も既定は通常100です。**Keycloakを2ノードにした時点で、プールの合計がDBの上限を超えます。** 決め方は単純で、「Keycloakのノード数×`db-pool-max-size`」に保守用の余裕を足した値が`max_connections`に収まるよう、どちらかを調整します。3ノードでDB上限が150なら、プールは40前後に抑えるのが目安です。 ### db-tls-modeでDB接続を暗号化し証明書まで検証する設定 26.8.0でDBのTLS設定はベンダー共通のオプションにまとまりました。`db-tls-mode=verify-server`で暗号化とサーバ証明書の検証を同時に有効にし、`db-tls-trust-store-file`でCA証明書を渡します。既定は`disabled`です。 PostgreSQLではトラストストアにPEM形式を使います。Aurora PostgreSQL 17.0以降は既定でTLS接続を求めますが、暗号化だけでは中間者を防げないため、リージョンの証明書バンドルを取得して検証まで有効にします。 ### MySQLの不可視主キーとSQL Serverの分離レベルで詰まる点 PostgreSQL以外を選ぶ場合、DB側の設定変更が先に必要です。MySQL 8.0.30以降で生成される不可視主キーが有効だと、スキーマ初期化と移行が`Multiple primary key defined (1068)`で失敗します。インストールやアップグレードの前に`sql_generate_invisible_primary_key`を`OFF`にします。 SQL Serverは既定の分離レベルREAD\_COMMITTEDで高負荷時にデッドロックを起こしやすく、公式ガイドは`ALTER DATABASE <データベース名> SET READ_COMMITTED_SNAPSHOT ON;`の実行を求めています。このコマンドはDBへの排他アクセスが必要なので、Keycloakの全インスタンスを止めてから流します。 ## Keycloakのバックアップとレルムのエクスポートで復旧手段を二重化する手順 運用で効いてくるのは**バックアップの対象がこのデータベースだということ**です。DBを失うと認証基盤ごと失います。レルムのエクスポートも併用すると復旧の選択肢が増えます。 ### DBバックアップを主・kc.sh exportを従にする理由と停止が必要な条件 ``` # 1. DBのバックアップ（稼働中でも取得できる） pg_dump -Fc -h db.internal.example.com -U keycloak -d keycloak -f keycloak_$(date +%Y%m%d).dump # 2. レルムのエクスポート（Keycloakを停止してから実行する） bin/kc.sh export --dir /backup/kc-export --realm myrealm --users different_files --users-per-file 100 ``` 主はDBのバックアップです。[pg\_dump](https://www.postgresql.org/docs/current/app-pgdump.html)は稼働中でも一貫したスナップショットを取れ、セッションや鍵を含めて丸ごと戻せます。PITRとの使い分けや復旧検証の進め方は[PostgreSQLのバックアップ設計｜pg\_dumpとPITRの使い分け・復旧検証の手順](https://www.issoh.co.jp/tech/details/16996/)にまとめています。 エクスポートは従の手段です。[インポートとエクスポートのガイド](https://www.keycloak.org/server/importExport)は、エクスポートの一貫性は全ノード停止時にしか保証されないと書いています。レルム単位のJSONなので、別環境への複製や設定差分の確認に向いた形式です。インポートの`--override`は既定で`true`なので、既存レルムを残したいときは`false`を明示します。 ### アップグレード前に確認するスキーマ移行とトランザクションのタイムアウト Keycloakは起動時にDBのスキーマを自動で移行します。移行やインポートに使われるトランザクションの上限は`transaction-setup-timeout`で、既定は30分です。大きなテーブルを持つ環境では移行がこれを超えることがあるため、アップグレード前に`1h`などへ延ばしておきます。 26.8.0では、大きなテーブルでも非ブロッキングでインデックスを作れるDBなら移行中に作成するよう変わりました。非対応のDBでは従来どおりSQLがログに出るので、手で実行します。**アップグレードの前には必ずDBのバックアップを取り、検証環境で同じ版への移行を一度通してください。** ## 権限モデル｜ロール・グループ・属性をKeycloakで使い分ける設計基準 Keycloakの権限設計で迷うのは、ロールとグループのどちらで表現するかです。役割は明確に分かれています。 | 概念 | 表すもの | 典型的な使い方 | | ---- | ------------ | ----------------------- | | ロール | 権限そのもの | admin / editor / viewer | | グループ | ユーザーの集合 | 部署・チーム単位 | | 属性 | ユーザーやリソースの性質 | 所属拠点・契約プラン | ### 権限はロールで定義し、割り当てはグループ経由にする運用とその根拠 実務上の指針はこうです。**権限はロールで定義し、ユーザーへの割り当てはグループ経由で行います。**グループにロールを紐づけておけば、人事異動のときにグループの所属を変えるだけで権限が切り替わります。ユーザーへロールを直接割り当てる運用では、対象が増えるほど棚卸しが追いつかなくなるのが実情です。 レルムの使い方も同じ考え方です。公式のGetting Startedは、最初からある`master`レルムをKeycloak自身の管理だけに使い、アプリケーション用には別のレルムを作るよう指示しています。 ### ユーザー属性をトークンのクレームに載せるABAC的な判定と線引き 「部署が営業かつ拠点が東京のユーザーだけ許可する」といった条件は、ロールの数を増やして表現すると組み合わせ爆発を起こします。この場合はユーザー属性を使い、条件で判定する設計に切り替えます。 Keycloakでは、ユーザー属性をトークンのクレームにマッピングして払い出せます。アプリケーション側はIDトークンやアクセストークンを検証したうえで、そのクレームを見て判定します。トークン検証の手順は[OIDC（OpenID Connect）とは？IDトークンの検証手順とOAuth 2.0との違い](https://www.issoh.co.jp/tech/details/6532/)で解説しました。**「誰が」ではなく「どういう属性を持つか」で判断する設計に寄せると、ロールの数を抑えられます。**ただし判定ロジックがアプリ側に分散するため、どこまでをKeycloakで判断し、どこからをアプリで判断するかの線引きは最初に決めてください。この線引きを曖昧にすると、権限の仕様がどこにも書かれていない状態になります。 ## Keycloakの運用で詰まりやすい点と外部DB構成を採用する条件・見送る場面 - **hostnameの設定漏れ**：リバースプロキシ配下で`--hostname`を正しく指定しないと、リダイレクトURLが内部アドレスのまま生成され、ログインが完了しません。 - **バージョン間の設定変更**：26系は更新が速く、オプション名や既定値が変わることがあります。アップグレード前にリリースノートで対象バージョンの変更点を確認してください。 - **トークン有効期限の初期値をそのまま使う**：アクセストークンの寿命はレルムごとに設定できます。要件を確認せず既定のまま運用すると、セッション管理の想定と食い違います。 - **レルムの分け方**：テナントごとにレルムを分けるか、1レルム内でグループ分割するかは後から変更しにくい判断です。運用対象数と分離要件から先に決めてください。 ### 外部DBを含む自前運用を採用する条件とマネージドIDaaSへ寄せる場面 Keycloakを自前で運用するということは、認証基盤に加えてそのDBの可用性・バックアップ・バージョン追従まで抱えることを意味します。判断は次のとおりです。 **採用する条件**は、DBを本番で運用した経験があるチームがいて、ユーザー数に比例しない費用、閉域網での稼働、認証フローの深いカスタマイズのいずれかが要件に入っている場合です。DBをAmazon RDSやAzure SQLなどのマネージドサービスに任せれば、バックアップとフェイルオーバーを外へ出せます。 **見送る場面**は、DBを運用する担当がおらず、2週間前後の間隔で出る更新に追従する体制も組めない場合です。dev-fileのまま本番を迎える構成になるくらいなら、Auth0やCognitoのようなマネージドIDaaSを選ぶほうが安全です。製品比較は[Keycloakとは？Oktaとの違いと連携手順｜Auth0・Cognito比較で導入を判断](https://www.issoh.co.jp/tech/details/7663/)で整理しています。 Keycloakの構築とDB設計、既存システムへのSSO連携をまとめて任せたい場合は、一創の[認証基盤・ID管理システム開発](https://www.issoh.co.jp/service/system/identity/)でご相談いただけます。 ## よくある質問 KeycloakのDB設定と使い方について、検索の多い質問に答えます。 ### Keycloakの起動コマンドは何ですか？ LinuxとmacOSは`bin/kc.sh start-dev`、Windowsは`bin\kc.bat start-dev`です。開発用の起動方法で、本番では設定を確定させたうえで`start`を使います。古い記事にある`standalone.sh`はWildFlyベースだった時代のもので、現行のQuarkus版には存在しません。前提となるJavaは、26.8系ではOpenJDK 25です。 ### 管理者の初期パスワードは何ですか？ 初期パスワードはありません。公式ドキュメントが「Keycloak has no default admin user.」と明記しているとおり、既定の管理者ユーザーは存在しないため、起動後に`http://localhost:8080/`を開いて表示されるフォームで自分で作成します。作成後の管理コンソールは`http://localhost:8080/admin`です。コンテナでは環境変数で一時管理者を作ります。 ### Keycloakのデータベースは何を使えばよいですか？ 新規構築ならPostgreSQLが第一候補です。26.8系では14〜18系がサポート対象で、ドライバも同梱済みです。ほかにMySQL・MariaDB・SQL Server・Oracle・Aurora PostgreSQL・Azure SQLに対応しますが、Oracleだけはドライバを自分で追加します。既定のdev-fileは開発専用なので本番では使いません。設定やユーザー情報はすべてDBに入るため、どの製品でもバックアップ対象に含めてください。 ### KeycloakのDBをdev-fileからPostgreSQLへ切り替えられますか？ DBの設定を変えるだけでは中身は移りません。切り替え先のDBは空の状態から初期化されるためです。移すなら、Keycloakを止めて`bin/kc.sh export --dir`でレルムとユーザーを書き出し、PostgreSQLを指定した構成で`bin/kc.sh import --dir`を実行します。ただしエクスポートの対象はレルム設定とユーザーで、ログイン中のセッションなどは引き継がれません。利用者が再ログインする前提で、切り替えの時間帯を決めておきます。 ### ロールとグループはどう使い分けますか？ 権限そのものはロールで定義し、ユーザーへの割り当てはグループ経由で行うのが基本です。グループにロールを紐づけておけば、異動時にグループの所属を変更するだけで権限が切り替わります。部署と拠点の組み合わせのような条件はロールを増やすと管理しきれなくなるため、ユーザー属性をトークンのクレームに載せてアプリ側で判定する設計に切り替えます。 ## 関連記事 - [Keycloakとは？Oktaとの違いと連携手順｜Auth0・Cognito比較で導入を判断【2026年10月】](https://www.issoh.co.jp/tech/details/7663/)：Keycloakを選ぶか、マネージドIDaaSにするかの比較 - [Docker PostgreSQL構築の手順｜18で変わったボリューム位置とcompose定義・initdb初期化を実装目線で解説](https://www.issoh.co.jp/tech/details/16976/)：本記事のcompose定義で使うPostgreSQL側の詳細 - [PostgreSQLのバックアップ設計｜pg\_dumpとPITRの使い分け・復旧検証の手順](https://www.issoh.co.jp/tech/details/16996/)：Keycloak DBのバックアップ方式の選び方 - [OIDC（OpenID Connect）とは？IDトークンの検証手順とOAuth 2.0との違いを解説](https://www.issoh.co.jp/tech/details/6532/)：Keycloakが発行するトークンをアプリ側で検証する手順 --- 出典: [Keycloakのデータベース設定と使い方｜PostgreSQL接続・対応DB・バックアップから権限モデルまで]()（株式会社一創）