概要

1. 概要

KeycloakはWebアプリケーションおよびRESTfulなWebサービスのためのシングルサインオン・ソリューションです。Keycloakの目的はセキュリティをシンプルに実現し、アプリケーション開発者が組織内にデプロイしたアプリケーションやサービスを保護することです。開発者が通常自分達自身で書かないといけないセキュリティ機能はすぐに提供され、組織内の個々の要件に合わせて簡単に調整することができます。Keycloakは、ログイン、登録、システム管理、アカウント管理のための、カスタマイズ可能なユーザー・インターフェイスを提供しています。Keycloakは、既存のLDAPやActive Directoryサーバーへ接続し、統合プラットフォームとして利用することもできます。また、FacebookやGoogle+のようなサードパーティーのアイデンティティー・プロバイダーに対して、認証を委譲することも可能です。

1.1. 機能

ブラウザー・アプリケーションに対するシングルサインオンとシングルサインアウト。
OpenID Connectのサポート。
OAuth 2.0のサポート。
SAMLのサポート。
アイデンティティー・ブローカリング - 外部のOpenID ConnectもしくはSAMLに対応したアイデンティティー・プロバイダーによる認証。
ソーシャル・ログイン - Google、GitHub、Facebook、Twitterや他のソーシャル・ネットワークによるログイン。
ユーザー・フェデレーション - LDAPやActive Directoryからのユーザー同期。
ケルベロス連携 - ケルベロス・サーバーにログイン済のユーザーに対する認証連携。
ユーザー、ロール、ロール・マッピング、クライアントと設定を一元管理するための管理コンソール。
ユーザーに自分達のアカウントを一元管理することを許可するためのアカウント管理コンソール。
テーマ対応 - すべての利用者向け画面についてカスタマイズでき、アプリケーションとブランディングを統合可能。
二要素認証 - Google AuthenticatorやFreeOTPを使用したTOTP/HOTPのサポート。
ログイン・フロー - オプションの利用者自身によるセルフ・レジストレーション、パスワード・リカバリー、電子メールによる検証、強制パスワード変更機能など。
セッション管理 - 管理者や利用者が自分のセッションを参照・管理することが可能。
トークン・マッパー - ユーザー属性やロールなどをトークンやステートメントにどのように反映するかの指定。
レルム、アプリケーション、ユーザー単位のNot-beforeリボケーション・ポリシー。
CORSのサポート - CORSに対応済みのクライアント・アダプター。
サービス・プロバイダー・インターフェイス（SPI） - サーバーの様々な側面をカスタマイズするための数多くのSPI。認証フロー、ユーザー・フェデレーション・プロバイダー、プロトコル・マッパーなどその他多数。
JavaScript、WildFly、JBoss EAP、Fuse、Tomcat、Jetty、Springなどのクライアント・アダプター。
OpenID Connectのリソース・プロバイダー・ライブラリ、もしくは、SAML 2.0のサービス・プロバイダー・ライブラリをもつ、あらゆるプラットフォーム/言語のサポート。

1.2. セキュリティはどう機能しますか？

Keycloakはあなたのネットワークに配置される、あなたが管理する分離されたサーバーです。アプリケーションはこのサーバーを指すように設定され、このサーバーによって保護されます。Keycloakはアプリケーションを保護するために、Open ID ConnectやSAML 2.0といった標準プロトコルを採用しています。ユーザーは完全にアプリケーションから分離され、アプリケーションはユーザーのクレデンシャルを見ることも決してないため、この点は重要です。代わりに、アプリケーションには、暗号化署名されたアイデンティティー・トークンまたはアサーションが与えられます。これらのトークンはユーザー名、住所、電子メール、および、その他プロファイルデータといったアイデンティティー情報を持つことができます。また、権限データを保持することも可能でアプリケーションは認可決定を行うことも可能です。これらのトークンはRESTベースのサービスに対して安全な呼び出しを行うためにも使用できます。

1.3. コアコンセプトと用語

Keycloakを使用して、WebアプリケーションやRESTサービスをセキュリティ保護しようとする前に、知っておくべきキーコンセプトと用語があります。

ユーザー: システムにログイン可能なエンティティーのことです。電子メール、ユーザー名、住所、電話番号、生年月日など自分自身に関連する属性を持ちます。また、グループ・メンバーシップが割り当てられたり、特定のロールが割り当てられたりします。
認証: ユーザーを特定し、検証するプロセスのことです。
authorization: ユーザーに対してアクセスを許可するプロセスのことです。
credentials: クレデンシャルは、Keycloakがユーザーの身元を確認するために使用するデータの一部のことです。例として、パスワード、ワンタイムパスワード、デジタル証明書、さらには指紋などがあります。
ロール: ロールは、ユーザーのタイプまたはカテゴリを識別します。 Admin、` user`、 manager、` employee` はすべて、組織内に存在する典型的なロールです。アプリケーションは、ユーザーの扱いをきめ細く管理することが難しくなる場合があるため、個々のユーザーではなく、特定のロールにパーミッションを割り当てることが多いです。
ユーザー・ロール・マッピング: ユーザー・ロール・マッピングは、ロールとユーザーの間のマッピングを定義します。ユーザーには、0以上のロールを関連付けることができます。このロールマッピング情報を、トークンとアサーションにカプセル化して、アプリケーションが管理するさまざまなリソースに対するアクセス許可を決定できるようにします。
複合ロール: 複合ロールは、他のロールと関連付けることができるロールです。例えば、 superuser 複合ロールは sales-admin ロールと order-entry-admin ロールに関連付けることができます。ユーザーが superuser ロールにマッピングされると、 sales-admin ロールと order-entry-admin ロールも継承します。
グループ: グループは、ユーザーのグループを管理します。グループには、属性を定義することができます。ロールもグループにマップすることができます。グループのメンバーになったユーザーは、そのグループが定義する属性とロールのマッピングを継承します。
レルム: レルムは、ユーザー、クレデンシャル、ロール、および、グループのセットを管理します。ユーザーは属しているレルムにログインします。レルムは互いに分離されており、制御するユーザーのみを管理して、認証することができます。
クライアント: クライアントは、Keycloakにユーザーの認証を要求できるエンティティーです。多くの場合、クライアントはKeycloakを使用して自分自身を保護し、シングル・サインオン・ソリューションを提供するアプリケーションとサービスのことを指します。また、クライアントはKeycloakによって保護されているネットワーク上の他のサービスを安全に呼び出すことができるように、アイデンティティー情報やアクセストークンを要求するエンティティーになります。
クライアント・アダプター: クライアント・アダプターは、アプリケーション環境にインストールすることで、Keycloakによりセキュリティーを確保されて通信できるようになるプラグインです。Keycloakには、異なるプラットフォーム向けにいくつかのアダプターが用意されており、ダウンロードが可能です。また、標準ではカバーしていない環境向けのサードパーティーのアダプターもあります。
同意: 同意は、クライアントが認証プロセスに参加する前に、クライアントに許可を与えることを管理者がユーザーに求めることです。ユーザーがクレデンシャルを入力すると、Keycloakがログインを要求しているクライアントを識別する画面とユーザーに要求された識別情報を表示します。ユーザーは、要求を許可するかどうかを決定できます。
クライアント・テンプレート: クライアントが登録されると、そのクライアントに関する設定情報を入力する必要があります。新しいクライアントの作成を容易にするためにテンプレートを保存すると便利なことがよくあります。Keycloakは、このためにクライアント・テンプレートを提供します。
クライアントロール: クライアントは、特定のロールを定義できます。これは、基本的にクライアント専用のロール・ネームスペースです。
アイデンティティー・トークン: ユーザーに関する識別情報を提供するトークンです。これは、OpenID Connect仕様の一部です。
アクセストークン: サービスへのアクセスを許可するHTTPリクエストの一部として提供できるトークンです。これは、OpenID ConnectおよびOAuth 2.0仕様の一部です。
アサーション: ユーザーに関する情報です。これは、通常、認証されたユーザーに関するアイデンティティー・メタデータを提供するSAML認証レスポンスに含まれるXML BLOBに関係します。
サービス・アカウント: 各クライアントには、アクセストークンを取得するための組み込みサービス・アカウントがあります。
ダイレクト・グラント: クライアントがREST呼び出しを介して、ユーザーに代わってアクセストークンを取得する方法です。
プロトコル・マッパー: 各クライアントに対して、どのクレームおよびアサーションをOIDCトークンまたはSAMLアサーションに格納するかを調整できます。クライアントごとに、プロトコル・マッパーを構成します。
セッション: ユーザーがログインすると、ログイン・セッションを管理するためのセッションが作成されます。セッションには、ユーザーがログインした時刻や、そのセッション中にシングル・サインオンに参加したアプリケーションなどの情報が含まれています。管理者とユーザーの両方がセッション情報を表示できます。
ユーザー・フェデレーション・プロバイダー: Keycloakはユーザーを保存および管理できます。多くの企業では、ユーザー情報とクレデンシャル情報を保存するLDAPまたはActive Directoryサービスが既に用意されています。外部ストアからのクレデンシャル情報を検証し、アイデンティティー情報を取得するように、Keycloakを設定できます。
アイデンティティー・プロバイダー: アイデンティティー・プロバイダー（IDP）は、ユーザを認証できるサービスです。KeycloakはIDPです。
アイデンティティー・プロバイダー・フェデレーション: Keycloakは、1つ以上のIDPに認証を委任するように設定できます。FacebookやGoogle+を介したソーシャル・ログインは、アイデンティティー・プロバイダー・フェデレーションの一例です。Keycloakをフックして、他のOpen ID ConnectまたはSAML 2.0 IDPに認証を委任することもできます。
アイデンティティー・プロバイダー・マッパー: IDPフェデレーションを実行するときに、受信したトークンやアサーションにユーザー属性やセッション属性をマップできます。これは外部IDPから認証を要求するクライアントへアイデンティティー情報を伝播させるのに役立ちます。
必須アクション: 必須アクションは、ユーザーが認証プロセス中に実行する必要があるアクションです。これらのアクションが完了するまで、ユーザーは認証プロセスを完了できません。例えば、管理者は、すべてのユーザーに対して、 update password の必須アクションを設定し、毎月パスワードをリセットするようにユーザーへ要求することができます。
認証フロー: 認証フローは、システムの特定の側面と対話するときにユーザーが実行する必要があるワークフローです。ログインフローでは、必要なクレデンシャル・タイプを定義します。登録フローでは、ユーザーが入力する必要のあるプロファイル情報と、reCAPTCHAを使用してボットをフィルタリングする必要があるかどうかを定義します。クレデンシャル・リセットフローは、ユーザーがパスワードをリセットする前に実行する必要があるアクションを定義します。
イベント: イベントは、管理者が表示したり、フックしたりすることができる監査ストリームです。
テーマ: Keycloakによって提供されるすべての画面にはテーマが付いています。テーマは必要に応じて上書きできるHTMLテンプレートとスタイルシートを定義します。

2. サーバーの初期化

Server Installation and Configuration Guideに定義されているすべてのインストールおよび設定タスクを実行したら、初期管理者アカウントを作成する必要があります。Keycloakには、設定済みの管理者アカウントはありません。このアカウントを使用すると、 master レルムの管理コンソールにログインできる管理者を作成できるため、レルム、ユーザー、およびKeycloakによって保護されるアプリケーションの登録を開始できます。

サーバーが localhost からアクセス可能な場合は、サーバーを起動して http://localhost:8080/auth のURLにアクセスすることで、この管理者ユーザーの作成ができます。

ウェルカムページ

initial welcome page

初期管理者に対するユーザー名とパスワードを指定するだけです。

localhost アドレスでサーバーにアクセスできない場合や、コマンドラインからKeycloakをプロビジョニングしたい場合は、 …/bin/add-user-keycloak スクリプトを使ってそれらを実行できます。

add-user-keycloakスクリプト

add user script

スタンドアローン動作モードまたはドメイン動作モードを使用している場合、パラメーターは少し異なります。スタンドアローン・モードの場合のスクリプトの使用方法を次に示します。

Linux/Unix

$ .../bin/add-user-keycloak.sh -r master -u <username> -p <password>

Windows

> ...\bin\add-user-keycloak.bat -r master -u <username> -p <password>

ドメインモードでは、 -sc スイッチを使ってスクリプトをサーバーホストの1つに向ける必要があります。

Linux/Unix

$ .../bin/add-user-keycloak.sh --sc domain/servers/server-one/configuration -r master -u <username> -p <password>

Windows

> ...\bin\add-user-keycloak.bat --sc domain/servers/server-one/configuration -r master -u <username> -p <password>

3. 管理コンソール

管理作業の大部分はKeycloak管理コンソールにて行います。http://localhost:8080/auth/admin/ のURLにて直接アクセスすることができます。

ログインページ

ウェルカムページまたはbinディレクトリ内の add-user-keycloak スクリプトにて作成したユーザー名とパスワードを入力します。Keycloak管理コンソールページが開きます。

管理コンソール

admin console

左のドロップダウン・メニューで管理または新しく作成したいレルムを選択できます。右のドロップダウン・メニューでは自身のユーザー・アカウントの参照やログアウトができます。管理コンソール内の特定の機能、ボタンまたはフィールドについて興味がある場合は、クエスチョンマーク ? アイコンにマウスオーバーします。そうすると、興味のある当該コンソール関連を説明するツールチップ・テキストがポップアップ表示されます。このとおりに実行すると、ツールチップは上記のようになります。

3.1. masterレルム

初めてKeycloakを起動すると、Keycloakはあらかじめ定義されたレルムを作成します。この初期レルムは master レルムです。これは、レルムの階層内で最も高いレベルです。このレルムの管理者アカウントには、サーバー・インスタンスで作成された他のレルムを表示および管理する権限があります。最初の管理者アカウントを定義するときは、 master レルムにアカウントを作成します。管理コンソールへの最初のログインも、 master レルム経由で行われます。

組織内のユーザーとアプリケーションを管理するために、master レルムを使用しないことをお勧めします。システム内のレルムの作成および管理を行うように、 super 管理者に対して、 master レルムの使用を予約します。このセキュリティー・モデルに従うことで、偶発的な変更を防ぎ、現在の作業を正常に完了するために必要な特権と権限のみにアクセスできるという伝統に従うことができます。

master レルムを無効にし、新たに作成する個々のレルム内で管理者アカウントを定義することは可能です。各レルムには専用の管理コンソールがあり、ローカルのアカウントでログインできます。このガイドでは、レルム専用管理コンソールの章でこれについて詳しく説明しています。

3.2. 新規レルムの作成

新しいレルムを作成することは非常に簡単です。左上隅の Master というタイトルのドロップダウン・メニューにマウスを置いてください。masterレルムにログインしている場合、このドロップダウン・メニューには作成されたすべてのレルムがリストされます。このドロップダウン・メニューの最後のエントリーは、常に Add Realm です。レルムを追加するには、これをクリックします。

レルムの追加メニュー

このメニュー・オプションをクリックすると、 Add Realm ページに移動します。定義するレルム名を指定し、 Create ボタンをクリックします。あるいは、新しいレルムを定義するJSONドキュメントをインポートすることもできます。これについては、エクスポートとインポートの章で詳しく説明します。

レルムの作成

create realm

レルムを作成したら、管理コンソールのメインページに戻ります。現在のレルムが、今作成したレルムに設定されます。左上隅のドロップダウン・メニューにマウスを置くことで、異なるレルムの管理を切り替えることができます。

3.3. SSLモード

各レルムには、SSLモードが関連付けられています。SSLモードは、レルムと対話するためのSSL/HTTPS要件を定義します。レルムと対話するブラウザーとアプリケーションは、SSLモードで定義されたSSL/HTTPS要件を満たしている必要があり、そうでなければサーバーと対話できません。

Keycloak is not set up by default to handle SSL/HTTPS. It is highly recommended that you either enable SSL on the Keycloak server itself or on a reverse proxy in front of the Keycloak server.

レルムのSSLモードを設定するには、左のメニュー項目の Realm Settings をクリックし、 Login タブに移動する必要があります。

Loginタブ

Require SSL オプションにより、SSLモードが選択できます。各モードの説明は次のとおりです。

external requests: localhost 、 127.0.0.1 、 10.0.x.x 、 192.168.x.x 、 172.16.x.x のようなプライベートIPアドレスに固定する限り、ユーザーはKeycloakと対話できます。非プライベートIPアドレスからKeycloakにアクセスしようとすると、エラーが発生します。
none: KeycloakはSSLを必要としません。この設定は、サーバー上でSSLの設定を気にせずにいろいろと触ってみる開発段階にのみ使用すべきです。
all requests: KeycloakはすべてのIPアドレスに対してSSLを要求します。

3.4. サーバー・キャッシュのクリア

Keycloakは、JVMおよび/または設定した制限の範囲内で、できる限りすべてをキャッシュします。サーバーのREST APIまたは管理コンソールの範囲外のDBAのような第三者によってKeycloakデータベースが変更された場合、インメモリ・キャッシュの一部が失効する可能性があります。管理コンソール左側メニュー項目 Realm Settings の Cache タブから、レルムキャッシュ、ユーザー・キャッシュ、または外部公開鍵（外部クライアントやアイデンティティー・プロバイダーの公開鍵など、Keycloakが外部エンティティーの検証署名に使用する公開鍵）のキャッシュをクリアすることができます。

Cacheタブ

cache tab

クリアしたいキャッシュの clear ボタンをクリックします。

3.5. 電子メールの設定

Keycloakは、パスワードを忘れたとき、または管理者がサーバーイベントに関する通知を受け取るときに、メールアドレスの確認するためユーザーに電子メールを送信します。Keycloakが電子メールを送信できるようにするには、KeycloakにSMTPサーバーの設定を行う必要があります。SMTPサーバーの設定は、レルムごとに設定することができます。 Realm Settings 左のメニュー項目に移動し、 Email タブをクリックしてください。

Emailタブ

email tab

Host: Host は、電子メールの送信に使用されるSMTPサーバーのホスト名です。
Port: Port は、SMTPサーバーのポート番号です。
From: From は、送信された電子メールの From SMTPヘッダーに使用されるアドレスです。
From Display Name: From Display Name は、ユーザー・フレンドリーなメールアドレスのエイリアスを設定します（オプション）。設定されていない場合は、電子メールクライアントに From メールアドレスが表示されます。
Reply To: Reply To は、送信された電子メールの Reply-To SMTPヘッダーに使用されるアドレスです（オプション）。設定されていない場合は、通常の From メールアドレスが使用されます。
Reply To Display Name: Reply To Display Name は、ユーザー・フレンドリーなメールアドレスのエイリアスを設定します（オプション）。設定されていない場合は、 Reply To 電子メールアドレスが表示されます。
Envelope From: Envelope From は、送信された電子メールの Return-Path SMTPヘッダーに使用されるバウンスアドレスです（オプション）。

電子メールは、ユーザー名とパスワードの回復に使用されるため、特にSMTPサーバーが外部ネットワーク上にある場合は、SSLまたはTLSを使用することを推奨します。SSLを有効にするため Enable SSL をクリックするか、TLSを有効にするため Enable TLS をクリックします。 Port も変更する必要があります（SSL/TLSのデフォルトポートは465）。

SMTPサーバーが認証を必要とする場合は、 Enable Authentication をクリックし、 Username と Password を入力します。

3.6. テーマと国際化

テーマによって、KeycloakのUIのデザインを変更することが可能です。テーマはレルムごとに設定されます。テーマを変更するには、左のメニュー項目の Realm Settings に移動し、 Themes タブをクリックします。

Themesタブ

themes tab

各UIカテゴリに必要なテーマを選び、 Save ボタンをクリックします。

Login Theme: ユーザー名・パスワード入力、OTP入力、新規ユーザー登録、その他ログインに関連する画面。
Account Theme: 各ユーザーのアカウント管理UI。
Admin Console Theme: Keycloak管理コンソールのスキン。
Email Theme: Keycloakが電子メールを送信する場合に、このテーマで定義されたテンプレートを使用して電子メールを作成します。

Server Developer Guideでは、新しいテーマを作成したり、既存のテーマを変更する方法について説明します。

3.6.1. 国際化

すべてのUI画面はKeycloakで国際化されています。デフォルトの言語は英語ですが、 Theme タブの Internationalization スイッチをオンにすると、サポートしたいロケールとデフォルト・ロケールを選択できます。次回ユーザーがログインすると、ログイン画面、ユーザー・アカウント管理UI、および管理コンソールで使用する言語をログインページで選択できます。Server Developer Guideでは、言語を追加する方法について説明しています。

4. ユーザーの管理

このセクションでは、ユーザーを管理するための管理機能について説明します。

4.1. ユーザーの検索

特定のユーザーを管理する必要がある場合は、左側のメニューバーの Users をクリックします。

Users

users

このメニュー・オプションは、ユーザーリストのページに移動します。検索ボックスには、ユーザー・データベースで検索するフルネーム、姓またはメールアドレスを入力できます。クエリーは、条件に一致するすべてのユーザーを表示します。 View all users ボタンは、システム内のすべてのユーザーを一覧表示します。これは、LDAPのようなバックエンドにユーザーをページングする方法がないため、ローカルのKeycloakデータベースだけを検索し、フェデレーション・データベース（つまりLDAP）は検索しません。したがって、フェデレーション・バックエンドのユーザーをKeycloakデータベースに同期させるには、次のいずれかを行う必要があります。

検索条件を調整します。これにより、条件に一致するバックエンド・ユーザーのみがKeycloakデータベースに同期されます。
User Federation タブに移動して、フェデレーション・プロバイダーとページ内の Sync all users または Sync changed users をクリックします。

詳細については、ユーザー・フェデレーションを参照してください。

4.2. 新規ユーザーの作成

ユーザーを作成するには、左側のメニューバーにある Users をクリックします。

Users

users

このメニューオプションは、ユーザーリストのページに移動します。空のユーザーリストの右側に、 Add User ボタンが表示されます。クリックすると、新しいユーザーの作成が開始されます。

Add User

add user

必須フィールドは Username だけです。保存をクリックすると、新しいユーザーの管理ページが表示されます。

4.3. ユーザー属性

名前や電子メールなどの基本的なユーザー・メタデータ以外にも、任意のユーザー属性を保存できます。管理するユーザーを選択してから、 Attributes タブをクリックします。

Users

user attributes

空のフィールドに属性名と値を入力し、その隣にある Add ボタンをクリックして新しいフィールドを追加します。このページで行った編集は、 Save ボタンを押すまで保存されないことに注意してください。

4.4. ユーザー・クレデンシャル

ユーザーを参照しているときに、 Credentials タブをクリックすると、ユーザーのクレデンシャルを管理することができます。

クレデンシャルの管理

user credentials

4.4.1. パスワード変更

ユーザーのパスワードを変更するには、新しいパスワードを入力します。すべてを入力した後にクリックする Reset Password ボタンが表示されます。 Temporary スイッチがオンの場合、新しいパスワードは一度しか使用できません。ユーザーはログイン後にパスワードを変更するよう求められます。

また、電子メールが設定されている場合は、パスワードのリセットを求めるメールをユーザーに送信できます。 Reset Action リストボックスから Update Password を選択し、 Send Email をクリックしてください。必要に応じて、レルム設定の Tokens タブから、電子メールのリンクの有効時間を変更することができます。送信された電子メールには、パスワードの更新画面へのリンクが含まれています。

4.4.2. OTPの変更

管理コンソール内の特定のユーザーに対してワンタイム・パスワードの設定することはできません。これはユーザーの責任で行われます。ユーザーがOTPジェネレーターを無くした場合は、 Credentials タブからOTPを無効にします。レルム設定において、OTPがオプションの場合、ユーザーは新しいOTPジェネレーターを、ユーザー・アカウント管理サービスから再設定することができます。OTPが必須の場合は、ログイン時に新しいOTPジェネレータを再設定するように求められます。

パスワードのように、ユーザーにOTPジェネレータをリセットするように依頼するメールを送信することもできます。 Reset Actions リストボックスで Configure OTP を選択し、 Send Email ボタンをクリックしてください。送信されたメールには、OTP設定画面へのリンクが含まれています。

4.5. 必須アクション

必須アクションは、ユーザーがログインを許可される前に完了しなければならないタスクです。ユーザーは、必須アクションが実行される前にクレデンシャルを提供する必要があります。必須アクションが完了すると、ユーザーはアクションを再実行する必要はありません。組み込みの必須アクション種別の説明を次に示します。

Update Password: 設定すると、ユーザーはパスワードを変更する必要があります。
Configure OTP: 設定すると、ユーザーはFree OTPまたはGoogleオーセンティケーター・アプリケーションを使用して、モバイルデバイスにワンタイム・パスワード・ジェネレーターを設定する必要があります。
Verify Email: 設定すると、ユーザーは有効な電子メール・アカウントの検証が必要となります。クリックしなければならないリンクがある電子メールがユーザーに送信されます。この検証作業が正常に完了すると、ログインが許可されます。
Update Profile: この必須アクションは、ユーザーの名前、住所、電子メール、電話番号といったプロファイル情報をユーザーに更新するように要求します。

管理者は、管理コンソールのユーザーの Details タブ内で、ユーザーごとに必須アクションを追加できます。

必須アクションの設定

user required action

Required User Actions リストボックスで、アカウントに追加するすべてのアクションを選択します。削除する場合は、アクション名の横にある X をクリックします。追加するアクションを選択し終えたら、 Save ボタンをクリックしてください。

4.5.1. デフォルト必須アクション

ユーザー一覧の Add User ボタンや、ログイン画面のユーザー登録リンクを介してユーザーが作成される時に、アカウントに追加される必須アクションを指定することもできます。デフォルトの必須アクションを指定するには、左側のメニューの Authentication から、 Required Actions タブをクリックします。

デフォルト必須アクション

default required actions

新しいユーザーがログインするときに実行する必須アクションの Default Action 列のチェックボックスをクリックするだけです。

4.5.2. 利用規約

多くの組織では、新規ユーザーが初めてログインするときに、Webサイトの利用規約に同意する必要があるという要件があります。Keycloakはこの機能を必須アクションとして実装していますが、利用するためには設定が必要です。1つは、前述の Required Actions タブに移動し、 Terms and Conditions アクションを有効にする必要があります。また、 base ログインテーマの terms.ftl ファイルも編集する必要があります。テーマの拡張と作成の詳細については、Server Developer Guideを参照してください。

4.6. Impersonation

管理者がユーザーの代理ログインを行うと便利なことがあります。たとえば、ユーザーがいずれかのアプリケーションでバグを経験している可能性があり、管理者がユーザーの代理ログインを行い問題の再現ができるか確認したい場合などです。適切な権限を持つ管理者がユーザーの代理ログインを行うことができます。管理者が代理ログインできる画面は2つあります。ひとつは Users リストタブにあります。

Users

ここでは管理者が jim を検索したことがわかります。Jimのアカウントの横に代理ログインのボタンが表示されます。ボタンをクリックすると、そのユーザーで代理ログインできます。

もうひとつは、ユーザーの Details タブからユーザーの代理ログインができます。

ユーザー詳細

user details

ページの下部には、 Impersonate ボタンがあります。これをクリックすると、そのユーザーで代理ログインできます。

代理ログインすると、管理者とユーザーが同じレルムである場合、管理者はログアウトされ、代理ログインされるユーザーとして自動的にログインします。管理者とユーザーが同じレルムでない場合、管理者はログインしたままになりますが、そのユーザーのレルムにユーザーとしてログインします。いずれの場合も、ブラウザーは代理ログインされたユーザーのユーザーアカウント管理ページにリダイレクトされます。

レルムの impersonation のロールを持つすべてのユーザーが、ユーザーの代理ログインを行うことができます。管理権限の割り当ての詳細については、管理コンソールのアクセス・コントロールの章を参照してください。

4.7. ユーザー登録

Keycloakでは、ユーザーの自己登録を許可することができます。有効にすると、ログインページには、ユーザーが新しいアカウントを作成するためにクリックできる登録リンクが表示されます。

ユーザーの自己登録が有効になっている場合、登録フォームを使用して有効なユーザー名と電子メールを検出することができます。これを回避するには、reCAPTCHAのサポートを有効にします。

登録を有効にするのは簡単です。左メニューの Realm Settings をクリックし、移動します。次に、 Login タブに移動します。このタブには User Registration スイッチがあります。それをオンにしてから、 Save ボタンをクリックします。

Loginタブ

この設定を有効にすると、ログインページに Register リンクが表示されます。

登録リンク

registration link

このリンクをクリックすると、登録ページが表示されるので、ユーザー・プロファイル情報と新しいパスワードを入力します。

登録フォーム

registration form

登録フォームのデザインを変更するだけでなく、入力項目を追加または削除することができます。詳細については、Server Developer Guideを参照ください。

4.7.1. reCAPTCHAのサポート

ボットに対する登録から保護するため、KeycloakはGoogle reCAPTCHAと連携しています。これを有効にするには、まずGoogle Recaptcha Websiteから、reCAPTCHAサイトの鍵とパスワードを取得できるようにAPIキーを作成する必要があります。参考までに、localhostはデフォルトで動作しますので、ドメインを指定する必要はありません。

次に、Keycloak管理コンソールで実行する必要のある手順がいくつかあります。左の Authentication メニューをクリックし、 Flows タブのドロップダウンリストから Registration フローを選択します。

登録フロー

registration flow

ラジオボタンをクリックして、'reCAPTCHA’の必要条件を Required に設定します。これにより、画面上でreCAPTCHAが有効になります。次に、Google reCAPTCHAウェブサイトで生成した鍵とパスワードを入力する必要があります。reCAPTCHAフローの右側にある’Actions’ボタンをクリックし、次に"Config"リンクをクリックし、この設定ページでreCAPTCHAサイトの鍵とパスワードを入力します。

Recaptcha設定画面

recaptcha config

最後に、Keycloakが設定するデフォルトのHTTPレスポンス・ヘッダーを変更する必要があります。Keycloakは、ウェブサイトのiframe内にログインページを含めることを防ぎます。これはクリックジャック攻撃を防ぐためです。iframe内で登録ページを使用するためGoogleを認可する必要があります。左メニューの Realm Settings から Security Defenses タブを選んでください。 X-Frame-Options と Content-Security-Policy ヘッダーの両方の値に https://www.google.com を追加する必要があります。

iframeの許可

security headers

ここまで設定を行うと、登録ページにreCAPTCHAが表示されます。ログインテーマの register.ftl を編集して、reCAPTCHAボタンの配置とスタイリングを行うこともできます。テーマの拡張と作成の詳細については、Server Developer Guideを参照してください。

5. ログインページの設定

必要な場合に有効にできる便利な組み込みのログインページ機能がいくつかあります。

5.1. パスワード忘れ

これを有効にすると、ユーザーはパスワードを忘れたり、OTPジェネレーターを無くした場合でも、クレデンシャルをリセットできます。左のメニュー項目の Realm Settings に移動し、 ` Login` タブをクリックします。 Forgot Password スイッチをオンにします。

Loginタブ

ログインページに forgot password リンクが表示されるようになります。

パスワード忘れリンク

forgot password link

このリンクをクリックすると、ユーザー名またはメールアドレスを入力できるページに移動し、クレデンシャルをリセットするためのリンクが記載されたメールが送信されます。

パスワード忘れページ

forgot password page

電子メールで送信されるテキストは完全に設定可能です。それに関連するテーマを拡張または編集するだけです。詳細については、Server Developer Guideのリンクをご覧ください。

ユーザーが電子メールのリンクをクリックすると、パスワードの更新が求められ、OTPジェネレーターが設定されている場合は、パスワードの再設定も求められます。組織のセキュリティ要件によっては、電子メールを使ってユーザーがOTPジェネレーターをリセットできないようにすることができます。この動作を変更するには、左メニュー項目の Authentication で Flows タブをクリックし、 Reset Credentials フローを選択します。

Reset Credentialsフロー

reset credentials flow

OTPをリセットしたくない場合は、 Reset OTP の右にある disabled ラジオボタンを選択してください。

5.2. Remember Me

ログインしているユーザーがブラウザーを閉じると、そのセッションは破棄され、再度ログインする必要があります。ユーザーが remember me チェックボックスをチェックすると、ブラウザーを閉じてもログインした状態になるように設定できます。これは基本的に、ログインCookieをセッション専用Cookieから永続Cookieに変えます。

この機能を有効にするには、左側のメニュー項目の Realm Settings に移動して、 Login タブをクリックし、 Remember Me スイッチをオンにしてください。

Loginタブ

この設定を保存すると、レルムのログインページに remember me チェックボックスが表示されます。

Remember Me

remember me

6. 認証

レルムの認証を設定する際に注意すべき機能がいくつかあります。多くの組織には、厳密なパスワードとOTPポリシーがありますが、管理コンソールの設定で実施することができます。認証には異なるクレデンシャル・タイプを必要とする場合とそうでない場合があります。ユーザーにKerberos経由でログインするオプションを与えたり、さまざまな組み込みのクレデンシャル・タイプを無効または有効にしたりすることができます。この章では、これらすべてのトピックについてご説明します。

6.1. パスワード・ポリシー

作成された新しいレルムには、パスワード・ポリシーは関連付けられていません。ユーザーは、短くても長くても、複雑でも、安全でなくても、自分の望むパスワードにすることができます。単純な設定は、Keycloakの開発や学習には問題ありませんが、プロダクション環境では受け入れられません。Keycloakには、管理コンソールから有効にできる豊富なパスワード・ポリシーがあります。

左メニュー項目の Authentication をクリックし、 Password Policy タブに移動します。追加するポリシーを右側のドロップダウン・リストボックスで選択します。これにより、画面上の表にポリシーが追加されます。ポリシーのパラメーターを選択します。 Save ボタンをクリックして変更を保存します。

パスワード・ポリシー

password policy

ポリシーを保存すると、ユーザー登録とUpdate Passwordの必須アクションが新しいポリシーを施行します。例として、ポリシーのチェックに失敗したユーザーは以下のようになります。

パスワード・ポリシーの失敗

failed password policy

パスワード・ポリシーが更新されている場合は、すべてのユーザーに対してUpdate Passwordアクションが設定されている必要があります。自動トリガーは将来の拡張として予定されています。

6.1.1. パスワード・ポリシーのタイプ

各ポリシータイプの説明は次のとおりです。

HashAlgorithm: パスワードはクリアーテキストとして保存されません。その代わりに、標準のハッシュ・アルゴリズムを使用してハッシュされ、保存または検証されます。利用可能なビルトイン・アルゴリズムかつデフォルト・アルゴリズムは、PBKDF2のみです。独自のアルゴリズムをプラグインする方法については、Server Developer Guideを参照してください。アルゴリズムを変更すると、次回ユーザーがログインするまでパスワード・ハッシュが変更されません。
Hashing Iterations: この値は、パスワードが保存または検証される前にハッシュされる回数を指定します。デフォルト値は20,000です。このハッシングは、ハッカーがパスワード・データベースにアクセスするまれなケースで行われます。データベースにアクセスすると、ユーザーのパスワードをリバース・エンジニアリングすることができます。このパラメーターの業界推奨値は、CPUパワーが向上するにつれて毎年変化します。ハッシュ反復の値が高いほど、ハッシュに必要なCPUパワーが増え、パフォーマンスに影響を与える可能性があります。パフォーマンスとパスワードストアの保護のどちらを重要視するかは、要件により異なります。もしくは、パスワードストアの保護よりも、費用対効果の高い方法があるかもしれません。
Digits: パスワード文字列に必要な桁数。
Lowercase Characters: パスワード文字列に必要な小文字の数。
Uppercase Characters: パスワード文字列に必要な大文字の数。
Special Characters: パスワード文字列に含める必要がある、'?!#%$'のような特殊文字の数。
Not Username: 設定すると、パスワードをユーザー名と同じにすることはできません。
Regular Expression: パスワードが一致する必要のある１つ以上のPerl正規表現パターンを定義します。
Expire Password: パスワードが有効な日数。有効期限が切れた後、ユーザーはパスワードを変更する必要があります。
Not Recently Used: このポリシーは、以前のパスワードの履歴を保存します。保存されている古いパスワードの数は設定可能です。ユーザーがパスワードを変更する際に、保存されたパスワードを使用することはできません。

6.2. OTPポリシー

Keycloakには、FreeOTPまたは、Googleオーセンティケーターのワンタイム・パスワード・ジェネレーター用に設定できる、いくつかのポリシーがあります。左メニュー項目の Authentication をクリックし、OTP Policy タブを表示します。

OTP Policy

otp policy

ここで設定したポリシーは、ワンタイム・パスワードの検証に使用されます。OTPを設定するとき、FreeOTPとGoogleオーセンティケーターはKeycloakが持つOTP設定ページで生成されたQRコードをスキャンすることができます。このバーコードは OTP Policy タブで設定された情報から生成されます。

6.2.1. TOTP vs. HOTP

OTPジェネレーターには、時間ベース（TOTP）およびカウンターベース（HOTP）の2つのアルゴリズムがあります。TOTPの場合、トークン・ジェネレーターは現在の時刻と共有パスワードをハッシュします。サーバーは、特定の時間枠内のすべてのハッシュをサブミットされた値と比較することによってOTPを検証します。したがって、TOTPは短い時間枠（通常は30秒）でのみ有効です。HOTPの場合、現在の時刻の代わりに共有カウンターが使用されます。サーバーは、成功したOTPログインごとにカウンターをインクリメントします。したがって、有効なOTPはログインが成功した後にのみ変更されます。

