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で26.8.1（10月13日公開）です。26系はリリース間隔が短く、9月だけでも26.7.4と26.7.5が出ています。記事やドキュメントを参照するときは対象バージョンを必ず確認してください。

Keycloakの起動と初期設定｜ZIP版start-devから管理者作成までの手順

ZIP配布版で試す場合の手順です。公式のGetting Started（OpenJDK版）は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で一時管理者を作ります。管理者のブートストラップと復旧のガイドによれば、この値が使われるのはmasterレルムがまだ無い初回起動時だけです。作られたアカウントは一時的な扱いで、恒久的な管理者を用意したら手で削除します。管理者を失ったときは、全ノードを止めてbin/kc.sh bootstrap-admin userで作り直せます。

start-devを本番へ持ち込まない理由とstartコマンドとの設定差

start-devは名前のとおり開発用です。HTTPSの強制やキャッシュ、データベース接続といった本番向けの設定が省略されており、そのまま本番に出すとセキュリティと性能の両面で問題になります。本番では設定を確定させたうえで通常のstartを使い、外部データベースとHTTPSを明示的に構成してください。本番化の確認項目はConfiguring Keycloak for productionにまとまっています。

Keycloakがデータベースに保存するデータと既定のdev-fileを本番で使えない理由

Keycloakの設定はファイルではなくデータベースに入ります。DBの扱いを決めることは、認証基盤そのものの保全方針を決めることと同じです。

レルム・ユーザー・クライアントからセッションまでDBに入る保存範囲

公式のデータベース設定ガイドは冒頭で、DBの役割を「ユーザー・クライアント・レルムのデータを保存する」と定義しています。さらに同ガイドはDBに入る機密情報として、ハッシュ化されたパスワード、クライアントの認証情報、トークン署名に使うレルムの鍵を挙げ、保存時の暗号化を推奨しています。

26系では永続化されたユーザーセッションやイベントもDBのテーブルに書かれます。26.8.0のリリースノートでは、ブルートフォース検知によるログイン失敗の記録も既定でDB保存に変わり、ロック中のユーザーはクラスタを再起動してもロックが続くようになりました。DBを失うと、設定だけでなくログイン状態とロック状態まで失います。

既定のdev-fileデータベースが検証専用とされる根拠と失われる設定

何も指定しないとKeycloakはdev-fileというファイル型の組み込みDBを使います。公式ガイドは「開発用途のためだけに存在し、本番デプロイ前に置き換える必要がある」と書いています。全設定オプションの一覧でも、本番モードでのdev-file既定値は非推奨扱いです。

組み込みDBのまま運用すると、コンテナやプロセスの再作成でレルム・ユーザー・クライアントの設定が失われます。ボリュームを付ければ残せますが、複数ノードで共有できず、バックアップとレプリケーションの道具も揃いません。

Keycloakが対応するデータベース一覧とバージョン別のサポート範囲（26.8系時点）

dbオプションに指定する値と、公式ガイドが掲げるテスト済み版・サポート版の対応です（2026年10月15日時点・26.8.1のドキュメント）。

このほか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初期化で詳しく扱っています。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・既定権限の決め方が参考になります。

Keycloak DBの接続プール・TLS・タイムアウトを本番運用に合わせる設定値

接続できた後に効いてくるのが、接続数の上限と通信の保護です。既定値のまま本番へ出すと、ノードを増やした時点で破綻する項目があります。

db-pool-max-size既定100をDBの接続上限から逆算して決める考え方

Keycloakの接続プールの上限db-pool-max-sizeは既定で100です（全設定オプション）。一方、PostgreSQLのmax_connectionsも既定は通常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は稼働中でも一貫したスナップショットを取れ、セッションや鍵を含めて丸ごと戻せます。PITRとの使い分けや復旧検証の進め方はPostgreSQLのバックアップ設計｜pg_dumpとPITRの使い分け・復旧検証の手順にまとめています。

エクスポートは従の手段です。インポートとエクスポートのガイドは、エクスポートの一貫性は全ノード停止時にしか保証されないと書いています。レルム単位のJSONなので、別環境への複製や設定差分の確認に向いた形式です。インポートの--overrideは既定でtrueなので、既存レルムを残したいときはfalseを明示します。

アップグレード前に確認するスキーマ移行とトランザクションのタイムアウト

Keycloakは起動時にDBのスキーマを自動で移行します。移行やインポートに使われるトランザクションの上限はtransaction-setup-timeoutで、既定は30分です。大きなテーブルを持つ環境では移行がこれを超えることがあるため、アップグレード前に1hなどへ延ばしておきます。

26.8.0では、大きなテーブルでも非ブロッキングでインデックスを作れるDBなら移行中に作成するよう変わりました。非対応のDBでは従来どおりSQLがログに出るので、手で実行します。アップグレードの前には必ずDBのバックアップを取り、検証環境で同じ版への移行を一度通してください。

権限モデル｜ロール・グループ・属性をKeycloakで使い分ける設計基準

Keycloakの権限設計で迷うのは、ロールとグループのどちらで表現するかです。役割は明確に分かれています。

権限はロールで定義し、割り当てはグループ経由にする運用とその根拠

実務上の指針はこうです。権限はロールで定義し、ユーザーへの割り当てはグループ経由で行います。グループにロールを紐づけておけば、人事異動のときにグループの所属を変えるだけで権限が切り替わります。ユーザーへロールを直接割り当てる運用では、対象が増えるほど棚卸しが追いつかなくなるのが実情です。

レルムの使い方も同じ考え方です。公式のGetting Startedは、最初からあるmasterレルムをKeycloak自身の管理だけに使い、アプリケーション用には別のレルムを作るよう指示しています。

ユーザー属性をトークンのクレームに載せるABAC的な判定と線引き

「部署が営業かつ拠点が東京のユーザーだけ許可する」といった条件は、ロールの数を増やして表現すると組み合わせ爆発を起こします。この場合はユーザー属性を使い、条件で判定する設計に切り替えます。

Keycloakでは、ユーザー属性をトークンのクレームにマッピングして払い出せます。アプリケーション側はIDトークンやアクセストークンを検証したうえで、そのクレームを見て判定します。トークン検証の手順はOIDC（OpenID Connect）とは？IDトークンの検証手順とOAuth 2.0との違いで解説しました。「誰が」ではなく「どういう属性を持つか」で判断する設計に寄せると、ロールの数を抑えられます。ただし判定ロジックがアプリ側に分散するため、どこまでを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比較で導入を判断で整理しています。

Keycloakの構築とDB設計、既存システムへのSSO連携をまとめて任せたい場合は、一創の認証基盤・ID管理システム開発でご相談いただけます。

よくある質問

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月】：Keycloakを選ぶか、マネージドIDaaSにするかの比較
• Docker PostgreSQL構築の手順｜18で変わったボリューム位置とcompose定義・initdb初期化を実装目線で解説：本記事のcompose定義で使うPostgreSQL側の詳細
• PostgreSQLのバックアップ設計｜pg_dumpとPITRの使い分け・復旧検証の手順：Keycloak DBのバックアップ方式の選び方
• OIDC（OpenID Connect）とは？IDトークンの検証手順とOAuth 2.0との違いを解説：Keycloakが発行するトークンをアプリ側で検証する手順