Keycloakの使い方｜起動から管理コンソール・DB設定と権限モデルまで

Keycloakは日本語の情報が古いまま残りやすいプロダクトです。とくに起動方法は、WildFlyベースだった時代のstandalone.shを案内する記事がいまも多く、そのとおりに実行してもファイルが見つかりません。現行はQuarkus版で、コマンドも初期セットアップの考え方も変わっています。この記事では2026年7月時点の公式手順にもとづいて、起動から管理コンソール、外部DBの設定、権限モデルの設計までを扱います。Keycloakを採用すべきかどうかの判断や他サービスとの比較はKeycloakとは？メリット・デメリットとAuth0・Okta・Cognito比較で導入を判断【2026年版】で解説しています。

まとめ：最初に押さえる4点

• 起動コマンドはbin/kc.sh start-dev（Windowsはbin\kc.bat start-dev）。standalone.shは旧ディストリビューションのもので現行版には存在しません。
• 前提はOpenJDK 25。公式のGetting Startedが明示しています。
• 既定の管理者ユーザーは存在しません。http://localhost:8080/を開いて表示されるフォームで自分で作成します。admin/adminでは入れません。
• start-devは本番で使えません。開発モードは設定が最適化されておらず、本番はビルドと明示的な設定を伴う起動が前提です。

最新の安定版は26.7.0（2026年7月9日リリース）です。26系はリリース間隔が短いため、記事やドキュメントを参照するときは対象バージョンを確認してください。

起動と初期セットアップ

ZIP配布版で試す場合の手順です。まずOpenJDK 25を用意します。配布物を展開したら、次のコマンドで開発モードで起動します。

# Linux / macOS
bin/kc.sh start-dev

# Windows
bin\kc.bat start-dev

ここでstandalone.shを探しても見つかりません。KeycloakはWildFlyベースからQuarkusベースへ移行しており、起動スクリプトの名前も設定の仕組みも別物になっています。古い記事の手順が動かない原因はほぼこれです。

管理者ユーザーは自分で作る

起動したらhttp://localhost:8080/にアクセスします。公式ドキュメントは「Keycloak has no default admin user.」と明記しており、初期管理者は存在しません。最初のアクセスで表示されるフォームにユーザー名とパスワードを入力して作成します。

作成後、管理コンソールはhttp://localhost:8080/adminです。ルートURLと管理コンソールのURLが分かれている点も、旧版から変わった部分です。

start-devを本番に持ち込まない

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

データベースの設定

開発モードでは組み込みデータベースが使われますが、これは検証専用です。組み込みDBのまま運用すると、コンテナやプロセスの再作成でレルム・ユーザー・クライアントの設定が失われます。本番では外部のPostgreSQLやMySQLなどを指定します。

設定はコマンドラインオプション、環境変数、設定ファイルのいずれでも与えられます。指定するのは、使用するデータベースの種類、接続URL、認証情報です。

bin/kc.sh start \
  --db=postgres \
  --db-url=jdbc:postgresql://db.example.com:5432/keycloak \
  --db-username=keycloak \
  --db-password=****** \
  --hostname=https://auth.example.com

運用で効いてくるのはバックアップの対象がこのデータベースだということです。Keycloakの設定はファイルではなくDBに入るため、DBを失うと認証基盤ごと失います。レルムのエクスポートも併用すると復旧の選択肢が増えます。

権限モデル｜ロール・グループ・属性の使い分け

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

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

属性を使った制御（ABAC的なアプローチ）

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

Keycloakでは、ユーザー属性をトークンのクレームにマッピングして払い出せます。アプリケーション側はそのクレームを見て判定します。「誰が」ではなく「どういう属性を持つか」で判断する設計に寄せると、ロールの数を抑えられます。ただし判定ロジックがアプリ側に分散するため、どこまでをKeycloakで判断し、どこからをアプリで判断するかの線引きは最初に決めてください。この線引きを曖昧にすると、権限の仕様がどこにも書かれていない状態になります。

運用で詰まりやすい点

• hostnameの設定漏れ：リバースプロキシ配下で--hostnameを正しく指定しないと、リダイレクトURLが内部アドレスのまま生成され、ログインが完了しません。
• バージョン間の設定変更：26系は更新が速く、オプション名や既定値が変わることがあります。アップグレード前にリリースノートで対象バージョンの変更点を確認してください。
• トークン有効期限の初期値をそのまま使う：アクセストークンの寿命はレルムごとに設定できます。要件を確認せず既定のまま運用すると、セッション管理の想定と食い違います。
• レルムの分け方：テナントごとにレルムを分けるか、1レルム内でグループ分割するかは後から変更しにくい判断です。運用対象数と分離要件から先に決めてください。

よくある質問

Keycloakの起動コマンドは何ですか？

LinuxとmacOSはbin/kc.sh start-dev、Windowsはbin\kc.bat start-devです。開発用の起動方法で、本番では設定を確定させたうえでstartを使います。古い記事にあるstandalone.shはWildFlyベースだった時代のもので、現行のQuarkus版には存在しません。

管理者の初期パスワードは何ですか？

初期パスワードはありません。公式ドキュメントが「Keycloak has no default admin user.」と明記しているとおり、既定の管理者ユーザーは存在しないため、起動後にhttp://localhost:8080/を開いて表示されるフォームで自分で作成します。作成後の管理コンソールはhttp://localhost:8080/adminです。

Keycloakに必要なJavaのバージョンは何ですか？

公式のGetting Startedでは、OpenJDK 25がインストールされていることを前提としています。JDKのバージョンはKeycloakのリリースごとに変わることがあるため、導入するバージョンのドキュメントで確認してください。

データベースは何を使えばよいですか？

開発時は組み込みデータベースで動きますが、これは検証専用です。設定やユーザー情報がすべてデータベースに保存されるため、本番ではPostgreSQLやMySQLなどの外部データベースを指定し、バックアップ対象に含めてください。組み込みのまま運用すると、プロセスやコンテナの再作成で設定を失います。

ロールとグループはどう使い分けますか？

権限そのものはロールで定義し、ユーザーへの割り当てはグループ経由で行うのが基本です。グループにロールを紐づけておけば、異動時にグループの所属を変更するだけで権限が切り替わります。部署と拠点の組み合わせのような条件はロールを増やすと管理しきれなくなるため、ユーザー属性をトークンのクレームに載せてアプリ側で判定する設計に切り替えます。

関連記事

• Keycloakとは？メリット・デメリットとAuth0・Okta・Cognito比較で導入を判断【2026年版】