TOTPは、短い時間枠でのみ有効であるため、HOTPより少し安全です。HOTPは、ユーザーが急いでOTPを入力する必要がないため、ユーザー・フレンドリーです。KeycloakがTOTPを実装した方法では、この区別はもう少しぼやけてしまいます。HOTPは、サーバーがカウンターをインクリメントするたびにデータベースを更新する必要があります。これは、負荷が大きいときに認証サーバー上でパフォーマンスが低下する可能性があります。より効率的な代替手段を提供するために、TOTPは使用されるパスワードを覚えていません。これにより、DBの更新は不要ですが、有効な時間間隔でTOTPを再利用できるという欠点があります。将来のバージョンのKeycloakでは、TOTPが時間間隔内に古いOTPをチェックするかどうかを設定できるようになる予定です。

6.2.2. TOTP設定オプション

OTP Hash Algorithm: デフォルトはSHA1です。より安全なオプションはSHA256とSHA512です。
Number of Digits: OTPの文字数。短い場合、ユーザーが入力する文字数が少なくなるため、ユーザー・フレンドリーです。長い場合、セキュリティの強度が高まります。
Look Ahead Window: サーバーがハッシュの照合を先行して試行する間隔。この設定は、TOTPジェネレーターまたは認証サーバーの時計が同期しなくなった場合に備えて存在します。通常は1というデフォルト値で十分です。たとえば、新しいトークンの時間間隔が30秒ごとの場合、デフォルト値1は、その30秒の枠内の有効なトークンのみを受け入れることを意味します。この設定値を増やすごとに有効な枠が30秒ずつ増加します。
OTP Token Period: 新しいTOTPがトークン・ジェネレーターによって生成される時間間隔（秒単位）。ハッシュが一致する時間枠。

6.2.3. HOTP設定オプション

OTP Hash Algorithm: デフォルトはSHA1です。より安全なオプションはSHA256とSHA512です。
Number of Digits: OTPの文字数。短い場合、ユーザーが入力する文字数が少なくなるため、ユーザー・フレンドリーです。長い場合、セキュリティの強度が高まります。
Look Ahead Window: サーバーが、ハッシュの照合を先行して試行するカウンターの数。デフォルト値は1です。これは、ユーザーのカウンターがサーバーよりも先行することをカバーするために存在します。ユーザーが頻繁にカウンターを手動で何回も増やすことが多いために、サーバーのカウンターと差分が発生します。この値は、実際の利用においては10程度に増やす必要があります。
Initial Counter: 最初のカウンターの値。

6.3. 認証フロー

認証フロー は、ログイン、登録、その他のKeycloakワークフロー利用時に発生するすべての認証、画面、およびアクションのためのコンテナーです。管理コンソールの左メニュー項目 Authentication から、 Flows タブを表示することで、システム内の定義されたすべてのフローと、各フローが必要とするアクションとチェックを見ることができます。このセクションでは、ブラウザーのログインフローについて説明します。左側のドロップダウン・リストで browser を選択すると、以下の画面が表示されます。

ブラウザーフロー

browser flow

フロー選択リストの右側にあるツールチップ（小さな疑問符）の上にカーソルを合わせると、フローの内容とその説明が表示されます。

Auth Type 列は、実行される認証またはアクションの名前です。認証がインデントされている場合、これはサブフローにあり、親の動作に応じて実行される場合と実行されない場合があります。 Requirement 列は、アクションが実行されるかどうかを定義するラジオボタンのセットです。各ラジオボタンの意味を説明します。

Required: この認証のエグゼキューションは正常に実行されなければなりません。ユーザーにそのタイプの認証メカニズムが設定されておらず、その認証タイプに関連する必須アクションがある場合、必須アクションがそのアカウントにアタッチされます。例えば、 OTP Form を Required に切り替えると、OTPジェネレーターが設定されていないユーザーには、OTPジェネレーターの設定が要求されます。
Optional: ユーザーに認証タイプが設定されている場合は、その認証タイプが実行されます。それ以外の場合は無視されます。
Disabled: 無効にすると、認証タイプは実行されません。
Alternative: 少なくとも1つの代替の認証タイプが、そのフローのレベルで正常に実行されなければならないことを意味します。

以下の browser 認証フローの例を見てみましょう。

最初の認証タイプは Cookie です。ユーザーが最初に正常にログインすると、セッションCookieが設定されます。このCookieがすでに設定されている場合、この認証タイプは正常です。Cookieプロバイダーは成功を返し、このフローのレベルでの各エグゼキューションは alternative であるため、他のエグゼキューションは実行されず、ログインに成功します。
フローの次の認証タイプは、Kerberosエグゼキューションです。このオーセンティケーターはデフォルトで無効になっており、スキップされます。
次のエグゼキューションはFormsと呼ばれるサブフローです。このサブフローは alternative とマークされているので、 Cookie 認証タイプが成功すると実行されません。このサブフローには、実行する必要のある追加の認証タイプが含まれています。サブフローのエグゼキューションはロードされ、同じ処理ロジックが発生します。
Formsサブフローでの最初のエグゼキューションは、Username Password Formです。この認証タイプは、ユーザー名とパスワードのページを表示します。 required とされているため、ユーザーは有効なユーザー名とパスワードを入力する必要があります。
次のエグゼキューションはOTPフォームです。これは optional としてマークされています。ユーザーがOTPを設定している場合は、この認証タイプを実行して成功させる必要があります。ユーザーにOTPが設定されていない場合、この認証タイプは無視されます。

6.4. エグゼキューション

以下のエグゼキューションが利用可能です。

スクリプト・オーセンティケーター

スクリプト オーセンティケーターを使用すると、JavaScript経由でカスタム認証ロジックを定義できます。カスタム・オーセンティケーター。認証スクリプトは、少なくとも次の機能のうちの1つを提供する必要があります。 Authenticator#authenticate(AuthenticationFlowContext) から呼び出される authenticate(..)。 Authenticator#action(AuthenticationFlowContext) から呼び出される action(..)。

カスタム オーセンティケーター は、 authenticate(..) 関数を提供するべきです。次のスクリプト javax.script.Bindings は、スクリプトコード内で便利に利用できます。

script: スクリプトのメタデータにアクセスするための ScriptModel
realm: RealmModel
user: 現在の UserModel
session: アクティブな KeycloakSession
authenticationSession: 現在の AuthenticationSessionModel
httpRequest: 現在の org.jboss.resteasy.spi.HttpRequest
LOG: ScriptBasedAuthenticator にスコープされた org.jboss.logging.Logger

追加のコンテキスト情報は、 authenticate(context) や、 action(context) 関数に渡される context 引数から抽出できます。

AuthenticationFlowError = Java.type("org.keycloak.authentication.AuthenticationFlowError");

function authenticate(context) {

  LOG.info(script.name + " --> trace auth for: " + user.username);

  if (   user.username === "tester"
      && user.getAttribute("someAttribute")
      && user.getAttribute("someAttribute").contains("someValue")) {

      context.failure(AuthenticationFlowError.INVALID_USER);
      return;
  }

  context.success();
}

6.5. Kerberos

Keycloakは、SPNEGOプロトコルを介したKerberosチケットによるログインをサポートしています。セッションにログインするときにユーザーが認証された後、Webブラウザーを介して透過的に認証するために、SPNEGO（単一および保護されたGSSAPIネゴシエーション・メカニズム）が使用されます。Web以外の場合やログイン中にチケットが利用できない場合、KeycloakはKerberosのユーザー名/パスワードによるログインもサポートしています。

Web認証の一般的なユースケースは次のとおりです。

ユーザーは自分のデスクトップ（Kerberosの統合が有効なActive Directoryドメイン内のWindowsマシンまたはLinuxマシンなど）にログインします。
ユーザーはブラウザー（IE/Firefox/Chrome）を使用して、Keycloakによって保護されたWebアプリケーションにアクセスします。
アプリケーションはKeycloakログインにリダイレクトされます。
Keycloakは、ステータス401とHTTPヘッダー WWW-Authenticate: Negotiate とともにHTMLログイン画面をレンダリングします
ブラウザーは、デスクトップ・ログインからのKerberosチケットがある場合、ヘッダー Authorization: Negotiate 'spnego-token' にデスクトップ・サインオン情報をセットしてKeycloakに転送します。それ以外の場合は、ログイン画面が表示されます。
Keycloakは、ブラウザーから送信されたトークンを検証し、ユーザーを認証します。LDAP（Kerberos認証をサポートするLDAPFederationProviderの場合）からユーザーデータをプロビジョニングするか、ユーザーにプロファイルを更新し、データを事前に入力させることができます（KerberosFederationProviderの場合）。
Keycloakはユーザーをアプリケーションに戻します。Keycloakとアプリケーションの間の通信は、OpenID ConnectまたはSAMLメッセージを介して行われます。KeycloakがKerberosを通じて認証されたという事実は、アプリケーションから隠されています。したがって、KeycloakはKerberos/SPNEGOログインのブローカーとして機能します。

セットアップには3つの主要な部分があります。

Kerberosサーバー（KDC）のセットアップと設定
Keycloakサーバーのセットアップと設定
クライアントマシンのセットアップと設定

6.5.1. Kerberosサーバーのセットアップ

これはプラットフォームに依存します。正確な手順は、使用するOSとKerberosベンダーによって異なります。Kerberosサーバーのセットアップと設定の正確な方法については、Windows Active Directory、MIT Kerberos、およびOSのドキュメントを参照してください。

少なくとも次のことが必要です。

一部のユーザー・プリンシパルをKerberosデータベースに追加します。KerberosとLDAPを統合することもできます。つまり、ユーザー・アカウントはLDAPサーバーからプロビジョニングされます。
"HTTP"サービスのサービス・プリンシパルを追加します。たとえば、Keycloakサーバーが www.mydomain.org で動作している場合、MYDOMAIN.ORGがKerberosレルムになると仮定して、プリンシパル HTTP/www.mydomain.org@MYDOMAIN.ORG を追加する必要があります。

たとえば、MIT Kerberosでは、"kadmin"セッションを実行できます。MIT Kerberosと同じマシン上にいる場合は、次の単純なコマンドを使用します。

sudo kadmin.local

次に、以下のコマンドで、HTTPプリンシパルを追加し、キーをkeytabファイルにエクスポートします。

addprinc -randkey HTTP/www.mydomain.org@MYDOMAIN.ORG
ktadd -k /tmp/http.keytab HTTP/www.mydomain.org@MYDOMAIN.ORG

keytabファイル /tmp/http.keytab は、Keycloakサーバーが実行されるホスト上でアクセス可能である必要があります。

6.5.2. Keycloakサーバーのセットアップと設定

Kerberosクライアントをマシンにインストールする必要があります。これもプラットフォームに依存します。Fedora、Ubuntu、またはRHELを使用している場合は、Kerberosクライアントとその他のいくつかのユーティリティーを含む freeipa-client パッケージをインストールできます。Kerberosクライアントを設定してください（Linuxの場合は /etc/krb5.conf にあります）。Kerberosレルムを配置し、少なくともサーバーが稼働するHTTPドメインを設定する必要があります。レルムMYDOMAIN.ORGの例では、 domain_realm セクションを次のように設定することができます。

[domain_realm]
  .mydomain.org = MYDOMAIN.ORG
  mydomain.org = MYDOMAIN.ORG

次に、HTTPプリンシパルを使用してkeytabファイルをエクスポートし、そのファイルがKeycloakサーバーが実行されているプロセスにアクセス可能であることを確認する必要があります。プロダクションでは、このプロセスだけで読み込めるのであれば理想的ですが、他のファイルも読み込めるわけではありません。上記のMIT Kerberosの例では、すでにkeytabを /tmp/http.keytab にエクスポートしています。KDCとKeycloakが同じホスト上で実行されている場合、そのファイルはすでに使用可能です。

SPNEGO処理を有効にする

Keycloakでは、デフォルトでSPNEGOプロトコルのサポートが有効になっていません。したがって、ブラウザーフローに移動して Kerberos を有効にする必要があります。

ブラウザーフロー

browser flow

`Kerberos`のrequirementを disabled から alternative または required に切り替えます。 alternative は、基本的にKerberosがオプショナルであることを意味します。ユーザーのブラウザーがSPNEGO/Kerberosで動作するように設定されていない場合、Keycloakは通常のログイン画面に戻ります。requirementを required に設定した場合、すべてのユーザーはブラウザーでKerberosを有効にする必要があります。

Kerberosユーザー・ストレージ・フェデレーション・プロバイダーを設定する

認証サーバーでSPNEGOプロトコルが有効になったので、KeycloakがKerberosチケットをどのように解釈するかを設定する必要があります。これは、ユーザー・ストレージ・フェデレーションを介して行われます。Kerberos認証をサポートする2つの異なるフェデレーション・プロバイダーがあります。

LDAPサーバーを背後にしてKerberosで認証する場合は、最初にLDAPフェデレーション・プロバイダーを設定する必要があります。LDAPプロバイダーの設定ページを見ると、 Kerberos Integration セクションが表示されます。

LDAPとKerberosの統合

ldap kerberos

Allow Kerberos authentication スイッチをオンにすると、KeycloakはKerberosプリンシパルを使用してユーザーに関する情報を検索し、Keycloak環境にインポートすることができます。

KerberosソリューションがLDAPサーバーの背後にない場合は、 Kerberos ユーザー・ストレージ・フェデレーション・プロバイダーを使用する必要があります。 User Federation の左メニュー項目に移動し、 Add provider 選択ボックスから Kerberos を選択します。

Kerberosユーザー・ストレージ・プロバイダー

kerberos provider

このプロバイダーは、単純なプリンシパル情報のためにKerberosチケットを解析し、ローカルのKeycloakデータベースへの細かいインポートを行います。名、姓、電子メールなどのユーザー・プロファイル情報はプロビジョニングされません。

6.5.3. クライアントマシンのセットアップと設定

クライアントはKerberosクライアントをインストールし、上記のようにkrb5.confを設定する必要があります。さらに、ブラウザーでSPNEGOログインを有効にする必要があります。そのブラウザを使用している場合は、KerberosのためのFirefoxの設定を参照してください。URI .mydomain.org は、 network.negotiate-auth.trusted-uris 設定オプションで許可する必要があります。

Windowsドメインでは、通常、WindowsドメインのSPNEGO認証にIEがすでに参加できるため、クライアントは特別な設定を行う必要はありません。

6.5.4. 設定例

Kerberosで簡単にテストできるように、テスト用の設定例をいくつか用意しました。

KeycloakとFreeIPAのDockerイメージ

Docker をインストールすると、FreeIPAサーバーがインストールされたDockerイメージを実行できます。FreeIPAは、とりわけMIT Kerberosと389LDAPサーバーを統合したセキュリティー・ソリューションを提供します。このイメージは、LDAPフェデレーション・プロバイダーと設定されたKeycloakサーバーも提供し、FreeIPAサーバーに対してSPNEGO/Kerberos認証を有効にします。詳細はこちらをご覧ください。

ApacheDSテストKerberosサーバー

迅速なテストとユニットテストのために、非常にシンプルな ApacheDS Kerberosサーバーを使用します。ソースからKeycloakをビルドし、テストスイートからmaven-exec-pluginを使ってKerberosサーバーを実行する必要があります。詳細はこちらをご覧ください。

6.5.5. クレデンシャルの委任

Kerberos 5は、クレデンシャルの委任の概念をサポートしています。このシナリオでは、アプリケーションがKerberosチケットにアクセスして、Kerberosでセキュリティー保護されている他のサービスとやりとりすることができます。KeycloakサーバーでSPNEGOプロトコルが処理されるため、Keycloakサーバーからアプリケーションに送信されるOpenID Connectトークンクレーム内のGSSクレデンシャルか、SAMLアサーション属性を伝播する必要があります。このクレームをトークンまたはアサーションに挿入するには、各アプリケーションで gss delegation credential と呼ばれるビルトイン・プロトコル・マッパーを有効にする必要があります。これは、アプリケーションのクライアント・ページの Mappers タブで有効になります。詳細については、プロトコル・マッパーの章を参照してください。

アプリケーションは、他のサービスに対してGSSコールを使用する前に、Keycloakから受け取ったクレームをデシリアライズする必要があります。クレデンシャルをアクセストークンからGSSクレデンシャル・オブジェクトにデシリアライズしたら、このクレデンシャルを GSSManager.createContext メソッドに渡して、次の例のようにGSSContextを作成する必要があります。

// Obtain accessToken in your application.
KeycloakPrincipal keycloakPrincipal = (KeycloakPrincipal) servletReq.getUserPrincipal();
AccessToken accessToken = keycloakPrincipal.getKeycloakSecurityContext().getToken();

// Retrieve kerberos credential from accessToken and deserialize it
String serializedGssCredential = (String) accessToken.getOtherClaims().
    get(org.keycloak.common.constants.KerberosConstants.GSS_DELEGATION_CREDENTIAL);

GSSCredential deserializedGssCredential = org.keycloak.common.util.KerberosSerializationUtils.
    deserializeCredential(serializedGssCredential);

// Create GSSContext to call other kerberos-secured services
GSSContext context = gssManager.createContext(serviceName, krb5Oid,
    deserializedGssCredential, GSSContext.DEFAULT_LIFETIME);

これを詳細に示した例があります。Keycloakのサンプル配布物またはデモ配布ダウンロードの examples/kerberos にあります。サンプルソースをここで直接チェックすることもできます。

krb5.conf ファイルで 転送可能な Kerberosチケットを設定し、ブラウザーに委任されたクレデンシャルのサポートを追加する必要があることに注意してください。

クレデンシャルの委任にはいくつかのセキュリティー上の影響があります。本当に必要な場合にのみ使用してください。HTTPSと一緒に使用することを強くお勧めします。詳細については、この記事の例を参照してください。

6.5.6. トラブルシューティング

課題がある場合は、追加のログを有効にして問題をデバッグすることをお勧めします。

KerberosまたはLDAPフェデレーション・プロバイダーの管理コンソールで Debug フラグを有効にする
standalone/configuration/standalone.xml のロギング・セクションに org.keycloak カテゴリのTRACEロギングを有効にして、詳細な情報 standalone/log/server.log を受け取ります。
システムプロパティ -Dsun.security.krb5.debug=true と -Dsun.security.spnego.debug=true を追加します

6.6. X.509クライアント証明書ユーザー認証

Keycloakは、サーバーが相互SSL認証用に設定されている場合、X.509クライアント証明書によるログインをサポートします。

一般的なワークフローは次のとおりです。

クライアントがSSL/TLSチャネルを介して認証リクエストを送信します。
SSL/TLSハンドシェイク中に、サーバーとクライアントはx.509/v3証明書を交換します。
コンテナ（WildFly）は、証明書のPKIXパスと有効期限を検証します。
x.509クライアント証明書オーセンティケーターは、次のようにクライアント証明書を検証します。
- 必要に応じて、CRLおよび（または）CRL配布ポイントを使用して証明書失効ステータスをチェックします。
- 必要に応じて、OCSP（オンライン証明書ステータス・プロトコル）を使用して証明書失効ステータスをチェックします。
- 必要に応じて、証明書内のキー使用が予想されるキー使用と一致するかどうかを検証します。
- 必要に応じて、証明書内の拡張キー使用法が予想される拡張キー使用法と一致するかどうかを検証します。
上記のチェックのいずれかが失敗した場合、x.509認証は失敗します。
それ以外の場合、オーセンティケーターは証明書アイデンティティーを抽出し、既存のユーザーにマッピングします。
証明書が既存のユーザーにマップされると、その動作は次のように認証フローによって分岐します。
- ブラウザーフローでは、サーバーはアイデンティティーを確認するかそれを無視して、代わりにユーザー名/パスワードでサインインすることをユーザーに促します。
- ダイレクト・グラント・フローの場合、サーバーはユーザーをサインインします。

6.6.1. 機能

サポートされている証明書のアイデンティティー・ソース

正規表現を使用したSubjectDN一致
X500 Subject’s e-mail属性
X500 Subject’s Common Name属性
正規表現を使用したIssuerDN一致
X500 Issuer’s e-mail属性
X500 Issuer’s Common Name属性
証明書のシリアル番号

正規表現

証明書アイデンティティーは、正規表現をフィルターとして使用して、SubjectDNまたはIssuerDNのいずれかから抽出できます。たとえば、以下の正規表現はe-mail属性と一致します。

emailAddress=(.*?)(?:,|$)

正規表現フィルタリングは、 Identity Source が Match SubjectDN using regular expression か、 Match IssuerDN using regular expression のどちらかにセットされている場合にのみ適用されます。

既存のユーザーに証明書のアイデンティティーをマッピングする: 証明書アイデンティティー・マッピングは、抽出されたユーザー・アイデンティティーを既存のユーザーのユーザー名、電子メール、または証明書アイデンティティーと一致する値を持つカスタム属性にマップするように設定できます。たとえば、 Identity source を Subject’s e-mail に、 User mapping method に Username or email に設定すると、X.509クライアント証明書オーセンティケーターはユーザー名または電子メールで既存のユーザーをルックアップするために、検索基準として証明書のSubjectDNのe-mail属性を使用します。

レルム設定で 電子メールによるログイン を無効にすると、同じルールが証明書認証に適用されることに注意してください。つまり、ユーザーはe-mail属性を使用してログインすることはできません。

その他の機能：拡張された証明書検証

CRLを使用した失効ステータスの確認
CRL/Distributionポイントを使用した失効ステータスの確認
OCSP/Responder URIを使用した失効ステータスの確認
証明書のKeyUsage検証
証明書のExtendedKeyUsage検証

6.6.2. X.509クライアント証明書のユーザー認証を有効にする

以下のセクションでは、X.509クライアント証明書認証を有効にするためにWildfly/UndertowとKeycloakサーバーを設定する方法について説明します。

WildFlyで相互SSLを有効にする

WildflyでSSLを有効にする方法については、Enable SSLとSSLを参照してください。

$KEYCLOAK_HOME/standalone/configuration/standalone.xmlを開き、新しいレルムを追加します。

<security-realms>
    <security-realm name="ssl-realm">
        <server-identities>
            <ssl>
                <keystore path="servercert.jks"
                          relative-to="jboss.server.config.dir"
                          keystore-password="servercert password"/>
            </ssl>
        </server-identities>
        <authentication>
            <truststore path="truststore.jks"
                        relative-to="jboss.server.config.dir"
                        keystore-password="truststore password"/>
        </authentication>
    </security-realm>
</security-realms>

ssl/keystore

ssl 要素には、JKSキーストアからサーバー公開鍵ペアをロードする方法を定義する keystore 要素が含まれています。

ssl/keystore/path

JKSキーストアへのパス。

ssl/keystore/relative-to

キーストアパスが相対的なパスを定義します。

ssl/keystore/keystore-password

キーストアを開くためのパスワード。

ssl/keystore/alias (optional)

キーストア内のエントリーのエイリアス。キーストアに複数のエントリが含まれている場合に設定します。

ssl/keystore/key-password （オプション）

秘密鍵のパスワード（キーストアのパスワードと異なる場合）。

authentication/truststore

インバウンド/アウトゴーイング接続のリモート側が提示する証明書を検証するためにトラストストアをロードする方法を定義します。通常、トラストストアには、信頼できる認証局の証明書のコレクションが含まれています。

authentication/truststore/path

信頼できるCA（認証局）の証明書を含むJKSキーストアへのパス。

authentication/truststore/relative-to

トラストストア・パスが相対的なパスを定義します。

authentication/truststore/keystore-password

トラストストアを開くためのパスワード。

httpsリスナーを有効にする

WildflyでHTTPSを有効にする方法については、HTTPS Listenerを参照してください。

<https-listener>要素を次のように追加します。

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
        ....
    <server name="default-server">
            <https-listener name="default"
                        socket-binding="https"
                        security-realm="ssl-realm"
                        verify-client="REQUESTED"/>
    </server>
</subsystem>

https-listener/security-realm: 値は、前のセクションのレルムの名前と一致する必要があります。
https-listener/verify-client: REQUESTED に設定した場合、サーバーは任意でクライアント証明書を要求します。 REQUIRED に属性を設定すると、クライアント証明書が提供されていない場合、サーバーはインバウンド接続を拒否します。

6.6.3. ブラウザーフローへのX.509クライアント証明書認証の追加

レルムを選択し、Authenticationのリンクをクリックし、"Browser"フローを選択します。
ビルトインの"Browser"フローのコピーを作成します。新しいフローに特有の名前、すなわち、"X.509 Browser"を付けることをお勧めします。
ドロップダウンを使用して、コピーされたフローを選択し、"Add execution"をクリックします。
ドロップダウンを使用して"X509/Validate User Form"を選択し、"Save"をクリックします。

x509 execution

上（下）の矢印を使用して、"X509/Validate Username Form"の順序を"Browser Forms"の上に移動させて、requirementを"ALTERNATIVE"に設定します。

x509 browser flow

"Bindings"タブを選択し、"Browser Flow"のドロップダウンを見つけます。ドロップダウンから新しく作成したX509 browser flowを選択し、"Save"をクリックします。

x509 browser flow bindings

X.509クライアント証明書認証の設定
User Identity Source: クライアント証明書からユーザー・アイデンティティーを抽出する方法を定義します。
A regular expression （オプション）: 証明書アイデンティティーを抽出するフィルターとして使用する正規表現を定義します。正規表現には1つのグループが含まれている必要があります。
User Mapping Method: 既存のユーザーに証明書アイデンティティーを一致させる方法を定義します。 Username or e-mail は、ユーザー名または電子メールから既存のユーザーを検索します。 Custom Attribute Mapper は、証明書アイデンティティーと一致するカスタム属性を持つ既存のユーザーを検索します。カスタム属性の名前は設定可能です。
A name of user attribute （オプション）: 値が証明書アイデンティティーと照合されるカスタム属性。
CRL Checking Enabled （オプション）: 証明書失効リストを使用して証明書の失効ステータスをチェックするかどうかを定義します。
Enable CRL Distribution Point to check certificate revocation status （オプション）: CDPを使用して証明書失効ステータスをチェックするかどうかを定義します。ほとんどのPKI機関には証明書にCDPが含まれています。
CRL file path （オプション）: CRLリストを含むファイルへのパスを定義します。 CRL Checking Enabled オプションがオンの場合、この値は有効なファイルへのパスである必要があります。
OCSP Checking Enabled （オプション）: オンライン証明書ステータス・プロトコルを使用して証明書失効ステータスをチェックするかどうかを定義します。
OCSP Responder URI （オプション）: 証明書内のOCSPレスポンダーURIの値を上書きすることを許可します。
Validate Key Usage （オプション）: 証明書のKeyUsage拡張のビットが設定されているかどうかを確認します。たとえば、"digitalSignature,KeyEncipherment"は、KeyUsage拡張のビット0と2がアサートされているかどうかを検証します。Key Usageの有効性を無効にするには、パラメータを空のままにします。RFC5280、セクション4.2.1.3を参照してください。サーバーは、発行認証局によってクリティカルであるとフラグが立てられ、キー使用拡張の不一致がある場合にのみ、エラーを発生させます。
Validate Extended Key Usage （オプション）: Extended Key Usage拡張で定義されている1つ以上の目的を検証します。RFC5280、セクション4.2.1.12を参照してください。Extended Key Usageの検証を無効にするには、パラメータを空のままにします。サーバーは、発行認証局によってクリティカルであるとフラグが立てられ、キー使用拡張の不一致がある場合にのみ、エラーを発生させます。
Bypass identity confirmation: 設定されている場合、X.509クライアント証明書認証は、ユーザーに証明書アイデンティティーの確認を促さず、ユーザーの認証に成功すると自動的にサインインします。

6.6.4. ダイレクト・グラント・フローへのX.509クライアント証明書認証の追加

Keycloak管理コンソールを使用して、"Authentication"をクリックし、"Direct Grant"フローを選択します。
ビルドインの "Direct Grant"フローのコピーを作成します。新しいフローに特有の名前、すなわち、"X509 Direct Grant"を付けることをお勧めします。
"Validate Username"と"Password"のオーセンティケーターを削除します。
"Add execution"をクリックし、"X509/Validate Username"を追加し、"Save"をクリックして実行ステップを親フローに追加します。

x509 directgrant execution

Requirement を REQUIRED に変更してください。

x509 directgrant flow

前述のx.509ブラウザーフローのセクションの手順に従って、x509認証設定のセットアップを行います。
"Bindings"タブを選択し、"Direct Grant Flow"のドロップダウンを見つけます。ドロップダウンから新しく作成したX509 direct grant flowを選択し、"Save"をクリックします。

x509 directgrant flow bindings

6.6.5. トラブルシューティング

X.509によるダイレクト・グラント認証: 次のテンプレートを使用して、リソース・オーナー・パスワード・クレデンシャル・グラントを使用してトークンをリクエストできます。

$ curl https://[host][:port]/auth/realms/master/protocol/openid-connect/token \
       --insecure \
       --data "grant_type=password&scope=openid profile&username=&password=&client_id=CLIENT_ID&client_secret=CLIENT_SECRET" \
       -E /path/to/client_cert.crt \
       --key /path/to/client_cert.key

[host][:port]: ダイレクト・グラント・フローを使用してx.509クライアント証明書でユーザーを認証できるように設定されているリモートのKeycloakサーバーのホストとポート番号。
CLIENT_ID: クライアントID。
CLIENT_SECRET: コンフィデンシャル・クライアントの場合は、クライアント・シークレット。それ以外の場合は、空のままにします。
client_cert.crt: 相互SSL認証でクライアントのアイデンティティーを確認するために使用される公開鍵証明書。証明書はPEM形式である必要があります。
client_cert.key: 公開鍵ペアの秘密鍵。PEM形式であることも期待されます。

7. SSOプロトコル

この章では、認証プロトコルと、Keycloak認証サーバーとセキュア保護されるアプリケーションがこれらのプロトコルで相互作用する仕組みについて簡単に説明します。

7.1. Open ID Connect

Open ID Connect（OIDC）はOAuth 2.0を拡張した認証プロトコルです。OAuth 2.0が認可プロトコルのみを構築するためのフレームワークで、不完全であるのに対し、OIDCは完成された認証および認可のプロトコルです。OIDCはまた、Json Web Token（JWT）の標準セットを多用します。これらの標準は、コンパクトでwebフレンドリーな方法で、アイデンティティー・トークンのJSON形式とデジタル署名、データ暗号化の方法を定義します。

OIDCを使用するユースケースは、実際には2つの種類があります。1つ目は、Keycloakサーバーにユーザーの認証を要求するアプリケーションのユースケースです。ログインが成功すると、アプリケーションは identity token と access token を受け取ります。 Identity token には、ユーザー名、電子メール、その他のプロファイル情報など、ユーザーに関する情報が含まれています。 Access token はレルムによってデジタル署名されており、アプリケーションがユーザーのアクセス可能なリソースを決定するために使用できるアクセス情報（ユーザー・ロール・マッピングのような）が含まれています。

2つ目のタイプは、リモートサービスへのアクセス権を取得したいクライアントのユースケースです。この場合、クライアントは、ユーザーの代理として他のリモートサービスの呼び出しに使用できる アクセストークン の取得をKeycloakに要求します。Keycloakは、ユーザーを認証し、クライアントのアクセスを許可する同意を要求します。そして、クライアントは アクセストークン を受け取ります。この アクセストークン はレルムによってデジタル署名されます。クライアントはこの アクセストークン を使用して、リモートサービスのREST呼び出しを行うことができます。REST サービスは アクセストークン を抽出し、トークンの署名を検証し、トークン内のアクセス情報に基づいて、リクエストを処理するかどうかを決定します。

7.1.1. OIDC認証フロー

OIDCには、クライアントまたはアプリケーションがユーザーを認証し、 identity トークンおよび access トークンを受け取るさまざまな方法があります。どの方法を使用するかは、アクセスを要求するアプリケーションまたはクライアントのタイプによって大きく異なります。これらのフローはすべてOIDCおよびOAuth 2.0の仕様で説明されていますので、ここでは簡単な概要のみを説明します。

認可コード・フロー

これはブラウザー・ベースのプロトコルであり、ブラウザー・ベースのアプリケーションの認証と認可に使用することをお勧めします。 identity トークンと access トークンを取得するために、ブラウザーのリダイレクトを頻繁に使用します。概要を以下に示します。

ブラウザーがアプリケーションにアクセスします。アプリケーションは、ユーザーがログインしていないことを検知し、認証させるためにブラウザーをKeycloakにリダイレクトします。アプリケーションは、Keycloakが認証を完了したときに使用するブラウザー・リダイレクトのコールバックURL（リダイレクトURL）をクエリー・パラメーターとして渡します。
Keycloakはユーザーを認証し、1回限りで非常に存続期間の短い、一時的なコードを作成します。Keycloakは、以前に提供されたコールバックURLを使用してアプリケーションにリダイレクトします。コールバックURLには、クエリー・パラメーターとして一時コードが追加されます。
アプリケーションは一時コードを抽出し、それを identity トークン、 access トークンおよび refresh トークンと交換するため、バックグラウンドで帯域外のKeycloakへのREST呼び出し｀を行います。この一時コードを一度使用してトークンを取得すると、それを再び使用することはできません。これにより潜在的なリプレイ攻撃が防止されます。

access トークンは通常短命であり、しばしば数分後に失効されることに注意することが重要です。ログイン・プロトコルによって送信された追加の refresh トークンにより、アプリケーションは有効期限が切れた後に新しいアクセス・トークンを取得できます。このリフレッシュ・プロトコルは、システムが侵害された状況で重要です。アクセス・トークンが短命である場合、システム全体は、アクセストークンの存続期間中に盗まれたトークンに対してのみ脆弱です。管理者がアクセスを取り消した場合、その後のリフレッシュ・トークン・リクエストは失敗します。これにより、より安全でスケーラブルになります。

このフローのもう一つの重要な側面は、 public クライアント対 confidential クライアントの概念です。 Confidential クライアントは、トークンと一時コードを交換するときにクライアント・シークレットを提供する必要があります。 Public クライアントはこのクライアント・シークレットを提供する必要がありません。 Public クライアントは、HTTPSが厳格に実施されており、クライアントにリダイレクトURIの登録が非常に厳密に行われている限り問題ありません。HTML5/JavaScriptクライアントは、常に安全な方法でクライアント・シークレットを送信する方法がないため、必ず public クライアントでなければなりません。前述の通り、HTTPSを使用し、リダイレクトURI登録を厳密に実施する限り、これは問題ありません。これに関するガイドは、クライアントの管理の章で詳しく説明しています。

インプリシット・フロー

これは、リクエストが少なく、リフレッシュ・トークンが含まれていない点を除いて、認可コードフローと同様のブラウザー・ベースのプロトコルです。トークンがリダイレクトURI（以下を参照）を介して送信されるため、ブラウザーの履歴に access トークンがリークする可能性があるため、このフローはお勧めしません。また、このフローではクライアントにリフレッシュ・トークンが提供されないため、アクセス・トークンを長くするか、期限切れになったときに再認証する必要があります。このフローは、OIDCおよびOAuth 2.0の仕様にあるため、サポートされています。プロトコルの概要を以下に示します。

ブラウザーがアプリケーションにアクセスします。アプリケーションは、ユーザーがログインしていないことを検知し、認証させるためにブラウザーをKeycloakにリダイレクトします。アプリケーションは、Keycloakが認証を完了したときに使用するブラウザー・リダイレクトのコールバックURL（リダイレクトURL）をクエリー・パラメーターとして渡します。
Keycloakはユーザーを認証し、 identity トークンと access トークンを作成します。Keycloakは、前述のコールバックURLを使用してアプリケーションにリダイレクトし、さらに identity トークンと access トークンをクエリー・パラメーターとしてコールバックURLに追加します。
アプリケーションは、コールバックURLから identity トークンと access トークンを抽出します。

リソース・オーナー・パスワード・クレデンシャル・グラント（ダイレクト・アクセス・グラント）

これは、管理コンソールでは Direct Access Grants と呼ばれます。ユーザーに代わってトークンを取得するRESTクライアントによって使用されます。これは、クライアントIDとクライアント・シークレット（コンフィデンシャル・クライアントの場合）と同様に、ユーザーのクレデンシャルを含む1つのHTTP POSTリクエストとなります。ユーザーのクレデンシャルは、フォーム・パラメーター内で送信されます。HTTPレスポンスには、 identity トークン、 access トークン、および refresh トークンが含まれています。

クライアント・クレデンシャル・グラント

これはRESTクライアントでも使用されますが、外部ユーザーの代わりに動作するトークンを取得する代わりに、クライアントに関連付けられているサービス・アカウントのメタデータとパーミッションに基づいてトークンが作成されます。さらに詳しい情報は、サービス・アカウントの章にあります。

7.1.2. KeycloakサーバーOIDC URIエンドポイント

Keycloakが発行するOIDCエンドポイントのリストです。これらのURLは、Keycloak以外のクライアント・アダプターを使用して、認証サーバーとOIDCでやりとりしている場合に便利です。これらはすべてが相対URLであり、URLのルートはHTTP(S)プロトコル、ホスト名、通常は /auth のプレフィックス付きのパスからなります。例： https://localhost:8080/auth

/realms/{realm-name}/protocol/openid-connect/token: これは、認可コード・フローで一時コードを取得するため、またはインプリシット・フロー、ダイレクト・グラント、またはクライアント・グラントを使用してトークンを取得するためのURLエンドポイントです。
/realms/{realm-name}/protocol/openid-connect/auth: これは、一時コードをトークンに変換する認可コード・フローのURLエンドポイントです。
/realms/{realm-name}/protocol/openid-connect/logout: これは、ログアウトを実行するためのURLエンドポイントです。
/realms/{realm-name}/protocol/openid-connect/userinfo: これは、OIDC仕様で説明されているUserInfoサービスのURLエンドポイントです。

これらのURLすべてで、 {realm-name} はレルムの名前に置き換えてください。

7.2. SAML

SAML 2.0はOIDCと似た仕様ですが、より古くて成熟しています。SOAPをルーツとしていて、WS- *の仕様も多すぎるため、OIDCよりも冗長な傾向があります。SAML 2.0は主に、認証サーバーとアプリケーションの間でXMLドキュメントを交換することによって機能する認証プロトコルです。XML署名と暗号化は、リクエストとレスポンスを検証するために使用されます。

SAMLを使用するユースケースは、実際には2つの種類があります。1つ目は、Keycloakサーバーにユーザーの認証を要求するアプリケーションのユースケースです。ログインが成功すると、アプリケーションはユーザーに関する様々な属性を指定するSAMLアサーションと呼ばれるものが含まれるXMLドキュメントを受け取ります。このXMLドキュメントはレルムによってデジタル署名されており、アプリケーションがユーザーのアクセス可能なリソースを決定するために使用できるアクセス情報（ユーザー・ロール・マッピングのような）が含まれています。

2番目のユースケースは、リモートサービスにアクセスしたいクライアントです。この場合、クライアントはユーザーの代わりに他のリモートサービスで呼び出すために使用できるSAMLアサーションを取得するようKeycloakに求めます。

7.2.1. SAMLバインディング

SAMLは、認証プロトコルを実行する際にXMLドキュメントを交換するためのいくつかの異なる方法を定義しています。 REDIRECT バインディングと POST バインディングは、ブラウザーベースのアプリケーションをカバーします。 ECP バインディングは、REST呼び出しを扱います。他のバインディング種別もありますが、Keycloakはこれらの3つしかサポートしていません。

REDIRECTバインディング

REDIRECT バインディングは、一連のブラウザー・リダイレクトURIを使用して情報を交換します。その動作の概要を示します。

ユーザーがアプリケーションへアクセスすると、認証されていないことがアプリケーションによって検出されます。XML認証リクエスト・ドキュメントを生成し、それをKeycloakサーバーにリダイレクトするために使用されるURIのクエリー・パラメーターとしてエンコードします。設定に応じて、アプリケーションはこのXMLドキュメントにデジタル署名し、この署名をKeycloakへのリダイレクトURIのクエリー・パラメーターとして埋め込むこともできます。この署名は、このリクエストを送信したクライアントを検証するために使用されます。
ブラウザーはKeycloakにリダイレクトされます。サーバーは、XML認証リクエスト・ドキュメントを抽出し、必要に応じてデジタル署名を検証します。ユーザーは認証されるためにクレデンシャルを入力する必要があります。
認証後、サーバーはXML認証レスポンス・ドキュメントを生成します。このドキュメントには、ユーザーの名前、住所、電子メール、およびユーザーが持つロール・マッピングなどのユーザーに関するメタデータを保持するSAMLアサーションが含まれています。このドキュメントは、ほとんどの場合、XML署名を使用してデジタル署名されており、暗号化されている場合もあります。
次に、XML認証レスポンス・ドキュメントは、ブラウザーをアプリケーションへ戻すためのリダイレクトURIのクエリー・パラメーターとしてエンコードされます。デジタル署名はクエリー・パラメーターとしても含まれています。
アプリケーションは、リダイレクトURIを受け取った後、XMLドキュメントを抽出し、レルムの署名を検証して正しい認証レスポンスかどうかを検証します。SAMLアサーション内の情報は、アクセスの決定やユーザー・データの表示に使用されます。

POSTバインディング

SAML POST バインディングは、REDIRECT バインディングとほぼ同じ方法で動作しますが、GETリクエストではなく、POSTリクエストによってXMLドキュメントが交換されます。 POST バインディングは、JavaScriptを使用して、ドキュメントを交換するときにKeycloakサーバーまたはアプリケーションに対してPOSTリクエストを行うようにブラウザを操作します。基本的にHTTPレスポンスには、JavaScriptが埋め込まれたフォームを含むHTMLが含まれています。ページが読み込まれると、JavaScriptはフォームを自動的に呼び出します。このことについて実際に知る必要はありませんが、これはかなり巧妙なトリックです。

ECP

ECPは、Webブラウザーのコンテキスト外でSAML属性を交換できるようにするSAML v.2.0プロファイルの"Enhanced Client or Proxy"の略です。これは、RESTまたはSOAPベースのクライアントで最も頻繁に使用されます。

7.2.2. KeycloakサーバーSAML URIエンドポイント

KeycloakではすべてのSAMLリクエストに対して1つのエンドポイントしかありません。

http(s)://authserver.host/auth/realms/{realm-name}/protocol/saml

すべてのバインディングはこのエンドポイントを使用します。

7.3. OpenID Connect vs. SAML

OpenID ConnectとSAMLの選択は、古いより成熟したプロトコル（SAML）の代わりに新しいプロトコル（OIDC）を使用するだけの問題ではありません。

In most cases Keycloak recommends using OIDC.

SAMLは、OIDCよりも少し冗長になる傾向があります。

交換するデータの詳細度を度外視して仕様を比較した場合、OIDCはもともとWebで動作するように設計されていますが、SAMLはWeb上で動作するように改造されていることが分かります。たとえば、OIDCはSAMLよりもクライアントサイドに実装することが簡単なため、HTML5/JavaScriptアプリケーションにも適しています。トークンはJSON形式なので、JavaScriptにより簡単に扱うことができます。また、Webアプリケーションに対してセキュリティーの実装を容易にする、いくつかの素晴らしい機能があります。たとえば、ユーザーがログインしているかどうかを容易に判断するために使用するiframeトリックの仕様をチェックしてください。

SAMLにも用途はあります。OIDCの仕様の進化を見ると、SAMLが長年に渡って実装してきた多数の機能がOIDCにも実装されていることが分かります。SAMLがOIDCより成熟しているという認識と、SAMLによりセキュリティー保護されている既存のアプリケーションが存在するという理由により、OIDCよりもSAMLが選ばれることは多々あります。

7.4. Dockerレジストリーv2認証

Docker認証はデフォルトで無効です。有効にするには、Profilesを参照してください。

Dockerレジストリーv2認証は、Dockerレジストリーに対してユーザーを認証するために使用されるOIDCのようなプロトコルです。Keycloakはこのプロトコルを実装しており、Dockerクライアントがレジストリーに対しての認証にKeycloak認証サーバーを使用することができます。このプロトコルはかなり標準的なトークンと署名メカニズムを使用しますが、真のOIDC実装としては扱うことができない問題点があります。最大の問題点は、リクエストとレスポンスが非常に特殊なJSON形式であり、リポジトリー名とパーミッションをOAuthのスコープ・メカニズムにマップする方法を理解する必要がある点です。

7.4.1. Docker認証フロー

Docker API documentationはこのプロセスを最もよく説明していますが、Keycloak認証サーバーの観点から簡単な要約を以下に示します。

このフローは、 docker login コマンドが既に実行されていることを前提としています。

DockerクライアントがDockerレジストリーからリソースを要求すると、フローが開始されます。リソースが保護されており、リクエストに認証トークンが存在しない場合、Dockerレジストリー・サーバーは、必要なパーミッションに関する情報と認可サーバーの場所を401でクライアントに応答します。
Dockerクライアントは、Dockerレジストリーからの401レスポンスに基づいて認証リクエストを作成します。クライアントは、Keycloak認証サーバーへのHTTP Basic Authenticationリクエストの一部として、（以前に実行された docker login コマンドから）ローカルにキャッシュされたクレデンシャルを使用します。
Keycloak認証サーバーはユーザーを認証し、OAuth形式のベアラートークンを含むJSON本体を返します。
Dockerクライアントは、JSONレスポンスからベアラートークンを取得し、Authorizationヘッダーでベアラートークンを使用して、保護されたリソースを要求します。
Dockerレジストリーが保護されたリソースへの新しいリクエストをKeycloakサーバーからのトークンとともに受信すると、Dockerレジストリーはトークンを検証し、必要に応じてリソースへのアクセスを許可します。

7.4.2. Keycloak Dockerレジストリーv2認証サーバーのURIエンドポイント

Keycloakは、すべてのDocker認証v2リクエストに対して、実際には1つのエンドポイントしか持っていません。

http(s)://authserver.host/auth/realms/{realm-name}/protocol/docker-v2

8. クライアントの管理

クライアントは、ユーザーの認証を要求できるエンティティです。クライアントには2つの形式があります。最初のタイプのクライアントは、シングル・サインオンに参加させるアプリケーションです。これらのクライアントはKeycloakにセキュリティを提供するだけです。もう1つのタイプのクライアントは、認証されたユーザーに代わって他のサービスを呼び出すために、アクセストークンを要求します。このセクションでは、クライアントの設定に関するさまざまな側面とそれを実行するさまざまな方法について説明します。

8.1. OIDCクライアント

OpenID Connectは、アプリケーションを保護するのに好ましいプロトコルです。ウェブ・フレンドリーで、HTML5/JavaScriptアプリケーションで最もうまく動作するように、一から設計されました。

OIDCクライアントを作成するには、左側のメニュー項目 Clients に移動します。このページには右側に Create ボタンがあります。

Clients

clients

これにより、 Add Client ページが表示されます。

Add Client

add client oidc

クライアントの Client ID を入力します。これは、単純な英数字の文字列でなければなりません。クライアントを識別するために、リクエストとKeycloakデータベースで使用されます。次に、 Client Protocol ドロップダウンボックスで openid-connect を選択します。今は Client Template リストボックスを無視して、この章の後半で説明します。最後に、アプリケーションのベースURLを Root URL フィールドに入力し、 Save をクリックします。これでクライアントが作成され、クライアントの Settings タブに移動します。

クライアントの設定

client settings oidc

このページの各設定項目について説明します。

Client ID

これは、OIDC要求のクライアント識別子として使用される英数字の文字列を指定します。

Name

これはKeycloakのUI画面に表示されるクライアントの表示名です。置換文字列値の${myapp}を設定して、このフィールドの値をローカライズすることができます。詳細については、Server Developer Guideを参照してください。

Description

これは、クライアントの説明を指定します。これはローカライズすることもできます。

Enabled

これをオフにすると、クライアントは認証を要求できなくなります。

Consent Required

これがオンになっている場合、ユーザーに同意ページが表示され、そのアプリケーションへのアクセスを許可するかどうかが尋ねられます。また、クライアントがアクセスする情報をユーザーが正確に把握できるように、クライアントが関心を持つメタデータも表示されます。Googleにソーシャル・ログインしたことがある場合は、よく似たようなページを見ているでしょう。Keycloakは同じ機能を提供します。

Access Type

これは、OIDCクライアントのタイプを定義します。

confidential: コンフィデンシャルのアクセスタイプは、ブラウザー・ログインを実行し、アクセスコードをアクセストークンに変換する際に、クライアントシークレットを必要とするサーバーサイドのクライアント向けです（詳細はOAuth 2.0仕様の Access Token Request を参照してください）。このタイプは、サーバーサイドのアプリケーションに使用する必要があります。
public: パブリックのアクセスタイプは、ブラウザー・ログインを実行する必要のあるクライアントサイドのクライアント用です。クライアントサイドのアプリケーションでは、シークレットを安全に保つ方法はありません。代わりに、クライアントの正しいリダイレクトURIを設定することによってアクセスを制限することが非常に重要です。
bearer-only: ベアラーオンリーのアクセスタイプは、アプリケーションがベアラートークン要求のみを許可することを意味します。これが有効になっている場合、このアプリケーションはブラウザー・ログインに参加できません。

Root URL

Keycloakが設定された相対URLを使用する場合、この値が先頭に追加されます。

Valid Redirect URIs

これは必須項目です。追加するには、URLパターンを入力し + 記号をクリックします。削除するには、URLの横にある - 記号をクリックします。 Save ボタンもクリックしなければならないことを覚えておいてください。ワイルドカード（\*）は http://host.com/* のように、URIの最後にのみ使用できます。

有効なリダイレクトURIパターンを登録するときは、特別な注意を払う必要があります。それらをあまりにも一般的にすると、攻撃に対して脆弱です。詳細については脅威モデル緩和の章を参照してください。

Base URL

Keycloakがクライアントにリンクする必要がある場合、このURLが使用されます。

Standard Flow Enabled

これがオンの場合、クライアントはOIDC認可コードフローを使用できます。

Implicit Flow Enabled

これがオンの場合、クライアントはOIDCインプリシット・フローを使用できます。

Direct Grants Enabled

これがオンの場合、クライアントはOIDCダイレクト・グラントを使用できます。

Admin URL

Keycloak固有のクライアント・アダプターの場合、これはクライアントのコールバック・エンドポイントです。KeycloakサーバーはこのURIを使用して、失効ポリシーのプッシュ、バックチャネル・ログアウトの実行、その他の管理操作などのコールバックを行います。Keycloakサーブレット・アダプターの場合、これはサーブレット・アプリケーションのルートURLになります。詳細については、 Securing Applications and Services Guide を参照してください。

Web Origins

このオプションは、Cross-Origin Resource Sharingを意味する CORS に関するものです。ブラウザーのJavaScriptが、AJAX HTTPリクエストをJavaScriptコードのドメインとは異なるサーバーに送信しようとすると、そのリクエストはCORSを使用する必要があります。サーバーはCORSリクエストを特別な方法で処理する必要があります。そうしないと、ブラウザーは表示されずリクエストの処理が許可されません。このプロトコルは、XSS、CSRFおよびその他のJavaScriptベースの攻撃から保護するために存在します。

KeycloakはCORSリクエストの検証をサポートしています。クライアントの Web Origins 設定にリストされているドメインが、クライアント・アプリケーションに送信されるアクセストークンに埋め込まれます。クライアント・アプリケーションは、この情報を使用して、CORSリクエストを呼び出すかどうかを決定します。これはOIDCプロトコルの拡張であり、Keycloakクライアント・アダプターのみがこの機能をサポートしています。詳細については、 Securing Applications and Services Guide を参照してください。

Web Origins データを入力するには、ベースURLを入力し、 + 記号をクリックして追加します。削除するには、URLの横にある - 記号をクリックします。 `Save`ボタンをクリックしなければならないことを覚えておいてください。

8.1.1. コンフィデンシャル・クライアントのクレデンシャル

クライアントの Settings タブでクライアントのアクセスタイプを confidential に設定した場合、新しい Credentials タブが表示されます。このタイプのクライアントを扱う際には、クライアントのクレデンシャルを設定する必要があります。

Credentialsタブ

client credentials

Client Authenticator リストボックスはコンフィデンシャル・クライアントのために使用するクレデンシャルのタイプを指定します。デフォルトでは、クライアントIDとシークレットが使用されます。シークレットは自動的に生成され、 Regenerate Secret ボタンを使用して、必要に応じてこのシークレットを再生成することができます。

また、シークレットではなく署名付きJson Webトークン（JWT）を使用することもできます。

署名付きJWT

client credentials jwt

このクレデンシャル・タイプを選択するときは、クライアント用の秘密鍵と証明書も生成する必要があります。秘密鍵はJWTに署名するために使用され、証明書はサーバーによって署名の検証に使用されます。この手順を開始するには、 Generate new keys and certificate ボタンをクリックしてください。

鍵を生成する

generate client keys

これらの鍵を生成すると、Keycloakが証明書を保管するので、使用するクライアントの秘密鍵と証明書をダウンロードする必要があります。必要なアーカイブ形式を選択し、秘密鍵とストアのパスワードを指定します。

また、外部ツールを使用してこれらを生成し、クライアントの証明書をインポートすることもできます。

証明書のインポート

import client cert

インポートできるフォーマットは複数あります。証明書が保存されているアーカイブ形式を選択し、ファイルを選択して、 Import ボタンをクリックします。

最後に注意ですが、 Use JWKS URL を選択した場合は、証明書をインポートする必要はありません。その場合、クライアントが公開鍵を公開するURLを JWK 形式で指定することができます。クライアントが鍵を変更すると、Keycloakが自動的にダウンロードするため、Keycloak側で再インポートする必要がなく、柔軟性があります。

Keycloakアダプターで保護されたクライアントを使用する場合は、 https://myhost.com/myapp がクライアント・アプリケーションのルートURLであるとすると、 https://myhost.com/myapp/k_jwks のようなJWKS URLを設定できます。詳細については、Server Developer Guideを参照してください。

パフォーマンスのために、KeycloakはOIDCクライアントの公開鍵をキャッシュします。クライアントの秘密鍵が侵害されたと思われる場合は、鍵を更新するのは明らかに良いことですが、鍵キャッシュをクリアするのも良いことです。詳細については、キャッシュのクリアの節を参照してください。

8.2. サービス・アカウント

各OIDCクライアントには、 サービス・アカウント が組み込まれており、アクセストークンを取得できます。これは、<クライアント・クレデンシャル・グラントのOAuth 2.0仕様で説明されています。この機能を使用するには、クライアントのアクセスタイプを confidential に設定する必要があります。これを行うと、 Service Accounts Enabled スイッチが現れます。このスイッチをオンにする必要があります。また、クライアント・クレデンシャルを設定していることを確認してください。

サービス・アカウントを使用するには、有効な コンフィデンシャル クライアントを登録していなければなりません。また、そのクライアントのKeycloak管理コンソールの Service Accounts Enabled スイッチをオンにする必要があります。 Service Account Roles タブでは、このクライアントに代わって取得されたサービス・アカウントで使用可能なロールを設定できます。 Full Scope Allowed がオンの場合を除いて、このクライアントのスコープで利用できるロールが必要であることを忘れないでください。通常のログインと同様に、アクセストークンからのロールは、スコープとサービス・アカウントのロールの共通集合です。

起動するREST URLは /auth/realms/{realm-name}/protocol/openid-connect/token です。このURLを呼び出すのはPOSTリクエストで、クライアントのクレデンシャルを送信する必要があります。デフォルトでは、クライアントのクレデンシャルはクライアントのclientIdとclientSecretによって Authorization: Basic ヘッダーで表されますが、署名されたJWTアサーションまたはクライアント認証のためのその他のカスタム・メカニズムでクライアントを認証することもできます。また、OAuth2仕様に従ってパラメータ grant_type=client_credentials を使う必要があります。

たとえば、サービス・アカウントを取得するためのPOST呼び出しは次のようになります。

POST /auth/realms/demo/protocol/openid-connect/token
 Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
 Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

このレスポンスは、OAuth 2.0仕様の standard JSON document になります。

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
 "access_token":"2YotnFZFEjr1zCsicMWpAA",
 "token_type":"bearer",
 "expires_in":60,
 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
 "refresh_expires_in":600,
 "id_token":"tGzv3JOkF0XG5Qx2TlKWIA",
 "not-before-policy":0,
 "session_state":"234234-234234-234234"
}

取得したアクセストークンはリフレッシュされたり、有効期間を超えたリクエストによりログアウトされます。

8.3. SAMLクライアント

Keycloakは、登録されたアプリケーションのためにSAML 2.0をサポートしています。POSTバインディングとREDIRECTバインディングの両方がサポートされています。クライアントの署名検証を要求することもできますし、サーバーに署名したり、レスポンスを暗号化したりすることもできます。

SAMLクライアントを作成するには、左側メニューの項目 Clients に移動します。このページには右側に Create ボタンがあります。

Clients

clients

これにより、 Add Client ページが表示されます。

Add Client

add client saml

クライアントの Client ID を入力します。これは、よく見かけるURLであり、アプリケーションが送信するSAMLリクエストの期待される issuer 値になります。次に、 Client Protocol ドロップダウン・ボックスで saml を選択します。今は Client Template リストボックスを無視して、この章の後半で説明します。最後に、 Client SAML Endpoint URLを入力します。KeycloakサーバーがSAMLリクエストとレスポンスを送信するURLを入力します。通常、アプリケーションにはSAMLリクエストを処理するURLが1つしかありません。アプリケーションのバインディングに異なるURLがある場合でも、クライアントの Settings タブでこれを修正できます。 Save をクリックすることでクライアントが作成され、クライアントの Settings タブに移動します。

クライアントの設定

client settings saml

Client ID: この値は、AuthNRequestsで送信されたissuer値と一致する必要があります。KeycloakはissuerをAuthn SAMLリクエストから引き出し、この値でクライアントに照合します。
Name: これはKeycloakのUI画面に表示されるクライアントの表示名です。置換文字列値の${myapp}を設定して、このフィールドの値をローカライズすることができます。詳細については、Server Developer Guideを参照してください。
Description: これは、クライアントの説明を指定します。これはローカライズすることもできます。
Enabled: これをオフにすると、クライアントは認証を要求できなくなります。
Consent Required: これがオンになっている場合、ユーザーに同意ページが表示され、そのアプリケーションへのアクセスを許可するかどうかが尋ねられます。また、クライアントがアクセスする情報をユーザーが正確に把握できるように、クライアントが関心を持つメタデータも表示されます。Googleにソーシャル・ログインしたことがある場合は、よく似たようなページを見ているでしょう。Keycloakは同じ機能を提供します。
Include AuthnStatement: SAMLログイン・レスポンスは、使用された認証方法（パスワードなど）とログインのタイムスタンプを含めることができます。これをONに設定すると、そのステートメントがレスポンス・ドキュメントに含まれます。
Sign Documents: onにすると、Keycloakはレルムの秘密鍵を使用してドキュメントに署名します。
Optimize REDIRECT signing key lookup: onにすると、SAMLプロトコル・メッセージに署名鍵IDのヒントを含むKeycloakのネイティブ拡張が含まれます。 SPがこの拡張を理解すると、既知のすべての鍵で署名を検証するのではなく、署名の検証にヒントを使用できます。このオプションは、署名情報にこの情報が含まれておらず、クエリー・パラメータで署名が転送される、REDIRECTバインディングにのみ適用されます（鍵IDが常にドキュメントの署名に含まれるPOSTバインディング・メッセージとは異なります）。現時点では、IDPとSPの両方がKeycloakサーバーとアダプターによって提供される状況に関係します。このオプションは、 Sign Documents がonになっている場合にのみ関係します。
Sign Assertions: Sign Documents スイッチはドキュメント全体に署名します。この設定では、アサーションも署名され、SAML XML Authレスポンスに埋め込まれます。
Signature Algorithm: SAMLドキュメントに署名するためのアルゴリズムを選択します。
SAML Signature Key Name: POSTバインディングを介して送信された署名付きSAMLドキュメントは、 KeyName 要素内に署名鍵のIDを含みます。デフォルトでは、Keycloakの鍵IDを含みます。しかし、ベンダーによっては異なるKeyNameであったり、KeyName要素のない署名付きSAMLドキュメントとなる場合もあります。このスイッチは、 KeyName が鍵IDを保持しているか（オプション KEY_ID ）、レルム鍵に対応する証明書からのsubjectを保持しているか（オプション CERT_SUBJECT 、Microsoft Active Directoryフェデレーション・サービスによって期待される）、あるいは、KeyNameのヒントがSAMLメッセージから完全に省略されるか（オプション NONE ）を制御します。
Canonicalization Method: XML署名の正規化方法を選択します。
Encrypt Assertions: レルムの秘密鍵を使用してSAMLドキュメントのアサーションを暗号化します。AESアルゴリズムは128ビットの鍵サイズで使用されます。
Client Signature Required: クライアントからのドキュメントに署名があることを期待します。Keycloakは、 SAML Keys タブに設定されたクライアント公開鍵または証明書を使用して、この署名を検証します。
Force POST Binding: デフォルトでは、Keycloakは元のリクエストの最初のSAMLバインディングを使用して応答します。このスイッチをonにすると、元のリクエストがREDIRECTバインディングであっても、Keycloakが常にSAML POSTバインディングを使用して応答するようになります。
Front Channel Logout: trueの場合、このアプリケーションは、ログアウトを実行するのにブラウザーのリダイレクトを必要とします。たとえば、アプリケーションは、リダイレクトを介してのみリセットすることができるCookieを必要とするかもしれません。このスイッチがfalseの場合、KeycloakはバックグラウンドのSAMLリクエストを呼び出してアプリケーションをログアウトします。
Force Name ID Format: リクエストにName IDポリシーがある場合、それを無視し、管理コンソールの Name ID Format で設定された値を使用します。
Name ID Format: subjectのName ID Format。リクエストにName IDポリシーが指定されていない場合、または Force Name ID Format 属性がtrueの場合、この値が使用されます。フォーマットとして使用されるプロパティが定義されています。
Root URL: Keycloakが設定された相対URLを使用する場合、この値が先頭に追加されます。
Valid Redirect URIs: これはオプションのフィールドです。URLパターンを入力し、+ 記号をクリックして追加します。削除するにはURLの横にある - 記号をクリックします。反映には Save ボタンをクリックする必要があることに留意してください。ワイルドカード（\*）は http://host.com/* のように、URIの最後にのみ使用できます。このフィールドは、正確なSAMLエンドポイントが登録されておらず、Keycloakがリクエストからアサーション・コンシューマURLを取得している場合に使用されます。
Base URL: Keycloakがクライアントにリンクする必要がある場合、このURLが使用されます。
Master SAML Processing URL: このURLはすべてのSAMLリクエストに使用され、レスポンスはSPに送信されます。アサーション・コンシューマー・サービスURLとシングル・ログアウト・サービスURLとして使用されます。ログイン・リクエストにアサーション・コンシューマー・サービスのURLが含まれている場合、そのURLが優先されますが、URLは登録済みのValid Redirect URIパターンで妥当性を確認する必要があります。
Assertion Consumer Service POST Binding URL: アサーション・コンシューマー・サービスのPOSTバインディングURL。
Assertion Consumer Service Redirect Binding URL: アサーション・コンシューマー・サービスのREDIRECTバインディングURL。
Logout Service POST Binding URL: ログアウト・サービスのPOSTバインディングURL。
Logout Service Redirect Binding URL: ログアウト・サービスのREDIRECTバインディングURL。

8.3.1. IDP Initiated ログイン

IDP Initiated ログインは、特定のアプリケーション／クライアントにログインするエンドポイントをKeycloakサーバーに設定できるようにする機能です。クライアントの Settings タブで、 IDP Initiated SSO URL Name を指定する必要があります。これは空白を含まない単純な文字列です。その後、 root/auth/realms/{realm}/protocol/saml/clients/{url-name} のURLでクライアントを参照することができます。

クライアントが特別なリレーステートを必要とする場合は、 IDP Initiated SSO Relay State フィールドの Settings タブでこれを設定することもできます。あるいはブラウザーは RelayState クエリー・パラメーター root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate でリレーステートを指定することができます。

アイデンティティー・ブローカリングを使用する場合、クライアントに対して外部IDPからのIDP Initiated ログインを設定することができます。実際のクライアントは、上記のようにブローカーIDPでIDP Initiated ログインするように設定されます。外部IDPはクライアントを、特別なURLを指し示す、アプリケーションIDP Initiated ログインのためにセットアップする必要があります。URLはブローカーを指し、ブローカリングIDPで選択されたクライアントのために、IDP Initiated ログイン・エンドポイントを代理します。つまり、外部IDPのクライアント設定では次のようになります。

IDP Initiated SSO URL Name は、IDP Initiated ログインのイニシャル・ポイントとして公開される名前に設定されます。
Fine Grain SAML Endpoint Configuration 欄の Assertion Consumer Service POST Binding URL は broker-root/auth/realms/{broker-realm}/broker/{idp-name}/endpoint/clients/{client-id} のURLで設定する必要があります。URLの詳細は次のとおりです。
- broker-root はベースブローカーURLです。
- broker-realm は外部IDPが宣言されているブローカーのレルムの名前です。
- idp-name はブローカーでの外部IDPの名前です。
- client-id は、ブローカーで定義されたSAMLクライアントの IDP Initiated SSO URL Name 属性の値です。このクライアントは、外部IDPからのIDP Initiated ログインに対して利用可能になります。

基本的なクライアント設定をブローカリングIDPから外部IDPのクライアント設定にインポートすることができます。ブローカリングIDPのアイデンティティー・プロバイダーの設定から利用可能なSP 記述子を使用し、 clients/client-id をエンドポイントURLに追加します。

8.3.2. SAMLエンティティ記述子

手動でSAML 2.0クライアントを登録する代わりに、標準のSAMLエンティティー記述子XMLファイルを使用してインポートできます。Add Clientページには Import オプションがあります。

Add Client

add client saml

Select File ボタンをクリックし、エンティティー記述子ファイルを読み込みます。そこにあるすべての情報を見直して、すべてが正しく設定されていることを確認してください。

mod-auth-mellon のような一部のSAMLクライアント・アダプターでは、IDPのXMLエンティティー記述子が必要です。公開URL root/auth/realms/{realm}/protocol/saml/descriptor にアクセスすれば、これを取得することができます。

8.4. クライアントのリンク

あるクライアントから別のクライアントにリンクしたい場合のために、Keycloakは特別なリダイレクト・エンドポイント /realms/realm_name/clients/{client-id}/redirect を提供します。

クライアントが HTTP GET リクエストを介してこのエンドポイントにアクセスすると、Keycloakはレスポンスの Location ヘッダを介して HTTP 307 （テンポラリー・リダイレクト）形式で、指定されたクライアントとレルムの設定済みのベースURLを返します。

したがって、クライアントは、それらにリンクするために、レルム名とクライアントIDだけを知る必要があります。この間接参照は、クライアントのベースURLのハード・コーディングを避けるのに役立ちます。

一例として、レルムの master とクライアントIDの account が指定されているとします。

http://host:port/auth/realms/master/clients/account/redirect

一時的に http://host:port/auth/realms/master/account にリダイレクトします。

8.5. OIDCトークンとSAMLアサーションのマッピング

IDトークン、アクセストークン、またはSAMLアサーションを受け取るアプリケーションでは、異なるユーザーのメタデータとロールが必要または求める場合があります。Keycloakでは、正確に何が転送されるかを定義することができます。ロール、クレーム、カスタム属性をハードコードすることができます。ユーザー・メタデータをトークンまたはアサーションに取り込むことができます。ロールの名前を変更できます。基本的に、正確に何がクライアントに戻るのかをコントロールできます。

管理コンソール内で、登録したアプリケーションに移動すると Mappers タブが表示されます。ここには、OIDCベースのクライアントの一例があります。

Mappersタブ

mappers oidc

各クライアントには、そのためにデフォルトで作成されたいくつかのビルトイン・マッパーがあります。それらのマッパーは、たとえば、メールアドレスをアイデンティティー・トークンとアクセストークンの特定のクレームにマッピングします。それらの機能はそれぞれの名前から自明でなければなりません。クライアントにアタッチされていない追加の事前設定されたマッパーがあり、 Add Builtin ボタンをクリックすることで追加できます。

各マッパーには、追加するマッパーのタイプに応じて、共通の設定と追加の設定があります。リスト内のマッパーの1つを選択し、横にある Edit ボタンをクリックして、設定画面を表示します。

マッパーの設定

mapper config

設定オプションについて学ぶ最も良い方法は、ツールチップにカーソルを合わせることです。すべてのマッパーに共通の設定オプションがいくつかあります。

Consent Required: クライアントが同意する必要がある場合、このマッパーがユーザーに表示される同意画面に表示されます。
Consent Text: クライアントが同意を必要とし、 Consent Required スイッチがオンの場合、このテキストがユーザーに表示されます。このテキストの値は、 ${var-name} 文字列で置換変数を指定することによってローカライズ可能です。ローカライズされた値は、テーマのプロパティー・ファイル内で設定されます。ローカリゼーションの詳細については、Server Developer Guideを参照してください。

ほとんどのOIDCマッパーでは、クレームがどこに置かれるかを制御することもできます。 Add to ID token と Add to access token のスイッチを切り替えることで、 id トークンと access トークンの両方にクレームを含めるかどうかを制御することができます。

最後に、他のマッパータイプを追加することもできます。 Mappers タブに戻ったら、 Create ボタンをクリックします。

マッパーの追加

add mapper

リストボックスから Mapper Type を選びます。ツールチップにカーソルを合わせると、そのマッパータイプが何をするのかの説明が表示されます。さまざまなマッパータイプに対して異なる設定パラメーターが表示されます。

8.6. クライアント・アダプター設定の生成

Keycloakは、アプリケーションの配備環境にクライアント・アダプターをインストールするために使用できる設定ファイルを事前に生成することができます。OIDCとSAMLの両方で、いくつかのアダプタータイプがサポートされています。設定を生成したいクライアントの Installation タブに移動します。

client installation

設定が生成されるようにする Format Option を選択してください。OIDCとSAMLのすべてのKeycloakクライアント・アダプターがサポートされています。SAML用のmod-auth-mellon Apache HTTPDアダプターは、標準のSAMLエンティティ記述子ファイルと同様にサポートされています。

8.7. クライアント・テンプレート

組織内にセキュリティを確保して登録する必要があるアプリケーションが多数存在する場合、これらのクライアントごとにプロトコル・マッパーやスコープを設定するのは非常に面倒です。Keycloakを使用すると、 クライアント・テンプレート というエンティティで共通クライアント設定を定義できます。

クライアント・テンプレートを作成するには、左側メニューの Client Templates を表示します。この初期画面には、現在定義されているテンプレートのリストが表示されます。

テンプレートを作成するには、 Create ボタンをクリックします。テンプレートに名前を付けて保存する簡単な画面が表示されます。 クライアント・テンプレート は、通常のクライアントと同様のタブを持ちます。他のクライアントが継承できるプロトコル・マッパー、スコープを定義することができます。

クライアントをテンプレートから継承させるのは簡単で、 Add Client またはクライアントの Settings タブのどちらかの Client Template ドロップダウン・リストからテンプレートを選ぶだけです。 Mappers と Scope タブには、親テンプレートを継承するかどうかを設定するON/OFFのスイッチがあります。

クライアント・テンプレートの将来のバージョンでは、継承可能な設定オプションが増えるかもしれません。現在のところでは、先に述べた設定オプションのみとなっています。

9. ロール

ロールは、ユーザーのタイプまたはカテゴリを識別します。 Admin 、 user 、 manager 、 employee はすべて、組織内に存在する典型的なロールです。個々のユーザーを扱うことはきめ細かく管理が難しいため、アプリケーションは多くの場合、特定のロールにアクセスと権限を割り当てます。たとえば、管理コンソールには、管理コンソールUIの一部にアクセスして特定の操作を実行する権限をユーザーに与える特定のロールがあります。ロールにはグローバルな名前空間があり、各クライアントにも、ロールを定義できる専用の名前空間があります。

9.1. レルムロール

レルムレベルのロールは、ロールを定義するグローバルな名前空間です。左のメニュー項目の Roles をクリックすると、組み込みのロールと作成されたロールのリストが表示されます。

roles

ロールを作成するには、このページの Add Role をクリックし、ロールの名前と説明を入力して、 Save をクリックします。

ロールの追加

role

description フィールドの値は、置換変数を ${var-name} 文字列で指定することによってローカライズ可能です。ローカライズされた値は、テーマのプロパティー・ファイル内で設定します。ローカライズの詳細については、Server Developer Guideのリンクを参照してください。クライアントがユーザーの同意を必要とする場合、このdescription文字列はユーザーの同意ページに表示されます。

クライアントがレルムロールを明示的に要求しなければならない場合は、 Scope Param Required をtrueに設定します。そうすると、トークンを要求するときに scope パラメーターを使用してロールを指定する必要があります。複数のレルムロールは、スペースで区切られます。

scope=admin user

9.2. クライアントロール

クライアントロールは、基本的にクライアント専用の名前空間です。各クライアントは独自の名前空間を取得します。クライアントロールは、個々のクライアントの Roles タブで管理されます。レルムレベルのロールと同じ方法で、このUIとやりとりします。

クライアントが別のクライアントのロールを明示的に要求しなければならない場合は、scopeパラメーターを使用して要求を実行するときに、ロールにクライアントIDの接頭辞を付ける必要があります。たとえば、クライアントIDが account でロールが admin の場合、scopeパラメーターは次のようになります。

scope=account/admin

レルムロールの節で説明したように、複数のロールはスペースで区切られます。

9.3. 複合ロール

すべてのレルムレベルまたはクライアントレベルのロールは、 複合ロール にすることができます。 複合ロール は、関連する1つ以上の追加ロールを持つロールです。複合ロールがユーザーにマップされると、ユーザーはその複合ロールに関連付けられたロールも取得します。この継承は再帰的なので、複合ロールの複合ロールも継承されます。

通常のロールを複合ロールにするには、ロールの詳細ページに移動し Composite Role スイッチをオンにします。

複合ロール

composite role

このスイッチをオンにすると、ロール選択UIがページの下側に表示され、作成する複合ロールにレルムレベルとクライアントレベルのロールを関連付けることができます。この例では、 employee レルムレベルのロールが developer 複合ロールに関連付けられています。 developer ロールを持つユーザーは ` employee` ロールも継承します。

トークンやSAMLアサーションが作成される際に、複合ロールに関連するロールが認証レスポンスのクレームやトークンに追加され、クライアントに返されます。

9.4. ユーザー・ロール・マッピング

ユーザ・ロール・マッピングは、各ユーザーの Role Mappings タブを介して個別に割り当てることができます。

ロールマッピング

user role mappings

上の例では、複合ロールの章で作成した複合ロール developer を割り当てようとしています。

有効なロールマッピング

effective role mappings

developer ロールが割り当てられると、 developer のコンポジットに関連付けられた employee ロールが Effective Roles に現れます。 Effective Roles は、ユーザーに明示的に割り当てられたすべてのロールと、コンポジットから継承されたロールです。

9.4.1. デフォルトロール

デフォルトロールを使用すると、アイデンティティー・ブローカリングを使用してユーザーを新規作成またはインポートしたときに、ユーザー・ロール・マッピングを自動的に割り当てることができます。デフォルトロールを指定するには、左側のメニュー項目 Roles に移動し、 Default Roles タブをクリックします。

デフォルトロール

default roles

スクリーンショットから分かるように、デフォルトでは多くの デフォルトロール が既に設定されています。

9.5. クライアント・スコープ

OIDCアクセストークンまたはSAMLアサーションが作成されると、ユーザーのすべてのユーザー・ロール・マッピングは、デフォルトでトークンまたはアサーション内にクレームとして追加されます。アプリケーションは、この情報を使用して、そのアプリケーションによって制御されるリソースのアクセスを決定します。Keycloakでは、アクセストークンはデジタル署名されており、実際にアプリケーションによって再利用され、他のリモートで保護されたRESTサービスを呼び出すことができます。これは、アプリケーションが危険にさらされたり、レルムに登録された不正なクライアントが存在する場合、攻撃者が広範囲のパーミッションを持つアクセストークンを取得し、ネットワーク全体が侵害されることを意味します。これは、 クライアント・スコープ が重要になる場面です。

クライアント・スコープ は、アクセストークン内で宣言されるロールを制限する方法です。クライアントがユーザーの認証を要求すると、受け取ったアクセストークンには、クライアントのスコープに対して明示的に指定したロールマッピングのみが含まれます。これにより、ユーザーの全パーミッションへのアクセスをクライアントに与えるのではなく、個々のアクセストークンのパーミッションを制限することができます。デフォルトでは、各クライアントはユーザーのすべてのロールマッピングを取得します。各クライアントの Scope タブでこれを見ることができます。

フルスコープ

full client scope

この図から、スコープの有効なロールは、レルム内のすべての宣言されたロールであることが分かります。このデフォルト動作を変更するには、 Full Scope Allowed スイッチを明示的にオフにして、個々のクライアントで必要な特定のロールを宣言する必要があります。また、クライアント・テンプレートを使用して、クライアント全体のスコープを定義することもできます。

部分的なスコープ

client scope

10. Groups

Keycloakのグループは、ユーザーのセットに対する共通の属性とロールマッピングを管理できます。ユーザーは0個以上のグループのメンバーになることができます。ユーザーは、各グループに割り当てられた属性とロールマッピングを継承します。グループを管理するには、左のメニュー項目の Groups に移動します。

Groups

groups

グループは階層的です。グループには複数のサブグループが存在できますが、グループには1つの親しか持てません。サブグループは、親から属性とロールマッピングを継承します。これはユーザーにも当てはまります。したがって、親グループと子グループ、および子グループのみに属するユーザーがいる場合、ユーザーは親と子の両方の属性とロールマッピングを継承します。この例では、トップレベルの Sales グループと子の North America サブグループがあります。グループを追加するには、新しい子を追加したい親をクリックし、 New ボタンをクリックします。ツリー内の Groups アイコンを選択して、トップレベルのグループを作成します。 Create Group 画面にグループ名を入力して Save をクリックすると、個々のグループ管理ページが表示されます。

グループ

group

Attributes と Role Mappings のタブは、ユーザーの下にある同様の名前のタブと同じように機能します。定義した属性およびロールマッピングは、このグループのメンバーであるグループおよびユーザーによって継承されます。

グループにユーザーを追加するには、ユーザーの詳細ページに戻って Groups タブをクリックする必要があります。

ユーザーグループ

user groups

Available Groups ツリーからグループを選択し、 join ボタンをクリックしてグループにユーザーを追加します。グループを削除するにはその逆になります。ここでは North America のセールスグループにユーザー Jim を追加しました。そのグループの詳細ページに戻って Membership タブを選択すると、そこに Jim が表示されます。

グループ・メンバーシップ

group membership

10.1. グループ VS ロール

ITの世界では、グループとロールの概念はしばしば曖昧になり、互換性があります。 Keycloakでは、グループはロールと属性を1か所に適用できるユーザーのコレクションです。ロールはユーザーのタイプを定義し、アプリケーションはロールにパーミッションとアクセス制御を割り当てます。

複合ロールもグループに似ているでしょうか？論理的には同等の機能を提供しますが、概念的である点が異なります。複合ロールは、サービスとアプリケーションのセットにパーミッション・モデルを適用するために使用されるべきです。グループは、組織内のユーザーとロールのコレクションに焦点を当てるべきです。グループは、ユーザーを管理するために使用します。複合ロールは、アプリケーションとサービスを管理するために使用します。

10.2. デフォルト・グループ

デフォルト・グループを使用すると、新しいユーザーがアイデンティティー・ブローカリングによって作成またはインポートされるたびに、自動的にグループ・メンバーシップを割り当てることができます。デフォルト・グループを指定するには、左メニュー項目の Groups へ移動し、 Default Groups タブをクリックしてください。

デフォルト・グループ

default groups

11. 管理コンソールのアクセス・コントロールと権限

Keycloakで作成された各レルムには、そのレルムを管理できる専用の管理コンソールがあります。 master レルムは、管理者がシステム上で複数のレルムを管理できる特別なレルムです。また、異なるレルム内のユーザーに対するきめ細かいアクセスを定義して、サーバーを管理することもできます。この章では、このシナリオのすべてについて説明します。

11.1. Masterレルムのアクセス・コントロール

Keycloakの master レルムは特別なレルムであり、他のレルムとは異なる扱い方をされます。Keycloakの master レルムのユーザーには、Keycloakサーバーにデプロイされている0個以上のレルムを管理する権限を与えることができます。レルムが作成されると、Keycloakは新しいレルムにアクセスするためのきめ細かい権限を与えるさまざまなロールを自動的に作成します。これらのロールを master レルムのユーザーにマッピングすることで、管理コンソールおよび管理RESTエンドポイントへのアクセスを制御できます。特定のレルムだけを管理できるユーザーだけでなく、複数のスーパーユーザーを作成することも可能です。

11.1.1. グローバルロール

master レルムには次の2つのレルムレベルのロールがあります。

admin
create-realm

admin ロールを持つユーザーはスーパーユーザーであり、サーバー上のあらゆるレルムを管理する完全なアクセス権を持っています。 create-realm ロールを持つユーザーは、新しいレルムを作成することができます。このユーザーは、自身が作成した全ての新しいレルムに対して、完全にアクセスできるようになります。

11.1.2. レルム特有のロール

master レルム内の管理ユーザーは、システム内の1つ以上の他のレルムに対して管理権限を与えることができます。Keycloakの各レルムは、 master レルムのクライアントによって表されます。クライアントの名前は <realm name>-realm です。これらのクライアントには、個々のレルムを管理するためのさまざまなアクセスのレベルを定義したクライアントレベルのロールが定義されています。

利用可能なロールは次のとおりです。

view-realm
view-users
view-clients
view-events
manage-realm
manage-users
create-client
manage-clients
manage-events
view-identity-providers
manage-identity-providers
impersonation

ユーザーに必要なロールを割り当てると、管理コンソールの特定の部分のみを使用できます。

manage-users ロールを持つ管理者は、自分自身が管理するユーザーにのみ管理ロールを割り当てることができます。したがって、 manage-users ロールを持っていても、 manage-realm ロールを持っていない管理者は、このロールを割り当てることはできません。

11.2. レルム専用の管理コンソール

各レルムには専用の管理コンソールがあり、 /auth/admin/{realm-name}/console のURLでアクセスできます。特定のユーザー・ロール・マッピングを割り当てることによって、そのレルム内のユーザーにレルム管理権限を与えることができます。

各レルムには、 realm-management という名前のビルトイン・クライアントがあります。レルムの左メニュー項目の Clients をクリックすることでこのクライアントを見ることができます。このクライアントは、レルムを管理する権限を指定するクライアント・レベルのロールを定義します。

view-realm
view-users
view-clients
view-events
manage-realm
manage-users
create-client
manage-clients
manage-events
view-identity-providers
manage-identity-providers
impersonation

ユーザーに必要なロールを割り当てると、管理コンソールの特定の部分のみを使用できます。

11.3. きめ細かい管理権限

時には manage-realm や manage-users のようなロールより、きめ細かい権限を持つ制限付き管理者アカウントを作成したいことがあります。Keycloakでは、レルムを管理するための制限付きアクセスポリシーを定義して割り当てることができます。アクセスポリシーには次のようなものがあります。

特定のクライアントの管理
特定のグループに属するユーザーの管理
グループのメンバーシップの管理
制限付きのユーザー管理
きめ細かい代理ログイン制御
特定の制約付きロールセットをユーザーに割り当てる
特定の制約付きロールセットを複合ロールに割り当てる
特定の制約付きロールセットをクライアントのスコープに割り当てる
ユーザー、グループ、ロール、およびクライアントの表示と管理のための新しい一般ポリシー

きめ細かい管理権限について、いくつか注意すべき点があります。

きめ細かい管理権限は、認可サービス上に実装されています。きめ細かい権限を設定する前に、それらの機能を読んでおくことを強くお勧めします。
きめ細かい権限は、専用の管理コンソールおよびレルム管理者のみ使用できます。レルム間のきめ細かい権限は、定義することはできません。
きめ細かい権限は、追加の権限を付与するために使用されます。組み込みの管理者ロールのデフォルトの動作を上書きすることはできません。

11.3.1. 特定のクライアントの管理

最初に、管理者が1つのクライアントだけを管理できるようにしましょう。この例では、 test というレルムと sales-application というクライアントがあります。レルム test では、レルムのユーザーに、そのアプリケーションだけを管理する権限を与えます。

きめ細かい権限はレルム間で使用することはできません。 master レルムの管理者は、前の章で定義されている組み込みの管理者ロールに限定されています。

権限設定

最初に、管理コンソールにログインして、クライアントの権限を設定する必要があります。きめ細かい権限を定義するクライアントの管理画面に移動します。

クライアント管理

fine grain client

Permissions というタブメニュー項目が表示されるので、そのタブをクリックします。

クライアント権限タブ

fine grain client permissions tab off

デフォルトでは、各クライアントはきめ細かい権限が有効になっていません。 Permissions Enabled スイッチをONにして権限を初期化してください。

Permissions Enabled スイッチをOFFにすると、このクライアントに対して定義したすべての権限が削除されます。

クライアント権限タブ

fine grain client permissions tab on

Permissions Enabled をONにすると、認可サービスを使用してさまざまな権限オブジェクトを初期化します。ここでは、クライアントの manage 権限を例にします。 manage 権限リンクをクリックすると、クライアントの権限設定画面にリダイレクトされます。すべての認可オブジェクトは、 realm-management クライアントの Authorization タブに含まれています。

クライアント管理権限

fine grain client manage permissions

最初に初期化されたとき、 manage 権限は関連付けられたポリシーを持ちません。ポリシータブに移動して作成する必要があります。ポリシータブにアクセスするには、上記の画像に表示されている Authorization リンクをクリックしてください。次に、Policiesタブをクリックします。

このページには、 Create policy というプルダウン・メニューがあります。このメニューには、定義することができる多くのポリシーがあります。ロールまたはグループに関連付けられたポリシーを定義したり、Javascriptでルールを定義することもできます。この例では、 User Policy を作成します。

ユーザーポリシー

fine grain client user policy

このポリシーは、ユーザー・データベース内のハードコードされたユーザーと一致させます。この例では、 sales-admin ユーザーです。次に、 sales-application クライアントの manage 権限ページに戻り、ポリシーを権限オブジェクトに割り当てる必要があります。

ユーザーポリシーの割り当て

fine grain client assign user policy

sales-admin ユーザーは、 sales-application クライアントを管理する権限を持つことができます。

また、Role Mappings タブから、 sales-admin に query-clients ロールを割り当てる必要があります。

query-clientsの割り当て

fine grain assign query clients

query-clients ロールを割り当てる理由として、このロールは、 sales-admin が管理コンソールを訪れたときに表示するメニュー項目を管理コンソールに伝えるためです。 query-clients ロールは、管理コンソールに sales-admin ユーザー用の表示すべきクライアント・メニューを伝えます。

重要な点として、 query-clients ロールを設定しないと、 sales-admin のような制限付きの管理者は、管理コンソールにログインするときにメニューオプションが表示されません。

テストする

次に、masterレルムからログアウトし、 sales-admin ユーザーで test レルムの[_per_realm_admin_permissions、専用の管理コンソール]に再ログインします。専用の管理コンソールは /auth/admin/test/console にあります。

Sales Adminのログイン

fine grain sales admin login

この管理者はこの1つのクライアントを管理できるようになりました。

11.3.2. ユーザー・ロール・マッピングの制限

もう一つは、管理者がユーザーへの割り当てを許可したロールを制限することです。最後の例に続けて、 sales-admin ユーザーの権限セットを拡張して、このアプリケーションにアクセスできるユーザーを制御できるようにしましょう。きめ細かい権限を使用して、 sales-admin が sales-application に特定のアクセスを許可するロールのみを割り当てることができます。また、管理者だけがロールを割り当てることができ、その他のユーザー管理は実行できないように制限することもできます。

sales-application には3つの異なるクライアント・ロールを定義しています。

Sales Applicationロール

fine grain sales application roles

sales-admin ユーザーが、これらのロールをシステム内のどのユーザーにも割り当てられるようにしたいです。これを行うための最初のステップは、管理者によってロールを割り当て可能とすることです。 viewLeads ロールをクリックすると、このロールの Permissions タブがあります。

View LeadsロールのPermissionタブ

fine grain view leads role tab

そのタブをクリックし、 Permissions Enabled をONにすると、ポリシーを適用できるアクションが表示されます。

View Leads権限

fine grain view leads permissions

ここで知りたいのは map-role です。この権限をクリックし、前の例で作成したユーザーポリシーを追加します。

Map-rolesの権限

fine grain map roles permission

これまでに行ったことは、 sales-admin が viewLeads ロールを割り当て可能とすることです。これから行うことは、管理者がこのロールをどのように割り当てることができるかを指定することです。これを行うには、このレルムの管理コンソールの Users セクションに移動する必要があります。左のメニュー項目の Users をクリックすると、レルムのユーザー・インターフェイスが表示されます。 Permissions タブから、 Permissions Enabled をクリックして有効にします。

ユーザーの権限

fine grain users permissions

ここで知りたい権限は map-roles です。これは、管理者がロールをユーザーに割り当てる機能のみを許可するという点で、制限的なポリシーです。 map-roles 権限をクリックし、これに対して作成したユーザーポリシーを再度追加すると、 sales-admin はロールを任意のユーザーに割り当てることができます。

最後に、 view-users ロールを sales-admin に追加します。これにより、管理者は sales-application ロールを追加したいレルムのユーザーを表示することができます。

view-usersの追加

fine grain add view users

テストする

sales-admin がシステム内のユーザーを表示することができるようになりました。いずれかのユーザーを選択すると、 Role Mappings タブを除き、各ユーザーの詳細ページは読み取り専用になります。これらのタブでは、管理者が sales-application ロールを表示する場合を除いて、ユーザーに割り当てるための 利用可能な ロールがないことがわかります。

viewLeadsの追加

fine grain add view leads

sales-admin が viewLeads ロールの割り当てができることを指定しました。

クライアントごとのmap-rolesへのショートカット

sales-application が公開したすべてのクライアント・ロールに対して、これを実行しなければならないのは面倒です。作業を簡単にするために、管理者がクライアントによって定義された任意のロールを割り当てられるように指定する方法があります。管理コンソールにログインしてmasterレルムの管理者でログインし、 sales-application 権限ページに戻ると、 map-roles 権限が表示されます。

クライアントのmap-roles権限

fine grain client permissions tab on

この特定の権限へのアクセスを管理者に許可すると、その管理者はクライアントによって定義されたすべてのロールを割り当てることができます。

11.3.3. 権限一覧

特定のクライアントやクライアントの特定のロールを管理する以外にも、きめ細かい権限を使用すると、さらに多くのことを行うことができます。この章では、レルムで記述できる権限種別の一覧を示します。

ロール

特定のロールの Permissions タブでは、これらの権限種別が一覧で表示されます。

map-role: 管理者がロールをユーザーに割り当て可能であるかを決定するポリシーです。これらのポリシーでは、管理者がユーザーにロールを割り当てることができるのではなく、ロールをユーザーに割り当てることができます。また、管理者は管理またはロールの割り当ての権限を持っている必要があります。詳細については、ユーザーの権限を参照してください。
map-role-composite: 管理者がこのロールを複合ロールとして別のロールに割り当て可能であるかを決定するポリシーです。管理者はクライアントのロールを定義することができますが、そのクライアントの権限を管理していても、複合ロールとして追加したいロールに対して map-role-composite 権限を持っていなければ、それらのロールに複合ロールを追加することはできません。
map-role-client-scope: 管理者がこのロールをクライアントのスコープに適用可能であるかを決定するポリシーです。管理者がクライアントを管理できるとしても、この権限が与えられていない限り、このロールを含むクライアントのトークンを作成する権限はありません。

クライアント

特定のクライアントの Permissions タブで、これらの権限種別が表示されます。

view: 管理者がクライアントの設定を表示可能であるかを決定するポリシーです。
manage: 管理者がクライアントの設定を表示および管理することが可能であるかを決定するポリシーです。特権が意図せず漏れる可能性があるという点で、いくつかの問題があります。たとえば、管理者は、ロールをクライアントのスコープに割り当てる権限を持っていなくても、ロールをハードコーディングしたプロトコル・マッパーを定義することができます。プロトコル・マッパーには、ロールのように個々の権限を割り当てる方法がありません。これは現在のプロトコル・マッパーの制約です。
configure: クライアントを管理する特権セットを除外したポリシーです。プロトコル・マッパーの定義、クライアント・テンプレートの変更、クライアントのスコープの変更が許可されてないこと以外は manage スコープと似ています。
map-roles: 管理者がクライアントによって定義されたロールをユーザーに割り当て可能であるかを決定するポリシーです。ショートカットで使いやすい機能となっていて、クライアントが定義したすべてのロールごとにポリシーを設定する必要がありません。
map-roles-composite: 管理者がクライアントによって定義されたロールを複合ロールとして別のロールに割り当て可能であるかを決定するポリシーです。ショートカットで使いやすい機能となっていて、クライアントが定義したすべてのロールごとにポリシーを定義する必要がありません。
map-roles-client-scope: 管理者がクライアントによって定義されたロールを別のクライアントのスコープに割り当て可能であるかを決定するポリシーです。ショートカットで使いやすい機能となっていて、クライアントが定義したすべてのロールごとにポリシーを定義する必要がありません。

Users

ユーザーの Permissions タブでは、これらの権限種別が表示されます。

view: 管理者がレルム内のすべてのユーザーを表示可能であるかを決定するポリシーです。
manage: 管理者がレルム内のすべてのユーザーを管理することが可能であるかを決定するポリシーです。この権限は、管理者にユーザー・ロール・マッピングの権限を付与しますが、割り当てるロールは指定しません。管理者が割り当て可能とする各ロールの権限を定義する必要があります。
map-roles: これは、 manage スコープによって与えられた権限のサブセットです。管理者はロールのみを割り当てることができますが、他のユーザーの管理操作を実行することはできません。また、 manage と同様に、管理者が適用できるロールは、クライアント・ロールを扱う場合、ロールごとまたはロールセットごとに指定する必要があります。
manage-group-membership: map-roles に似ていますが、これはユーザーを追加または削除できるグループのグループ・メンバーシップに付属します。これらのポリシーは、管理者がメンバーシップの管理を許可されているグループではなく、グループ・メンバーシップを管理するための管理者権限を許可します。グループの manage-members 権限ごとにポリシーを指定する必要があります。
impersonate: 管理者が他のユーザーの代理ログインを許可するかを決定するポリシーです。これらのポリシーは、管理者の属性とロール・マッピングに適用されます。
user-impersonated: どのユーザーが代理ログインの対象となるかを決定するポリシーです。これらのポリシーは、代理ログインされるユーザーに適用されます。たとえば、管理者特権を持つユーザーとして代理ログインすることを禁止するポリシーを定義することができます。

グループ

特定のグループの Permissions タブでは、これらの権限種別が表示されます。

view: 管理者がグループに関する情報を表示可能であるかを決定するポリシーです。
manage: 管理者がグループの設定を管理することが可能であるかを決定するポリシーです。
view-members: 管理者がグループメンバーのユーザー詳細を表示可能であるかを決定するポリシーです。
manage-members: 管理者がこのグループに属するユーザーを管理することが可能であるかを決定するポリシーです。
manage-membership: 管理者がグループのメンバーシップを変更することが可能であるかを決定するポリシーです。グループにメンバーを追加または削除することができます。

11.4. レルム鍵

Keycloakで使用される認証プロトコルには、暗号署名と暗号化が必要な場合があります。 Keycloakは、これに対応するために秘密鍵と公開鍵の鍵ペアを使用します。

Keycloakには一度に1つのアクティブな鍵ペアを持ちますが、複数のパッシブな鍵も持つことができます。アクティブな鍵ペアを使用して新しい署名を作成し、パッシブな鍵ペアを使用して以前の署名を検証することができます。これにより、ダウンタイムやユーザーの中断を招くことなく、鍵を定期的にローテーションさせることができます。

レルムが作成されると、鍵ペアと自己署名証明書が自動的に生成されます。

レルムのアクティブな鍵を表示するには、管理コンソールでレルムを選択し、 Realm settings から Keys をクリックします。これにより、レルムの現在有効な鍵が表示されます。Keycloakは現在、RSA署名のみをサポートしているので、アクティブな鍵ペアは1つのみです。将来、署名アルゴリズムが追加された場合、アクティブな鍵ペアが増えることになります。

使用可能なすべてのキーを表示するには、 All を選択します。これにより、アクティブ、パッシブ、無効のすべての鍵が表示されます。鍵ペアのステータスは Active ですが、レルムの現在のアクティブな鍵ペアとしてはまだ選択されません。署名のために使用されるアクティブな鍵ペアは、優先度によってソートされた最初の鍵プロバイダーが選択されます。

11.4.1. 鍵のローテーション

鍵を定期的にローテーションさせることをお勧めします。ローテーションを行うには、既存のアクティブな鍵よりも優先度の高い新しい鍵を作成することから始めます。または、同じ優先度で新しい鍵を作成し、以前の鍵をパッシブにします。

新しい鍵が利用可能になると、新しいトークンとCookieはすべて新しい鍵で署名されます。ユーザーがアプリケーションを認証すると、SSO Cookieは新しい署名で更新されます。OpenID Connectトークンをリフレッシュすると、新しいトークンが新しい鍵で署名されます。つまり、すべてのトークンとCookieが新しい鍵を使用するようになるため、しばらく経つと古い鍵を削除することができます。

古い鍵を削除するのにどれくらいかかるのかは、セキュリティと、すべてのCookieとトークンが確実に更新される時間とのトレードオフです。一般的には、数週間後に古い鍵を削除することが可能となるべきでしょう。追加された新しい鍵と古い鍵が削除されるまでの間にアクティブでなかったユーザーは、再認証する必要があります。

これは、オフライン・トークンにも適用されます。トークンが更新されていることを確認するには、古い鍵が削除される前にアプリケーションでトークンをリフレッシュする必要があります。

ガイドラインとして、3～6か月ごとに新しい鍵を作成し、新しい鍵が作成されてから1～2か月後に古い鍵を削除することをお勧めします。

11.4.2. 鍵ペアの追加

新しい鍵ペアを追加するには、 Providers を選択し、ドロップダウンから rsa-generated を選択します。優先順位を変更して、新しい鍵ペアがアクティブな鍵ペアになるようにすることができます。より小さい、またはより大きい鍵を必要とする場合、 鍵のサイズ を変更することもできます（デフォルトは2048、サポートされている値は1024、2048、および4096）。

新しい鍵を追加するには Save をクリックしてください。これにより、自己署名証明書を含む新しい鍵ペアが生成されます。

プロバイダーの優先順位を変更しても鍵は再生成されませんが、鍵のサイズを変更したい場合は、プロバイダーを編集して新しい鍵を生成することができます。

11.4.3. 既存の鍵ペアと証明書の追加

他で取得した鍵ペアと証明書を追加するには、 Providers を選択し、ドロップダウンから rsa を選択します。優先順位を変更することで、新しい鍵ペアをアクティブな鍵ペアにすることができます。

秘密鍵をアップロードするには、 Private RSA Key の Select file をクリックしてください。ファイルはPEM形式でエンコードする必要があります。公開鍵は、秘密鍵から自動的に抽出されるため、アップロードする必要はありません。

鍵の署名付き証明書を持っている場合、 X509 Certificate の横の Select file をクリックしてください。持っていない場合は、これをスキップすることができ、自己署名証明書が生成されます。

11.4.4. Javaキーストアから鍵をロードする

ホスト上のJavaキーストアファイルに格納されている鍵ペアと証明書を追加するには、 Providers を選択し、ドロップダウンから java-keystore を選択します。優先順位を変更して、新しい鍵ペアをアクティブすることができます。

Keystore 、 Keystore Password 、 Key Alias 、 Key Password の値を入力し、 Save をクリックします。

11.4.5. 鍵をパッシブにする

Active または All で鍵ペアを見つけて、 Provider 列のプロバイダーをクリックします。これにより、鍵のプロバイダーの設定画面が表示されます。 Active のスイッチをクリックして OFF にし、 Save をクリックします。鍵はアクティブでなくなり、署名の検証にのみ使用できます。

11.4.6. 鍵の無効化

Active または All で鍵ペアを見つけて、 Provider 列のプロバイダーをクリックします。これにより、鍵のプロバイダーの設定画面が表示されます。 Enabled のスイッチをクリックして OFF にし、 Save をクリックします。鍵は無効化されます。

また、 Providers テーブルからプロバイダーを削除することもできます。

11.4.7. 鍵の漏洩

Keycloakでは署名鍵がローカルに格納されており、クライアント・アプリケーション、ユーザーまたは他のエンティティと共有されることはありません。しかし、レルムの署名鍵が漏洩したと思われる場合は、先に説明したように新しい鍵ペアを生成してから、即座に漏洩した鍵ペアを削除する必要があります。

次に、クライアント・アプリケーションが漏洩した鍵で署名されたトークンを受け入れないようにするためには、管理コンソールから実行可能なレルムのnot-beforeポリシーを更新して適用する必要があります。新しいポリシーを適用すると、クライアント・アプリケーションは、漏洩した鍵で署名された既存のトークンを受け入れなくなり、クライアント・アプリケーションはKeycloakから新しい鍵ペアをダウンロードすることになります。したがって、漏洩した鍵で署名されたトークンは有効でなくなります。RESTとコンフィデンシャル・クライアントは Admin URL を設定する必要があるので、Keycloakは適用されたnot-beforeポリシーに関するリクエストを送ることができます。

12. アイデンティティー・ブローカリング

アイデンティティー・ブローカーは、複数のサービス・プロバイダーを異なるアイデンティティー・プロバイダーに接続する仲介サービスです。仲介サービスとして、アイデンティティー・ブローカーは、サービス・プロバイダーによって公開される内部サービスへのアクセスでアイデンティティーを使用するために、外部アイデンティティー・プロバイダーとの信頼関係を作成する責任があります。

ユーザーの観点から、アイデンティティー・ブローカーは、異なるセキュリティ・ドメインまたはレルム間のアイデンティティーを管理するための、ユーザー中心かつ一元的な方法を提供します。既存のアカウントは、異なるアイデンティティー・プロバイダーの1つ以上のアイデンティティーとリンクすることも、それらから取得したアイデンティティー情報に基づいて作成することもできます。

アイデンティティー・プロバイダーは、通常、認証して、ユーザーに認証と認可の情報を伝えるために使用される特定のプロトコルに基づいています。Facebook、Google、Twitterなどのソーシャル・プロバイダーや、サービスにアクセスする必要のあるユーザーの属するビジネス・パートナー、または統合したいクラウドベースのアイデンティティー・サービスにすることもできます。

通常、アイデンティティー・プロバイダーは次のプロトコルに基づいて実装されています。

SAML v2.0
OpenID Connect v1.0
OAuth v2.0

次のセクションでは、Keycloakをアイデンティティー・ブローカーとして設定および使用する方法を説明します。以下のいくつかの重要な側面について説明します。

Social Authentication
OpenID Connect v1.0 Brokering
SAML v2.0 Brokering
Identity Federation

12.1. ブローカリングの概要

Keycloakをアイデンティティー・ブローカーとして使用する場合、ユーザーは特定のレルムで認証するためにクレデンシャルを提供する必要はありません。代わりに、認証可能なアイデンティティー・プロバイダーのリストが提示されます。

また、デフォルトのブローカーを設定することもできます。この場合、ユーザーには選択肢が与えられず、親のブローカーに直接リダイレクトされます。

次の図は、Keycloakを使用して外部アイデンティティー・プロバイダーを仲介するときに、必要な手順を示しています。

アイデンティティー・ブローカーのフロー

identity broker flow

ユーザーは認証しておらず、クライアント・アプリケーションの保護されたリソースを要求します。
クライアント・アプリケーションは、ユーザーを認証するためにKeycloakにリダイレクトさせます。
この時点で、ユーザーにはログイン・ページが表示されます。ログイン・ページには、レルムがサポートするアイデンティティー・プロバイダーのリストがあります。
ユーザーは、各ボタンまたはリンクをクリックしてアイデンティティー・プロバイダーの1つを選択します。
Keycloakは、ターゲットのアイデンティティー・プロバイダーに認証を要求する認証リクエストを発行し、ユーザーはアイデンティティー・プロバイダーのログイン・ページにリダイレクトされます。アイデンティティー・プロバイダーの接続プロパティとその他の設定オプションは、管理者が管理コンソールで前もって設定したものになります。
ユーザーは、アイデンティティー・プロバイダーで認証するためにクレデンシャルまたは同意を提供します。
アイデンティティー・プロバイダーによる認証が成功すると、ユーザは認証レスポンスとともにKeycloakにリダイレクトされます。通常、このレスポンスには、Keycloakによって使用されるセキュリティ・トークンが含まれています。セキュリティ・トークンは、アイデンティティー・プロバイダーによって実行された認証を信頼し、そのユーザーに関する情報を取得するために使用されます。
Keycloakは、アイデンティティー・プロバイダーからのレスポンスが有効かどうかをチェックします。有効な場合は、新しいユーザーをインポートして作成するか、ユーザーがすでに存在する場合はスキップします。新規ユーザーの場合、Keycloakは、ユーザーに関する情報がトークンにまだ存在していなければアイデンティティー・プロバイダーに問い合わせることがあります。これが アイデンティティー・フェデレーション と呼ばれるものです。ユーザーがすでに存在する場合、Keycloakはアイデンティティー・プロバイダーから返されたアイデンティティーを既存のアカウントにリンクするように要求することがあります。このプロセスを アカウント・リンキング と呼びます。正確に行われることは設定可能で、First Login Flowの設定で指定できます。このステップの最後で、Keycloakがユーザーを認証し、サービス・プロバイダーの要求されたリソースにアクセスするために独自のトークンを発行します。
ユーザーがローカルで認証されると、Keycloakは、ローカル認証時に先に発行されたトークンを送信してユーザーをサービス・プロバイダーにリダイレクトします。
サービス・プロバイダーはKeycloakからトークンを受け取り、保護されたリソースへのアクセスを許可します。

このフローにはいくつかのバリエーションがありますので、後ほど説明します。例えば、アイデンティティー・プロバイダーのリストを提示する代わりに、クライアント・アプリケーションは特定のプロバイダーを要求することができます。または、ユーザーが自分のアイデンティティーを統合する前に、ユーザーに追加の情報提供を強制させるようにKeycloakに指示できます。

異なるプロトコルは、異なる認証フローを必要とすることがあります。現在のところ、Keycloakでサポートされているすべてのアイデンティティー・プロバイダーは、前述のようなフローを使用します。しかし、使用するプロトコルにかかわらず、ユーザー・エクスペリエンスはほぼ同じでなければなりません。

気づいたかもしれませんが、認証プロセスの終わりにKeycloakは常に独自のトークンをクライアント・アプリケーションに発行します。これは、クライアント・アプリケーションが外部アイデンティティー・プロバイダーと完全に分離されていることを意味します。クライアント・アプリケーションは、どのプロトコル（例：SAML、OpenID Connect、OAuthなど）が使用されたか、またはユーザーのアイデンティティーがどのように検証されたかを知る必要はなく、Keycloakについて知る必要があるだけです。

12.2. デフォルトのアイデンティティー・プロバイダー

ログイン・フォームを表示する代わりに、アイデンティティー・プロバイダーに自動的にリダイレクトすることが可能です。これを有効にするには Authentication に行き、 Browser フローを選択してください。次に、 Identity Provider Redirector オーセンティケーターの設定をクリックします。 Default Identity Provider を、自動的にユーザーをリダイレクトするアイデンティティー・プロバイダーのエイリアスに設定します。

設定されたデフォルトのアイデンティティー・プロバイダーが見つからない場合は、代わりにログイン・フォームが表示されます。

このオーセンティケーターは、 kc_idp_hint クエリー・パラメーターを扱う責任も持っています。詳細については、クライアント提案のアイデンティティー・プロバイダーのセクションを参照してください。

12.3. 共通設定

アイデンティティー・ブローカーの設定は、すべてアイデンティティー・プロバイダーに基づいています。アイデンティティー・プロバイダーは各レルムに対して作成され、デフォルトでは単一アプリケーションごとに有効化されます。つまり、レルムのユーザーは、アプリケーションにサインインするときに、登録されているアイデンティティー・プロバイダーのいずれかを使用することができます。

アイデンティティー・プロバイダーを作成するには、左側の Identity Providers をクリックします。

Identity Providers

identity providers

ドロップ・ダウン・リスト・ボックスで、追加するアイデンティティー・プロバイダを選択します。これにより、そのアイデンティティー・プロバイダー・タイプの設定ページが表示されます。

アイデンティティー・プロバイダーの追加

add identity provider

上記は、Googleのソーシャル・ログイン・プロバイダーを設定する例です。IDPを設定すると、オプションとしてKeycloakのログイン・ページにそれが表示されます。

IDPログイン・ページ

identity provider login page

ソーシャル: ソーシャル・プロバイダーは、レルムでソーシャル認証を有効にすることができます。Keycloakは、ユーザーがソーシャル・ネットワークの既存アカウントを使用して、アプリケーションに簡単にログインできるようにします。現在、Facebook、Google、Twitter、GitHub、LinkedIn、Microsoft、StackOverflowがサポートされており、将来的にはさらなる追加が計画されています。
プロトコル・ベース: プロトコル・ベースのプロバイダーは、特定のプロトコルに依存してユーザーを認証および認可するものです。特定のプロトコルに準拠しているすべてのアイデンティティー・プロバイダーに接続できます。KeycloakはSAML v2.0とOpenID Connect v1.0プロトコルをサポートしています。これにより、これらのオープンスタンダードに基づいた任意のアイデンティティー・プロバイダーを簡単に設定および仲介できるようになります。

各タイプのアイデンティティー・プロバイダーには独自の設定オプションがありますが、すべて共通の設定を共有しています。作成しているアイデンティティー・プロバイダに関係なく、次の設定オプションが使用できます。

Table 1. 共通の設定
設定	説明
Alias	エイリアスは、アイデンティティー・プロバイダの一意な識別子です。アイデンティティー・プロバイダーを内部的に参照するために使用されます。 OpenID Connectなどの一部のプロトコルでは、アイデンティティー・プロバイダーと通信するために、リダイレクトURIまたはコールバックURLが必要です。この場合、エイリアスはリダイレクトURIを構築するために使用されます。すべてのアイデンティティー・プロバイダーにエイリアスが必要です。例としては、facebook、google、idp.acme.comなどです。
Enabled	プロバイダーのオン/オフ
Hide On Login Page	このスイッチがオンの場合、このプロバイダーはログイン・ページにログイン・オプションとして表示されません。クライアントは、ログインを要求するために使用するURLの 'kc_idp_hint' パラメーターを使用して、このプロバイダーの使用を引き続き依頼できます。
Link Only	このスイッチをオンにすると、このプロバイダーはユーザーのログインでは使用することができず、ログイン・ページにはオプションとして表示されません。しかし、既存のアカウントはこのプロバイダーとリンクできます。
Store Tokens	アイデンティティー・プロバイダーから受け取ったトークンを保存するかどうか。
Stored Tokens Readable	ユーザーは保存されたアイデンティティー・プロバイダー・トークンを取得できるかどうか。 broker クライアント・レベルのロール read token にも適用されます。
Trust email	アイデンティティー・プロバイダーがメールアドレスを提供する場合、このメールアドレスは信頼されます。レルムに電子メールの検証が必要な場合、このIDPからログインしたユーザーは電子メールの検証プロセスを経る必要はありません。
GUI order	利用可能なIDPがKeycloakログイン・ページにどのように表示されるかを並べ替えるオーダー番号。
First Login Flow	このIDPを通じて、初めてKeycloakにログインするユーザーのためにトリガーされる認証フローです。
Post Login Flow	ユーザーが外部アイデンティティー・プロバイダーへのログインを完了した後にトリガーされる認証フロー。

12.4. ソーシャル・アイデンティティー・プロバイダー

インターネット上のアプリケーションでは、ユーザーはアクセスするためにサイトに登録する必要があります。さらに別のユーザー名とパスワードの組み合わせを覚えておく必要があります。ソーシャル・アイデンティティー・プロバイダーを使用すると、ユーザーはすでにアカウントを持っている可能性のある、ある程度信頼性があり評判のよい事業者に認証を委譲することができます。Keycloakは、Google、Facebook、Twitter、Github、LinkedIn、Microsoft、StackOverflowなど、最も一般的なソーシャル・ネットワークのビルトイン・サポートを提供しています。

12.4.1. Google

Googleにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから Google を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

google add identity provider

Googleから Client ID と Client Secret を取得する必要があるので、まだ保存ボタンをクリックすることはできません。このページで必須入力のデータの1つは、 Redirect URI です。GoogleにKeycloakをクライアントとして登録するときに提供する必要があるため、このURIをクリップボードにコピーしてください。

Googleでのログインを可能にするには、まず Google Developer Console でプロジェクトとクライアントを作成する必要があります。次に、クライアントIDとシークレットをKeycloakの管理コンソールにコピーする必要があります。

GoogleはGoogle Developer Consoleのデザインを変更することが多いため、これらの指示が常に最新のものではなく、設定手順が多少異なる場合があります。

最初にGoogleでプロジェクトを作成する方法を説明します。

Google Developer Consoleにログインします。

Google Developer Console

google developer console

Create Project ボタンをクリックします。 Project name と Project ID に任意の値を使用し、 Create ボタンをクリックします。プロジェクトが作成されるのを待ちます（これには時間がかかることがあります）。作成されると、プロジェクトのダッシュボードに遷移します。

ダッシュボード

google dashboard

Googleユーザーのプロファイルを取得するには、Google+ APIsを有効にする必要があります。 Enable and manage APIs を選択し、 Google+ API リンクをクリックします。

API

google api list

このページの Enable ボタンをクリックします。プロジェクトのクレデンシャルを作成する必要があるというメッセージが表示されます。そこで、 Go to Credentials ボタンをクリックします。

クレデンシャルへ移動

google go to credentials

これで、クレデンシャルのページが表示されます。

この間にログアウトすると、左上隅にメニューが表示されます。 API Manager を選択すると、目的の画面が表示されます。

次に、必要なクレデンシャルとアクセスするデータの種類を指定するよう求められます。

クレデンシャルの追加

google add credentials

Web server と User data を選択し、 What credentials do I need? ボタンをクリックします。

OAuth IDの作成

google create oauth id

次に、OAuth 2.0クライアントIDを作成する必要があります。クライアントに必要な名前を指定します。また、Keycloakの Add Identity Provider ページから Redirect URI をコピーし、 Authorized redirect URIs フィールドに貼り付ける必要があります。これを済ませたら、 Create client ID ボタンをクリックします。

ユーザーがKeycloakからGoogleにログインすると、Googleからの同意画面が表示され、Keycloakにユーザー・プロファイルに関する情報の表示が許可されているかどうかが尋ねられます。次のGoogleの設定画面に、この画面に関する情報が表示されます。

Done をクリックすると、 Credentials ページが表示されます。新しいOAuth 2.0クライアントのIDをクリックすると、新しいGoogleクライアントの設定が表示されます。

Googleクライアント・クレデンシャル

google client credentials

このページからクライアントIDとシークレットを取得し、Keycloakの Add identity provider ページに入力する必要があります。Keycloakに戻り、それらの項目を入力します。

Google用の Add identity provider ページで注意が必要な1つの設定オプションは、 Default Scopes フィールドです。このフィールドでは、プロバイダで認証するときにユーザーが認可する必要があるスコープを手動で指定できます。スコープの一覧については、 https://developers.google.com/oauthplayground/ をご覧ください。デフォルトでは、Keycloakは openid profile email のスコープを使用します。

12.4.2. Facebook

Facebookにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから Facebook を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

Facebookから Client ID と Client Secret を取得する必要があるので、まだ保存ボタンをクリックすることはできません。このページで必須入力のデータの1つは、 Redirect URI です。FacebookにKeycloakをクライアントとして登録するときに提供する必要があるため、このURIをクリップボードにコピーしてください。

Facebookでのログインを可能にするには、まず Facebook Developer Console でプロジェクトとクライアントを作成する必要があります。

FacebookはFacebook Developer Consoleのデザインを変更することが多いため、これらの指示が常に最新のものではなく、設定手順が多少異なる場合があります。

コンソールにログインすると、画面の右上に My Apps と表示されるプル・ダウン・メニューが表示されます。 Add a New App メニュー項目を選択します。

Add a New App

Website アイコンを選択します。 Skip and Create App ID ボタンをクリックします。

新しいApp IDの作成

メールアドレスとアプリのカテゴリは必須フィールドです。作業が完了すると、アプリケーションのダッシュボードに移動します。 Settings の左のメニュー項目をクリックしてください。

新しいApp IDの作成

このページの最後にある + Add Platform ボタンをクリックし、 Website アイコンを選択します。Keycloakの Add identity provider ページの Redirect URI をコピーして、Facebookの Website 設定ブロックの Site URL に貼り付けます。

Webサイトの指定

この後、Facebookアプリを公開する必要があります。左のメニューの App Review をクリックし、ボタンを"Yes"に切り替えます。

このページからApp IDとApp Secretを取得して、Keycloakの Add identity provider ページに入力する必要があります。これを取得するには、左のメニュー項目 Dashboard をクリックし、 App Secret の下の Show をクリックします。Keycloakに戻り、これらの項目を指定し、最後にFacebookアイデンティティー・プロバイダーを保存します。

Facebook用の Add identity provider ページで注意が必要な1つの設定オプションは、 Default Scopes フィールドです。このフィールドでは、このプロバイダーで認証するときに、ユーザーが承認する必要があるスコープを手動で指定できます。スコープの完全なリストについては、 https://developers.facebook.com/docs/graph-api をご覧ください。デフォルトでは、Keycloakは email のスコープを使用します。

12.4.3. Twitter

Twitterにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add identity provider のドロップダウン・リストから Twitter を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

Twitterから Client ID と Client Secret を取得する必要があるので、まだ保存ボタンをクリックすることはできません。このページで必須入力のデータの1つは、 Redirect URI です。TwitterにKeycloakをクライアントとして登録するときに提供する必要があるため、このURIをクリップボードにコピーしてください。

Twtterでログインを可能にするには、まず Twitter Application Management でアプリケーションを作成する必要があります。

アプリケーションの登録

Create New App ボタンをクリックします。これにより、 Create an Application ページが表示されます。

アプリケーションの登録

NameとDescriptionを入力します。Websiteは何でも構いませんが、 localhost アドレスを持つことはできません。 Callback URL には、Keycloak の Add Identity Provider ページから Redirect URI をコピーする必要があります。

Callback URL に localhost を使うことはできません。ラップトップでTwitterのログインを試してみる場合は、 127.0.0.1 に置き換えてください。

保存をクリックすると、 Details ページに移動します。

App Details

次に、 Keys and Access Tokens タブをクリックします。

Keys and Access Tokens

最後に、このページからAPIキーとシークレットを取得し、Keycloakの Add identity provider ページの Client ID フィールドと Client Secret フィールドにコピーする必要があります。

12.4.4. Github

GitHubにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから GitHub を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

github add identity provider

GitHubから Client ID と Client Secret を取得する必要があるので、まだ保存をクリックすることはできません。このページから必要なデータの1つは、 Redirect URI です。GitHubにKeycloakをクライアントとして登録するときに提供する必要があるため、このURIをクリップボードにコピーしてください。

GitHubでログインを可能にするには、まず GitHub Developer applications でアプリケーションを登録する必要があります。

Githubはアプリケーション登録のデザインを変更することが多いため、これらの指示は常に最新のものではなく、設定手順が多少異なる場合があります。

Add a New App

github developer applications

Register a new application ボタンをクリックします。

アプリケーションの登録

github register app

Keycloakの Add Identity Provider ページから Redirect URI をコピーし、Githubの Register a new OAuth application ページの Authorization callback URL フィールドにそれを入力する必要があります。このページを完了すると、アプリケーションの管理ページに移動します。

Githubアプリケーション・ページ

github app page

12.4.5. LinkedIn

LinkedInにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから LinkedIn を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

linked in add identity provider

LinkedInから Client ID と Client Secret を取得する必要があるので、まだ保存をクリックすることはできません。このページから必要なデータの1つは、 Redirect URI です。クライアントとしてKeycloakを登録するときに、LinkedInにそれを提供する必要がありますので、このURIをクリップボードにコピーしておいてください。

LinkedInでログインを可能にするには、まず LinkedIn Developer Network でアプリケーションを作成する必要があります。

LinkedInはアプリケーション登録のデザインを変更する可能性があるため、これらの指示は常に最新のものではない場合があります。

Developer Network

linked in developer network

Create Application ボタンをクリックします。これにより、 Create a New Application ページが表示されます。

アプリケーションの作成

linked in create app

フォームに適切な値を入力し、 Submit ボタンをクリックします。これにより、新しいアプリケーションの設定ページが表示されます。

アプリケーションの設定

linked in app settings

Default Application Permissions セクションで r_basicprofile と r_emailaddress を選択してください。Keycloakの Add Identity Provider ページから Redirect URI をコピーし、それをLinkedInアプリ設定ページの OAuth 2.0 の Authorized Redirect URLs フィールドに入力する必要があります。入力後、 Update ボタンをクリックすることを忘れないでください！

12.4.6. Microsoft

Microsoftにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから Microsoft を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

microsoft add identity provider

Microsoftから Client ID と Client Secret を取得する必要があるので、まだ保存ボタンをクリックすることはできません。このページで必須入力のデータの1つは、 Redirect URI です。MicrosoftにKeycloakをクライアントとして登録するときに提供する必要があるため、このURIをクリップボードにコピーしてください。

Microsoftアカウントでログインを可能にするには、まずMicrosoftでOAuthアプリケーションを登録する必要があります。 Microsoft Application Registration のURLにアクセスします。

Microsoftはアプリケーション登録のデザインを変更することが多いため、これらの指示は常に最新のものではなく、設定手順が多少異なる場合があります。

アプリケーションの登録

microsoft app register

アプリケーション名を入力し、 Create application をクリックします。これにより、新しいアプリケーションのアプリケーション設定ページが表示されます。

設定

microsoft app settings

Keycloakの Add Identity Provider ページから Redirect URI をコピーし、それをMicrosoftアプリケーション・ページの Redirect URIs フィールドに追加する必要があります。 Add Url ボタンをクリックし、変更を Save してください。

最後に、このページからクライアントIDとシークレットを取得し、Keycloakの Add identity provider ページに入力する必要があります。Keycloakに戻り、それらの項目を入力します。

12.4.7. PayPal

PayPalにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから PayPal を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

paypal add identity provider

PayPalから Client ID と Client Secret を取得する必要があるので、まだ保存ボタンをクリックすることはできません。このページで必須入力のデータの1つは、 Redirect URI です。PayPalにKeycloakをクライアントとして登録するときに提供する必要があるため、このURIをクリップボードにコピーしてください。

PayPalでログインを可能にするには、まず PayPal Developer applications でアプリケーションを登録する必要があります。

Add a New App

paypal developer applications

Create App ボタンをクリックします。

アプリケーションの登録

paypal register app

これで、アプリケーションの設定ページが表示されます。

12.4.8. 次の変更を行います。

SandboxまたはLiveの設定を選択します（ Add identity provider ページで、 Target Sandbox スイッチを有効にしていない場合は、Liveを選択します）。
クライアントIDとシークレットをコピーして、Keycloakの Add identity provider ページに貼り付けることができます。
App Settings へスクロールダウンしてください。
Keycloakの Add Identity Provider ページから Redirect URI をコピーし、それを Return URL フィールドに入力してください。
Log In with PayPal のチェックボックスをチェックしてください。
personal informationセクションの Full name チェックボックスをチェックしてください。
address informationセクションの Email address チェックボックスをチェックしてください。
プライバシーと利用規約の両方のURLをドメインのそれぞれのページを指すように追加してください。

12.4.9. StackOverflow

StackOverflowにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから StackOverflow を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

stack overflow add identity provider

StackOverflowでログインを可能にするには、まず Stack Apps にOAuthアプリケーションを登録する必要があります。 registering your application on Stack Apps のURLにアクセスしてログインします。

StackOverflowはアプリケーション登録のデザインを変更することが多いため、これらの指示は常に最新のものではなく、設定手順が多少異なる場合があります。

アプリケーションの登録

stack overflow app register

アプリケーション名とOAuthドメイン名を入力し、 Register your Application をクリックします。他の項目に必要なものを入力してください。

設定

stack overflow app settings

12.4.10. Openshift

Openshift Onlineは現在、開発者プレビューモードになっています。このドキュメントは、オンプレミスでのインストールとローカルの minishift 開発環境に基づいています。

OpenShiftにログインするには、いくつかのステップを完了する必要があります。まず、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから OpenShift を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

openshift add identity provider

OAuthクライアントの登録

oc コマンドライン・ツールを使ってクライアントを登録することができます。

$ oc create -f <(echo '
kind: OAuthClient
apiVersion: v1
metadata:
 name: kc-client (1)
secret: "..." (2)
redirectURIs:
 - "http://www.example.com/" (3)
grantMethod: prompt (4)
')

1	OAuthクライアントの `name` です。 `<openshift_master>/oauth/authorize` と `<openshift_master>/oauth/token` へのリクエストを行うときに `client_id` リクエスト・パラメーターとして渡されます。
2	`secret` は `client_secret` リクエスト・パラメーターとして使われます。
3	`<openshift_master>/oauth/authorize` と `<openshift_master>/oauth/token` へのリクエストで指定された `redirect_uri` パラメーターは、 `redirectURIs` の（または接頭辞付きの）URIの一つと等しくなければなりません。
4	`grantMethod` は、このクライアントがトークンを要求し、ユーザーによってまだアクセスが許可されていないときに、行うアクションを決定するために使用されます。

oc create コマンドで定義されたクライアントIDとシークレットを使用して、Keycloakの Add identity provider ページに入力します。Keycloakに戻り、それらの項目を入力します。

詳細なガイドについては、 official Openshift documentation を参照してください。

12.5. OpenID Connect v1.0アイデンティティー・プロバイダー

Keycloakは、OpenID Connectのプロトコルに基づいて、アイデンティティー・プロバイダーを仲介できます。これらのIDPは、ユーザーを認証してアクセスを認可するため、この仕様で定義されている認可コードフローをサポートしなければなりません。

OIDCプロバイダーの設定を開始するには、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから OpenID Connect v1.0 を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

oidc add identity provider

このページの初期設定オプションについては、共通のIDP設定で説明しています。OpenID Connectの設定オプションも定義する必要があります。それらは基本的に通信しているOIDC IDPを記述します。

Table 2. OpenID Connectの設定
設定	説明
Authorization URL	OIDCプロトコルで必要な認可URLエンドポイント
Token URL	OIDCプロトコルで必要なトークンURLエンドポイント
Logout URL	OIDCプロトコルで定義されたログアウトURLエンドポイント。この値はオプションです。
Backchannel Logout	バックチャネル・ログアウトは、バックグラウンド（帯域外）で、IDPへのREST呼び出しでユーザーをログアウトします。一部のIDPは、ブラウザのリダイレクトを介してのみログアウトを実行できます。ブラウザのCookieを使用してセッションを識別できる場合があるためです。
User Info URL	OIDCプロトコルで定義されたUserInfo URLエンドポイント。これは、ユーザー・プロファイル情報をダウンロードできるエンドポイントです。
Client ID	このレルムは、ここで設定している外部フェデレーションIDPへのOIDCクライアントとして機能します。認可コードフローを使用して外部IDPと対話するときに、レルムにはOIDCのクライアントIDが必要になります。
Client Secret	このレルムには、認可コードフローを使用する際に利用するクライアント・シークレットが必要です。
Issuer	IDPからのレスポンスには、発行者のクレームが含まれる場合があります。この設定値はオプションです。指定されている場合、提供する値に対してこのクレームが検証されます。
Default Scopes	認証リクエストとともに送信される、OIDCスコープのスペース区切りのリスト。デフォルトは `openid` です。
Prompt	オプションの項目。これは、OIDC仕様で定義されたプロンプト・パラメーターです。これにより、再認証やその他のオプションを強制することができます。詳細は、仕様を参照してください。
Validate Signatures	オプションの項目。Keycloakがこのアイデンティティー・プロバイダーによって署名された外部IDトークンの署名を検証するかどうかを指定します。これがonの場合、Keycloakは外部OIDCアイデンティティー・プロバイダーの公開鍵を知る必要があります。セットアップ方法は以下を参照してください。警告：パフォーマンスのために、Keycloakは外部OIDCアイデンティティー・プロバイダーの公開鍵をキャッシュします。アイデンティティー・プロバイダーの秘密鍵が侵害されたと思われる場合は、鍵を更新するのは明らか良い方法ですが、鍵キャッシュをクリアするのも良い方法です。詳細については、キャッシュのクリアのセクションを参照してください。
Use JWKS URL	`Validate Signatures` がonの場合に適用されます。スイッチがonの場合、特定のJWKS URLからアイデンティティー・プロバイダーの公開鍵がダウンロードされます。これにより、アイデンティティー・プロバイダーが新しい鍵ペアを生成するときに、新しい鍵が常に再ダウンロードされるため、柔軟性が向上します。スイッチがoffの場合、KeycloakのDBからの公開鍵（または証明書）が使用されるため、アイデンティティー・プロバイダーの鍵ペアが変更されたときは、常に新しい鍵をKeycloakのDBにインポートする必要があります。
JWKS URL	JWK形式のアイデンティティー・プロバイダーの鍵が保存されているURL。詳細については、 JWK仕様を参照してください。外部のKeycloakアイデンティティー・プロバイダーを使用している場合、Keycloakは http://broker-keycloak:8180 上で実行されており、そのレルムは `test` であると仮定すると、 http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs のようなURLを使用することができます。
Validating Public Key	`Use JWKS URL` がoffの場合に適用されます。外部IDPの署名を検証するために使用する必要がある、PEM形式の公開鍵をここに指定します。
Validating Public Key Id	`Use JWKS URL` がoffの場合に適用されます。このフィールドは、PEM形式の公開鍵のIDを指定します。この設定値はオプションです。鍵から鍵IDを計算するための標準的な方法は無いので、さまざまな外部アイデンティティー・プロバイダーがKeycloakとは異なるアルゴリズムを使用する可能性があります。このフィールドの値が指定されていない場合、外部IDPから送信された鍵IDに関係なく、上記で指定された検証用公開鍵がすべてのリクエストに使用されます。設定されている場合、このフィールドの値は、そのプロバイダーからの署名を検証するためにKeycloakが使用する鍵IDとして機能し、IDPで指定された鍵IDと一致する必要があります。

OpenIDプロバイダーのメタデータを指すURLまたはファイルを提供することによって、この設定データをすべてインポートすることもできます（OIDCのディスカバリーの仕様を参照）。Keycloakの外部IDPに接続している場合は、URL <root>/auth/realms/{realm-name}/.well-known/openid-configuration からIDPの設定をインポートできます。このリンクは、IDPに関するメタデータを記述するJSONドキュメントです。

12.6. SAML v2.0アイデンティティー・プロバイダー

Keycloakは、SAML v2.0プロトコルに基づいて、アイデンティティー・プロバイダーを仲介できます。

SAML v2.0プロバイダーの設定を開始するには、左のメニュー項目の Identity Providers に移動し、 Add provider のドロップダウン・リストから SAML v2.0 を選択します。これにより、 Add identity provider ページが表示されます。

アイデンティティー・プロバイダーの追加

saml add identity provider

このページの初期設定オプションについては、共通のIDP設定で説明しています。SAMLの設定オプションも定義する必要があります。それらは基本的に通信しているSAML IDPを記述します。

Table 3. SAMLの設定
設定	説明
Single Sign-On Service URL	これは必須フィールドであり、認証プロセスを開始するSAMLエンドポイントを指定します。SAML IDPがIDPエンティティ記述子を表記する場合、このフィールドの値がそこに指定されます。
Single Logout Service URL	SAMLログアウト・エンドポイントを指定するオプションのフィールドです。SAML IDPがIDPエンティティ記述子を表記する場合、このフィールドの値がそこに指定されます。
Backchannel Logout	SAML IDPがバックチャンネル・ログアウトをサポートしている場合に有効にします。
NameID Policy Format	名前識別子の形式に対応するURI参照を指定します。デフォルトはurn:oasis:names:tc:SAML:2.0:nameid-format:persistentです。
HTTP-POST Binding Response	このレルムが外部IDPから送信されたSAMLリクエストに応答するとき、どのSAMLバインディングを使用する必要があるかを指定します。 `off` に設定すると、リダイレクト・バインディングが使用されます。
HTTP-POST Binding for AuthnRequest	このレルムが外部SAML IDPからの認証を要求する場合、どのSAMLバインディングを使用する必要があるかを指定します。 `off` に設定すると、リダイレクト・バインディングが使用されます。
Want AuthnRequests Signed	trueの場合、レルムの鍵ペアを使用して、外部SAML IDPに送信されたリクエストに署名します。
Signature Algorithm	`Want AuthnRequests Signed` がonの場合、使用する署名アルゴリズムを選択することもできます。
SAML Signature Key Name	POSTバインディングを介して送信された署名付きSAMLドキュメントは、 `KeyName` 要素内の署名鍵の識別情報を含みます。これは、デフォルトでKeycloakの鍵IDを含みます。しかし、外部SAML IDPによっては、異なるKeyNameであったり、KeyName要素のない署名付きSAMLドキュメントとなる場合もあります。このスイッチは `KeyName` が鍵IDを含むか（オプション `KEY_ID` ）、レルムの鍵に対応する証明書からサブジェクトを含むか（オプション `CERT_SUBJECT` - 例えば、Microsoft Active Directory Federation Servicesに対して期待される）、鍵名のヒントがSAMLメッセージから完全に省略されるかを制御します（オプション `NONE` ）。
Force Authentication	すでにログインしている場合でも、ユーザーが外部IDPでクレデンシャルを入力するよう強制されることを指定します。
Validate Signature	外部IDPからのSAMLリクエストとレスポンスがデジタル署名されることを、レルムが期待するかどうかを指定します。これをonにすることを強くお勧めします。
Validating X509 Certificate	外部IDPからのSAMLリクエストとレスポンスの署名を検証するために使用される公開証明書。

外部IDPのSAML IDPエンティティ記述子を指すURLまたはファイルを指定することによって、この設定データをすべてインポートすることもできます。Keycloakの外部IDPに接続している場合は、 <root>/auth/realms/{realm-name}/protocol/saml/descriptor からIDP設定をインポートできます。このリンクは、IDPに関するメタデータを記述したXML文書です。

また、接続する外部SAML IDPのエンティティ記述子を指すURLまたはXMLファイルを提供することによって、この設定データをすべてインポートすることもできます。

12.6.1. SP記述子

SAMLプロバイダーを作成すると、そのプロバイダーを表示するときに EXPORT ボタンも表示されます。このボタンをクリックすると、外部SPにインポートするために使用できるSAML SPエンティティ記述子がエクスポートされます。

このメタデータは、このURLにアクセスすることで一般公開されています。

http[s]://{host:port}/auth/realms/{realm-name}/broker/{broker-alias}/endpoint/descriptor

12.7. クライアント推奨のアイデンティティー・プロバイダー

使用したいアイデンティティー・プロバイダーのヒントを指定することで、OIDCアプリケーションは、Keycloakログインページをバイパスすることができます。

これは、認可コードフローの認可エンドポイントに kc_idp_hint クエリー・パラメーターを設定することによって行われます。

KeycloakのOIDCクライアント・アダプターでは、アプリケーションで保護されたリソースにアクセスするときに、このクエリー・パラメーターを指定することもできます。

たとえば、次のようになります。

GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1
Host: localhost:8080

この場合、レルムにはエイリアス facebook を持つアイデンティティー・プロバイダーが存在することが予想されます。このプロバイダーが存在しない場合、ログインフォームが表示されます。

keycloak.js アダプターを使用している場合、次のように同じ動作を実現することもできます。

var keycloak = new Keycloak('keycloak.json');

keycloak.createLoginUrl({
        idpHint: 'facebook'
});

クライアントが Identity Provider Redirector オーセンティケーター用に設定されている場合に、 kc_idp_hint クエリー・パラメーターによって、デフォルトのアイデンティティー・プロバイダーをオーバーライドすることもできます。クライアントは、 kc_idp_hint クエリー・パラメーターを空の値に設定することによって自動リダイレクトを無効にすることもできます。

12.8. クレームとアサーションのマッピング

認証している外部IDPによって提供されるSAMLおよびOpenID Connectのメタデータを、レルムの環境にインポートすることができます。これにより、ユーザー・プロファイルのメタデータおよびその他の情報を抽出して、アプリケーションで使用できるようにすることができます。

外部アイデンティティー・プロバイダーを使用してレルムにログインする新規ユーザーは、ローカルのKeycloakデータベースにエントリーが作成されます。SAMLまたはOIDCのアサーションおよびクレームからメタデータをインポートすると、ローカルのレルム・データベースにこのデータが作成されます。

レルムの Identity Providers ページにリストされているアイデンティティー・プロバイダーをクリックすると、IDPの Settings タブが表示されます。このページには、 Mappers タブもあります。そのタブをクリックして、受信するIDPメタデータのマッピングを開始します。

identity provider mappers

このページには Create ボタンがあります。このボタンをクリックすると、ブローカー・マッパーを作成できます。ブローカー・マッパーは、SAML属性またはOIDCのID/アクセストークンのクレームをユーザー属性およびユーザーロールのマッピングにインポートできます。

identity provider mapper

Mapper Type のリストからマッパーを選択してください。ツールチップにカーソルを合わせると、マッパーの機能の説明が表示されます。ツールチップには、入力する必要がある設定情報も記載されています。 Save ボタンをクリックすると、新しいマッパーが追加されます。

JSONベースのクレームでは、ネストと角括弧にドット表記を使用して、インデックスで配列フィールドにアクセスできます。たとえば、'contact.address[0].country’です。

ソーシャル・プロバイダーが提供するユーザー・プロファイルJSONデータの構造を調べるために、 DEBUG レベルのロガー org.keycloak.social.user_profile_dump を有効にできます。これは、サーバーのアプリケーション・サーバー設定ファイル（domain.xmlまたはstandalone.xml）で行います。

12.9. 利用可能なユーザー・セッション・データ

ユーザーが外部IDPからログインすると、アクセス可能なユーザー・セッション・ノート・データがKeycloakに追加で保存されます。このデータは、適切なクライアント・マッパーを使用して戻されるトークンまたはSAMLアサーションを介して、ログインを要求するクライアントに伝播できます。

identity_provider: ログインを実行するために使用されるブローカーのIDPエイリアスです。
identity_provider_identity: 現在認証されているユーザーのIDPユーザー名です。これはKeycloakユーザー名と同じことが多いですが、必ずしもそうである必要はありません。たとえば、Keycloakのユーザー john は、Facebookのユーザー john123@gmail.com にリンクできます。その場合、ユーザー・セッション・ノートの値は john123@gmail.com になります。

この情報をクライアントに伝えるために、 ユーザー・セッション・ノート タイプのプロトコル・マッパーを使うことができます。

12.10. First Login Flow

ユーザーがアイデンティティー・ブローカリングを介してログインすると、ユーザー情報が部分的にインポートされ、レルムのローカル・データベース内でリンクされます。Keycloakが外部アイデンティティー・プロバイダーを通じてユーザーを正常に認証すると、次の2つの状況が発生する可能性があります。

認証済みのアイデンティティー・プロバイダー・アカウントをインポートしてリンクしたKeycloakユーザー・アカウントが既に存在する場合、Keycloakは既存のユーザーとして認証され、アプリケーションにリダイレクトされます。
外部ユーザー用にインポートされてリンクされている既存のKeycloakユーザー・アカウントがまだ無い場合、通常は、新しいアカウントを登録してKeycloakデータベースにインポートするだけですが、既存のKeycloakアカウントに同じメールがある場合はどうなるでしょうか？既存のローカル・アカウントを外部アイデンティティー・プロバイダーに自動的にリンクすることは、外部アイデンティティー・プロバイダーから取得した情報を常に信頼できるとは限らないため、潜在的なセキュリティ・ホールになります。

何らかの競合や上記の状況に対処する際の要件は組織によって異なります。このため、IDPの設定には First Login Flow オプションがあります。このオプションを使用すると、初めて外部IDPからユーザーがログインした後に使用されるワークフローが選択できます。デフォルトでは、 first broker login フローが指定されていますが、独自のフローを設定して使用し、異なるアイデンティティー・プロバイダーに対して異なるフローを使用することができます。

フロー自体は、管理コンソールの Authentication タブで設定します。 First Broker Login フローを選択すると、デフォルトでどのオーセンティケーターが使用されているかが分かります。既存のフローを再設定することができます（たとえば、いくつかのオーセンティケーターを無効にしたり、それらのうちのいくつかを 必須 としてマークしたり、いくつかのオーセンティケーターを設定する、など）。

また、新しい認証フローを作成したり、独自の認証プロバイダー実装を作成して、そのフローで使用することもできます。詳細については、Server Developer Guideを参照してください。

12.10.1. デフォルトの初回ログインフロー

First Broker Login フローによって提供されるデフォルトの動作について説明します。

Review Profile: このオーセンティケーターは、プロファイル情報ページを表示することができ、ユーザーはアイデンティティー・プロバイダーから取得したプロファイルを確認できます。オーセンティケーターは設定可能です。 Update Profile On First Login オプションを設定できます。 On にすると、ユーザーには自分のアイデンティティーを統合するために追加情報を求めるプロファイル・ページが常に提示されます。 missing の場合、アイデンティティー・プロバイダーによっていくつかの必須情報（電子メール、名、姓）が提供されない場合にのみ、プロファイル・ページがユーザーに提示されます。 Off の場合、 Review profile info リンク（後のフェーズで Confirm Link Existing Account オーセンティケーターによって表示されるページ）を後のフェーズでユーザーがクリックしない限り、プロファイル・ページは表示されません。
Create User If Unique: このオーセンティケーターは、アイデンティティー・プロバイダーのアカウントの電子メールまたはユーザー名が同じKeycloakアカウントが、既に存在するかどうかをチェックします。存在しない場合、オーセンティケーターは新しいローカルのKeycloakアカウントを作成し、それをアイデンティティー・プロバイダーにリンクすることで、フロー全体が終了します。それ以外の場合は、次の Handle Existing Account サブフローに進みます。重複したアカウントがないことを常に確認したい場合は、このオーセンティケーターを REQUIRED にマークすることができます。この場合、既存のKeycloakアカウントが存在する場合は、エラーページが表示され、ユーザーはアカウント管理を通じてアイデンティティー・プロバイダーのアカウントをリンクする必要があります。
Confirm Link Existing Account: 情報ページに、同じ電子メールを持つ既存のKeycloakアカウントがあることが分かります。ユーザーは自身のプロファイルをもう一度見直し、別の電子メールまたはユーザー名を使用することができます（フローが再開され、 Review Profile オーセンティケーターに戻ります）。または、アイデンティティー・プロバイダーのアカウントと既存のKeycloakのアカウントをリンクさせたいかどうかをユーザーに確認できます。ユーザーにこの確認ページが表示されないようにする場合は、このオーセンティケーターを無効にしますが、電子メールの確認または再認証によって、アイデンティティー・プロバイダーのアカウントを直接リンクするようにしてください。
Verify Existing Account By Email: このオーセンティケーターは、デフォルトでは ALTERNATIVE であるため、レルムにSMTPが設定されている場合にのみ使用されます。ユーザーにメールが送信され、アイデンティティー・プロバイダーとKeycloakアカウントをリンクさせたいかどうかを確認できます。電子メールによるリンクを確認したくないが、代わりに、ユーザーに常にパスワード（またはOTP）で再認証させたい場合は、これを無効にしてください。
Verify Existing Account By Re-authentication: このオーセンティケーターは、電子メールのオーセンティケーターが無効であるか、または使用できない場合に使用されます（レルムに対してSMTPが設定されていない場合）。Keycloakアカウントとアイデンティティー・プロバイダーをリンクするために、パスワードで認証する必要があるログイン画面が表示されます。また、ユーザーは、自分のKeycloakアカウントに既にリンクされている別のアイデンティティー・プロバイダーで再認証することもできます。ユーザーに強制的にOTPを使用させることもできます。それ以外の場合はオプションで、既にOTPがユーザー・アカウントに設定されている場合にのみ使用されます。

12.11. 外部IDPトークンの取得

Keycloakでは、外部IDPを使用して認証プロセスからのトークンとレスポンスを保存できます。そのために、IDPの設定ページで Store Token の設定オプションを使用できます。

アプリケーション・コードで、追加のユーザー情報を取得するためにこれらのトークンとレスポンスを検索したり、外部IDPにリクエストを送信することができます。たとえば、アプリケーションは、Googleトークンを使用して、他のGoogleサービスやREST APIを呼び出すことができます。特定のアイデンティティー・プロバイダーのトークンを取得するには、次のようにリクエストを送信する必要があります。

GET /auth/realms/{realm}/broker/{provider_alias}/token HTTP/1.1
Host: localhost:8080
Authorization: Bearer <KEYCLOAK ACCESS TOKEN>

アプリケーションはKeycloakで認証され、アクセストークンを受け取っている必要があります。このアクセストークンには、 broker クライアントレベルの read-token ロールが設定されている必要があります。つまり、ユーザーはこのロールのロールマッピングを持っていなければならず、クライアント・アプリケーションのスコープ内でそのロールが必要です。この場合（Keycloak内のセキュリティー保護されたサービスにアクセスしている場合）は、ユーザー認証時にKeycloakが発行したアクセストークンを送信する必要があります。ブローカーの設定ページでは、 Stored Tokens Readable のスイッチをオンにすることで、新しくインポートされたユーザーにこのロールを自動的に割り当てることができます。

これらの外部トークンは、プロバイダーを介して再度ログインするか、Client Initiated Account Linking APIを使用して再確立できます。

13. ユーザー・セッションの管理

ユーザーがレルムにログインすると、Keycloakはユーザー・セッションを維持し、セッション内で訪問したすべてのクライアントを記憶します。これらのユーザー・セッションに対してレルム管理者が実行できる多くの管理機能があります。レルム全体のログイン統計を表示し、各クライアントに誰がどこからログインしているのかを確認できます。管理者は、管理コンソールからユーザーまたはユーザーのセットをログアウトできます。トークンを取り消したり、すべてのトークンとセッションのタイムアウトを設定することも可能です。

13.1. セッションの管理

左のメニュー項目 Sessions をクリックすると、現在そのレルムでアクティブなセッション数のトップレベルのビューが表示されます。

Sessions

sessions

クライアントと、そのクライアントに現在アクティブなセッションの数が一覧表示されます。また、この一覧表示の右側にある Logout all ボタンをクリックして、レルム内のすべてのユーザーをログアウトすることもできます。

13.1.1. Logout allの制限事項

すべてのSSO Cookieセットが無効になり、アクティブなブラウザー・セッションで認証を要求するクライアントは再ログインする必要があります。このログアウト・イベントは、特定のクライアント（特に、Keycloak OIDCクライアント・アダプターを使用しているクライアント）にのみ通知されます。他のクライアント・タイプ（SAML）はバックチャネル・ログアウト・リクエストを受信しません。

Logout all をクリックしても、未処理のアクセストークンは取り消されないことに注意することが重要です。それらは失効する必要があります。失効ポリシーをクライアントにプッシュする必要がありますが、これもKeycloak OIDCクライアント・アダプターを使用するクライアントだけで機能します。

13.1.2. アプリケーション・ドリルダウン

Sessions ページでは、各クライアントにドリルダウンすることもできます。これにより、そのクライアントの Sessions タブが表示されます。 Show Sessions ボタンをクリックすると、そのアプリケーションにログインしているユーザーを参照できます。

アプリケーション・セッション

application sessions

13.1.3. ユーザー・ドリルダウン

個々のユーザーの Sessions タブに移動すると、セッション情報を表示することもできます。

ユーザー・セッション

user sessions

13.2. 失効ポリシー

あなたのシステムが侵害された場合は、すべてのセッションと配布されたアクセストークンを取り消す方法が必要になります。 Sessions 画面の Revocation タブに移動することでこれを行うことができます。

失効

revocation

タイムベースの失効ポリシーのみを設定できます。コンソールでは、それより前に発行されたセッションまたはトークンが無効となる日時を指定できます。 Set to now ボタンは、ポリシーを現在の日時に設定します。 Push ボタンは、この失効ポリシーを、Keycloak OIDCクライアント・アダプターがインストールされている登録済みOIDCクライアントにプッシュします。

13.3. セッションとトークンのタイムアウト

Keycloakはセッション、Cookie、トークンのタイムアウトのきめ細かい制御ができます。これは、すべて左のメニュー項目の Realm Settings の Tokens タブで行います。

Tokensタブ

tokens tab

このページの各項目を見てみましょう。

設定	説明
Revoke Refresh Token	リフレッシュ・トークン・フローを実行しているOIDCクライアントの場合、このフラグをオンにすると、クライアントが使用しなければならないリクエストでそのリフレッシュ・トークンを取り消し、別のリフレッシュ・トークンを発行します。これは、基本的にリフレッシュ・トークンが1回限りの使用となることを意味します。
SSO Session Idle	OIDCクライアントにも関係します。ユーザーがこのタイムアウトよりも長くアクティブでない場合、ユーザー・セッションは無効になります。どのようにアイドル時間はチェックされるでしょうか？認証を要求するクライアントは、アイドル・タイムアウトがあります。リフレッシュ・トークン・リクエストもアイドル・タイムアウトがあります。
SSO Session Max	ユーザー・セッションが期限切れで無効になるまでの最大時間。これは具体的な数字と時間です。最大時間を制御します。アクティビティに関係なく、ユーザー・セッションがアクティブのままにできる最大時間を制御します。
Offline Session Idle	オフライン・アクセスの場合、これはオフライン・トークンが取り消される前にセッションがアイドル状態を維持できる時間です。
Access Token Lifespan	OIDCアクセス・トークンが作成される時、この値が有効期限に反映されます。
Access Token Lifespan For Implicit Flow	インプリシット・フローでは、リフレッシュ・トークンは提供されません。このため、インプリシット・フローで作成されたアクセス・トークンには別のタイムアウトがあります。
Client login timeout	これは、クライアントがOIDCで認可コード・フローを完了するまでの最大時間です。
Login timeout	ログインに必要な合計時間。認証がこの時間より長くかかる場合、ユーザーは認証プロセスをやり直す必要があります。
Login action timeout	ユーザーが認証プロセスで1アクションに費やすことができる最大時間。
User-Initiated Action Lifespan	ユーザーが送信したアクション許可（パスワード忘れのメールなど）の有効期限が切れるまでの最大時間。ユーザーが自分で作成した操作にすばやく反応することが期待されるため、この値は短くすることをお勧めします。
Default Admin-Initiated Action Lifespan	管理者によってユーザーに送信されたアクション許可が失効するまでの最大時間。この値は、管理者が現在オフラインになっているユーザーに対して電子メールを送信できるようにするために長くすることをお勧めします。デフォルトのタイムアウトは、トークンを発行する直前にオーバーライドすることができます。
Override User-Initiated Action Lifespan	操作ごとに独立したタイムアウトがある可能性があります（電子メールの確認、パスワード忘れ、ユーザーの操作、アイデンティティー・プロバイダーの電子メールの確認など）。このフィールドは必須ではなく、未指定の場合、 User-Initiated Action Lifespan で設定された値がデフォルトになります。

設定

説明

Revoke Refresh Token

リフレッシュ・トークン・フローを実行しているOIDCクライアントの場合、このフラグをオンにすると、クライアントが使用しなければならないリクエストでそのリフレッシュ・トークンを取り消し、別のリフレッシュ・トークンを発行します。これは、基本的にリフレッシュ・トークンが1回限りの使用となることを意味します。

SSO Session Idle

OIDCクライアントにも関係します。ユーザーがこのタイムアウトよりも長くアクティブでない場合、ユーザー・セッションは無効になります。どのようにアイドル時間はチェックされるでしょうか？認証を要求するクライアントは、アイドル・タイムアウトがあります。リフレッシュ・トークン・リクエストもアイドル・タイムアウトがあります。

SSO Session Max

ユーザー・セッションが期限切れで無効になるまでの最大時間。これは具体的な数字と時間です。最大時間を制御します。アクティビティに関係なく、ユーザー・セッションがアクティブのままにできる最大時間を制御します。

Offline Session Idle

オフライン・アクセスの場合、これはオフライン・トークンが取り消される前にセッションがアイドル状態を維持できる時間です。

Access Token Lifespan

OIDCアクセス・トークンが作成される時、この値が有効期限に反映されます。

Access Token Lifespan For Implicit Flow

インプリシット・フローでは、リフレッシュ・トークンは提供されません。このため、インプリシット・フローで作成されたアクセス・トークンには別のタイムアウトがあります。

Client login timeout

これは、クライアントがOIDCで認可コード・フローを完了するまでの最大時間です。

ログインに必要な合計時間。認証がこの時間より長くかかる場合、ユーザーは認証プロセスをやり直す必要があります。

ユーザーが認証プロセスで1アクションに費やすことができる最大時間。

User-Initiated Action Lifespan

ユーザーが送信したアクション許可（パスワード忘れのメールなど）の有効期限が切れるまでの最大時間。ユーザーが自分で作成した操作にすばやく反応することが期待されるため、この値は短くすることをお勧めします。

Default Admin-Initiated Action Lifespan

管理者によってユーザーに送信されたアクション許可が失効するまでの最大時間。この値は、管理者が現在オフラインになっているユーザーに対して電子メールを送信できるようにするために長くすることをお勧めします。デフォルトのタイムアウトは、トークンを発行する直前にオーバーライドすることができます。

Override User-Initiated Action Lifespan

操作ごとに独立したタイムアウトがある可能性があります（電子メールの確認、パスワード忘れ、ユーザーの操作、アイデンティティー・プロバイダーの電子メールの確認など）。このフィールドは必須ではなく、未指定の場合、 User-Initiated Action Lifespan で設定された値がデフォルトになります。

13.4. オフライン・アクセス

オフライン・アクセスは、 OpenID Connect仕様で説明されている機能です。このアイディアは、ログイン中にクライアント・アプリケーションが古典的なリフレッシュトークンの代わりにオフライントークンを要求するというものです。アプリケーションはこのオフライントークンをデータベースまたはディスクに保存し、ユーザーがログアウトしても後で使用できます。これは、ユーザーがオンラインでなくても、アプリケーションがユーザーのために何らかの "オフライン" アクションを実行する必要がある場合に便利です。一例として、毎晩の何らかのデータの定期的なバックアップがあります。

アプリケーションは、一部のストレージ（通常はデータベース）にオフライントークンを永続化し、それを使用してKeycloakサーバーから新しいアクセストークンを手動で取得する役割を担います。

従来のリフレッシュトークンとオフライントークンの違いは、オフライントークンは期限切れせず、 SSO Session Idle timeout の対象ではないということです。オフライントークンは、ユーザー・ログアウトまたはサーバーの再起動後も有効です。ただしデフォルトでは、オフライントークンを少なくとも30日に1回、トークン更新アクションに使用する必要があります（この値は、管理コンソールの Realm Settings の Tokens タブの Offline Session Idle timeout で変更できます）。また、オプションの Revoke refresh tokens を有効にした場合、各オフライントークンは1回だけしか使用できません。そのためリフレッシュ後は、リフレッシュ・レスポンス内の新しいオフライントークンを常に以前のトークンの代わりにDBに保存する必要があります。

ユーザーは、ユーザー・アカウント・サービスで付与されたオフライントークンの表示と取り消しができます。管理ユーザーは、管理コンソールの特定ユーザーの Consents タブで、個々のユーザーのオフライントークンを取り消すことができます。管理者は各クライアントの Offline Access タブで、発行されたすべてのオフライントークンを表示することもできます。オフライントークンは、失効ポリシーを設定することによっても取り消すことができます。

オフライントークンを発行できるようにするには、ユーザーにレルムレベルのロール offline_access のロールマッピングが必要です。クライアントもスコープにそのロールを持っている必要があります。

クライアントは、Keycloakに認可リクエストを送信するときに、パラメーター scope=offline_access を追加することにより、オフライントークンを要求できます。Keycloak OIDCクライアント・アダプターは、アプリケーションのセキュリティ保護されたURL（http://localhost:8080/customer-portal/secured?scope=offline_access ）にアクセスするときに、このパラメータを自動的に追加します。ダイレクト・アクセス・グラントとサービス・アカウントは、認証リクエストのボディーに scope=offline_access を含めると、オフライントークンもサポートします。

14. ユーザー・ストレージ・フェデレーション

多くの企業には、ユーザーとそのパスワードやその他のクレデンシャルに関する情報を保持する既存のユーザー・データベースがあります。多くの場合、既存のストアから純粋なKeycloakデプロイメントに移行することはできません。 Keycloakは既存の外部ユーザー・データベースを統合できます。デフォルトで、LDAPとActive Directoryをサポートしています。 User Storage SPIを使用して、カスタムのユーザー・データベースに独自の拡張機能をコーディングすることもできます。

それは以下のように動作します。ユーザーがログインすると、Keycloakがユーザーを見つけるために内部のユーザーストアを調べます。それが見つからない場合は、一致するものが見つかるまで、レルムに対して設定したすべてのユーザー・ストレージ・プロバイダを繰り返し処理します。外部ストアからのデータは、Keycloakランタイムによって消費される、共通のユーザーモデルにマップされます。そして、この共通のユーザーモデルは、OIDCトークンクレームとSAMLアサーション属性にマッピングできます。

外部ユーザー・データベースは、Keycloakが持つすべての機能をサポートするのに必要なデータを、すべて持つことはほとんどありません。この場合、ユーザ－・ストレージ・プロバイダーは、Keycloakユーザーストアにローカルでいくつかのものを保存することを選ぶことができます。一部のプロバイダーでは、ユーザーをローカルにインポートして、定期的に外部ストアと同期します。このすべては、プロバイダの機能とその設定方法によって異なります。たとえば、外部ユーザーストアがOTPをサポートしていない可能性があります。プロバイダーに応じて、このOTPサポートはKeycloakによって処理され格納されます。

14.1. プロバイダーの追加

ストレージ・プロバイダーを追加するには、管理コンソールの左側メニュー項目 User Federation に移動します。

User Federation

user federation

右側には、 Add Provider リストボックスがあります。追加するプロバイダー・タイプを選択すると、そのプロバイダーの設定ページに移動します。

14.2. LDAPとActive Directory

Keycloakには、LDAP/ADプロバイダーが組み込まれています。これにより、同じKeycloakレルムに複数の異なるLDAPサーバーを統合することが可能です。LDAPユーザー属性をKeycloak共通ユーザーモデルにマップできます。デフォルトでは、ユーザー名、電子メール、名、姓をマッピングしますが、追加のマッピングを自由に設定することができます。LDAPプロバイダーは、異なるストレージとLDAP/ADプロトコルによるパスワード検証、編集および同期モードもサポートしています。

フェデレーテッドLDAPストアを設定するには、管理コンソールを開きます。左メニューのオプションから User Federation をクリックしてください。このページに移動すると、 Add Provider 選択ボックスがあります。このリストの中に ldap があるはずです。 ldap を選択すると、LDAP設定ページが表示されます。

14.2.1. ストレージモード

デフォルトでは、KeycloakはLDAPからローカルKeycloakユーザー・データベースにユーザーをインポートします。このユーザーのコピーは、オンデマンドで同期されるか、または定期的なバックグラウンド・タスクによって同期されます。1つの例外はパスワードです。パスワードはインポートされず、パスワードの検証はLDAPサーバーに委任されます。このアプローチの利点は、必要とされる追加のユーザーごとのデータをローカルに保存できるため、すべてのKeycloak機能が動作することです。この方法はまた、LDAPサーバーの負荷を軽減します。非キャッシュ・ユーザーは、2回目のアクセス時にKeycloakデータベースからロードされます。LDAPサーバーが持つ唯一の負荷はパスワードの検証です。このアプローチの欠点は、ユーザーが最初に問い合わせされるときに、Keycloakデータベースの挿入が必要になることです。インポートも、必要に応じてLDAPサーバーと同期する必要があります。

また、ユーザーをKeycloakユーザー・データベースにインポートしないように選択することもできます。この場合、Keycloakランタイムが使用する共通ユーザーモデルは、LDAPサーバーによってのみバックアップされます。つまり、LDAPがKeycloak機能に必要なデータをサポートしていない場合、その機能は動作しません。この方法の利点は、LDAPユーザーのコピーをKeycloakユーザー・データベースにインポートして同期するオーバーヘッドがないことです。

このストレージモードは Import Enabled スイッチによって制御されます。ユーザーをインポートするには On に設定します。

14.2.2. 編集モード

ユーザーはユーザー・アカウント・サービスを介して、管理者は管理コンソールを介して、ユーザーのメタデータを変更できます。設定に応じて、LDAPの更新権限がある場合とない場合があります。 Edit Mode 設定オプションは、LDAPストアの編集ポリシーを定義します。

READONLY: ユーザー名、電子メール、姓、名、およびその他のマップされた属性は変更できません。いつでも誰でも、これらのフィールドを更新しようとすると、Keycloakはエラーを表示します。また、パスワードの更新はサポートされません。
WRITABLE: ユーザー名、電子メール、姓、名、およびその他のマップされた属性とパスワードはすべて更新でき、LDAPストアと自動的に同期されます。
UNSYNCED: ユーザー名、メールアドレス、姓、パスワードの変更はKeycloakローカル・ストレージに保存されます。LDAPに同期する方法は、あなた次第です。これにより、Keycloakデプロイメントは、読み取り専用LDAPサーバー上のユーザー・メタデータの更新をサポートできます。このオプションは、LDAPからローカルKeycloakユーザー・データベースにユーザーをインポートする場合にのみ適用されます。

14.2.3. その他の設定オプション

Console Display Name: このプロバイダーが管理コンソールで参照されるときに使用される名前。
Priority: ユーザーを検索したり、登録を追加したりするときのこのプロバイダーの優先順位。
Sync Registrations: LDAPは新規ユーザーの追加をサポートするかどうか。管理コンソールのKeycloakによって作成された新しいユーザーまたは登録ページをLDAPに追加する場合は、このスイッチをクリックします。
Allow Kerberos authentication: LDAPからプロビジョニングされたユーザーデータでの、レルム内のKerberos/SPNEGO認証を有効にします。詳細はKerberosのセクションにあります。
その他のオプション: 残りの設定オプションは自明のはずです。管理コンソールでツールチップをマウスオーバーすると、それらの詳細が表示されます。

14.2.4. SSL経由でLDAPに接続する

LDAPストアへのセキュリティで保護された接続URL（たとえば ldaps://myhost.com:636 ）を設定すると、KeycloakはLDAPサーバーとの通信にSSLを使用します。重要なことは、Keycloakサーバー側でトラストストアを適切に構成することです。そうしないとKeycloakはLDAPへのSSL接続を信頼できません。

Keycloakのグローバル・トラストストアは、トラストストアSPIで設定できます。詳細については、 Server Installation and Configuration Guide のリンクをご覧ください。トラストストアSPIを設定しないと、トラストストアは、Javaによって提供されるデフォルトのメカニズム（システム・プロパティー javax.net.ssl.trustStore によって提供されるファイルか、システム・プロパティーが設定されていなければJDKのcacertsファイル）にフォールバックします。

LDAPフェデレーション・プロバイダーの設定には、設定プロパティー Use Truststore SPI があり、トラストストアSPIを使用するかどうかを選択できます。デフォルト値は Only for ldaps です。ほとんどのデプロイメントで問題ありません。トラストストアSPIは、LDAPへの接続が ldaps で始まる場合にのみ使用されます。

14.2.5. LDAPユーザーとKeycloakの同期

インポートが有効になっている場合、LDAPプロバイダーは必要なLDAPユーザーの同期（インポート）をKeycloakローカル・データベースに自動的に行います。ユーザーがログインすると、LDAPプロバイダーはLDAPユーザーをKeycloakデータベースにインポートし、LDAPパスワードに対して認証します。これは、ユーザーがインポートされる唯一のタイミングです。管理コンソールの左側の Users メニュー項目に移動し、 View all users ボタンをクリックすると、Keycloakによって少なくとも1回は認証されたLDAPユーザーのみが表示されます。管理者が誤って巨大なLDAPユーザーDBをインポートしようとしないように、この方法で実装されています。

すべてのLDAPユーザーをKeycloakデータベースに同期させたい場合は、設定したLDAPプロバイダーの Sync Settings を設定して有効にすることができます。同期には2種類あります。

定期的な完全同期: これにより、すべてのLDAPユーザーがKeycloak DBに同期されます。Keycloakに既に存在し、LDAPで直接変更されたLDAPユーザーは、Keycloak DBで更新されます（たとえば、ユーザー Mary Kelly がLDAPで Mary Smith に変更された場合）。
定期的な変更ユーザーの同期: 同期が行われると、最後の同期後に作成または更新されたユーザーのみがインポートまたは更新されます。

同期を処理する最善の方法は、LDAPプロバイダーを最初に作成するときに Synchronize all users ボタンをクリックした後、変更されたユーザの定期的な同期を設定することです。 LDAPプロバイダーの設定ページには、いくつかのオプションがあります。

14.2.6. LDAPマッパー

LDAPマッパーは リスナー であり、さまざまな時点でLDAPプロバイダーによってトリガーされ、LDAP統合の別の拡張ポイントを提供します。これらは、ユーザーがLDAP経由でログインしてインポートが要求されたとき、Keycloakの登録が開始されたとき、または、ユーザーが管理コンソールから問い合わせを受けたときにトリガーされます。LDAPフェデレーション・プロバイダーを作成すると、Keycloakは自動的にこのプロバイダー用の組込み マッパー セットを提供します。このセットを変更して新しいマッパーを作成したり、既存のマッパーを更新/削除することが自由にできます。

ユーザー属性マッパー: これにより、Keycloakユーザーの属性にマップされるLDAP属性を指定できます。たとえば、Keycloakデータベースの属性 email にLDAP属性 mail を設定することができます。このマッパー実装では、常に1対1のマッピングとなります（1つのLDAP属性が1つのKeycloak属性にマップされます）。
フルネーム・マッパー: これにより、一部のLDAP属性（通常は cn ）に保存されているユーザーのフルネームがKeycloakデータベースの firstName 属性と lastname 属性にマップされるように指定することができます。 cn にユーザーのフルネームを含めることは、いくつかのLDAPデプロイメントにおいて一般的なケースです。
ロールマッパー: これにより、LDAPからのロールマッピングをKeycloakのロールマッピングに設定できます。1つのロールマッパーを使用して、LDAPロール（通常はLDAPツリーの特定のブランチからのグループ）を、レルムロールまたはクライアントロールのいずれかにマップできます。同じLDAPプロバイダーに対してさらにロールマッパーを設定することは問題ではありません。たとえば、 ou=main,dc=example,dc=org のグループからのロールマッピングをレルムロール・マッピングにマップし、 ou=finance,dc=example,dc=org のグループからのロールマッピングをクライアント finance のクライアントロール・マッピングにマップするように指定できます。
ハードコードされたロールマッパー: このマッパーは、LDAPにリンクされた各Keycloakユーザーに特定のKeycloakロールを付与します。
グループマッパー: これにより、LDAPからのグループ・マッピングをKeycloakグループ・マッピングに設定できます。グループマッパーを使用すると、LDAPツリーの特定のブランチからのLDAPグループをKeycloakのグループにマップできます。また、LDAPからのユーザーグループ・マッピングをKeycloakのユーザーグループ・マッピングに伝播します。
MSADユーザー・アカウント・マッパー: このマッパーは、Microsoft Active Directory（MSAD）固有のものです。 MSADユーザー・アカウントの状態をKeycloakアカウントの状態（アカウントが有効、パスワードが期限切れなど）に緊密に統合できます。 userAccountControl と ` pwdLastSet` LDAP属性を使っています（どちらもMSAD固有のものであり、LDAP標準ではありません）。たとえば pwdLastSet が 0 の場合、Keycloakユーザーはパスワードを更新する必要があり、UPDATE_PASSWORD必須アクションがユーザーに追加されます。 userAccountControl が 514 （無効なアカウント）の場合、Keycloakユーザーも無効になります。

デフォルトでは、ユーザー名、姓、名、電子メールなどの基本的なKeycloakユーザー属性を対応するLDAP属性にマップする、ユーザー属性マッパーがあります。これらを拡張し、追加の属性マッピングを自由に与えることができます。管理コンソールにはツールチップが用意されており、対応するマッパーの設定に役立ちます。

14.3. SSSDとFreeIPAのアイデンティティ管理の統合

Keycloakには、組み込みの SSSD （System Security Services Daemon）プラグインも付属しています。SSSDは最新のFedoraまたはRed Hat Enterprise Linuxの一部であり、複数のアイデンティティーと認証プロバイダーへのアクセスを提供します。フェイルオーバーやオフライン・サポートなどの利点があります。設定オプションや詳細については、 Red Hat Enterprise Linux Identity Managementのドキュメントを参照してください。

また、SSSDは、認証とアクセス制御を提供するFreeIPAアイデンティティー管理（IdM）サーバーと統合しています。この統合により、Keycloakでは PAM サービスで認証し、SSSDからユーザーデータを取得することができます。Linux環境でRed Hat Identity Managementを使用する方法の詳細については、 Red Hat Enterprise Linux Identity Managementのドキュメントを参照してください。

keycloak sssd freeipa integration overview

KeycloakとSSSD間の通信のほとんどは、読み取り専用のD-Busインターフェイスを通じて行われます。このため、ユーザーをプロビジョニングして更新する唯一の方法は、FreeIPA/IdM管理インターフェイスを使用することです。デフォルトでは、LDAPフェデレーション・プロバイダーと同様に、ユーザー名、電子メール、姓、名をインポートするように設定されています。

グループとロールは自動的に登録されますが、同期されないため、Keycloak管理者がKeycloakに直接行った変更はSSSDと同期されません。

FreeIPA/IdMサーバーの設定方法に関する情報は、次のとおりです。

14.3.1. FreeIPA/IdMサーバー

簡単にするために、すでに利用可能な FreeIPA Docker image が使用されています。サーバーを設定するには、 FreeIPAのドキュメントを参照してください。

DockerでFreeIPAサーバーを実行するには、次のコマンドが必要です。

docker run --name freeipa-server-container -it \
-h server.freeipa.local -e PASSWORD=YOUR_PASSWORD \
-v /sys/fs/cgroup:/sys/fs/cgroup:ro \
-v /var/lib/ipa-data:/data:Z freeipa/freeipa-server

パラメーター -h と server.freeipa.local はFreeIPA/IdMサーバーのホスト名を表します。 YOUR_PASSWORD は選択したパスワードに変更してください。

コンテナの起動後、 /etc/hosts を次のように変更します。

x.x.x.x server.freeipa.local

この変更を行わない場合は、DNSサーバーを設定する必要があります。

SSSDフェデレーション・プロバイダーがKeycloakで起動して実行されるように、LinuxマシンをIPAドメインに登録する必要があります。

ipa-client-install --mkhomedir -p admin -w password

期待どおりにすべてが機能していることを確認するには、クライアント・マシンで次のコマンドを実行します。

kinit admin

パスワードの入力が求められます。その後、次のコマンドを使用してIPAサーバーにユーザーを追加できます。

$ ipa user-add john --first=John --last=Smith --email=john@smith.com --phone=042424242 --street="Testing street" \ --city="Testing city" --state="Testing State" --postalcode=0000000000

14.3.2. SSSDとD-Bus

前述のように、フェデレーション・プロバイダーはD-BUSを使用してSSSDからデータを取得し、 PAM を使用して認証が行われます。

まず、sssd-dbusのRPMをインストールする必要があります。これにより、SSSDからの情報をシステムバス経由で送ることができます。

$ sudo yum install sssd-dbus

Keycloak配布物から提供されているプロビジョニング・スクリプトを実行する必要があります。

$ bin/federation-sssd-setup.sh

このスクリプトは /etc/sssd/sssd.conf に必要な変更を行います。

...
ldap_user_extra_attrs = mail:mail, sn:sn, givenname:givenname, telephoneNumber:telephoneNumber
...
[sssd]
services = nss, sudo, pam, ssh, ifp
...
[ifp]
allowed_uids = root, yourOSUsername
user_attributes = +mail, +telephoneNumber, +givenname, +sn

また、 /etc/pam.d/ の下に keycloak ファイルが組み込まれています。

auth required pam_sss.so account required pam_sss.so

dbus-send を実行することで、すべてが期待どおりに動作していることを確認してください。

sudo dbus-send --print-reply --system --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserGroups string:john

そのユーザーのグループを確認することができるはずです。このコマンドでタイムアウトまたはエラーが返された場合、フェデレーション・プロバイダーはKeycloakで何も取得できないことを意味します。

ほとんどの場合、マシンがFreeIPA IdMサーバーに登録されていないか、SSSDサービスへのアクセス許可がないために発生します。

アクセス許可がない場合は、Keycloakを実行しているユーザーが次の節の /etc/sssd/sssd.conf ファイルに含まれていることを確認してください。

allowed_uids = root, your_username

14.3.3. SSSDフェデレーション・プロバイダーの有効化

KeycloakはDBus-Javaを使用して、D-Busと低レベルで通信します。これは Unixソケット・ライブラリに依存します。

このライブラリのRPMは、このリポジトリにあります。インストールする前に、必ずRPM署名を確認してください。

$ rpm -K libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm: Header V4 RSA/SHA256 Signature, key ID 84dc9914: OK Header SHA1 digest: OK (d17bb7ebaa7a5304c1856ee4357c8ba4ec9c0b89) V4 RSA/SHA256 Signature, key ID 84dc9914: OK MD5 digest: OK (770c2e68d052cb4a4473e1e9fd8818cf) $ sudo yum install libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm

PAMによる認証では、KeycloakはJNAを使用します。このパッケージがインストールされていることを確認してください。

$ sudo yum install jna

sssctl user-checks コマンドを使って設定を確認してください。

$ sudo sssctl user-checks admin -s keycloak

14.4. フェデレーションSSSDストアの設定

インストール後、フェデレーションSSSDストアを設定する必要があります。

フェデレーションSSSDストアを設定するには、次の手順を実行します。

管理コンソールに移動します。
左のメニューから User Federation を選択します。
Add Provider ドロップダウン・リストから、 sssd を選択します。sssd設定ページが開きます。
Save をクリックします。

FreeIPA/IdMのクレデンシャルを使用してKeycloakに対して認証できます。

14.5. カスタム・プロバイダー

Keycloakには独自のカスタム・プロバイダーを作成するために使用できるユーザー・ストレージ・フェデレーション用のSPIがあります。このドキュメントは、Server Developer Guideから参照できます。

15. 監査とイベント

Keycloakは豊富な監査機能を提供します。すべてのログイン・アクションの記録をデータベースに格納し、管理コンソールで確認することができます。すべての管理アクションを記録してレビューすることもできます。プラグインがこれらのイベントを待ち受けて何らかのアクションを実行できるListener SPIもあります。ビルトインのリスナーには、単純なログファイルと、イベントが発生した場合に電子メールを送信する機能が含まれています。

15.1. ログインイベント

ログインイベントは、ユーザーが正常にログインしたとき、誰かが間違ったパスワードを入力したとき、またはユーザー・アカウントが更新されたときなどに発生します。ユーザーに起こるすべてのイベントを記録して表示することができます。デフォルトでは、イベントは保存されず、管理コンソールに表示されることもありません。エラーイベントのみがコンソールとサーバーのログファイルに記録されます。永続化を開始するには、ストレージを有効にする必要があります。左側の Events メニュー項目に行き、 Config タブを選択してください。

Event Configuration

イベントの保存を開始するには、 Login Events Settings の Save Events スイッチをオンにする必要があります。

イベントの保存

Saved Types フィールドでは、イベントストアに保存するイベントタイプを指定することができます。 Clear events ボタンで、データベース内のすべてのイベントを削除できます。 Expiration フィールドでは、イベントを保存する期間を指定することができます。ログインイベントの保存を有効にして設定を決定したら、このページの下部にある Save ボタンをクリックすることを忘れないでください。

イベントを表示するには、 Login Events タブに移動します。

ログインイベント

見てのとおり、多くの情報が保存されています。すべてのイベントを保存している場合は、ログイン・アクションごとに多数のイベントが保存されています。このページの Filter ボタンを使用すると、実際に関心のあるイベントをフィルタリングすることができます。

ログインイベント・フィルター

このスクリーンショットでは、 Login イベントのみをフィルタリングしています。 Update ボタンをクリックするとフィルターが実行されます。

15.1.1. イベントの種類

ログインイベント：

Login - ユーザーがログインしました。
Register - ユーザーが登録しました。
Logout - ユーザーがログアウトしました。
Code to Token - アプリケーション/クライアントがコードをトークンに交換しました。
Refresh Token - アプリケーション/クライアントがトークンをリフレッシュしました。

アカウントイベント：

Social Link - アカウントはソーシャル・プロバイダーにリンクされました。
Remove Social Link - ソーシャル・プロバイダーがアカウントから削除されました。
Update Email - アカウントのメールアドレスが変更されました。
Update Profile - アカウントのプロファイルが変更されました。
Send Password Reset - パスワードリセット・メールが送信されました。
Update Password - アカウントのパスワードが変更されました。
Update TOTP - アカウントのTOTP設定が変更されました。
Remove TOTP - TOTPがアカウントから削除されました。
Send Verify Email - メールアドレス検証のメールが送信されました。
Verify Email - アカウントのメールアドレスが検証されました。

すべてのイベントに対応するエラーイベントがあります。

15.1.2. イベントリスナー

イベントリスナーは、イベントを待ち受け、そのイベントに基づいてアクションを実行します。 Keycloakにはロギング・イベントリスナーと電子メール・イベントリスナーの2つのビルトインのリスナーがあります。

ロギング・イベントリスナーは、エラーイベントが発生したときにログファイルに書き込みます。デフォルトで有効になっています。次に、ログメッセージの例を示します。

11:36:09,965 WARN [org.keycloak.events] (default task-51) type=LOGIN_ERROR, realmId=master,
 clientId=myapp,
 userId=19aeb848-96fc-44f6-b0a3-59a17570d374, ipAddress=127.0.0.1,
 error=invalid_user_credentials, auth_method=openid-connect, auth_type=code,
 redirect_uri=http://localhost:8180/myapp,
 code_id=b669da14-cdbb-41d0-b055-0810a0334607, username=admin

このロギングは、Fail2Banのようなツールを使用して、ユーザーのパスワードを推測しようとしているハッカーのボットがあるかどうかを検出する場合に非常に便利です。 LOGIN_ERROR のログファイルを解析してIPアドレスを抜き出すことができます。その後、攻撃を防ぐことができるように、この情報をFail2Banに与えます。

電子メール・イベントリスナーは、イベントが発生したときにユーザーのアカウントに電子メールを送信します。電子メール・イベントリスナーは、現時点で次のイベントのみをサポートしています。

ログインエラー
Update Password
TOTPの更新
TOTPの削除

電子メールリスナーを有効にするには Config タブに行き、 Event Listeners フィールドをクリックしてください。これにより、電子メールを選択できるドロップダウン・リストボックスが表示されます。

1つまたは複数のイベントを除外するには、配布物に付属している`standalone.xml`、` standalone-ha.xml`、 `domain.xml`を編集して、次のように追加します。

<spi name="eventsListener">
 <provider name="email" enabled="true">
 <properties>
 <property name="exclude-events" value="[&quot;UPDATE_TOTP&quot;,&quot;REMOVE_TOTP&quot;]"/>
 </properties>
 </provider>
</spi>

standalone.xml 、 standalone-ha.xml 、 domain.xml ファイルがどこにあるかの詳細は Server Installation and Configuration Guide を参照してください。

15.2. 管理イベント

管理コンソール内で管理者が実行するアクションは、監査目的で記録できます。管理コンソールは、Keycloak RESTインターフェイスを使用して管理機能を実行します。Keycloakは、これらのREST呼び出しを監査します。結果のイベントは、管理コンソールで表示できます。

管理者のアクションの監査を有効にするには、左側の Events メニュー項目で、 Config タブを選択します。

Event Configuration

Admin Events Settings セクションで Save Events スイッチをオンにします。

管理イベントの設定

admin events settings

Include Representation スイッチには、管理REST APIを介して送信される任意のJSONドキュメントが含まれます。これにより、管理者が行ったことを正確に表示できますが、多くの情報がデータベースに保存されることになる可能性があります。 Clear admin events ボタンを押すと、保存されている現在の情報を消去することができます。

管理イベントを表示するには、 Admin Events タブをクリックします。

管理イベント

admin events

Details カラムに Representation ボックスがある場合、それをクリックして、その操作で送られたJSONを表示することができます。

管理イベントの表現

admin events representation

Filter ボタンをクリックすることで、興味のあるイベントをフィルタリングすることもできます。

管理イベントのフィルター

admin events filter

16. エクスポートとインポート

Keycloakには、データベース全体をエクスポートおよびインポートする機能があります。これは、Keycloakデータベース全体をある環境から別の環境に移行する場合や、別のデータベース（MySQLからOracleなど）に移行する場合に特に便利です。エクスポートとインポートはサーバーの起動時にトリガーされ、そのパラメーターはJavaのシステム・プロパティーを介して渡されます。インポートとエクスポートはサーバーの起動時に行われるため、この間にサーバーまたはデータベースに対して、他には何もしないように注意することが重要です。

次のどちらかでデータベースをエクスポート/インポートすることができます。

ローカル・ファイルシステム上のディレクトリー
ファイルシステム上の単一のJSONファイル

ディレクトリー方式を使用してインポートする場合、ファイルは以下で指定された命名規則に従う必要があることに注意してください。以前にエクスポートしたファイルをインポートする場合、ファイルはすでにこの規則に従っています。

"acme-roadrunner-affairs"という名前のレルムのための"acme-roadrunner-affairs-realm.json"のような<REALM_NAME>-realm.json
"acme-roadrunner-affairs"という名前のレルムのユーザーファイルの1つ目のための"acme-roadrunner-affairs-users-0.json"のような<REALM_NAME>-users-<INDEX>.json

ディレクトリーにエクスポートする場合は、各JSONファイルに格納されるユーザー数を指定することもできます。

データベースにより多くのユーザー（500以上）が存在する場合、単一のファイルではなくディレクトリーにエクスポートすることを強くお勧めします。1つのファイルにエクスポートすると、非常に大きなファイルになる可能性があります。また、ディレクトリー・プロバイダーは、各 "ページ"（ユーザーとのファイル）ごとに個別のトランザクションを使用しており、パフォーマンスが大幅に向上します。ファイル（およびトランザクション）あたりのユーザーのデフォルト数は50で、これが最高のパフォーマンスを示しましたが、上書きすることもできます（下記参照）。 1つのファイルにエクスポートすると、エクスポート全体で1つのトランザクションが使用され、インポート全体においても1つのトランザクションが使用されることになります。その結果、大量のユーザーだとパフォーマンスが低下します。

暗号化されていないディレクトリーにエクスポートするには、次のようにします。

bin/standalone.sh -Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=<DIR TO EXPORT TO>

同様にインポートするには export の代わりに -Dkeycloak.migration.action=import を使います。単一のJSONファイルにエクスポートするには、以下を使用できます。

bin/standalone.sh -Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO EXPORT TO>

インポートの例を次に示します。

bin/standalone.sh -Dkeycloak.migration.action=import
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO IMPORT>
-Dkeycloak.migration.strategy=OVERWRITE_EXISTING

その他の利用可能なオプションは次のとおりです。

-Dkeycloak.migration.realmName

このプロパティは、すべてのレルムではなく、指定されたレルムを1つだけエクスポートする場合に使用されます。指定しないと、すべてのレルムがエクスポートされます。

-Dkeycloak.migration.usersExportStrategy

このプロパティは、ユーザーのエクスポート先を指定するために使用します。可能な値は次のとおりです。

DIFFERENT_FILES - ユーザーはファイルごとの最大ユーザー数に応じて異なるファイルにエクスポートされます。これはデフォルト値です。
SKIP - ユーザーのエクスポートは完全にスキップされます。
REALM_FILE - すべてのユーザーは、レルム設定とともに同じファイルにエクスポートされます。（レルムデータとユーザーの両方を含む "foo-realm.json" のようなファイルになります。）
SAME_FILE - すべてのユーザーは同じファイルにエクスポートされますが、レルムファイルとは別になります。（レルムデータを含む "foo-realm.json" とユーザーを含む "foo-users.json" のようなファイルになります。）

-Dkeycloak.migration.usersPerFile

このプロパティは、ファイルごとの（およびDBトランザクションごとの）ユーザー数を指定するために使用されます。デフォルトでは50です。 DIFFERENT_FILESの場合にのみ使用されます。

-Dkeycloak.migration.strategy

このプロパティはインポート時に使用されます。データをインポートするデータベースに、同じ名前のレルムがすでに存在する場合、どのように進めるかを指定するために使用できます。可能な値は次のとおりです。

IGNORE_EXISTING - この名前のレルムがすでに存在する場合は、インポートを無視します。
OVERWRITE_EXISTING - 既存のレルムを削除し、新しいデータをJSONファイルから再度インポートします。ある環境を別の環境に完全に移行し、新しい環境に古い環境と同じデータが含まれていることを保障したい場合には、これを指定します。

これまでにエクスポートされていないレルムファイルをインポートする場合、 keycloak.import オプションを使用することができます。複数のレルムファイルをインポートする必要がある場合は、ファイル名のカンマ区切りリストを指定できます。これは、masterレルムが初期化された後にのみ行われるため、前の場合よりも適切です。例：

-Dkeycloak.import=/tmp/realm1.json
-Dkeycloak.import=/tmp/realm1.json,/tmp/realm2.json

16.1. 管理コンソールのエクスポート/インポート

ほとんどのリソースのインポートは、ほとんどのリソースのエクスポートと同様に、管理コンソールから実行することができます。ユーザーのエクスポートはサポートされていません。

注意：エクスポート・ファイルの中の機密情報または個人情報を含む属性は、マスクされます。管理コンソールから取得したエクスポート・ファイルは、バックアップやサーバー間のデータ転送には適切ではありません。ブート時のエクスポートだけが、それらに対して適切です。

"スタートアップ" エクスポート中に作成されたファイルは、管理UIからインポートするために使用することもできます。これにより、あるレルムからエクスポートして別のレルムにインポートすることができます。また、あるサーバーからエクスポートして別のサーバーにインポートすることもできます。注：管理コンソールのエクスポート/インポートでは、ファイルごとに1つのレルムしか使用できません。

管理コンソールのインポートによって、選択した場合にリソースを上書きすることができます。この機能は、特に実動システムでは注意して使用してください。管理コンソールのエクスポート操作からのエクスポートした.jsonファイルは、シークレットに対して無効な値が含まれているため、通常データのインポートには適切ではありません。

管理コンソールのエクスポートでは、クライアント、グループ、およびロールをエクスポートできます。レルム内にこれらの数が多い場合、操作には時間がかかることがあります。この間、サーバーはユーザーのリクエストに応答しない可能性があります。この機能は、特にプロダクション・システムでは注意して使用してください。

17. ユーザー・アカウント・サービス

Keycloakには、すべてのユーザーがアクセスできるビルトインのユーザー・アカウント・サービスがあります。このサービスでは、ユーザーはアカウントの管理、クレデンシャルの変更、プロファイルの更新、ログイン・セッションの表示を行うことができます。このサービスのURLは <server-root>/auth/realms/{realm-name}/account です。

アカウント・サービス

最初のページはユーザーのプロファイル（左メニュー項目の Account ）です。ここでは、自分自身に関する基本データを指定します。この画面を拡張して、ユーザーが追加の属性を管理できるようにすることができます。詳細については、Server Developer Guideを参照してください。

左メニュー項目の Password では、ユーザーが自身のパスワードを変更できます。

パスワードの更新

account service password

メニュー項目の Authenticator は、ユーザーの要望に応じてOTPを設定することを可能にします。これは、OTPがレルムの有効な認証メカニズムである場合にのみ表示されます。ユーザーには、OTPジェネレータとしてモバイルデバイスに FreeOTP または Google Authenticator をインストールする手順が提供されます。スクリーンショットに表示されるQRコードは、FreeOTPまたはGoogle Authenticatorのモバイル・アプリケーションでスキャンして、すばやく簡単に設定できます。

OTP Authenticator

account service authenticator

メニュー項目の Federated Identity は、ユーザが自分のアカウントをアイデンティティー・ブローカーとリンクすることを可能にします（これは通常、ソーシャル・プロバイダー・アカウントをリンクするために使用されます）。これにより、レルムに設定した外部アイデンティティー・プロバイダーのリストが表示されます。

Federated Identity

account service federated identity

メニュー項目の Sessions を使用すると、どのデバイスでどこからログインしているかを表示して管理することができます。これらのセッションのログアウトもこの画面から実行できます。

Sessions

account service sessions

メニュー項目の Applications は、どのアプリケーションにアクセス権があるのかを表示します。

Applications

account service apps

17.1. テーマ設定が可能

KeycloakのすべてのUIと同様に、ユーザー・アカウント・サービスは完全にテーマ設定が可能であり、国際化も可能です。詳細については、Server Developer Guideのリンクを参照してください。

18. 脅威モデルの緩和

この章では、認証サーバーが持つ可能性のあるセキュリティ脆弱性と、Keycloakがどのようにこれらの脆弱性を緩和するかについてご説明します。潜在的な脆弱性のよいリストと、それらを緩和するためにセキュリティ実装が行うべきことは、IETFによって出された OAuth 2.0脅威モデルの文書に記載されています。これらの脆弱性の多くはここで説明されています。

18.1. Host

Keycloakは、リクエストURLをさまざまな用途に使用します。たとえば、パスワード・リセット・メールで送信されるURLです。

デフォルトでは、リクエストURLは Host ヘッダーに基づいており、このURLが有効で正しいURLであることを確認するチェックはありません。

無効なホストヘッダーを防ぐために、Keycloakの前にロードバランサーまたはプロキシを使用していない場合は、受け入れるURLを明示的に設定する必要があります。

次の例では、 localhost.localdomain または localhost へのリクエストのみを許可します。

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    <server name="default-server" default-host="ignore">
        ...
        <host name="default-host" alias="localhost.localdomain, localhost">
            <location name="/" handler="welcome-content"/>
            <http-invoker security-realm="ApplicationRealm"/>
        </host>
    </server>
</subsystem>

デフォルトの設定から行われた変更は、属性 default-host="ignore" の追加と、属性 alias の更新です。 default-host="ignore" は不明なホストが処理されることを防ぎますが、 alias は受け入れられたホストの一覧化に使われます。

CLIコマンドを使用した同等の設定は以下になります。

/subsystem=undertow/server=default-server:write-attribute(name=default-host,value=ignore)
/subsystem=undertow/server=default-server/host=default-host:write-attribute(name=alias,value=[localhost.localdomain, localhost]

:reload

18.2. 管理エンドポイントと管理コンソール

Keycloak管理REST APIとWebコンソールは、非管理用途と同じポートにデフォルトで公開されています。Keycloakをインターネットで公開している場合は、管理エンドポイントをインターネットに公開しないことをお勧めします。

これは、Keycloakで直接行うことも、Apacheやnginxなどのプロキシで行うこともできます。

プロキシ・オプションについては、プロキシのマニュアルを参照してください。 /auth/admin へのリクエストのアクセスを制御する必要があります。

これをKeycloakで直接実現するには、いくつかのオプションがあります。このドキュメントでは、IP制限とポートの分離の2つのオプションについて説明します。

18.2.1. IP制限

/auth/admin へのアクセスを特定のIPアドレスだけに制限することが可能です。

次の例では、 /auth/admin へのアクセスを 10.0.0.1 から 10.0.0.255 の範囲のIPアドレスに制限しています。

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    ...
    <server name="default-server">
        ...
        <host name="default-host" alias="localhost">
            ...
            <filter-ref name="ipAccess"/>
        </host>
    </server>
    <filters>
        <expression-filter name="ipAccess" expression="path-prefix('/auth/admin') -> ip-access-control(acl={'10.0.0.0/24 allow'})"/>
    </filters>
    ...
</subsystem>

CLIコマンドを使用した同等の設定は以下になります。

/subsystem=undertow/configuration=filter/expression-filter=ipAccess:add(,expression="path-prefix[/auth/admin] -> ip-access-control(acl={'10.0.0.0/24 allow'})")
/subsystem=undertow/server=default-server/host=default-host/filter-ref=ipAccess:add()

IP制限において、プロキシを使用している場合は、プロキシのIPアドレスではなく、クライアントのIPアドレスでKeycloakが受け取るようにIPを正しく設定することが重要です。

18.2.2. ポート制限

/auth/admin をインターネットに公開されていない別のポートに公開することが可能です。

次の例では、 /auth/admin をポート` 8444` で公開しますが、デフォルトポート 8443 ではアクセスを許可しません。

<subsystem xmlns="urn:jboss:domain:undertow:4.0">
    ...
    <server name="default-server">
        ...
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <https-listener name="https-admin" socket-binding="https-admin" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
            ...
            <filter-ref name="portAccess"/>
        </host>
    </server>
    <filters>
        <expression-filter name="portAccess" expression="path-prefix('/auth/admin') and not equals(%p, 8444) -> response-code(403)"/>
    </filters>
    ...
</subsystem>

...

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
    ...
    <socket-binding name="https" port="${jboss.https.port:8443}"/>
    <socket-binding name="https-admin" port="${jboss.https.port:8444}"/>
    ...
</socket-binding-group>

CLIコマンドを使用した同等の設定は以下になります。

/socket-binding-group=standard-sockets/socket-binding=https-admin/:add(port=8444)

/subsystem=undertow/server=default-server/https-listener=https-admin:add(socket-binding=https-admin, security-realm=ApplicationRealm, enable-http2=true)

/subsystem=undertow/configuration=filter/expression-filter=portAccess:add(,expression="path-prefix('/auth/admin') and not equals(%p, 8444) -> response-code(403)")
/subsystem=undertow/server=default-server/host=default-host/filter-ref=portAccess:add()

18.3. パスワード推測：ブルートフォース攻撃

ブルートフォース攻撃は、攻撃者がユーザーのパスワードを推測しようとしているときに発生します。Keycloakにはいくつかの限定的なブルートフォースの検出機能があります。オンにすると、ログイン失敗のしきい値に達した場合に、ユーザー・アカウントが一時的に無効になります。この機能を有効にするには、左側のメニューの Realm Settings に移動し、 Security Defenses タブをクリックし、さらに Brute Force Detection サブタブに移動します。

ブルートフォース検出

brute force

Failure Reset Time の期間中に Max Login Failures を超えるログイン失敗があった場合、アカウントは一時的に、 Wait Increment に超過した回数分を掛けた時間の間、無効にされます。 Failure Reset Time が経過すると、失敗はすべてクリアされます。 Max Wait は、アカウントが無効にされる最大時間です。もう1つの予防策として、あるアカウントに対して人間が行うにしては早すぎるログイン失敗が続いた場合に、アカウントが無効にされます。これは Quick Login Check Milli Seconds 値によって制御されます。その値の間に同じアカウントに対して2回のログイン失敗があった場合、アカウントは Minimum Quick Login Wait の間だけ無効になります。

Keycloakのブルートフォース検出の欠点は、サーバーがDoS攻撃に対して脆弱になることです。攻撃者が、自分の知っているアカウントのパスワード推測を試みるだけで、アカウントは無効になります。最終的には、ユーザーをブロックするかどうかを決定する際にクライアントのIPアドレスを考慮に入れるように、この機能を拡張する予定です。

より良いオプションは、 Fail2Ban のようなツールです。このサービスに、Keycloakサーバーのログファイルを指定できます。 Keycloakは、失敗したすべてのログイン失敗とクライアントIPアドレスを記録します。攻撃を検出した後、特定のIPアドレスからの接続をブロックするようにファイアウォールを変更するために、Fail2Banを使用できます。

18.3.1. パスワード・ポリシー

パスワード推測を防ぐために行うべきもう1つの作業は、推測が難しいパスワードをユーザーが選択するように、複雑なパスワードポリシーを持つことです。詳細については、パスワード・ポリシーの章を参照してください。

ただし、パスワードが推測されないようにする最善の方法は、ワンタイム・パスワード（OTP）を使用するようにサーバーを設定することです。

18.4. クリック・ジャッキング

クリック・ジャッキングは、悪意のあるサイトが標的サイトを透明なIFrameで読み込み、注意深く構築されたダミーボタンのセットを標的サイトの重要なボタンに位置するように上に重ねます。ユーザーが表示されているボタンをクリックすると、実際には隠されたページのボタン（"ログイン" ボタンなど）をクリックしています。攻撃者は、ユーザーの認証クレデンシャル情報を盗み、リソースにアクセスできます。

デフォルトでは、Keycloakによるすべてのレスポンスは、これが起こらないように特定のブラウザー・ヘッダーを設定します。具体的には、 X-FRAME_OPTIONS と Content-Security-Policy を設定します。細かい粒度のブラウザー・アクセスが制御できるので、これらのヘッダーの両方の定義を見てください。管理コンソールでは、これらのヘッダーに含める値を指定できます。左メニュー項目 Realm Settings に移動し、 Security Defenses タブをクリックし、 Headers サブタブにいることを確認します。

security headers

デフォルトでは、KeycloakはIFrameの same-origin ポリシーのみを設定します。

18.5. SSL/HTTPS要件

Keycloak認証サーバーとそれが保護するクライアントの間のすべての通信にSSL/HTTPSを使用しないと、中間者攻撃に非常に脆弱になります。OAuth 2.0/OpenID Connectはセキュリティのためにアクセストークンを使用します。SSL/HTTPSなしでは、攻撃者はネットワークを盗聴してアクセストークンを取得することができます。アクセストークンを取得すれば、トークンにアクセス許可が与えられたあらゆる操作を実行できます。

KeycloakはSSL/HTTPSの3つのモードを持っています。SSLは設定が難しいのですぐにセットアップできるように、Keycloakはデフォルトでlocalhost、192.168.x.x、その他のプライベートIPアドレスを介した非HTTPS通信を許可します。プロダクション環境では、SSLが有効になっており全面的に必要とされることを確認する必要があります。

アダプター/クライアント側では、Keycloakを使用してSSLトラスト・マネージャーを無効にすることができます。トラスト・マネージャーは、クライアントが通信している相手のアイデンティティーを保証します。DNSドメイン名をサーバーの証明書と照合してチェックします。プロダクション環境では、各クライアント・アダプターがトラストストアを使用するように設定されていることを確認する必要があります。そうでない場合、DNSの中間者攻撃に脆弱です。

18.6. CSRF攻撃

クロスサイト・リクエスト・フォージェリ（CSRF）は、ウェブサイトが信頼するユーザーまたは（HTTPリダイレクトやHTMLフォームを介して）認証されたユーザーからHTTPリクエストが送信される、ウェブベースの攻撃です。Cookieベースの認証を使用するサイトは、これらの種類の攻撃に対して脆弱です。これらの攻撃は、ポストされたフォームまたはクエリー・パラメーターとstate Cookieの状態を照合することによって緩和されます。

OAuth 2.0ログイン仕様では、state Cookieを使用し、送信されたstateパラメーターと照合する必要があります。Keycloakは仕様のこの部分を完全に実装しているので、すべてのログインが保護されます。

Keycloak管理コンソールは、バックエンドのKeycloak管理REST APIに対してREST呼び出しを行う純粋なJavaScript/HTML5アプリケーションです。これらの呼び出しはすべてベアラートークン認証を必要とし、JavaScript Ajax呼び出しによって行われます。CSRFはここでは適用されません。管理REST APIは、CORS Originを検証するように設定することもできます。

CSRFに実際に該当するKeycloakの唯一の部分は、ユーザー・アカウント管理ページです。これを緩和するため、Keycloakはstate Cookieを設定し、このstate Cookieの値をhiddenフォーム・フィールドまたはアクションリンクのクエリー・パラメーターに埋め込みます。このクエリーまたはフォームのパラメーターは、state Cookieと照合されて、呼び出しがユーザーによって行われたことを検証します。

18.7. 不特定のリダイレクトURI

認可コードフローでは、あまりにも一般的なリダイレクトURIを登録すると、不正なクライアントがより広い範囲のアクセス権を持つ別のクライアントに偽装する可能性があります。たとえば、2つのクライアントが同じドメインの下にある場合にこれが起こります。したがって、登録されたリダイレクトURIを可能な限り具体的なものにすることをお勧めします。

18.8. セキュリティ侵害されたアクセストークンとリフレッシュトークン

アクセストークンとリフレッシュトークンが盗まれることを軽減するためにできることがいくつかあります。最も重要なことは、Keycloakとそのクライアントとアプリケーションの間でSSL/HTTPS通信を強制することです。明らかなことだと思われるかもしれませんが、KeycloakはデフォルトでSSLが有効になっていないため、管理者はそれが必要であると認識していない可能性があります。

アクセストークンのリークを軽減するために実行できるもう1つの方法は、寿命を短くすることです。これはタイムアウト・ページ内で指定できます。短時間でクライアントとアプリケーションがアクセストークンをリフレッシュするように、アクセストークンは短い寿命（数分）とします。管理者がリークを検出した場合には、すべてのユーザー・セッションをログアウトしてこれらのリフレッシュトークンを無効にするか、失効ポリシーを設定することができます。リフレッシュトークンが常にクライアントでプライベートに保たれ、決して送信されないことを確認することは非常に重要です。

アクセストークンまたはリフレッシュトークンが侵害された場合、最初に行うべきことは管理コンソールに行き、not-before失効ポリシーをすべてのアプリケーションにプッシュすることです。これにより、その日時以前に発行されたトークンは無効になります。新しいnot-beforeポリシーを適用することで、アプリケーションがKeycloakから新しい公開鍵をダウンロードするように強制されるので、レルムの署名鍵が侵害されたと思われる場合にも有用です。より詳しい情報は鍵の章にあります。

特定のアプリケーション、クライアント、およびユーザーのいずれかが完全に侵害されたと思われる場合は、そのエンティティーを無効にすることもできます。

18.9. 侵害された認可コード

OIDC認可コードフローでは、攻撃者がKeycloak認可コードを侵害することは非常に困難です。Keycloakは、認可コードに対して暗号的に強いランダムな値を生成するので、アクセストークンを推測することは非常に困難です。認可コードは、アクセストークンを取得するために1回しか使用できません。管理コンソールのタイムアウト・ページで認可コードの有効期間を指定できます。この値は、実際には数秒と短く、クライアントがコードからトークンを取得するリクエストを行うのに十分な長さでなければなりません。

18.10. オープン・リダイレクター

攻撃者は、エンドユーザーの認可エンドポイントとリダイレクトURIパラメーターを使用して、認可サーバーをオープン・リダイレクターとして悪用する可能性があります。オープン・リダイレクターは、パラメーターを使用してユーザー・エージェントをパラメーター値で指定された場所に自動的にリダイレクトするエンドポイントです。攻撃者は、認可サーバーに対するユーザーの信頼を利用して、フィッシング攻撃を開始する可能性があります。

Keycloakは、登録されたすべてのアプリケーションとクライアントが少なくとも1つのリダイレクトURIパターンを登録することを要求します。クライアントがKeycloakにリダイレクト（ログインやログアウトなど）を依頼すると、KeycloakはリダイレクトURIと有効な登録済みURIパターンのリストをチェックします。オープン・リダイレクターの攻撃を軽減するために、クライアントとアプリケーションができるだけ具体的なURIパターンを登録することが重要です。

18.11. パスワード・データベースの侵害

Keycloakはパスワードを生のテキストで保存しません。PBKDF2アルゴリズムを使用して、それらのハッシュを保存します。実際には、デフォルトの20,000回のハッシング反復を使用します。これは、セキュリティ・コミュニティが推奨する反復回数です。設計上、PBKDF2が大量のCPUを浪費するため、システムにかなり大きな負荷がかかる可能性があります。パスワード・データベースをどの程度保護したいのかは、要件次第です。

18.12. スコープの制限

デフォルトでは、新しいクライアント・アプリケーションごとに無制限のスコープがあります。つまり、そのクライアント用に作成されたすべてのアクセストークンには、ユーザーが持つすべての権限が含まれます。クライアントが侵害されてアクセストークンが漏洩した場合、ユーザーがアクセス許可を持つ各システムも侵害されます。クライアントごとにスコープ・メニューを使用してアクセストークンが割り当てられるロールを制限することを強くお勧めします。

18.13. SQLインジェクション攻撃

現時点では、KeycloakのSQLインジェクションの脆弱性に関するナレッジはありません。

19. 管理CLI

前の章では、Keycloak管理コンソールを使用して管理タスクを実行する方法について説明しました。管理CLIツールを使用して、コマンドライン・インターフェイス（CLI）からこれらの管理タスクを実行することもできます。

19.1. 管理CLIのインストール

管理CLIは、Keycloakサーバーの配布物に含まれています。実行スクリプトは bin ディレクトリーにあります。

Linuxのスクリプトは kcadm.sh 、Windowsのスクリプトは kcadm.bat です。

Keycloakサーバー・ディレクトリーを PATH に追加することで、ファイルシステム上の任意の場所からクライアントを使用することができます。

以下に例を示します。

Linuxの場合：

$ export PATH=$PATH:$KEYCLOAK_HOME/bin
$ kcadm.sh

Windowsの場合：

c:\> set PATH=%PATH%;%KEYCLOAK_HOME%\bin
c:\> kcadm

KEYCLOAK_HOME 環境変数は、Keycloakサーバーの配布物を解凍したパスに設定されているものとします。

これ以降、繰り返しの説明を避けるため、CLIの違いが kcadm コマンド名だけである場合は、Windowsの例を示しています。

19.2. 管理CLIの利用

管理CLIは、管理RESTエンドポイントへのHTTPリクエストを作成することによって動作します。エンドポイントへのアクセスは保護されており、認証が必要です。

特定のエンドポイントのJSON属性の詳細については、Admin REST APIのドキュメントを参照してください。

クレデンシャルを提供すること、つまりログインすることで、認証セッションを開始します。作成、読み取り、更新、および削除（CRUD）操作を実行する準備ができました。

例えば

Linuxの場合：

$ kcadm.sh config credentials --server http://localhost:8080/auth --realm demo --user admin --client admin
$ kcadm.sh create realms -s realm=demorealm -s enabled=true -o
$ C=$(kcadm.sh create clients -r demorealm -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]' -i)
$ kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json

Windowsの場合：

c:\> kcadm config credentials --server http://localhost:8080/auth --realm demo --user admin --client admin
c:\> kcadm create realms -s realm=demorealm -s enabled=true -o
c:\> kcadm create clients -r demorealm -s clientId=my_client -s "redirectUris=[\"http://localhost:8980/myapp/*\"]" -i > clientid.txt
c:\> set /p CID=<clientid.txt
c:\> kcadm get clients/%CID%/installation/providers/keycloak-oidc-keycloak-json

プロダクション環境では、ネットワーク・スニファーによりトークンが漏洩しないように、Keycloakに https: でアクセスする必要があります。サーバーの証明書が、Javaのデフォルトの証明書トラストストアに含まれる信頼できる認証局（CA）のいずれかによって発行されていない場合は、 truststore.jks ファイルを準備し、管理CLIに使用するよう指示します。

以下に例を示します。
- Linuxの場合：
  $ kcadm.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks
- Windowsの場合：
  c:\> kcadm config truststore --trustpass %PASSWORD% %HOMEPATH%\.keycloak\truststore.jks

19.3. 認証

管理CLIでログインするときは、サーバーのエンドポイントURLとレルムを指定してから、ユーザー名を指定します。別のオプションはclientIdのみを指定することで、特別な「サービスアカウント」を使用することになります。ユーザー名を使用してログインするときは、指定したユーザーのパスワードを使用する必要があります。clientIdを使用してログインする場合、ユーザーのパスワードではなくクライアント・シークレットのみが必要です。また、クライアント・シークレットの代わりに Signed JWT を使用することもできます。

セッションに使用されるアカウントに、管理REST API操作を呼び出すための適切な権限があることを確認します。例えば、 realm-management クライアントの realm-admin ロールは、ユーザーが定義されているレルムを管理することを許可します。

認証には主に2つの機構があります。1つ目の機構は、kcadm config credentials を使用して認証セッションを開始します。

$ kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin

このアプローチは、取得したアクセストークンと関連するリフレッシュ・トークンを保存することによって、 kcadm コマンドの呼び出し間で認証されたセッションを維持します。また、プライベート設定ファイルに他のシークレットを保持することもできます。設定ファイルの詳細については、次の章を参照してください。

2番目のアプローチは、各コマンド呼び出しごとに認証する方法です。この方法は、サーバーへの負荷とトークンを取得するやり取りに費やされる時間を増加させます。利点としては、呼び出しの間にトークンを保存する必要がないため、何もディスクに保存されないことです。このモードは、 --no-config 引数が指定されている場合に使用されます。

たとえば、操作を実行するときに、認証に必要なすべての情報を指定します。

$ kcadm.sh get realms --no-config --server http://localhost:8080/auth --realm master --user admin --password admin

管理CLIの使用方法の詳細については、 kcadm.sh help コマンドを実行してください。

認証されたセッションの開始については、kcadm.sh config credentials --help コマンドを実行してください。

19.4. 代替設定の使用

デフォルトでは、管理CLIはユーザーのホーム・ディレクトリーにある kcadm.config という設定ファイルを自動的に維持します。Linuxベースのシステムでは、フルパス名は[filename]$HOME/.keycloak/kcadm.config です。 Windowsでは、フルパス名は %HOMEPATH%\.keycloak\kcadm.config です。 --config オプションを使うと、別のファイルや場所を指し示すことができるので、複数の認証されたセッションを並行して維持することができます。

単一のスレッドから単一の設定ファイルに結び付けられた操作を実行することが最善の方法です。

システム上の他のユーザーが設定ファイルを参照できないようにしてください。プライベートにしておくべきアクセストークンとシークレットが含まれています。デフォルトでは、~/.keycloak ディレクトリーとその内容は適切なアクセス制限で自動的に作成されます。ディレクトリーが既に存在する場合、そのパーミッションは更新されません。

特殊な状況で、シークレットを設定ファイルに保管しないようにする必要がある場合は、そうすることが可能です。この方法はあまり便利ではなく、トークン・リクエストが多くなります。シークレットを保存しないためには、すべてのコマンドで --no-config オプションを使用し、 config credentials コマンドで必要とされるすべての認証情報を kcadm 呼び出しごとに指定します。

19.5. 基本操作とリソースURI

管理CLIでは、特定のタスクの実行を簡略化するために追加されたコマンドを使用して、管理REST APIエンドポイントに対してCRUD操作を実行できます。

主な使用パターンを以下に示します。 create 、 get 、 update 、 delete コマンドは、それぞれHTTP動詞の POST 、 GET 、 PUT 、 DELETE に該当します。

$ kcadm.sh create ENDPOINT [ARGUMENTS]
$ kcadm.sh get ENDPOINT [ARGUMENTS]
$ kcadm.sh update ENDPOINT [ARGUMENTS]
$ kcadm.sh delete ENDPOINT [ARGUMENTS]

ENDPOINTはターゲット・リソースURIであり、 http: または https: で始まる絶対URL、もしくは相対URLで、次の形式の絶対URLを構成するために使用されます。

SERVER_URI/admin/realms/REALM/ENDPOINT

たとえば、http://localhost:8080/authのサーバーに対して認証し、レルムが master の場合、エンドポイントとして users を使用すると、リソースURLはhttp://localhost:8080/auth/admin/realms/master/usersとなります。

エンドポイントに clients を設定すると、有効なリソースURIはhttp://localhost:8080/auth/admin/realms/master/clientsになります。

レルムのコンテナーであるため、少し異なる方法で扱われる realms エンドポイントがあります。このエンドポイントは次のようになります。

SERVER_URI/admin/realms

同様のエンドポイントとして、serverinfo エンドポイントも存在します。

レルムの管理者権限を持つユーザーとして認証する場合は、複数のレルムでコマンドを実行する必要があります。その場合、 -r オプションを指定して、どのレルムに対してコマンドを実行するかを明示的に指示します。 kcadm.sh config credentials の --realm オプションで指定した REALM を使う代わりに TARGET_REALM が使われます。

SERVER_URI/admin/realms/TARGET_REALM/ENDPOINT

例えば

$ kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin --password admin
$ kcadm.sh create users -s username=testuser -s enabled=true -r demorealm

この例では、 master レルムの admin ユーザーとして認証されたセッションを開始します。その後、リソースURL http://localhost:8080/auth/admin/realms/demorealm/users に対してPOST呼び出しを実行します。

create と update コマンドは、デフォルトでJSON本体をサーバーに送信します。 -f FILENAME を使うと、ファイルから作成しておいたJSONを読みこむことができます。 -f - オプションを使うことができる場合、メッセージ本文は標準入力から読み込まれます。前の create users の例に見られるように、個々の属性とその値を指定することもできます。それらはJSONで構成され、サーバーに送信されます。

update コマンドを使ってリソースを更新する方法はいくつかあります。リソースの現在の状態をファイルに保存し、そのファイルを編集してサーバーに送信することで更新できます。

例：

$ kcadm.sh get realms/demorealm > demorealm.json
$ vi demorealm.json
$ kcadm.sh update realms/demorealm -f demorealm.json

この方法は、送信されたJSONドキュメントのすべての属性を使用してサーバー上のリソースを更新します。

もう1つの方法は、 -s, --set オプションにより、新しい値を設定して更新することです。

例：

$ kcadm.sh update realms/demorealm -s enabled=false

これは enabled 属性を false に更新するだけです。

デフォルトでは、 update コマンドは最初に get を実行し、新しい属性値を既存の値とマージします。これが推奨動作です。場合によっては、エンドポイントは PUT コマンドをサポートすることができますが、 GET コマンドはサポートしない場合があります。 -n オプションを使用して、 GET コマンドを最初に実行することなく PUT コマンドを実行する"マージしない"更新を実行することができます。

19.6. レルム操作

新しいレルムを作成する

realms エンドポイントで create コマンドを使用して新しいレルムを作成し、 realm と enabled に属性を設定します。

$ kcadm.sh create realms -s realm=demorealm -s enabled=true

レルムはデフォルトで有効になっていません。有効にすることで、認証のためにレルムをすぐに使用できます。

新しいオブジェクトの説明は、JSON形式で記述することもできます。

$ kcadm.sh create realms -f demorealm.json

レルム属性を持つJSONドキュメントをファイルや標準入力のパイプから直接送信することもできます。

以下に例を示します。

Linuxの場合：

$ kcadm.sh create realms -f - << EOF
{ "realm": "demorealm", "enabled": true }
EOF

Windowsの場合：

c:\> echo { "realm": "demorealm", "enabled": true } | kcadm create realms -f -

既存レルムの一覧表示

次のコマンドは、すべてのレルムの一覧を返します。

$ kcadm.sh get realms

レルムの一覧は、サーバー上でフィルターされ、ユーザーが見ることができるレルムだけを返します。

レルムの詳細全体を取得することができますが、レルム名やレルムが有効かどうかなど、一部の属性のみ取得したい場合があります。 --fields オプションを使用すると、返す属性を指定することができます。

$ kcadm.sh get realms --fields realm,enabled

結果をカンマ区切りの値として表示することもできます。

$ kcadm.sh get realms --fields realm --format csv --noquotes

特定のレルムを取得する

コレクションURIにレルム名を指定し、個々のレルムを取得することができます。

$ kcadm.sh get realms/master

レルムの更新

レルムの属性の一部だけを変更したい場合は、 -s オプションを使用して属性の新しい値を設定します。

例：
```
$ kcadm.sh update realms/demorealm -s enabled=false
```
書き込み可能なすべての属性を新しい値に設定するには、 get コマンドを実行し、JSONファイルの現在の値を編集して送信します。

例：
```
$ kcadm.sh get realms/demorealm > demorealm.json
$ vi demorealm.json
$ kcadm.sh update realms/demorealm -f demorealm.json
```

レルムの削除

レルムを削除するには、次のコマンドを実行します。

$ kcadm.sh delete realms/demorealm

レルムのすべてのログイン・ページ・オプションを有効にする

特定の機能を制御する属性を true に設定します。

例：

$ kcadm.sh update realms/demorealm -s registrationAllowed=true -s registrationEmailAsUsername=true -s rememberMe=true -s verifyEmail=true -s resetPasswordAllowed=true -s editUsernameAllowed=true

レルム鍵の一覧表示

対象レルムの keys エンドポイントで get 操作を使用してください。

$ kcadm.sh get keys -r demorealm

新しいレルム鍵の生成

新しいRSA生成キーペアを追加する前に、対象レルムのIDを取得します。

例：
```
$ kcadm.sh get realms/demorealm --fields id --format csv --noquotes
```

kcadm.sh get keys -r demorealm で取得した既存のプロバイダーよりも優先度の高い、新しい鍵プロバイダーを追加してください。

以下に例を示します。

Linuxの場合：

$ kcadm.sh create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keySize=["2048"]'

Windowsの場合：

c:\> kcadm create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keySize=[\"2048\"]"

parentId 属性を対象レルムのIDの値に設定します。

新しく追加された鍵は、 kcadm.sh get keys -r demorealm によって取得したとおり、アクティブな鍵になります。

Javaキーストア・ファイルから新しいレルム鍵を追加する

新しい鍵プロバイダーを追加して、すでにサーバー上にJKSファイルとして用意されている新しい鍵ペアを追加します。

以下に例を示します。

Linuxの場合：

$ kcadm.sh create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keystore=["/opt/keycloak/keystore.jks"]' -s 'config.keystorePassword=["secret"]' -s 'config.keyPassword=["secret"]' -s 'config.alias=["localhost"]'

Windowsの場合：

c:\> kcadm create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keystore=[\"/opt/keycloak/keystore.jks\"]" -s "config.keystorePassword=[\"secret\"]" -s "config.keyPassword=[\"secret\"]" -s "config.alias=[\"localhost\"]"

特定のキーストアに一致するように、 keystore 、 ` keystorePassword` 、keyPassword 、および alias の属性値を変更してください。
parentId 属性を対象レルムのIDの値に設定します。

鍵をパッシブにする、または無効にする

パッシブにしたい鍵を特定する
```
$ kcadm.sh get keys -r demorealm
```
鍵の providerId 属性を使用して、 components/PROVIDER_ID のようなエンドポイントURIを構築します。

update を実行します。

以下に例を示します。

Linuxの場合：

$ kcadm.sh update components/PROVIDER_ID -r demorealm -s 'config.active=["false"]'

Windowsの場合：

c:\> kcadm update components/PROVIDER_ID -r demorealm -s "config.active=[\"false\"]"

他のキー属性を更新することができます。

例えば、 config.enabled=["false"] のように、鍵を無効にするために enabled の値を設定してください。
鍵の優先度を変更するために新しい priority 値を設定します。たとえば、 config.priority=["110"] です。

古い鍵を削除する

削除している鍵がパッシブで無効になっていることを確認して、アプリケーションやユーザーが保持している既存のトークンを無効にします。
パッシブにする鍵を特定します。
```
$ kcadm.sh get keys -r demorealm
```
その鍵の providerId を使用して削除を行います。
```
$ kcadm.sh delete components/PROVIDER_ID -r demorealm
```

レルムのイベントログの設定

events/config エンドポイントで update コマンドを使用してください。

eventsListeners 属性には、イベントを受け取るすべてのイベントリスナーを指定するEventListenerProviderFactory IDのリストが含まれています。これとは別に、組み込みイベント・ストレージを制御する属性があり、管理REST APIを介して過去のイベントを照会することができます。eventsEnabled`と呼ばれるサービス呼び出しログと、`adminEventsEnabled と呼ばれる管理コンソールまたは管理REST APIをトリガーとするイベント監査という独立した制御があります。古いイベントの有効期限を設定してデータベースがいっぱいにならないようにすることができます。 eventsExpiration は有効期限を秒で表します。

ここでは、すべてのイベントを受け取り、jboss-loggingを通じてそれらを記録する組み込みのイベント・リスナーを設定する例を示します。 org.keycloak.events というロガーを使うと、エラー・イベントは WARN として記録され、他は`DEBUG` として記録されます。

以下に例を示します。

Linuxの場合：

$ kcadm.sh update events/config -r demorealm -s 'eventsListeners=["jboss-logging"]'

Windowsの場合：

c:\> kcadm update events/config -r demorealm -s "eventsListeners=[\"jboss-logging\"]"

次に、利用可能なすべてのERRORイベント（監査イベントを除く）の保管を2日間有効にする例を示します。

以下に例を示します。

Linuxの場合：

$ kcadm.sh update events/config -r demorealm -s eventsEnabled=true -s 'enabledEventTypes=["LOGIN_ERROR","REGISTER_ERROR","LOGOUT_ERROR","CODE_TO_TOKEN_ERROR","CLIENT_LOGIN_ERROR","FEDERATED_IDENTITY_LINK_ERROR","REMOVE_FEDERATED_IDENTITY_ERROR","UPDATE_EMAIL_ERROR","UPDATE_PROFILE_ERROR","UPDATE_PASSWORD_ERROR","UPDATE_TOTP_ERROR","VERIFY_EMAIL_ERROR","REMOVE_TOTP_ERROR","SEND_VERIFY_EMAIL_ERROR","SEND_RESET_PASSWORD_ERROR","SEND_IDENTITY_PROVIDER_LINK_ERROR","RESET_PASSWORD_ERROR","IDENTITY_PROVIDER_FIRST_LOGIN_ERROR","IDENTITY_PROVIDER_POST_LOGIN_ERROR","CUSTOM_REQUIRED_ACTION_ERROR","EXECUTE_ACTIONS_ERROR","CLIENT_REGISTER_ERROR","CLIENT_UPDATE_ERROR","CLIENT_DELETE_ERROR"]' -s eventsExpiration=172800

Windowsの場合：

c:\> kcadm update events/config -r demorealm -s eventsEnabled=true -s "enabledEventTypes=[\"LOGIN_ERROR\",\"REGISTER_ERROR\",\"LOGOUT_ERROR\",\"CODE_TO_TOKEN_ERROR\",\"CLIENT_LOGIN_ERROR\",\"FEDERATED_IDENTITY_LINK_ERROR\",\"REMOVE_FEDERATED_IDENTITY_ERROR\",\"UPDATE_EMAIL_ERROR\",\"UPDATE_PROFILE_ERROR\",\"UPDATE_PASSWORD_ERROR\",\"UPDATE_TOTP_ERROR\",\"VERIFY_EMAIL_ERROR\",\"REMOVE_TOTP_ERROR\",\"SEND_VERIFY_EMAIL_ERROR\",\"SEND_RESET_PASSWORD_ERROR\",\"SEND_IDENTITY_PROVIDER_LINK_ERROR\",\"RESET_PASSWORD_ERROR\",\"IDENTITY_PROVIDER_FIRST_LOGIN_ERROR\",\"IDENTITY_PROVIDER_POST_LOGIN_ERROR\",\"CUSTOM_REQUIRED_ACTION_ERROR\",\"EXECUTE_ACTIONS_ERROR\",\"CLIENT_REGISTER_ERROR\",\"CLIENT_UPDATE_ERROR\",\"CLIENT_DELETE_ERROR\"]" -s eventsExpiration=172800

保存されているイベントタイプを すべての利用可能なイベントタイプ にリセットする方法の例を次に示します。空のリストに設定することは、すべてを列挙することを意味します。

$ kcadm.sh update events/config -r demorealm -s enabledEventTypes=[]

次に、監査イベントの保存を有効にする方法の例を示します。

$ kcadm.sh update events/config -r demorealm -s adminEventsEnabled=true -s adminEventsDetailsEnabled=true

最新の100個のイベントを取得する方法を次に示します。新しいイベントから順番に並んでいます。

$ kcadm.sh get events --offset 0 --limit 100

保存されたすべてのイベントを削除する方法の例を次に示します。

$ kcadm delete events

キャッシュのフラッシュ

create コマンドと、 clear-realm-cache 、 clear-user-cache 、 clear-keys-cache のいずれかのエンドポイントを使用します。

realm を対象のレルムと同じ値に設定します。

例：

$ kcadm.sh create clear-realm-cache -r demorealm -s realm=demorealm
$ kcadm.sh create clear-user-cache -r demorealm -s realm=demorealm
$ kcadm.sh create clear-keys-cache -r demorealm -s realm=demorealm

19.7. ロール操作

レルムロールの作成

レルムロールを作成するには、 roles エンドポイントを使用します。

$ kcadm.sh create roles -r demorealm -s name=user -s 'description=Regular user with limited set of permissions'

クライアントロールの作成

クライアントロールを作成するときは、最初にクライアントを特定し、 get コマンドを使用して使用可能なクライアントを一覧表示します。
```
$ kcadm.sh get clients -r demorealm --fields id,clientId
```

clients/ID/roles のようなエンドポイントURIを構築するには、 clientId 属性を使用して新しいロールを作成します。

例：

$ kcadm.sh create clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles -r demorealm -s name=editor -s 'description=Editor can edit, and publish any article'

レルムロールの一覧表示

roles エンドポイントで get コマンドを使用して、既存のレルムロール一覧を取得します。

$ kcadm.sh get roles -r demorealm

get-roles コマンドを使用することもできます。

$ kcadm.sh get-roles -r demorealm

クライアントロールの一覧表示

レルムロールとクライアントロールを一覧表示するための専用の get-roles コマンドがあります。これは[command] `get`コマンドの拡張です。

クライアントロールを一覧表示するには、get-roles コマンドを使用します。 [command] clientId または [command] id 属性を渡すことで（ --cclientid または --cid オプションを介して）、クライアントを指定します。

例：

$ kcadm.sh get-roles -r demorealm --cclientid realm-management

特定のレルムロールを取得する

roles/ROLE_NAME のように特定のレルムロールのエンドポイントURIを構築するには、 get コマンドとロール name を使用します。ここで、 [filename]`user`は既存のロールです。

例：

$ kcadm.sh get roles/user -r demorealm

get-roles コマンドを使用することもできます。 --rolename オプションでロール名を渡すか、 --roleid オプションでIDを渡します。

例：

$ kcadm.sh get-roles -r demorealm --rolename user

特定のクライアントロールを取得する

専用の[command]get-roles コマンドを使用します。クライアントを識別するためにclientId属性（--cclientid`オプションで）またはID（[command]--cid`オプションで）を渡し、クライアントロールを識別するためにロール名（--rolename`オプションで）またはID（[command]--roleid`で）を渡します。

例：

$ kcadm.sh get-roles -r demorealm --cclientid realm-management --rolename manage-clients

レルムロールの更新

特定のレルムロールを取得するために使用したものと同じエンドポイントURIを指定して update コマンドを使用します。

例：

$ kcadm.sh update roles/user -r demorealm -s 'description=Role representing a regular user'

クライアントロールの更新

特定のロールを取得するために使用したのと同じエンドポイントURIを指定して update コマンドを使用します。

例：

$ kcadm.sh update clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles/editor -r demorealm -s 'description=User that can edit, and publish articles'

レルムロールの削除

特定のレルムロールを取得するために使用したものと同じエンドポイントURIを指定して delete コマンドを使用します。

例：

$ kcadm.sh delete roles/user -r demorealm

クライアントロールの削除

特定のクライアントロールを取得するために使用したものと同じエンドポイントURIを持つ delete コマンドを使用します。

例：

$ kcadm.sh delete clients/a95b6af3-0bdc-4878-ae2e-6d61a4eca9a0/roles/editor -r demorealm

複合ロールに割り当てられた、利用可能な、有効なレルムロールの一覧表示

専用の get-roles コマンドを使用して、複合ロールに割り当てられた、利用可能な、有効なレルムロールを一覧表示します。

複合ロールに 割り当てられた レルムロールを一覧表示するには、name（ --rname オプションで）またはID（ --rid オプションで）のいずれかで対象の複合ロールを指定します。

例：
```
$ kcadm.sh get-roles -r demorealm --rname testrole
```
有効な レルムロールをリストするには、 --effective オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --rname testrole --effective
```
複合ロールにまだ利用可能なレルムロールを一覧表示するには、 --available オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --rname testrole --available
```

複合ロールに割り当てられた、利用可能な、有効なクライアントロールの一覧表示

専用の get-roles コマンドを使用して、複合ロールに割り当てられた、利用可能な、有効なクライアントロールを一覧表示します。

複合ロールの 割り当てられた クライアントロールを一覧表示するには、 --rname オプションでロール名を指定するか、または --rid オプションでIDを指定します。また、クライアントを特定するために、 [command] --cclientid オプションでclientId属性、または [command]` --cid` オプションでIDのいずれかを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management
```
有効な レルムロールをリストするには、 --effective オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --effective
```
対象の複合ロールにまだ追加できるレルムロールを一覧表示するには、 --available オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --available
```

レルムロールを複合ロールに追加する

レルムロールとクライアントロールを追加するために使用できる専用の add-roles コマンドがあります。

user ロールを複合ロール testrole に追加する例を示します。

$ kcadm.sh add-roles --rname testrole --rolename user -r demorealm

複合ロールからレルムロールを削除する

レルムロールとクライアントロールを削除するための専用の remove-roles コマンドがあります。

次の例では、ターゲットの複合ロール testrole から user ロールを削除します。

$ kcadm.sh remove-roles --rname testrole --rolename user -r demorealm

レルムロールへのクライアントロールの追加

レルムロールとクライアントロールを追加するために使用できる専用の add-roles コマンドを使用します。

次の例では、 realm-management - create-client クライアントに定義されたロールと view-users ロールを複合ロール testrole に追加します。

$ kcadm.sh add-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users

クライアントロールへのクライアントロールの追加

get-roles コマンドを使用して複合クライアントロールのIDを特定します。

例：
```
$ kcadm.sh get-roles -r demorealm --cclientid test-client --rolename operations
```
test-client のclientId属性をもつクライアントと、 support というクライアントロール、および operations という別のクライアントロールがあり、IDが"fc400897-ef6a-4e8c-872b-1581b7fa8a71"という複合ロールになると仮定します。

次の例を使用して、複合ロールに別のロールを追加します。

$ kcadm.sh add-roles -r demorealm --cclientid test-client --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --rolename support

get-roles --all コマンドを使用して、複合ロールのロールを一覧表示します。

例：
```
$ kcadm.sh get-roles --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --all
```

複合ロールからのクライアントロールの削除

複合ロールからクライアントロールを削除するには、専用の remove-roles コマンドを使用します。

次の例を使用して、 realm management - create-client ロールと view-users ロールで定義された2つのクライアントロールを複合ロール testrole から削除します。

$ kcadm.sh remove-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users

19.8. クライアント操作

クライアントの作成

clients エンドポイントで create コマンドを実行して、新しいクライアントを作成します。

例：
```
$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true
```

認証するアダプターのシークレットを設定したい場合は、シークレットを指定します。

例：

$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true -s clientAuthenticatorType=client-secret -s secret=d0b8122f-8dfb-46b7-b68a-f5cc4e25d000

クライアントの一覧表示

クライアントの一覧を表示するには、 clients エンドポイントで get コマンドを使用します。

例：

$ kcadm.sh get clients -r demorealm --fields id,clientId

この例では、 id および clientId 属性のみを一覧出力するように、出力をフィルタリングしています。

特定のクライアントを取得する

クライアントのIDを使用して、 clients/ID のような特定のクライアントを対象とするエンドポイントURIを構築します。

例：

$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm

特定のクライアントの現在のシークレットの取得

クライアントのIDを使用して、 clients/ID/client-secret のようなエンドポイントURIを構築します。

例：

$ kcadm.sh get clients/$CID/client-secret

特定のクライアントのアダプター設定ファイル（keycloak.json）の取得

クライアントIDを使用して、 clients/ID/installation/providers/keycloak-oidc-keycloak-json のような特定のクライアントを対象とするエンドポイントURIを構築します。

例：

$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3/installation/providers/keycloak-oidc-keycloak-json -r demorealm

特定のクライアントのためのWildFlyサブシステム・アダプター設定の取得

クライアントIDを使用して、 clients/ID/installation/providers/keycloak-oidc-jboss-subsystem のような特定のクライアントを対象とするエンドポイントURIを構築します。

例：

$ kcadm.sh get clients/c7b8547f-e748-4333-95d0-410b76b3f4a3/installation/providers/keycloak-oidc-jboss-subsystem -r demorealm

クライアントの更新

特定のクライアントを取得するために使用したURIと同じエンドポイントURIで、 update コマンドを使用します。

以下に例を示します。

Linuxの場合：

$ kcadm.sh update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s enabled=false -s publicClient=true -s 'redirectUris=["http://localhost:8080/myapp/*"]' -s baseUrl=http://localhost:8080/myapp -s adminUrl=http://localhost:8080/myapp

Windowsの場合：

c:\> kcadm update clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm -s enabled=false -s publicClient=true -s "redirectUris=[\"http://localhost:8080/myapp/*\"]" -s baseUrl=http://localhost:8080/myapp -s adminUrl=http://localhost:8080/myapp

クライアントの削除

特定のクライアントを取得するのに使用したURIと同じエンドポイントURIで、 delete コマンドを使用します。

例：

$ kcadm.sh delete clients/c7b8547f-e748-4333-95d0-410b76b3f4a3 -r demorealm

19.9. ユーザー操作

ユーザーの作成

users エンドポイントで create コマンドを実行して、新しいユーザーを作成します。

例：

$ kcadm.sh create users -r demorealm -s username=testuser -s enabled=true

ユーザーの一覧表示

users エンドポイントを使用してユーザーをリストします。対象ユーザーは、次回のログイン時にパスワードを変更する必要があります。

例：

$ kcadm.sh get users -r demorealm --offset 0 --limit 1000

username 、 firstName 、 lastName 、 email でユーザーをフィルタリングできます。

例：

$ kcadm.sh get users -r demorealm -q email=google.com
$ kcadm.sh get users -r demorealm -q username=testuser

フィルタリングでは完全一致は使用されません。例えば、上記の例では、*testuser*` のパターンと username 属性の値が一致します。

複数の -q オプションを指定することで、複数の属性をフィルタリングすることもできます。このオプションは、すべての属性の条件に一致するユーザーのみを返します。

特定のユーザーを取得する

users/USER_ID などのエンドポイントURIを作成するには、ユーザーのIDを使用します。

例：

$ kcadm.sh get users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm

ユーザーの更新

特定のユーザーを取得するために使用したURIと同じエンドポイントURIで、 update コマンドを使用します。

以下に例を示します。

Linuxの場合：

$ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s 'requiredActions=["VERIFY_EMAIL","UPDATE_PROFILE","CONFIGURE_TOTP","UPDATE_PASSWORD"]'

Windowsの場合：

c:\> kcadm update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm -s "requiredActions=[\"VERIFY_EMAIL\",\"UPDATE_PROFILE\",\"CONFIGURE_TOTP\",\"UPDATE_PASSWORD\"]"

ユーザーの削除

特定のユーザーを取得するために使用したURIと同じエンドポイントURIで delete コマンドを使用します。

例：

$ kcadm.sh delete users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm

ユーザー・パスワードのリセット

専用の set-password コマンドを使用して、ユーザーのパスワードをリセットします。

例：

$ kcadm.sh set-password -r demorealm --username testuser --new-password NEWPASSWORD --temporary

このコマンドは、ユーザーの一時パスワードを設定します。対象ユーザーは、次回のログイン時にパスワードを変更する必要があります。

id 属性を使用してユーザーを指定する場合は、 --userid を使用できます。

users/USER_ID/reset-password のように、特定のユーザーを取得するために使用したユーザーIDで構築されたエンドポイントで update コマンドを使用しても同じ結果が得ることができます。

例：

$ kcadm.sh update users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2/reset-password -r demorealm -s type=password -s value=NEWPASSWORD -s temporary=true -n

最後のパラメーター -n は、 GET コマンドなしで PUT コマンドだけが実行されるようにします。この場合、 reset-password エンドポイントは GET をサポートしていないので指定が必要です。

ユーザーに割り当てられた、使用可能な、有効なレルムロールの一覧表示

専用の get-roles コマンドを使用して、ユーザーに割り当てられた、利用可能で、有効なレルムロールを一覧表示することができます。

ユーザーの 割り当てられた レルムロールを一覧表示するには、ユーザー名またはIDのどちらかを使用して対象ユーザーを指定します。

例：

$ kcadm.sh get-roles -r demorealm --uusername testuser

有効な レルムロールをリストするには、 --effective オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --uusername testuser --effective
```
ユーザーに利用可能なレルムロールを一覧表示するには、 --available オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --uusername testuser --available
```

ユーザーに割り当てられた、利用可能な、有効なクライアントロールの一覧表示

専用の get-roles コマンドを使用して、ユーザーに割り当てられた、利用可能で、有効なクライアントロールを一覧表示します。

ユーザーに 割り当てられた クライアントロールを一覧表示するには、--uusername オプションでユーザー名を指定するか、 --uid オプションでIDを指定して対象ユーザー特定し、 --cclientid オプションでclientId属性を指定するか、 --cid オプションでIDを指定して対象クライアントを特定します。

例：
```
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management
```
有効な レルムロールをリストするには、 --effective オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --effective
```
ユーザーに利用可能なレルムロールを一覧表示するには、 --available オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --available
```

ユーザーにレルムロールを追加する

レルムロールをユーザーに追加するには、専用の add-roles コマンドを使用します。

次の例を使用して、 user ロールをユーザー testuser に追加します。

$ kcadm.sh add-roles --username testuser --rolename user -r demorealm

ユーザーからレルムロールを削除する

ユーザーからレルムロールを削除するには、専用の remove-roles コマンドを使用します。

以下の例を使用して、ユーザー testuser から user ロールを削除します。

$ kcadm.sh remove-roles --username testuser --rolename user -r demorealm

ユーザーにクライアントロールを追加する

クライアントロールをユーザーに追加するには、専用の add-roles コマンドを使用します。

次の例を使用して、クライアント[command]realm management に定義された2つのロール（ create-client ロールと view-users ロール）を testuser ユーザーに追加します。

$ kcadm.sh add-roles -r demorealm --uusername testuser --cclientid realm-management --rolename create-client --rolename view-users

ユーザーからのクライアントロールの削除

専用の remove-roles コマンドを使用して、クライアントロールをユーザーから削除します。

次の例を使用して、レルム管理クライアントで定義されている2つのロールを削除します。

$ kcadm.sh remove-roles -r demorealm --uusername testuser --cclientid realm-management --rolename create-client --rolename view-users

ユーザー・セッションの一覧表示

ユーザーのIDを特定し、それを利用して users/ID/sessions などのエンドポイントURIを作成します。
ユーザーのセッションの一覧を取得するには、 get コマンドを使用します。

例：
```
$kcadm get users/6da5ab89-3397-4205-afaa-e201ff638f9e/sessions
```

特定のセッションからユーザーをログアウトする

上記のようにセッションのIDを決定します。
セッションIDを使用して、 sessions/ID のようなエンドポイントURIを作成します。
セッションを無効にするには、 delete コマンドを使用します。

例：
```
$ kcadm.sh delete sessions/d0eaa7cc-8c5d-489d-811a-69d3c4ec84d1
```

すべてのセッションからユーザーをログアウトする

users/ID/logout のようなエンドポイントURIを構築するには、ユーザーのIDが必要です。

そのエンドポイントURIに対して、 create コマンドを使って POST を実行します。

例：

$ kcadm.sh create users/6da5ab89-3397-4205-afaa-e201ff638f9e/logout -r demorealm -s realm=demorealm -s user=6da5ab89-3397-4205-afaa-e201ff638f9e

19.10. グループの操作

グループの作成

新しいグループを作成するには、 groups エンドポイントで create コマンドを使用します。

例：

$ kcadm.sh create groups -r demorealm -s name=Group

グループの一覧表示

グループを一覧表示するには、 groups エンドポイントで get コマンドを使います。

例：

$ kcadm.sh get groups -r demorealm

特定のグループを取得する

グループのIDを使用して、 groups/GROUP_ID のようなのエンドポイントURIを作成します。

例：

$ kcadm.sh get groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm

グループの更新

特定のグループを取得するために使用したものと同じエンドポイントURIを指定して update コマンドを使用します。

例：

$ kcadm.sh update groups/51204821-0580-46db-8f2d-27106c6b5ded -s 'attributes.email=["group@example.com"]' -r demorealm

グループの削除

特定のグループを取得するために使用したものと同じエンドポイントURIで delete コマンドを使用します。

例：

$ kcadm.sh delete groups/51204821-0580-46db-8f2d-27106c6b5ded -r demorealm

サブグループの作成

グループを一覧表示して親グループのIDを探し、そのIDを使用して groups/GROUP_ID/children のようなエンドポイントURIを構築します。

例：

$ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s name=SubGroup

グループを別のグループの下に移動する

既存の親グループと既存の子グループのIDを検索します。
親グループのIDを使用して、 groups/PARENT_GROUP_ID/children のようなエンドポイントURIを作成します。
このエンドポイントで create コマンドを実行し、子グループのIDをJSONとして渡します。

例：

$ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s id=08d410c6-d585-4059-bb07-54dcb92c5094

特定のユーザーのグループを取得する

グループ内のユーザーのメンバーシップを判断するため、ユーザーのIDを使用して、 users/USER_ID/groups のようなエンドポイントURIを構成します。

例：

$ kcadm.sh get users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups -r demorealm

グループにユーザーを追加する

グループにユーザーを追加するには、ユーザーのIDとグループのID（ users/USER_ID/groups/GROUP_ID のような）から構成されるエンドポイントURIで、 update コマンドを使用します。

例：

$ kcadm.sh update users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups/ce01117a-7426-4670-a29a-5c118056fe20 -r demorealm -s realm=demorealm -s userId=b544f379-5fc4-49e5-8a8d-5cfb71f46f53 -s groupId=ce01117a-7426-4670-a29a-5c118056fe20 -n

グループからユーザーを削除する

グループからユーザーを削除するには、 users/USER_ID/groups/GROUP_ID のように、ユーザーをグループに追加するときに使用したのと同じエンドポイントURIで delete コマンドを使用します。

例：

$ kcadm.sh delete users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups/ce01117a-7426-4670-a29a-5c118056fe20 -r demorealm

グループに割り当てられた、使用可能で、有効なレルムロールの一覧表示

グループに割り当てられた、使用可能で、有効なレルムロールを一覧表示するには、専用の get-roles コマンドを使用します。

対象グループを、 --gname オプションで名前を指定するか、 [command] --gpath オプションでパスをを指定する、または --gid オプションでIDを指定することにとり、そのグループの 割り当てられた レルムロールを一覧表示します。

例：
```
$ kcadm.sh get-roles -r demorealm --gname Group
```
有効な レルムロールをリストするには、 --effective オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --gname Group --effective
```
グループに追加できるレルムロールを表示するには、 --available オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --gname Group --available
```

グループに割り当てられた、利用可能で、有効なクライアントロールの一覧表示

グループに割り当てられた、利用可能で、有効なクライアントロールを一覧表示するには、専用の get-roles コマンドを使用します。

--gname オプションで名前指定するか、 --gid オプションでIDを指定することでグループを指定します。また、 [command] --cclientid オプションでclientId属性を指定するか、 --id オプションでIDを指定することでクライアントを特定し、ユーザーの 割り当てられた クライアントロールを一覧表示します。

例：
```
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management
```
有効な レルムロールをリストするには、 --effective オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --effective
```
グループに追加できるレルムロールを表示するには、 --available オプションを使用します。

例：
```
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --available
```

19.11. アイデンティティー・プロバイダーの操作

使用可能なアイデンティティー・プロバイダーの一覧表示

使用可能なアイデンティティー・プロバイダーを一覧表示するには、 serverinfo エンドポイントを使用します。

例：

$ kcadm.sh get serverinfo -r demorealm --fields 'identityProviders(*)'

serverinfo エンドポイントは、特定のレルムの外に存在するため、対象レルムに対して関連がないという点において realms エンドポイントと同様に扱われます。

設定済みアイデンティティー・プロバイダーの一覧表示

identity-provider/instances エンドポイントを使用します。

例：

$ kcadm.sh get identity-provider/instances -r demorealm --fields alias,providerId,enabled

特定の設定済みアイデンティティー・プロバイダーの取得

アイデンティティー・プロバイダーの alias 属性を使用して、 identity-provider/instances/ALIAS などのエンドポイントURIを構築し、特定のアイデンティティー・プロバイダーを取得します。

例：

$ kcadm.sh get identity-provider/instances/facebook -r demorealm

特定の設定済みアイデンティティー・プロバイダーの削除

特定の設定済みのアイデンティティー・プロバイダーを取得するために使用したものと同じエンドポイントURIで、 delete コマンドを使用します。

例：

$ kcadm.sh delete identity-provider/instances/facebook -r demorealm

Keycloak OpenID Connect アイデンティティー・プロバイダーの設定

新しいアイデンティティー・プロバイダー・インスタンスを作成するときは、 providerId として keycloak-oidc を使用してください。

authorizationUrl 、 tokenUrl 、 clientId 、 clientSecret の config 属性として指定します。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=keycloak-oidc -s providerId=keycloak-oidc -s enabled=true -s 'config.useJwksUrl="true"' -s config.authorizationUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/auth -s config.tokenUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/token -s config.clientId=demo-oidc-provider -s config.clientSecret=secret

OpenID Connect アイデンティティー・プロバイダーの設定

providerId 属性値を oidc に設定することを除いて、Keycloak OpenID Connectプロバイダーを設定するのと同じ方法で、汎用OpenID Connectプロバイダーを設定します。

SAML 2 アイデンティティー・プロバイダーの設定

providerId として saml を使います。
singleSignOnServiceUrl 、 nameIDPolicyFormat 、 signatureAlgorithm を config 属性として指定します。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=saml -s providerId=saml -s enabled=true -s 'config.useJwksUrl="true"' -s config.singleSignOnServiceUrl=http://localhost:8180/auth/realms/saml-broker-realm/protocol/saml -s config.nameIDPolicyFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent -s config.signatureAlgorithm=RSA_SHA256

Facebookアイデンティティー・プロバイダーの設定

providerId として facebook を使用します。

clientId と clientSecret の[command]config 属性をして指定します。これらの属性は、アプリケーションのFacebook Developersアプリケーション設定ページで確認できます。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=facebook -s providerId=facebook -s enabled=true  -s 'config.useJwksUrl="true"' -s config.clientId=FACEBOOK_CLIENT_ID -s config.clientSecret=FACEBOOK_CLIENT_SECRET

Googleアイデンティティー・プロバイダーの設定

providerId として google を使用します。

clientId と clientSecret を config 属性として指定します。これらの属性は、アプリケーションのGoogle Developersアプリケーション設定ページで確認できます。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=google -s providerId=google -s enabled=true  -s 'config.useJwksUrl="true"' -s config.clientId=GOOGLE_CLIENT_ID -s config.clientSecret=GOOGLE_CLIENT_SECRET

Twitterアイデンティティー・プロバイダーの設定

providerId として twitter を使用します。
clientId と clientSecret を config 属性として指定します。これらの属性は、アプリケーションのTwitterアプリケーション管理のアプリケーション設定ページで確認できます。

例：
```
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=google -s providerId=google -s enabled=true  -s 'config.useJwksUrl="true"' -s config.clientId=TWITTER_API_KEY -s config.clientSecret=TWITTER_API_SECRET
```

GitHubアイデンティティー・プロバイダーの設定

providerId として github を使用します。

clientId と clientSecret を config 属性として指定します。これらの属性は、アプリケーションのGitHub開発者アプリケーション設定ページで確認できます。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=github -s providerId=github -s enabled=true  -s 'config.useJwksUrl="true"' -s config.clientId=GITHUB_CLIENT_ID -s config.clientSecret=GITHUB_CLIENT_SECRET

LinkedInアイデンティティー・プロバイダーの設定

providerId として linkedin を使用します。

clientId と clientSecret を config 属性として指定します。これらの属性は、アプリケーションのLinkedInデベロッパー・コンソールのアプリケーション・ページで確認できます。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=linkedin -s providerId=linkedin -s enabled=true  -s 'config.useJwksUrl="true"' -s config.clientId=LINKEDIN_CLIENT_ID -s config.clientSecret=LINKEDIN_CLIENT_SECRET

Microsoft Live アイデンティティー・プロバイダーの設定

providerId として microsoft を使用します。

clientId and clientSecret を config 属性として指定します。これらの属性は、アプリケーションのMicrosoftアプリケーション登録ポータルページで確認できます。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=microsoft -s providerId=microsoft -s enabled=true  -s 'config.useJwksUrl="true"' -s config.clientId=MICROSOFT_APP_ID -s config.clientSecret=MICROSOFT_PASSWORD

StackOverflowアイデンティティー・プロバイダーの設定

providerId として stackoverflow を使用します。

clientId 、 clientSecret 、 key を config として提供します。これらの属性は、アプリケーションのStack Apps OAuthページで確認できます。

例：

$ kcadm.sh create identity-provider/instances -r demorealm -s alias=stackoverflow -s providerId=stackoverflow -s enabled=true  -s 'config.useJwksUrl="true"' -s config.clientId=STACKAPPS_CLIENT_ID -s config.clientSecret=STACKAPPS_CLIENT_SECRET -s config.key=STACKAPPS_KEY

19.12. ストレージ・プロバイダーの操作

Kerberosストレージ・プロバイダーの設定

user-federation/instances エンドポイントに対して create コマンドを使用します。

providerName 属性の値として kerberos を指定します。

例：

$ kcadm.sh create user-federation/instances -r demorealm -s providerName=kerberos -s priority=0 -s config.debug=false -s config.allowPasswordAuthentication=true -s 'config.editMode="UNSYNCED"' -s config.updateProfileFirstLogin=true -s config.allowKerberosAuthentication=true -s 'config.kerberosRealm="KEYCLOAK.ORG"' -s 'config.keyTab="http.keytab"' -s 'config.serverPrincipal="HTTP/localhost@KEYCLOAK.ORG"'

LDAPユーザー・ストレージ・プロバイダーの設定

components エンドポイントに対して create コマンドを使用します。
providerId 属性の値として ldap を指定し、 providerType 属性の値として org.keycloak.storage.UserStorageProvider を指定します。
レルムIDを parentId 属性の値として指定します。

次の例を使用して、Kerberos統合LDAPプロバイダーを作成します。

$ kcadm.sh create components -r demorealm -s name=kerberos-ldap-provider -s providerId=ldap -s providerType=org.keycloak.storage.UserStorageProvider -s parentId=3d9c572b-8f33-483f-98a6-8bb421667867  -s 'config.priority=["1"]' -s 'config.fullSyncPeriod=["-1"]' -s 'config.changedSyncPeriod=["-1"]' -s 'config.cachePolicy=["DEFAULT"]' -s config.evictionDay=[] -s config.evictionHour=[] -s config.evictionMinute=[] -s config.maxLifespan=[] -s 'config.batchSizeForSync=["1000"]' -s 'config.editMode=["WRITABLE"]' -s 'config.syncRegistrations=["false"]' -s 'config.vendor=["other"]' -s 'config.usernameLDAPAttribute=["uid"]' -s 'config.rdnLDAPAttribute=["uid"]' -s 'config.uuidLDAPAttribute=["entryUUID"]' -s 'config.userObjectClasses=["inetOrgPerson, organizationalPerson"]' -s 'config.connectionUrl=["ldap://localhost:10389"]'  -s 'config.usersDn=["ou=People,dc=keycloak,dc=org"]' -s 'config.authType=["simple"]' -s 'config.bindDn=["uid=admin,ou=system"]' -s 'config.bindCredential=["secret"]' -s 'config.searchScope=["1"]' -s 'config.useTruststoreSpi=["ldapsOnly"]' -s 'config.connectionPooling=["true"]' -s 'config.pagination=["true"]' -s 'config.allowKerberosAuthentication=["true"]' -s 'config.serverPrincipal=["HTTP/localhost@KEYCLOAK.ORG"]' -s 'config.keyTab=["http.keytab"]' -s 'config.kerberosRealm=["KEYCLOAK.ORG"]' -s 'config.debug=["true"]' -s 'config.useKerberosForPasswordAuthentication=["true"]'

ユーザー・ストレージ・プロバイダー・インスタンスの削除

ストレージ・プロバイダー・インスタンスの id 属性を使用して、 components/ID のようなエンドポイントURIを作成します。
このエンドポイントに対して delete コマンドを実行します。

例：
```
$ kcadm.sh delete components/3d9c572b-8f33-483f-98a6-8bb421667867 -r demorealm
```

特定のユーザー・ストレージ・プロバイダーのすべてのユーザーの同期をトリガーする

ストレージ・プロバイダーの id 属性を使用して、 user-storage/ID_OF_USER_STORAGE_INSTANCE/sync のようなエンドポイントURIを作成します。
action=triggerFullSync クエリー・パラメーターを追加し、 create コマンドを実行します。

例：
```
$ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerFullSync
```

特定のユーザー・ストレージ・プロバイダーに対して、変更されたユーザーの同期をトリガーする

ストレージ・プロバイダーの id 属性を使用して、 user-storage/ID_OF_USER_STORAGE_INSTANCE/sync のようなエンドポイントURIを作成します。
action=triggerChangedUsersSync クエリー・パラメーターを追加し、 create コマンドを実行します。

例：
```
$ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerChangedUsersSync
```

LDAPユーザー・ストレージの接続をテストする

testLDAPConnection エンドポイントで get コマンドを実行します。
bindCredential 、 bindDn 、 connectionUrl 、 useTruststoreSpi をクエリー・パラメーターとして指定します。action クエリー・パラメーターに testConnection を設定します。

例：
```
$ kcadm.sh get testLDAPConnection -q action=testConnection -q bindCredential=secret -q bindDn=uid=admin,ou=system -q connectionUrl=ldap://localhost:10389 -q useTruststoreSpi=ldapsOnly
```

LDAPユーザー・ストレージ認証をテストする

testLDAPConnection エンドポイントで get コマンドを実行します。
bindCredential 、 bindDn 、 connectionUrl 、 useTruststoreSpi をクエリー・パラメーターに指定します。 action クエリー・パラメーターに testAuthentication を指定します。

例：
```
$ kcadm.sh get testLDAPConnection -q action=testAuthentication -q bindCredential=secret -q bindDn=uid=admin,ou=system -q connectionUrl=ldap://localhost:10389 -q useTruststoreSpi=ldapsOnly
```

19.13. マッパーの追加

ハードコードされたロールLDAPマッパーの追加

components エンドポイントで create コマンドを実行します。
providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。
parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

providerId 属性に hardcoded-ldap-role-mapper を設定します。 role 設定パラメーターの値を指定します。

例：

$ kcadm.sh create components -r demorealm -s name=hardcoded-ldap-role-mapper -s providerId=hardcoded-ldap-role-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config.role=["realm-management.create-client"]'

MS Active Directoryマッパーの追加

components エンドポイントで create コマンドを実行します。
providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。
parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

providerId 属性を msad-user-account-control-mapper に設定します。

例：

$ kcadm.sh create components -r demorealm -s name=msad-user-account-control-mapper -s providerId=msad-user-account-control-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea

ユーザー属性LDAPマッパーの追加

components エンドポイントで create コマンドを実行します。
providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。
parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

providerId 属性を user-attribute-ldap-mapper に設定します。

例：

$ kcadm.sh create components -r demorealm -s name=user-attribute-ldap-mapper -s providerId=user-attribute-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."user.model.attribute"=["email"]' -s 'config."ldap.attribute"=["mail"]' -s 'config."read.only"=["false"]' -s 'config."always.read.value.from.ldap"=["false"]' -s 'config."is.mandatory.in.ldap"=["false"]'

グループLDAPマッパーの追加

components エンドポイントで create コマンドを実行します。
providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。
parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

providerId 属性を group-ldap-mapper に設定します。

例：

$ kcadm.sh create components -r demorealm -s name=group-ldap-mapper -s providerId=group-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."groups.dn"=[]' -s 'config."group.name.ldap.attribute"=["cn"]' -s 'config."group.object.classes"=["groupOfNames"]' -s 'config."preserve.group.inheritance"=["true"]' -s 'config."membership.ldap.attribute"=["member"]' -s 'config."membership.attribute.type"=["DN"]' -s 'config."groups.ldap.filter"=[]' -s 'config.mode=["LDAP_ONLY"]' -s 'config."user.roles.retrieve.strategy"=["LOAD_GROUPS_BY_MEMBER_ATTRIBUTE"]' -s 'config."mapped.group.attributes"=["admins-group"]' -s 'config."drop.non.existing.groups.during.sync"=["false"]' -s 'config.roles=["admins"]' -s 'config.groups=["admins-group"]' -s 'config.group=[]' -s 'config.preserve=["true"]' -s 'config.membership=["member"]'

フルネームLDAPマッパーの追加

components エンドポイントで create コマンドを実行します。
providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。
parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

providerId 属性を full-name-ldap-mapper に設定します。

例：

$ kcadm.sh create components -r demorealm -s name=full-name-ldap-mapper -s providerId=full-name-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."ldap.full.name.attribute"=["cn"]' -s 'config."read.only"=["false"]' -s 'config."write.only"=["true"]'

19.14. 認証の操作

パスワード・ポリシーの設定

レルムの passwordPolicy 属性に、特定のポリシー・プロバイダーIDとオプション設定を含む列挙表現を設定します。
次の例を使用して、パスワード・ポリシーをデフォルト値に設定します。デフォルト値は次のとおりです。
- 27,500ハッシュ反復
- 少なくとも1つの特殊文字
- 少なくとも1つの大文字
- 少なくとも1つの数字
- ユーザーの username と等しくないこと
- 8文字以上の長さ
  $ kcadm.sh update realms/demorealm -s 'passwordPolicy="hashIterations and specialChars and upperCase and digits and notUsername and length"'
デフォルトと異なる値を使用する場合は、設定を大括弧で囲みます。
パスワードポリシーを次のように設定するには、以下の例を使用します。
- 25,000ハッシュ反復
- 少なくとも2つの特殊文字
- 少なくとも2つの大文字
- 少なくとも2つの小文字
- 少なくとも2つの数字
- 9文字以上の長さ
- ユーザーの username と等しくないこと
- 過去4回の変更履歴の重複を許可しない
  $ kcadm.sh update realms/demorealm -s 'passwordPolicy="hashIterations(25000) and specialChars(2) and upperCase(2) and lowerCase(2) and digits(2) and length(9) and notUsername and passwordHistory(4)"'

現在のパスワード・ポリシーの取得

現在のレルム設定を取得し、 passwordPolicy 属性以外のすべてをフィルタリングします。

demorealm に対して passwordPolicy を表示するには、次の例を使用します。

$ kcadm.sh get realms/demorealm --fields passwordPolicy

認証フローの一覧表示

authentication/flows エンドポイントで get コマンドを実行します。

例：

$ kcadm.sh get authentication/flows -r demorealm