概要

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

機能

  • ブラウザー・アプリケーションに対するシングル・サインオンとシングル・サインアウト。

  • 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のサービス・プロバイダー・ライブラリーをもつ、あらゆるプラットフォーム/言語のサポート。

セキュリティーはどう機能するか

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

コアコンセプトと用語

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

ユーザー

システムにログイン可能なエンティティーのことです。電子メール、ユーザー名、住所、電話番号、生年月日など自分自身に関連する属性を持ちます。また、グループ・メンバーシップが割り当てられたり、特定のロールが割り当てられたりします。

認証

ユーザーを特定し、検証するプロセスのことです。

認可

ユーザーに対してアクセスを許可するプロセスのことです。

credentials

クレデンシャルは、Keycloakがユーザーの身元を確認するために使用するデータの一部のことです。例として、パスワード、ワンタイムパスワード、デジタル証明書、さらには指紋などがあります。

ロール

ロールは、ユーザーのタイプまたはカテゴリーを識別します。 Adminusermanageremployee はすべて、組織内に存在する典型的なロールです。アプリケーションは、ユーザーの扱いをきめ細く管理することが難しくなる場合があるため、個々のユーザーではなく、特定のロールにパーミッションを割り当てることが多いです。

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

ユーザー・ロール・マッピングは、ロールとユーザーの間のマッピングを定義します。ユーザーには、0以上のロールを関連付けることができます。このロールマッピング情報を、トークンとアサーションにカプセル化して、アプリケーションが管理するさまざまなリソースに対するアクセス許可を決定できるようにします。

複合ロール

複合ロールは、他のロールと関連付けることができるロールです。たとえば、 superuser 複合ロールは sales-admin ロールと order-entry-admin ロールに関連付けることができます。ユーザーが superuser ロールにマッピングされると、 sales-admin ロールと order-entry-admin ロールも継承します。

グループ

グループは、ユーザーのグループを管理します。グループには、属性を定義することができます。ロールもグループにマップすることができます。グループのメンバーになったユーザーは、そのグループが定義する属性とロールのマッピングを継承します。

レルム

レルムは、ユーザー、クレデンシャル、ロール、および、グループのセットを管理します。ユーザーは属しているレルムにログインします。レルムは互いに分離されており、制御するユーザーのみを管理して、認証することができます。

クライアント

クライアントは、Keycloakにユーザーの認証を要求できるエンティティーです。多くの場合、クライアントはKeycloakを使用して自分自身を保護し、シングル・サインオン・ソリューションを提供するアプリケーションとサービスのことを指します。また、クライアントはKeycloakによって保護されているネットワーク上の他のサービスを安全に呼び出すことができるように、アイデンティティー情報やアクセストークンを要求するエンティティーになります。

クライアント・アダプター

クライアント・アダプターは、Keycloakによる通信とセキュリティー保護を可能にするためにアプリケーション環境にインストールするプラグインです。Keycloakには、異なるプラットフォーム向けにいくつかのアダプターが用意されており、ダウンロードが可能です。また、標準ではカバーしていない環境向けのサードパーティーのアダプターもあります。

同意

同意は、クライアントが認証プロセスに参加する前に、クライアントに許可を与えることを管理者がユーザーに求めることです。ユーザーがクレデンシャルを入力すると、Keycloakがログインを要求しているクライアントを識別する画面とユーザーに要求された識別情報を表示します。ユーザーは、要求を許可するかどうかを決定できます。

クライアント・スコープ

クライアントが登録されたら、そのクライアントのプロトコル・マッパーとロールスコープのマッピングを定義する必要があります。いくつかの共通の設定を共有することで、新しいクライアントの作成を容易にするために、クライアント・スコープを保存すると便利なことがよくあります。これは、 scope パラメーターの値に基づいて条件付きでクレームやロールを要求する場合にも便利です。Keycloakは、このためにクライアント・スコープの概念を提供します。

クライアントロール

クライアントは、特定のロールを定義できます。これは、基本的にクライアント専用のロールの名前空間です。

IDトークン

ユーザーに関する識別情報を提供するトークンです。これは、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をフックして、他のOpenID ConnectまたはSAML 2.0 IDPに認証を委任することもできます。

アイデンティティー・プロバイダー・マッパー

IDPフェデレーションを実行するときに、受信したトークンやアサーションにユーザー属性やセッション属性をマップできます。これは外部IDPから認証を要求するクライアントへアイデンティティー情報を伝播させるのに役立ちます。

必須アクション

必須アクションは、ユーザーが認証プロセス中に実行する必要があるアクションです。これらのアクションが完了するまで、ユーザーは認証プロセスを完了できません。たとえば、管理者は、すべてのユーザーに対して、 update password の必須アクションを設定し、毎月パスワードをリセットするようにユーザーへ要求することができます。

認証フロー

認証フローは、システムの特定の側面と対話するときにユーザーが実行する必要があるワークフローです。ログインフローでは、必要なクレデンシャル・タイプを定義します。登録フローでは、ユーザーが入力する必要のあるプロファイル情報と、reCAPTCHAを使用してボットをフィルタリングする必要があるかどうかを定義します。クレデンシャル・リセットフローは、ユーザーがパスワードをリセットする前に実行する必要があるアクションを定義します。

イベント

イベントは、管理者が表示したり、フックしたりすることができる監査ストリームです。

テーマ

Keycloakによって提供されるすべての画面にはテーマが付いています。テーマは必要に応じて上書きできるHTMLテンプレートとスタイルシートを定義します。

サーバーの初期化

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>

管理コンソール

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

ログインページ

login page

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

管理コンソール

admin console

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

masterレルム

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

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

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

新規レルムの作成

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

レルムの追加メニュー

add realm menu

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

レルムの作成

create realm

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

SSLモード

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

Keycloakは、初回実行時に自己署名証明書を生成します。自己署名証明書は安全ではないため、テスト目的でのみ使用してください。CA署名付き証明書をKeycloakサーバー自体、またはKeycloakサーバーの前にあるリバース・プロキシーにインストールすることを強くお勧めします。 Server Installation and Configuration Guide を参照してください。

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

Loginタブ

login tab

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

external requests

localhost127.0.0.110.x.x.x192.168.x.x172.16.x.x のようなプライベートIPアドレスに固定する限り、ユーザーはSSL無しでKeycloakと対話できます。非プライベートIPアドレスからSSL無しでKeycloakにアクセスしようとすると、エラーが発生します。

none

KeycloakはSSLを必要としません。この設定は、サーバー上でSSLの設定を気にせずにいろいろと触ってみる開発段階にのみ使用すべきです。

all requests

KeycloakはすべてのIPアドレスに対してSSLを要求します。

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

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

Cacheタブ

cache tab

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

電子メールの設定

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 をクリックし、 UsernamePassword を入力します。 Password フィールドの値は、外部ボールトからの値を参照できます。

テーマと国際化

テーマによって、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では、新しいテーマを作成したり、既存のテーマを変更する方法について説明します。

国際化

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

ユーザーロケールの選択

ユーザーに最適なロケールを選択するために、利用可能な情報で最適なロケールを決定するロケール・セレクター・プロバイダーがあります。ここで注意すべき点の1つは、ユーザーが誰であるかが常にわかっているとは限らないことです。このため、以前に認証されたユーザーのロケールは、永続的なCookieに記憶されます。

ロケールを選択するためのロジックは、以下の利用可能な最初のものが使用されます。

  • ユーザーが選択 - ユーザーがドロップダウン・ロケール・セレクターを使用してロケールを選択した場合

  • ユーザー・プロファイル - 認証されたユーザーがいて、そのユーザーが優先ロケールを設定している場合

  • クライアントによる選択 - たとえばui_localesパラメーターを使用してクライアントから渡された場合

  • Cookie - ブラウザーで最後に選択されたロケール

  • 受け入れられる言語 - Accept-Language ヘッダーのロケール

  • レルムのデフォルト

  • 上記のいずれでもない場合、英語にフォールバック

ユーザーが認証されると、前述の永続化されたCookieのロケールを更新するアクションがトリガーされます。ユーザーがログインページのロケール・セレクターを介してアクティブにロケールを切り替えた場合、ユーザーロケールもこの時点で更新されます。

ユーザーの管理

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

ユーザーの検索

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

Users

users

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

  • 検索条件を調整します。これにより、条件に一致するバックエンド・ユーザーのみがKeycloakデータベースに同期されます。

  • User Federation タブに移動して、フェデレーション・プロバイダーとページ内の Sync all users または Sync changed users をクリックします。

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

新規ユーザーの作成

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

Users

users

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

Add User

add user

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

ユーザーの削除

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

Users

users

このメニュー・オプションは、ユーザーリストのページに移動します。 View all users をクリックするか検索して、削除するユーザーを探します。

View All Users

delete user

ユーザーのリストで、削除するユーザーの横にある Delete をクリックします。このユーザーを削除することを確認するメッセージが表示されます。確認ダイアログボックスで確認してから、 Delete をクリックします。

ユーザー属性

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

Users

user attributes

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

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

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

クレデンシャルの管理

user credentials

クレデンシャルは表に一覧表示され、次のフィールドがあります。

Position

この列の矢印ボタンを使用すると、ユーザーのクレデンシャルの優先度を変更できます。最上位のクレデンシャルが最高の優先度を持ちます。この優先度は、ログイン時に選択した場合にユーザーに最初に表示されるクレデンシャルを決定します。ユーザーが使用できるものの中で最も高い優先度が選択されます。

Type

これは、 passwordotp などのクレデンシャルのタイプを示します。

User Label

これは、ログイン時に選択オプションとして提示されたときにクレデンシャルを認識するための割り当て可能なラベルです。クレデンシャルを説明する任意の値に設定できます。

Data

これは、クレデンシャルに関する非機密の技術情報を示しています。元々非表示ですが、 Show data…​ をクリックしてクレデンシャルを表示できます。

Actions

この列には2つのボタンがあります。 Save はユーザーラベルの値を記録し、 Delete はクレデンシャルを削除します。

ユーザーのパスワードの作成

ユーザーがパスワードを持っていない場合、またはパスワードが削除されている場合、 Set Password セクションがページに表示されます。

クレデンシャルの管理 - パスワードの設定

user credentials set password

ユーザーのパスワードを作成するには、新しいパスワードを入力します。すべてを入力したら、 Set Password ボタンをクリックします。 Temporary スイッチがオンの場合、この新しいパスワードは1回しか使用できず、ユーザーはログイン後にパスワードの変更を求められます。

ユーザーがパスワードを既に持っている場合、 Reset Password セクションでリセットすることが出来ます。

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

ユーザーは、パスワードタイプのクレデンシャルを1つしか持てないことに注意してください。

他のクレデンシャルの作成

管理コンソール内で特定のユーザーに他の種類のクレデンシャルを設定することはできません。これはユーザーの責任です。ユーザーがOTPデバイスを紛失した場合、またはクレデンシャルが侵害された場合は、 Credentials タブでユーザーのクレデンシャルを削除だけできます。

OTPの作成

レルムでOTPがconditionalである場合、ユーザーはユーザーアカウント管理サービスにアクセスして、新しいOTPジェネレーターを再設定する必要があります。OTPが必要な場合、ユーザーはログイン時に新しいOTPジェネレーターを再設定するよう求められます。

パスワードと同様に、OTPジェネレーターをリセットするように求めるメールをユーザーに送信することもできます。 Reset Actions のリストボックスで Configure OTP を選択し、 Send Email ボタンをクリックします。送信されたメールには、ユーザーをOTP設定画面に移動するリンクが含まれています。ユーザーが既にOTPクレデンシャルを持っている場合でも、この方法を使用できます。

必須アクション

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

Update Password

設定すると、ユーザーはパスワードを変更する必要があります。

Configure OTP

設定すると、ユーザーはFree OTPまたはGoogleオーセンティケーター・アプリケーションを使用して、モバイルデバイスにワンタイム・パスワード・ジェネレーターを設定する必要があります。

Verify Email

設定すると、ユーザーは有効な電子メール・アカウントの検証が必要となります。クリックしなければならないリンクがある電子メールがユーザーに送信されます。この検証作業が正常に完了すると、ログインが許可されます。

Update Profile

この必須アクションは、ユーザーの名前、住所、電子メール、電話番号といったプロファイル情報をユーザーに更新するように要求します。

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

必須アクションの設定

user required action

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

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

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

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

default required actions

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

利用規約

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

Impersonation

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

Users

user search

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

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

ユーザー詳細

user details

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

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

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

ユーザー登録

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

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

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

Loginタブ

login tab

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

登録リンク

registration link

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

登録フォーム

registration form

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

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-OptionsContent-Security-Policy ヘッダーの両方の値に https://www.google.com を追加する必要があります。

iframeの許可

security headers

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

Keycloakによって収集された個人データ

デフォルトでは、Keycloakは次のものを収集します。

  • 電子メール、名、姓などの基本的なユーザー・プロファイル

  • ソーシャル・ログインに使用するときにソーシャル・アカウントとソーシャル・アカウントへの参照に使用される基本的なユーザー・プロファイル

  • IPアドレス、オペレーティング・システム名、ブラウザー名など、監査とセキュリティーの目的で収集されたデバイス情報

Keycloakで収集された情報は高度にカスタマイズできます。カスタマイズを行うときは、次のガイドラインに注意してください。

  • 登録およびアカウント・フォームには、誕生日、性別、国籍などのカスタム・フィールドを含めることができます。管理者は、Keycloakを設定して、ソーシャル・プロバイダーまたはLDAPなどのユーザー・ストレージ・プロバイダーからそのデータを取得できます。

  • Keycloakは、パスワード、OTPコード、WebAuthn公開鍵などのユーザー・クレデンシャルを収集します。この情報は暗号化されてデータベースに保存されるため、Keycloak管理者には表示されません。ただし、クレデンシャルの各タイプには、パスワードのハッシュに使用されるアルゴリズムやパスワードのハッシュに使用されるハッシュ反復回数など、管理者に表示される非機密メタデータを含めることができます。

  • 認可サービスとUMAサポートを有効にすると、Keycloakは特定のユーザーが所有者であるオブジェクトに関する情報を保持できます。たとえば、Keycloakは、ユーザー john はフォトアルバム album with animals と、このアルバムの lion picturecow picture と呼ばれるいくつかの写真の所有者であることを追跡できます。

ユーザーによるアカウント削除の有効化

Keycloakでは、アプリケーションのエンドユーザーはアカウント・コンソールからアカウントを削除できます。この機能はデフォルトでは有効になっていません。これを有効にするには、次の手順を実行する必要があります。

  • "Delete Account" 必須アクションを有効にする

ユーザーが自分のアカウントを削除できるようにすることは、AIA(Application Initiated Action)を介して行われます。まず、管理コンソールからアクションを有効にする必要があります。Authenticationメニューで、Required Actionsタブに移動し、 "Delete Account" アクションの有効なチェックボックスをオンにします。

enable delete account action

  • ユーザーがクライアントロールとして "delete-account" を持っていることを確認します。

アカウントの削除機能は、ユーザーごとに有効になります。アカウントの削除機能を有効にするための2番目の要件は、ユーザーがクライアントロールとして delete-account を持っていることを確認することです。

ユーザーのアカウント削除ロールを有効にするには、Usersメニューに移動し、アカウント削除機能を有効にするユーザーを見つけます。 "Role Mappings" タブで、 "Clients Role" の一覧から "account" クライアントを選択します。

最後に、 delete-account を選択し、 "Add selected" をクリックします。

delete account client role

アクションによるユーザーの削除

機能を有効にすると、 "Personal Info" ページの下部に "Delete Account" という名前の新しいセクションが表示されます。

delete account landing screen

delete account page

警告メッセージに記載されているように、このアクションは元に戻せません。これは、Keycloak内のすべてのユーザーのデータが削除されることを意味します。

ユーザーがDeleteをクリックすると、クレデンシャルを再度入力するように求められ、最後の確認手順にリダイレクトされます。

delete account confirm

確認後、ユーザーのアカウントは削除されます。

ログインページの設定

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

パスワード忘れ

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

Loginタブ

login tab

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

パスワード忘れリンク

forgot password link

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

パスワード忘れページ

forgot password page

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

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

Reset Credentialsフロー

reset credentials flow

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

Required ActionsタブでUpdate Passwordを有効のままにしてください。そうしないと、Forgot Passwordは機能しません。

Remember Me

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

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

Loginタブ

login tab

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

Remember Me

remember me

認証

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

パスワード・ポリシー

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

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

パスワード・ポリシー

password policy

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

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

failed password policy

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

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

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

HashAlgorithm

パスワードはクリアーテキストとして保存されません。その代わりに、標準のハッシュ・アルゴリズムを使用してハッシュされ、保存または検証されます。利用可能なビルトイン・アルゴリズムかつデフォルト・アルゴリズムは、PBKDF2のみです。独自のアルゴリズムをプラグインする方法については、Server Developer Guideを参照してください。アルゴリズムを変更すると、次回ユーザーがログインするまでパスワード・ハッシュが変更されません。

Hashing Iterations

この値は、パスワードが保存または検証される前にハッシュされる回数を指定します。デフォルト値は27,500です。このハッシングは、ハッカーがパスワード・データベースにアクセスするまれなケースで行われます。データベースにアクセスすると、ユーザーのパスワードをリバース・エンジニアリングすることができます。このパラメーターの業界推奨値は、CPUパワーが向上するにつれて毎年変化します。ハッシュ反復の値が高いほど、ハッシュに必要なCPUパワーが増え、パフォーマンスに影響を与える可能性があります。パフォーマンスとパスワードストアの保護のどちらを重要視するかは、要件により異なります。もしくは、パスワードストアの保護よりも、費用対効果の高い方法があるかもしれません。

Digits

パスワード文字列に必要な桁数。

Lowercase Characters

パスワード文字列に必要な小文字の数。

Uppercase Characters

パスワード文字列に必要な大文字の数。

Special Characters

パスワード文字列に含める必要がある、'?!#%$'のような特殊文字の数。

Not Username

設定すると、パスワードをユーザー名と同じにすることはできません。

Not Email

設定すると、パスワードをメールアドレスと同じにすることができなくなります。

Regular Expression

パスワードが一致する必要のある1つ以上の正規表現パターン( java.util.regex.Pattern で定義される)を定義します。

Expire Password

パスワードが有効な日数。有効期限が切れた後、ユーザーはパスワードを変更する必要があります。

Not Recently Used

このポリシーは、以前のパスワードの履歴を保存します。保存されている古いパスワードの数は設定可能です。ユーザーがパスワードを変更する際に、保存されたパスワードを使用することはできません。

Password Blacklist

このポリシーは、与えられたパスワード(小文字に変換されます)がブラックリスト・ファイル(非常に大きなファイルになる可能性があります)に含まれているかどうかをチェックします。パスワード・ブラックリストはUnixの改行コードを持つUTF-8プレーンテキスト・ファイルで、各行はブラックリストに載っているパスワードを表します。大文字と小文字を区別しない比較を容易にするために、ブラックリスト内のすべてのパスワードを小文字にする必要があります。ブラックリスト・ファイルのファイル名は、パスワード・ポリシー値として提供されなければなりません。例えば、 10_million_password_list_top_1000000.txt です。ブラックリスト・ファイルはデフォルトで ${jboss.server.data.dir}/password-blacklists/ に対して解決されます。このパスは、 keycloak.password.blacklists.path システム・プロパティー、または passwordBlacklist ポリシーSPI設定の blacklistsPath プロパティーによってカスタマイズできます。

OTPポリシー

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

OTP Policy

otp policy

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

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をチェックするかどうかを設定できるようになる予定です。

TOTP設定オプション

OTP Hash Algorithm

デフォルトはSHA1です。より安全なオプションはSHA256とSHA512です。

Number of Digits

OTPの文字数。短い場合、ユーザーが入力する文字数が少なくなるため、ユーザー・フレンドリーです。長い場合、セキュリティーの強度が高まります。

Look Ahead Window

サーバーがハッシュの照合を先行して試行する間隔。この設定は、TOTPジェネレーターまたは認証サーバーの時計が同期しなくなった場合に備えて存在します。通常は1というデフォルト値で十分です。たとえば、新しいトークンの時間間隔が30秒ごとの場合、デフォルト値1は、その30秒の枠内の有効なトークンのみを受け入れることを意味します。この設定値を増やすごとに有効な枠が30秒ずつ増加します。

OTP Token Period

サーバーがハッシュと一致するまでの時間間隔(秒)。間隔が経過するたびに、トークン・ジェネレーターによって新しいTOTPが生成されます。

HOTP設定オプション

OTP Hash Algorithm

デフォルトはSHA1です。より安全なオプションはSHA256とSHA512です。

Number of Digits

OTPの文字数。短い場合、ユーザーが入力する文字数が少なくなるため、ユーザー・フレンドリーです。長い場合、セキュリティーの強度が高まります。

Look Ahead Window

サーバーが、ハッシュの照合を先行して試行するカウンターの数。デフォルト値は1です。これは、ユーザーのカウンターがサーバーよりも先行することをカバーするために存在します。ユーザーが頻繁にカウンターを手動で何回も増やすことが多いために、サーバーのカウンターと差分が発生します。この値は、実際の利用においては10程度に増やす必要があります。

Initial Counter

最初のカウンターの値。

認証フロー

認証フロー は、ログイン、登録、その他のKeycloakワークフロー利用時に発生するすべての認証、画面、およびアクションのためのコンテナーです。管理コンソールの左メニュー項目 Authentication から、 Flows タブを表示することで、システム内の定義されたすべてのフローと、各フローが必要とするアクションとチェックを見ることができます。

組み込みフロー

Keycloakには、一定数の組み込みフローが付属しています。これらのフローは変更できませんが、要件はニーズに合わせて変更できます。

このセクションでは、組み込みのブラウザー・ログイン・フローのウォークスルーを行います。左側のドロップダウン・リストで browser を選択して、以下に示す画面に移動します。

ブラウザーフロー

browser flow

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

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

エグゼキューション要件
Required

フローが成功と評価されるには、フロー内のすべての必須要素が成功と評価される必要があります。つまり、要素がフローの失敗を引き起こさない限り、フロー内のすべての Required 要素を上から下に順番に実行する必要があります。ただし、これは現在のフローにのみ当てはまります。サブフロー内の Required 要素は、そのサブフローが入力された場合にのみ処理されます。

Alternative

フローに Alternative 要素のみが含まれる場合、フローが成功と評価されるためには、単一の要素のみが成功と評価される必要があります。フロー内の Required 要素はフローを成功としてマークするには十分なので、 Required 要素を含むフロー内の Alternative 要素は実行されません。この場合、それらは機能的には Disabled です。

Disabled

Disabled 要素は評価されず、フローを成功としてマークする際にカウントされません。

Conditional

この要件タイプは、サブフローでのみ設定できます。 Conditional サブフローには、"Condition"のエグゼキューションを含めることができます。これらの "Condition"のエグゼキューションは、論理ステートメントとして評価する必要があります。すべての "Condition"のエグゼキューションが true として評価される場合、 Conditional サブフローは Required として機能します。そうでない場合、 Conditional サブフローは Disabled として機能します。 "Condition"の実行が設定されていない場合、 Conditional サブフローは Disabled として機能します。フローに "Condition"のエグゼキューションが含まれ、 Conditional に設定されていない場合、 "Condition"のエグゼキューションは評価されず、機能的に Disabled と見なすことができます。

例を用いて、これを詳しく説明します。 browser 認証フローを見てみましょう。

  1. 最初の認証タイプは Cookie です。ユーザーが最初に正常にログインすると、セッションCookieが設定されます。このCookieがすでに設定されている場合、この認証タイプは成功です。この場合、Cookieプロバイダーは成功を返し、このフローのレベルでの各エグゼキューションは alternative であるため、他のエグゼキューションは実行されず、ログインに成功します。

  2. フローの2番目のエグゼキューションは、 Kerberos エグゼキューションです。このオーセンティケーターはデフォルトで無効になっており、スキップされます。

  3. 3番目のエグゼキューションは Identity Provider Redirector です。アイデンティティー・ブローカリングの別のIdPに自動的にリダイレクトするように、 Actions > Config のリンクから設定できます。

  4. 次のエグゼキューションは Forms と呼ばれるサブフローです。このサブフローは alternative とマークされているので、 Cookie 認証タイプが成功すると実行されません。このサブフローには、実行する必要のある追加の認証タイプが含まれています。サブフローのエグゼキューションはロードされ、同じ処理ロジックが発生します。

  5. Formsサブフローでの最初の実行は、 Username Password Form です。この認証タイプは、ユーザー名とパスワードのページを表示します。 required とされているため、ユーザーは有効なユーザー名とパスワードを入力する必要があります。

  6. Formsサブフローの2番目のエグゼキューションは、新しいサブフローである Browser - Conditional OTP サブフローです。このサブフローは conditional であるため、実行されるかどうかは、 Condition - User Configured のエグゼキューションの評価結果に依存します。そうである場合、このサブフローのエグゼキューションがロードされ、同じ処理ロジックが発生します。

  7. 次のエグゼキューションは Condition - User Configured です。これにより、フロー内の他のエグゼキューションがユーザーに対して設定されているかどうかが確認されます。つまり、 Browser - Conditional OTP サブフローは、ユーザーがOTPクレデンシャルを設定している場合にのみ実行されます。

  8. 最後のエグゼキューションは OTP Form です。これは required としてマークされていますが、 conditional サブフローでのセットアップのため、ユーザーがOTPクレデンシャルをセットアップしている場合にのみ実行されます。そうでない場合、ユーザーにはOTPフォームが表示されません。

フローの作成

このセクションでは、フローの仕組みと独自のフローの作成方法について詳しく説明します。独自のフローを設計する際には、重要な機能とセキュリティーの考慮事項があることに注意してください。不正なフローが作成されると、誰もログインできなくなるか、意図よりも少ない検証でユーザーがログインできてしまうか、または単にエラーになります。

次のいずれかで、フローを作成できます。

  1. 既存のフローをコピーして変更します。これを行うには、既存のフロー(たとえば、 Browser フロー)を選択し、 Copy ボタンを押します。次に、新しいフローの名前を設定するように求められます(作成する前に)。

  2. 新しいフローを最初から作成します。これを行うには、 New ボタンを押します。これはより一般的なケースであるため、この例で使用します。

新しいフローを作成するときは、トップレベルのフローを作成する必要があります。

トップレベルのフローを作成する

Create top level flow

次のオプションがあります。

Alias

フローの名前。

Description

フローに設定できる説明。

Top Level Flow Type

フローのタイプ。タイプ client は、クライアント(アプリケーション)の認証にのみ使用されます。それ以外の場合には、 generic を選択します。

フローが作成されると、 New ボタンと Copy ボタンに加えて、 DeleteAdd executionAdd flow ボタンがクリックできます。

空の新しいフロー

New flow

最終的にフローが行うことは、フローとサブフローの構造、それらのフローのエグゼキューション、およびサブフローとエグゼキューションに設定された要件によって決まります。

Add execution ボタンで実行をエグゼキューションできます。エグゼキューションには、リセットメールの送信からOTPの検証まで、さまざまなアクションがあります。 Provider の隣のツールチップ(小さなクエスチョン・マーク)にカーソルを合わせると、エグゼキューションが実行する内容が説明されます。

認証エグゼキューションの追加

Create authentication execution

これらは、 自動的エグゼキューション対話的エグゼキューション に分けることができます。 自動的エグゼキューションCookie エグゼキューションに似ており、フローで遭遇したときに自動的にアクションを実行します。 対話的エグゼキューション は、通常、ユーザー入力を取得するためにフローを停止します。正常に実行されたエグゼキューションは、 success ステータスを取得します。これは、フローが成功したかどうかの一部であるため、重要です。たとえば、空の Browser フローでは誰もログインできません。そのため、成功として評価されるエグゼキューションが少なくとも1つ、たとえば正しく入力されて送信される Username Password Form が必要です。

サブフローは、 Add flow ボタンを使用してトップレベルのフローに追加できます。このボタンは、 Create Top Level Form ページに非常によく似た Create Execution Flow ページを開きます。唯一の違いは、 Flow Typegeneric (前と同様)または form のいずれかになることです。 form タイプは、組み込みの Registration フローに対して行われるように、ユーザーに対して単一のフォームを生成するサブフローを構築するために使用されます。サブフローは、含まれるエグゼキューションの評価方法に応じて成功として評価される特別なタイプの実行です(これには、含まれるサブフローの評価も含まれます)。そして、この評価のロジックは、エグゼキューションとサブフローの要件に依存します。

これを完全に理解するには、フローを評価するときに要件がどのように機能するかについて、より完全な説明が必要です(これはサブフローにも適用されます)。詳しくは エグゼキューション要件のセクション を参照してください。

エグゼキューションを追加した後、要件が正しい値に設定されていることを確認する必要があることに注意してください。必要な要件が1つしかない場合でも、設定されていない可能性があります。

フローを構築するとき、フローに追加されるすべての要素の右側に Actions メニューがあります。フローに追加されたすべての要素には、このメニューに Delete オプションがあり、フローから削除できます。実行には、 Identity Provider Redirector の場合のように、エグゼキューションを設定するための Config メニューオプションを含めることができます。サブフローには、 Add execution および Add flow メニューオプションを使用して、エグゼキューションとサブフローを追加することもできます。

最後に、実行の順序が重要であるため、名前の左側に設定された上下ボタンを使用して、それぞれのフロー内でエグゼキューションとサブフローを上下に移動できます。

パスワードレスのブラウザー・ログイン・フローの作成

フローの作成を説明するために、このセクションでは、より高度なブラウザー・ログイン・フローの作成について説明します。このフローの目的は、ユーザーがWebAuthn、およびパスワードとOTPを使用した2要素認証を使用して、パスワードなしでログインすることを選択できるようにすることです。作成するフローは標準のブラウザー・ログインに似ていますが、ユーザー名の選択に到達すると分岐します。ただし、フローをコピーする代わりに、最初からフローを作成します。

  • レルムを選択し、Authenticationのリンクをクリックします

  • "new"を選択し、新しいフローに特有のAlias(つまり"Browser Password-less")を指定します

  • "Add execution",を選択し、ドロップダウンを使用して"Cookie"を選択します。"Save"を押した後、その要件を Alternative に設定します。

  • "Add execution"を選択し、ドロップダウンを使用して"Kerberos"を選択します。

  • "Add execution"を選択し、ドロップダウンを使用して"Identity Provider Redirector"を選択します。"Save"を押した後、その要件を Alternative に設定します。

  • "Add flow"を選択し、代理のAliasを選択します。たとえば、"Forms"。"Save"を押した後、その要件を Alternative に設定します。

ブラウザーフローとの共通部分

Passwordless browser login common

  • "Forms"サブフローの右側にある Actions メニューを使用して、"Add execution"を選択します。ドロップダウンを使用して、"Username Form"を選択します。"Save"を押した後、その要件を Required に設定します。

Username formは、"Browser"フローのUsername Password Formに似ていますが、ユーザー名のみを要求するため、ユーザーはパスワードレス・ログインを実行できます。ただし、これにより必然的にKeycloakサーバーでのユーザー列挙攻撃が可能であることに注意してください。これは利便性に対して避けられないセキュリティー・リスクであるため、このフローでは攻撃者がパスワードを推測するだけでは入れないようにしなければなりません。

  • "Forms"サブフローの右側にある Actions メニューを使用して、"Add flow"を選択します。代理のAlias(たとえば、"Authentication")を選択します。"Save"を押した後、その要件を Required に設定します。

  • "Authentication"サブフローの右側にある Actions メニューを使用して、"Add execution"を選択します。ドロップダウンを使用して、"Webauthn Passwordless Authenticator"を選択します。"Save"を押した後、その要件を Alternative に設定します。

  • "Authentication"サブフローの右側にある Actions メニューを使用して、"Add flow"を選択します。代理のAlias(たとえば、"Password with OTP")を選択します。"Save"を押した後、その要件を Alternative に設定します。

  • "Password with OTP"サブフローの右側にある Actions メニューを使用して、"Add execution"を選択します。ドロップダウンを使用して、"Password Form"を選択します。"Save"を押した後、その要件を Required に設定します。

  • "Password with OTP"サブフローの右側にある Actions メニューを使用して、"Add execution"を選択します。ドロップダウンを使用して、"OTP Form"を選択します。"Save"を押した後、その要件を Required に設定します。

  • "Bindings"メニューで、ブラウザーフローを"Browser"から"Browser Password-less"に変更します

生成される最終的なフローは次のとおりです。

パスワードレス・ブラウザー・ログイン

Passwordless browser login

ユーザー名を入力すると、このフローは次のように機能します。

  • ユーザーがWebAuthnパスワードレス・クレデンシャルを記録している場合、ユーザーはそれらのいずれかを使用して直接ログインできます。これがパスワードレス・ログインです。ユーザーは"Password with OTP"を選択することもできます。"WebAuthn"エグゼキューションと"Password with OTP"フローが Alternative に設定されているため、ユーザーはこれを行うことができます。これらが Required に設定されている場合、ユーザーはWebAuthn、パスワード、およびOTPを入力する必要があります。

  • ユーザーが"WebAuthn passwordless"認証のスクリーンで Try another way リンクを選択した場合、ユーザーは"Password"と"Security Key"(WebAuthnパスワードレス)から選択することが出来ます。パスワードを選択した場合、ユーザーは続けて紐づけられたOTPでログインする必要があります。ユーザーがWebAuthnクレデンシャルを持たない場合、ユーザーにWebAuthnクレデンシャルがない場合は、最初にパスワードを入力し、次にOTPを入力する必要があります。ユーザーにOTPクレデンシャルがない場合は、記録するように求められます。

WebAuthnパスワードレスのエグゼキューションは Required ではなく Alternative に設定されているため、このフローではユーザーにWebAuthnのクレデンシャルの登録を求めることはありません。ユーザーにWebAuthnのクレデンシャルを登録させるには、管理者が必須アクションを追加する必要があります。これは最初にレルムで Webauthn Register Passwordless の必須アクションが有効になっていることを確認して(WebAuthnドキュメントを参照)、次にユーザーのクレデンシャル管理メニューの Credential Reset の部分を使用して必須アクションを設定します。

このようなより高度なフローを作成すると、微妙な副作用が生じる可能性があります。たとえば、ユーザーのパスワードをリセットする機能を有効にする場合、パスワード・フォームからアクセスできます。デフォルトの"Reset Credentials"のフローでは、ユーザーはユーザー名を入力する必要があります。"Browser Password-less"フローの前半でユーザー名を既に入力しているため、これはKeycloakには不要であり、ユーザー・エクスペリエンスの観点からは最適ではありません。これを修正するには、次のことができます。

  • "Reset Credentials"フローをコピーし、名前を"Reset Credentials for password-less"などに設定します。

  • "Choose user"のエグゼキューションの右側にある Actions メニューを使用し、"Delete"を選択します

  • "Bindings"メニューで、クレデンシャルのリセットフローを"Reset Credentials"から"Reset Credentials for password-less"に変更します。

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

スクリプトを管理コンソールやRESTエンドポイントからアップロードする機能は廃止予定です。

詳しくは、 JavaScriptプロバイダー を参照してください。

Kerberos

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

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

  1. ユーザーは自分のデスクトップ(Kerberosの統合が有効なActive Directoryドメイン内のWindowsマシンまたはLinuxマシンなど)にログインします。

  2. ユーザーはブラウザー(IE/Firefox/Chrome)を使用して、Keycloakによって保護されたWebアプリケーションにアクセスします。

  3. アプリケーションはKeycloakログインにリダイレクトされます。

  4. Keycloakは、ステータス401とHTTPヘッダー WWW-Authenticate: Negotiate とともにHTMLログイン画面をレンダリングします

  5. ブラウザーは、デスクトップ・ログインからのKerberosチケットがある場合、ヘッダー Authorization: Negotiate 'spnego-token' にデスクトップ・サインオン情報をセットしてKeycloakに転送します。 それ以外の場合は、ログイン画面が表示されます。

  6. Keycloakは、ブラウザーから送信されたトークンを検証し、ユーザーを認証します。LDAP(Kerberos認証をサポートするLDAPFederationProviderの場合)からユーザーデータをプロビジョニングするか、ユーザーにプロファイルを更新し、データを事前に入力させることができます(KerberosFederationProviderの場合)。

  7. Keycloakはユーザーをアプリケーションに戻します。Keycloakとアプリケーションの間の通信は、OpenID ConnectまたはSAMLメッセージを介して行われます。KeycloakがKerberosを通じて認証されたという事実は、アプリケーションから隠されています。したがって、KeycloakはKerberos/SPNEGOログインのブローカーとして機能します。

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

  1. Kerberosサーバー(KDC)のセットアップと設定

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

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

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サーバーが実行されるホスト上でアクセス可能である必要があります。

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データベースへの細かいインポートを行います。名、姓、電子メールなどのユーザー・プロファイル情報はプロビジョニングされません。

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

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

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

設定例

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サーバーを実行する必要があります。詳細は こちら を参照してください。

クレデンシャルの委任

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と一緒に使用することを強くお勧めします。詳細については、 この記事 の例を参照してください。

クロスレルム・トラスト

Kerberos V5プロトコルでは、 realm はKerberosデータベース(通常はLDAPサーバー)で定義されたKerberosプリンシパルのセットです。Kerberosプロトコルには、クロスレルム・トラストという概念があります。たとえば、2つのケルベロス・レルムAとBがある場合、クロスレルム・トラストは、レルムAのユーザーがレルムBのリソース(サービス)にアクセスできるようにします。つまり、レルムBはレルムAを信頼します。

Kerberosクロスレルム・トラスト

kerberos trust basic

Keycloakサーバーは、クロスレルム・トラストをサポートしています。これを達成するために必要なことがいくつかあります。

  • クロスドメイン・トラストのためにKerberosサーバーを設定します。この手順は、使用された具体的なKerberosサーバー実装に依存します。一般に、レルムAとBの両方のKerberosデータベースにKerberosプリンシパル krbtgt/B@A を追加する必要があります。このプリンシパルは両方のKerberosレルムで同じキーを持つ必要があります。これは通常、プリンシパルが同じパスワード、キーバージョン番号を持ち、両方のレルムで同じ暗号が使用されている場合に実現されます。詳細については、Kerberosサーバーのマニュアルを参照することをお勧めします。

クロスレルム・トラストは、デフォルトでは単方向です。レルムAとレルムBを双方向に信頼させたい場合は、両方のKerberosデータベースにプリンシパル krbtgt/A@B を追加する必要があります。ただし、信頼はデフォルトでは推移的です。レルムBがレルムAを信頼し、レルムCがレルムBを信頼する場合、レルムCは利用可能なプリンシパル krbtgt/C@A を必要とせずに、レルムAを自動的に信頼します。Kerberosクライアント側で、クライアントがトラストパスを見つけることができるように設定するには、いくつかの追加の設定(例えば capaths )が必要な場合があります。詳細については、Kerberosのマニュアルを参照してください。
  • Keycloakサーバーの設定

    • KerberosサポートでLDAPストレージ・プロバイダーを使用する場合は、次の例のようにレルムBのサーバー・プリンシパルを設定する必要があります: HTTP/mydomain.com@B 。KeycloakサーバーがSPNEGOフローを実行してからユーザーを見つけることができる必要があるため、レルムAのユーザーがKeycloakに対して正常に認証されるようにするには、LDAPサーバーがレルムAからユーザーを検出できる必要があります。 たとえば、kerberosプリンシパル・ユーザー john@A が、 uid=john,ou=People,dc=example,dc=com のようなLDAP DNの下で、LDAPのユーザーとして利用可能でなければなりません。レルムAとレルムBの両方のユーザーが認証されるようにするには、LDAPがレルムAとレルムBの両方からユーザーを検出できるようにする必要があります。この制限を将来のバージョンで改善する計画があり、その場合は別々のレルムに対して別々のLDAPプロバイダーを作成し、両方でSPNEGOが機能することができます。

    • Kerberosユーザー・ストレージ・プロバイダー(通常はLDAP統合なしのKerberos)を使用する場合は、サーバーのプリンシパルを HTTP/mydomain.com@B として設定し、KerberosのレルムAとレルムBの両方のユーザーで認証できる必要があります。

Kerberosユーザー・ストレージ・プロバイダーでは、Kerberosレルム間で競合するユーザーが存在しないようにすることをお勧めします。競合するユーザーが存在する場合、それらは同じKeycloakユーザーに割り当てられます。これも将来のバージョンで改善し、KerberosプリンシパルからKeycloakユーザー名へのより柔軟なマッピングを提供する計画があります。

トラブルシューティング

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

  • KerberosまたはLDAPフェデレーション・プロバイダーの管理コンソールで Debug フラグを有効にする

  • standalone/configuration/standalone.xml のロギング・セクションに org.keycloak カテゴリのTRACEロギングを有効にして、詳細な情報 standalone/log/server.log を受け取ります。

  • システム・プロパティー -Dsun.security.krb5.debug=true-Dsun.security.spnego.debug=true を追加します

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

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

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

  • クライアントがSSL/TLSチャネルを介して認証リクエストを送信します。

  • SSL/TLSハンドシェイク中に、サーバーとクライアントはx.509/v3証明書を交換します。

  • コンテナ(WildFly)は、証明書のPKIXパスと有効期限を検証します。

  • x.509クライアント証明書オーセンティケーターは、次のようにクライアント証明書を検証します。

    • 必要に応じて、CRLおよび(または)CRL配布ポイントを使用して証明書失効ステータスをチェックします。

    • 必要に応じて、OCSP(オンライン証明書ステータス・プロトコル)を使用して証明書失効ステータスをチェックします。

    • 必要に応じて、証明書内のキー使用が予想されるキー使用と一致するかどうかを検証します。

    • 必要に応じて、証明書内の拡張キー使用法が予想される拡張キー使用法と一致するかどうかを検証します。

  • 上記のチェックのいずれかが失敗した場合、x.509認証は失敗します。

  • それ以外の場合、オーセンティケーターは証明書アイデンティティーを抽出し、既存のユーザーにマッピングします。

  • 証明書が既存のユーザーにマップされると、その動作は次のように認証フローによって分岐します。

    • ブラウザーフローでは、サーバーはアイデンティティーを確認するかそれを無視して、代わりにユーザー名/パスワードでサインインすることをユーザーに促します。

    • ダイレクト・グラント・フローの場合、サーバーはユーザーをサインインします。

機能

サポートされている証明書のアイデンティティー・ソース
  • 正規表現を使用したSubjectDN一致

  • X500 Subject’s e-mail属性

  • Subject Alternative Name Extension(RFC822Name General Name)からのX500 Subject’s e-mail

  • Subject Alternative Name Extensionから取得したX500サブジェクトの別の名前。これは通常UPN(User Principal Name)です。

  • X500 Subject’s Common Name属性

  • 正規表現を使用したIssuerDN一致

  • 証明書のシリアル番号

  • 証明書のシリアル番号とIssuerDN

  • SHA-256証明書のサムプリント

  • PEM形式の完全な証明書

正規表現

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

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

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

既存のユーザーに証明書のアイデンティティーをマッピングする

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

レルム設定で 電子メールによるログイン を無効にすると、同じルールが証明書認証に適用されることに注意してください。つまり、ユーザーはe-mail属性を使用してログインすることはできません。
アイデンティティー・ソースとして Certificate Serial Number and IssuerDN を使用するには、シリアル番号用とIssuerDN用の2つのカスタム属性が必要です。
SHA-256 Certificate thumbprint は、SHA-256証明書のサムプリントの小文字での16進数表現です。
アイデンティティー・ソースとしての Full certificate in PEM format の使用は、LDAPなどの外部フェデレーション・ソースにマッピングされたカスタム属性に制限されます。この場合、 Always Read Value From LDAP を有効にする必要があります。これは、長さの制限により証明書をKeycloakデータベースに保存できないためです。
その他の機能:拡張された証明書検証
  • CRLを使用した失効ステータスの確認

  • CRL/Distributionポイントを使用した失効ステータスの確認

  • OCSP/Responder URIを使用した失効ステータスの確認

  • 証明書のKeyUsage検証

  • 証明書のExtendedKeyUsage検証

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

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

WildFlyで相互SSLを有効にする

WildFlyでSSLを有効にする方法については、 Enable 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 (オプション)

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

ssl/keystore/key-password (オプション)

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

authentication/truststore

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

authentication/truststore/path

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

authentication/truststore/relative-to

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

authentication/truststore/keystore-password

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

httpsリスナーを有効にする

WildFlyでHTTPSを有効にする方法については、 HTTPSリスナー を参照してください。

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

<subsystem xmlns="urn:jboss:domain:undertow:11.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 に属性を設定すると、クライアント証明書が提供されていない場合、サーバーはインバウンド接続を拒否します。

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

  • レルムを選択し、Authenticationのリンクをクリックし、"Browser"フローを選択します。

  • ビルトインの "Browser" フローのコピーを作成します。新しいフローに特有の名前、すなわち、 "X.509 Browser" を付けることをお勧めします。

  • ドロップダウンを使用して、コピーされたフローを選択し、 "Add execution" をクリックします。

  • ドロップダウンを使用して"X509/Validate Username 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クライアント証明書認証の設定

x509 configuration

User Identity Source

クライアント証明書からユーザー・アイデンティティーを抽出する方法を定義します。

Canonical DN representation enabled (オプション)

標準形式を使用して識別名を決定するかどうかを定義します。形式については、公式 Java API documentation で詳しく説明されています。このオプションは、2つのユーザー・アイデンティティー・ソースの Match SubjectDN using regular expressionMatch IssuerDN using regular expression にのみ影響します。新しいKeycloakインスタンスをセットアップする場合は、このオプションを有効にすることをお勧めします。既存のKeycloakインスタンスとの互換性を維持するには、このオプションを無効のままにします。

Enable Serial Number hexadecimal representation (オプション)

シリアル番号の16進表現を使用するオプション。 RFC5280, Section-4.1.2.2 を参照してください。符号ビットが1に設定されたシリアル番号は、00オクテットで埋められる必要があります。例えば。 RFC5280に従って、10進数値が 161 のシリアル番号、または16進数表現の a100a1 としてエンコードする必要があります。詳細については、 RFC5280, appendix-B を参照してください。

A regular expression (オプション)

証明書アイデンティティーを抽出するフィルターとして使用する正規表現を定義します。正規表現には1つのグループが含まれている必要があります。

User Mapping Method

既存のユーザーに証明書アイデンティティーを一致させる方法を定義します。 Username or e-mail は、ユーザー名または電子メールから既存のユーザーを検索します。 Custom Attribute Mapper は、証明書アイデンティティーと一致するカスタム属性を持つ既存のユーザーを検索します。カスタム属性の名前は設定可能です。

A name of user attribute (オプション)

値が証明書IDと照合されるカスタム属性。属性マッピングが複数の値に関連している場合、複数のカスタム属性が関係します。例:'証明書のシリアル番号と発行者DN'。

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クライアント証明書認証は、ユーザーに証明書アイデンティティーの確認を促さず、ユーザーの認証に成功すると自動的にサインインします。

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

  • Keycloak管理コンソールを使用して、 "Authentication" をクリックし、 "Direct Grant" フローを選択します。

  • ビルドインの "Direct Grant"フローのコピーを作成します。新しいフローに特有の名前、すなわち、"X509 Direct Grant"を付けることをお勧めします。

  • "Username Validation" と "Password" のオーセンティケーターを削除します。

  • "Add execution" をクリックし、 "X509/Validate Username" を追加し、 "Save" をクリックして実行ステップを親フローに追加します。

x509 directgrant execution

  • RequirementREQUIRED に変更してください。

x509 directgrant flow

  • 前述のx.509ブラウザーフローのセクションの手順に従って、x509認証設定のセットアップを行います。

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

x509 directgrant flow bindings

クライアント証明書検索

HTTPリクエストがKeycloakサーバーに直接送信されると、WildFly undertowサブシステムはSSLハンドシェイクを確立し、クライアント証明書を抽出します。クライアント証明書は、サーブレット仕様で指定されているHTTPリクエストの属性 javax.servlet.request.X509Certificate に保存されます。Keycloak X509オーセンティケーターは、この属性から証明書を検索できます。

ただし、Keycloakサーバーがロードバランサーまたはリバース・プロキシーの背後にあるHTTPリクエストをリッスンする場合、クライアント証明書を抽出してMutual SSL接続を確立するのはプロキシー・サーバーであるかもしれません。リバース・プロキシーは通常、認証されたクライアント証明書を基礎となるもとのリクエストのHTTPヘッダーに入れ、バックエンドのKeycloakサーバーに転送します。この場合、Keycloakは、Undertowの場合と同様に、HTTPリクエストの属性ではなく、HTTPヘッダーからX.509証明書チェーンをルックアップできる必要があります。

Keycloakがリバース・プロキシーの背後にある場合、通常はKEYCLOAK_HOME/standalone/configuration/standalone.xmlに x509cert-lookup SPIの代替プロバイダーを設定する必要があります。HTTPヘッダーから証明書を検索する default プロバイダーに加えて、次に説明する haproxyapache という2つの組み込みプロバイダーも追加されています。

HAProxy証明書検索プロバイダー

KeycloakサーバーがHAProxyリバース・プロキシーの背後にある場合、このプロバイダーを使用できます。次のようにサーバーを構成します。

<spi name="x509cert-lookup">
    <default-provider>haproxy</default-provider>
    <provider name="haproxy" enabled="true">
        <properties>
            <property name="sslClientCert" value="SSL_CLIENT_CERT"/>
            <property name="sslCertChainPrefix" value="CERT_CHAIN"/>
            <property name="certificateChainLength" value="10"/>
        </properties>
    </provider>
</spi>

この設定例では、クライアント証明書はHTTPヘッダー SSL_CLIENT_CERT から検索され、チェーンの他の証明書は CERT_CHAIN_0CERT_CHAIN_1 、…、 CERT_CHAIN_9 のようなHTTPヘッダーから検索されます。属性 certificateChainLength はチェーンの最大長です。最後に試行された属性は CERT_CHAIN_9 です。

クライアント証明書とクライアント証明書チェーンのHTTPヘッダーの構成方法と固有名詞の詳細については、HAProxyのドキュメントを参照してください。

Apache証明書検索プロバイダー

KeycloakサーバーがApacheリバース・プロキシーの背後にある場合、このプロバイダーを使用できます。次のようにサーバーを設定します。

<spi name="x509cert-lookup">
    <default-provider>apache</default-provider>
    <provider name="apache" enabled="true">
        <properties>
            <property name="sslClientCert" value="SSL_CLIENT_CERT"/>
            <property name="sslCertChainPrefix" value="CERT_CHAIN"/>
            <property name="certificateChainLength" value="10"/>
        </properties>
    </provider>
</spi>

設定は haproxy プロバイダーと同じです。クライアント証明書とクライアント証明書チェーンのHTTPヘッダーの設定方法とその固有名については、 mod_sslmod_headers Apacheのドキュメントを参照してください。

Nginx証明書検索プロバイダー

KeycloakサーバーがNginxリバース・プロキシーの背後にある場合、このプロバイダーを使用できます。次のようにサーバーを構成します。

<spi name="x509cert-lookup">
    <default-provider>nginx</default-provider>
    <provider name="nginx" enabled="true">
        <properties>
            <property name="sslClientCert" value="ssl-client-cert"/>
            <property name="sslCertChainPrefix" value="USELESS"/>
            <property name="certificateChainLength" value="2"/>
        </properties>
    </provider>
</spi>
NGINX SSL/TLS module はクライアント証明書チェーンを公開しないため、Keycloak NGINX証明書ルックアップ・プロバイダーは Keycloak truststore を使用して再構築しています。keytool CLIを使用してクライアント証明書チェーンを再構築するために必要なすべてのルートCAおよび中間CAを使用して、Keycloakトラストストアにデータを入力してください。

クライアント証明書のHTTPヘッダーの設定方法の詳細については、NGINXのドキュメントを参照してください。NGINX設定ファイルの例を以下に示します。

 ...
 server {
    ...
    ssl_client_certificate                  trusted-ca-list-for-client-auth.pem;
    ssl_verify_client                       optional_no_ca;
    ssl_verify_depth                        2;
    ...
    location / {
      ...
      proxy_set_header ssl-client-cert        $ssl_client_escaped_cert;
      ...
    }
    ...
}
Keycloak truststore に、trusted-ca-list-for-client-auth.pemのすべての証明書を追加する必要があります。
その他のリバース・プロキシーの実装

他のリバース・プロキシーの実装のための組み込みサポートはありません。しかし、他のリバース・プロキシーを apachehaproxy と同様に動作させることができれば、それらのプロバイダーを使用することも可能です。そのような動作ができない場合は、 org.keycloak.services.x509.X509ClientCertificateLookupFactoryorg.keycloak.services.x509.X509ClientCertificateLookup プロバイダーの独自の実装を作成する必要があります。独自のプロバイダーを追加する方法については、Server Developer Guideを参照してください。

トラブルシューティング

HTTPヘッダーのダンプ

リバース・プロキシーがKeycloakに送信しているものを表示する場合は、 RequestDumpingHandler Undertowフィルターを有効にして、server.log ファイルを調べます。

ロギング・サブシステムでTRACEロギングを有効にします。
...
    <profile>
        <subsystem xmlns="urn:jboss:domain:logging:3.0">
...
            <logger category="org.keycloak.authentication.authenticators.x509">
                <level name="TRACE"/>
            </logger>
            <logger category="org.keycloak.services.x509">
                <level name="TRACE"/>
            </logger>
WARNING: Don't use RequestDumpingHandler or TRACE logging in production.
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形式であることも期待されます。

W3C Web Authentication(WebAuthn)

Keycloakは、 W3C Web Authentication(WebAuthn) の限定的なサポートを提供します。KeycloakはWebAuthnの Relying Party(RP) として機能します。

WebAuthnのサポートはまだ開発中であり、まだ完全ではないことに注意してください。この機能を実験的に使用することをお勧めします。また、このサポートの仕様とユーザー・インターフェイスは変更される場合があります。
WebAuthnの操作が成功するかどうかは、オーセンティケーター、ブラウザー、およびプラットフォームをサポートするユーザーのWebAuthnに依存します。このWebAuthnサポートを使用する場合は、それらのエンティティーがWebAuthn仕様をサポートする範囲を明確にしてください。

セットアップ

2FAのWebAuthnサポートのセットアップ手順は次のとおりです。

Webauthnオーセンティケーターの登録の有効化

管理者は、 管理コンソール で次の操作を行います。

  • Authentication → Required Actions タブを開きます。

  • Register をクリックします。

  • Required Action として Webauthn Register を選択します。

  • Enabled チェックボックスをチェックしてください。新しく作成された全てのユーザーにWebAuthnクレデンシャルを登録するよう要求したい場合は Default Action チェックボックスにチェックして下さい。

ブラウザーフローへのWebAuthn認証の追加
  • レルムを選択し、 Authentication のリンクをクリックし、 Browser フローを選択します。

  • ビルトインの "Browser" フローのコピーを作成します。新しいフローに特有の名前、たとえば、 "WebAuthn Browser" を付けることをお勧めします。

  • ドロップダウンを使用して、コピーしたフローを選択します

  • Actions メニューを使用して、 WebAuthn Browser Browser - Conditional OTP サブフローを削除します

すべてのユーザーにWebAuthnが必要な場合は以下のようにします。

  • WebAuthn Browser FormsActions メニューを使用して、 Add execution をクリックします

  • ドロップダウンを使用して WebAuthn Authenticator を選択し、 Save をクリックします

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

webauthn browser flow required

  • Bindings メニューで、ブラウザーフローを WebAuthn Browser に変更します

このシナリオでは、ユーザーがWebAuthnのクレデンシャルを持っていなければ、そのユーザーに強制的に登録させる必須アクションが設定されることに注意してください。

あるいは、WebAuthnのクレデンシャルが登録されている場合にのみ、ユーザーにWebAuthnでログインさせることができます。そのため、代わりに以下のように WebAuthn Authenticator のエグゼキューションを追加します。

  • WebAuthn Browser FormsActions メニューを使用して、 Add flow をクリックします

  • エイリアスを"Conditional 2FA"に設定し、 Save をクリックします

  • Conditional 2FA のRequirementを Conditional に設定します

  • Conditional 2FAActions メニューを使用して、 Add execution をクリックします

  • ドロップダウンを使用して Condition - User Configured を選択し、 Save をクリックします

  • Condition - User Configured のRequirementを Required に設定します

  • Conditional 2FAActions メニューを使用して、 Add execution をクリックします

  • ドロップダウンを使用して WebAuthn Authenticator を選択し、 Save をクリックします

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

webauthn browser flow conditional

ユーザーが2番目の要素としてWebAuthnとOTPのどちらを使用するかを選択できるようにすることもできます。

  • Conditional 2FAActions メニューを使用して、 Add execution をクリックします

  • ドロップダウンを使用して OTP Form を選択し、 Save をクリックします

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

webauthn browser flow conditional with OTP

WebAuthnオーセンティケーターで認証する

WebAuthn Authenticator を用いた条件サブフローが使用された認証フロー設定の場合、WebAuthnオーセンティケーターの登録後、ユーザーは以下の操作を行います。

  • ログインフォームを開きます。ユーザーはユーザー名とパスワードで認証する必要があります。

  • ユーザーのブラウザーは、WebAuthnオーセンティケーターによる認証をユーザーに要求します。

管理者としてWebAuthnを管理する

クレデンシャルの管理

WebAuthnクレデンシャルは、OTPなどの他のクレデンシャルと同様の方法で、ユーザー・クレデンシャル管理から管理されます。

  • ユーザーに Reset Actions のリストからWebAuthnクレデンシャルを作成するために必要なアクションを割り当て、 Webauthn Register を選択することができます

  • 管理者は、 Delete を押すことでWebAuthnのクレデンシャルを削除できます。

  • 管理者は、 Show data…​ を選択して、AAGUIDなどのクレデンシャルのデータを表示できます。

  • 管理者は、 User Label フィールドに値を設定してデータを保存することで、クレデンシャルのラベルを設定できます。

ポリシーの管理

管理者は、レルムごとに WebAuthn Policy としてWebAuthn関連の操作を設定できます。

管理者は、 管理コンソール で次の操作を行います。

  • Authentication → WebAuthn Policy タブを開きます。

  • アイテムを設定し、 Save をクリックします。

設定可能な項目とその説明は次のとおりです。

設定 説明

Relying Party Entity Name

人間が読めるWebAuthn Relying Partyのサーバー名。これは必須の設定であり、WebAuthnオーセンティケーターを登録する操作に適用されます。デフォルト設定は"keycloak"です。詳細については、 WebAuthn Specification を参照してください。

Signature Algorithms

これは、 認証アサーション の署名と検証に使用される 公開鍵クレデンシャル に使用する署名アルゴリズムをWebAuthnオーセンティケーターに伝えます。複数のアルゴリズムを指定できます。アルゴリズムが指定されていない場合、 ES256 が適応されます。デフォルト設定はES256です。これは、WebAuthnオーセンティケーターを登録する操作に適用されるオプションの設定項目です。詳細については、 WebAuthn Specification を参照してください。

Relying Party ID

これは、WebAuthnリライング・パーティーとしてのIDであり、公開鍵クレデンシャルのスコープを決定します。オリジンの有効なドメインでなければなりません。これは、WebAuthnオーセンティケーターを登録する操作に適用されるオプションの設定項目です。エントリーが入力されていない場合、KeycloakのサーバーのベースURLのホスト部分が適応されます。詳細については、 WebAuthn Specification を参照してください。

Attestation Conveyance Preference

ブラウザーのWebAuthn API実装( WebAuthnクライアント )に、認証ステートメントの生成方法の設定を伝えます。これは、WebAuthnオーセンティケーターを登録する操作に適用されるオプションの設定項目です。オプションが選択されていない場合、その動作は"none"を選択した場合と同じです。詳細については、 WebAuthn Specification を参照してください。

Authenticator Attachment

これは、WebAuthnオーセンティケーターの受け入れ可能なアタッチパターンをWebAuthnクライアントに伝えます。これは、WebAuthnオーセンティケーターを登録する操作に適用されるオプションの設定項目です。オプションが選択されていない場合、WebAuthnクライアントはアタッチパターンを考慮しません。詳細については、 WebAuthn Specification を参照してください。

Require Resident Key

Client-side-resident Public Key Credential Source として公開鍵クレデンシャルを生成するようにWebAuthnオーセンティケーターに指示します。これは、WebAuthnオーセンティケーターを登録する操作に適用されるオプションの設定項目です。オプションが選択されていない場合、その動作は"No"を選択した場合と同じです。詳細については、 WebAuthn Specification を参照してください。

User Verification Requirement

WebAuthnオーセンティケーターに、ユーザーの実際の検証を確認するよう指示します。これは、WebAuthnオーセンティケーターを登録し、WebAuthnオーセンティケーターによってユーザーを認証する操作に適用されるオプションの設定項目です。オプションが選択されていない場合、その動作は"preferred"を選択した場合と同じです。詳細については、 WebAuthn Specification for registering a WebAuthn authenticatorWebAuthn Specification for authenticating the user by a WebAuthn authenticator を参照してください。

Timeout

WebAuthnオーセンティケーターを登録し、WebAuthnオーセンティケーターによってユーザーを認証するためのタイムアウト値を秒単位で指定します。0に設定した場合、その動作はWebAuthnオーセンティケーターの実装に依存します。デフォルト値は0です。詳細については、 WebAuthn Specification for registering a WebAuthn authenticator および WebAuthn Specification for authenticating the user by a WebAuthn authenticator を参照してください。

Avoid Same Authenticator Registration

"ON"に設定すると、すでに登録されているWebAuthnオーセンティケーターを新規登録できません。これは、WebAuthnオーセンティケーターを登録する操作に適用されます。デフォルト設定は"OFF"です。

Acceptable AAGUIDs

WebAuthnオーセンティケーターを登録できるAAGUIDのホワイトリスト。これは、WebAuthnオーセンティケーターを登録する操作に適用されます。このリストにエントリーが設定されていない場合、任意のWebAuthnオーセンティケーターを登録できます。

Attestation Statement Verification

WebAuthnオーセンティケーターを登録するとき、KeycloakはこのWebAuthnオーセンティケーターによって生成された認証ステートメントを検証します。この検証プロセスで、Keycloakはこの認証ステートメントの信頼性を検証します。トラストアンカーの証明書が必要です。Keycloakは Keycloak truststore を使用するため、これらの証明書を事前にインポートする必要があります。

この検証ステートメントの信頼性検証を省略する場合は、このトラストストアを無効にするか、WebAuthnポリシーの設定項目"Attestation Conveyance Preference"を"none"に設定してください。

ユーザーとしてのWebAuthnクレデンシャルの管理

WebAuthnオーセンティケーターの登録

WebAuthnオーセンティケーターを登録する適切な方法は、ユーザーがKeycloakにアカウントを登録しているかどうかによって異なります。

新規ユーザー

レルムで WebAuthn Register 必須アクションが Default Action として設定された場合、新しいユーザーは最初のログイン成功時にWebAuthnセキュリティキーをセットアップすることが要求されます。新しいユーザーは以下の操作を実行します。

  • ログインフォームを開きます。

  • Register のリンクをクリックします。

  • 登録フォームの項目に入力し、 Register をクリックします。

  • ユーザーのブラウザーは、WebAuthnオーセンティケーターを登録するようにユーザーに要求します。

  • 登録が成功すると、ユーザーのブラウザーは、登録されたばかりのWebAuthnオーセンティケーターのラベルとしてテキストを入力するようにユーザーに要求します。

既存のユーザー

最初の例で示されたように、 WebAuthn Authenticator が必須として設定された場合、既存のユーザーがログインを試みた際もWebAuthnオーセンティケーターを登録することが自動的に要求されます。

  • ログインフォームを開きます。

  • 項目を入力し、 Save をクリックして Login をクリックします。

  • ユーザーがログインしたら、WebAuthnオーセンティケーターを登録する必要があります。

  • 登録が成功すると、ユーザーのブラウザーは、登録されたばかりのWebAuthnオーセンティケーターのラベルとしてテキストを入力するようにユーザーに要求します。

パスワードレスWebAuthnと二要素認証の併用

WebAuthnは二要素認証によく使用されますが、認証の第一要素として使用したい場合もあります。この場合、 passwordless WebAuthnクレデンシャルを持つユーザーはKeycloakにパスワード無しで認証することが出来ます。Keycloakは単一のレルムのコンテキスト、更には単一の認証フローのコンテキストでも、パスワードレスと二要素認証の両方でWebAuthnを使用することができます。

管理者は一般に、WebAuthnパスワードレス認証にユーザーが登録したセキュリティキーに対して、異なる(通常より強力な)要件を満たすことを要求する場合があります。たとえば、それらのセキュリティキーは、ユーザーがそのセキュリティキーに対してPINを用いて認証することを要求したり、そのセキュリティキーが強力な認証局で構成証明されていることを要求する場合があります。

このため、Keycloakでは管理者が個別に WebAuthn Passwordless Policy を設定できます。個別の Webauthn Register Passwordless タイプの必須アクションや、個別の WebAuthn Passwordless Authenticator タイプのオーセンティケーターを設定します。

セットアップ

WebAuthnパスワードレス・サポートのセットアップ手順は次のとおりです。

  • WebAuthnパスワードレス・サポートの為の新しい必須アクションを登録します。上記と同じ手順を使用しますが、一点異なることとして、 Webauthn Register Passwordless というアクションを登録する必要があります。

  • ポリシーを設定します。上記と同じ手順と設定を使用できますが、管理コンソールの WebAuthn Passwordless Policy タブで設定する必要があります。このポリシーは必要に応じて設定できますが、一般にセキュリティキーに対する要件は二要素認証の場合のポリシーに比べて強力になるでしょう。たとえば、パスワードレス・ポリシーを設定する際は、 User Verification RequirementRequired に設定できます。

  • 最後に、認証フローを設定します。上記で解説した WebAuthn Browser と同一のフローを使用すると仮定し、以下のように設定します。

    • WebAuthn Browser Forms サブフローは Username Form を第一のオーセンティケーターとして含みます。デフォルトの Username Password Form オーセンティケーターは削除し、 Username Form オーセンティケーターを代わりに追加します。この設定はユーザーがユーザー名だけを最初のステップで提供することを意味します。

必須サブフローもあるべきで、たとえば Passwordless Or Two-factor と命名することが出来ます。この設定はユーザーがパスワードレスWebAuthnクレデンシャルでも、二要素認証のどちらでも認証できることを示します。

  • フローは WebAuthn Passwordless Authenticator を第一の選択肢として含みます。

  • 第二の選択肢は、例えば Password And Two-factor Webauthn という命名をしたサブフローです。このサブフローは Password FormWebAuthn Authenticator を含みます。

フローの最終的な設定は、次のとおりです。

webauthn passwordless flow

これで、Keycloakに既に存在している任意のユーザーに必須アクションとして WebAuthn Register Passwordless を追加してテストすることができます。最初の認証では、ユーザーは依然としてパスワードと第二要素WebAuthnクレデンシャルを使用することが要求されます。しかしながら、一度ユーザーがクレデンシャルを登録すれば、ユーザーは今後の認証において、選択することが出来ます。ユーザーがWebAuthnパスワードレス・クレデンシャルを使用した場合、パスワードも、第二要素WebAuthnクレデンシャルも投入する必要はありません。

条件付きフロー内のCondition

エグゼキューション要件で述べたように、 Condition エグゼキューションは Conditional サブフローにのみ含めることができます。すべての Condition エグゼキューションがtrueと評価された場合、 Conditional サブフローは Required として機能します。 Conditional サブフローで次の実行を処理できます。 Conditional サブフローに含まれる一部のエグゼキューションがfalseと評価された場合、サブフロー全体が Disabled と見なされます。

利用可能なCondition

Condition - User Role

このエグゼキューションは、ユーザが User role フィールドで定義されたロールを持っているかどうかを判断する機能を持っています。ユーザが必要なロールを持っている場合、このエグゼキューションはtrueとみなされ、他のエグゼキューションが評価されます。管理者は以下のフィールドを定義しなければなりません。

Alias

認証フローに表示されるエグゼキューションの名前を記述します。

User role

ユーザがこのフローを実行するために持つべきロールです。アプリケーション・ロールを指定するには、構文は appname.approle (たとえば myapp.myrole )です。

Condition - User Configured

これは、フロー内の他のエグゼキューションがユーザに対して設定されているかどうかをチェックします。エグゼキューション要件のセクションには、OTPフォームの例が含まれています。

Condition - User Attribute

これは、ユーザが必要な属性を設定したかどうかをチェックします。ユーザーがその属性を持つべきではないことを意味する、出力を否定する可能性があります。 User Attributes セクションでは、カスタム属性を追加する方法を示しています。次のフィールドを提供することができます。

Alias

認証フローに表示されるエグゼキューションの名前を記述します。

Attribute name

チェックする属性の名前です。

Expected attribute value

属性に期待される値です。

Negate output

出力を否定することができます。つまり、属性が存在してはいけないということです。

SSOプロトコル

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

OpenID Connect

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

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

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

OIDC認証フロー

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

認可コード・フロー

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

  1. ブラウザーがアプリケーションにアクセスします。アプリケーションは、ユーザーがログインしていないことを検知し、認証させるためにブラウザーをKeycloakにリダイレクトします。アプリケーションは、Keycloakが認証を完了したときに使用するブラウザー・リダイレクトのコールバックURL(リダイレクトURL)をクエリー・パラメーターとして渡します。

  2. Keycloakはユーザーを認証し、1回限りで非常に存続期間の短い、一時的なコードを作成します。Keycloakは、以前に提供されたコールバックURLを使用してアプリケーションにリダイレクトします。コールバックURLには、クエリー・パラメーターとして一時コードが追加されます。

  3. アプリケーションは一時コードを抽出し、それを ID トークン、 アクセス トークンおよび リフレッシュ トークンと交換するため、バックグラウンドで帯域外のKeycloakへのREST呼び出しを行います。この一時コードを一度使用してトークンを取得すると、それを再び使用することはできません。これにより潜在的なリプレイ攻撃が防止されます。

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

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

Keycloakは、オプションの Proof Key for Code Exchange の仕様もサポートしています。

インプリシット・フロー

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

  1. ブラウザーがアプリケーションにアクセスします。アプリケーションは、ユーザーがログインしていないことを検知し、認証させるためにブラウザーをKeycloakにリダイレクトします。アプリケーションは、Keycloakが認証を完了したときに使用するブラウザー・リダイレクトのコールバックURL(リダイレクトURL)をクエリー・パラメーターとして渡します。

  2. Keycloakはユーザーを認証し、 ID トークンと アクセス トークンを作成します。Keycloakは、前述のコールバックURLを使用してアプリケーションにリダイレクトし、さらに ID トークンと アクセス トークンをクエリー・パラメーターとしてコールバックURLに追加します。

  3. アプリケーションは、コールバックURLから ID トークンと アクセス トークンを抽出します。

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

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

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

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

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

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

/realms/{realm-name}/protocol/openid-connect/auth

これは、認可コード・フローで一時コードを取得するため、またはインプリシット・フロー、ダイレクト・グラント、またはクライアント・グラントを使用してトークンを取得するためのURLエンドポイントです。

/realms/{realm-name}/protocol/openid-connect/token

これは、一時コードをトークンに変換する認可コード・フローのURLエンドポイントです。

/realms/{realm-name}/protocol/openid-connect/logout

これは、ログアウトを実行するためのURLエンドポイントです。

/realms/{realm-name}/protocol/openid-connect/userinfo

これは、OIDC仕様で説明されているUserInfoサービスのURLエンドポイントです。

/realms/{realm-name}/protocol/openid-connect/revoke

これは、 RFC7009 で説明されているOAuth 2.0トークン無効化のURLエンドポイントです。

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

SAML

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

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

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

SAMLバインディング

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

REDIRECTバインディング

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

  1. ユーザーがアプリケーションへアクセスすると、認証されていないことがアプリケーションによって検出されます。XML認証リクエスト・ドキュメントを生成し、それをKeycloakサーバーにリダイレクトするために使用されるURIのクエリー・パラメーターとしてエンコードします。設定に応じて、アプリケーションはこのXMLドキュメントにデジタル署名し、この署名をKeycloakへのリダイレクトURIのクエリー・パラメーターとして埋め込むこともできます。この署名は、このリクエストを送信したクライアントを検証するために使用されます。

  2. ブラウザーはKeycloakにリダイレクトされます。サーバーは、XML認証リクエスト・ドキュメントを抽出し、必要に応じてデジタル署名を検証します。ユーザーは認証されるためにクレデンシャルを入力する必要があります。

  3. 認証後、サーバーはXML認証レスポンス・ドキュメントを生成します。このドキュメントには、ユーザーの名前、住所、電子メール、およびユーザーが持つロール・マッピングなどのユーザーに関するメタデータを保持するSAMLアサーションが含まれています。このドキュメントは、ほとんどの場合、XML署名を使用してデジタル署名されており、暗号化されている場合もあります。

  4. 次に、XML認証レスポンス・ドキュメントは、ブラウザーをアプリケーションへ戻すためのリダイレクトURIのクエリー・パラメーターとしてエンコードされます。デジタル署名はクエリー・パラメーターとしても含まれています。

  5. アプリケーションは、リダイレクトURIを受け取った後、XMLドキュメントを抽出し、レルムの署名を検証して正しい認証レスポンスかどうかを検証します。SAMLアサーション内の情報は、アクセスの決定やユーザー・データの表示に使用されます。

POSTバインディング

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

セキュリティーとサイズの制限のため、通常 POST バインディングが推奨されます。 REDIRECT を使用する場合、SAMLレスポンスはURLの一部になります(前に説明したようにクエリー・パラメーターです)。したがって、ログに記録される可能性があり、安全性が低いと見なされます。サイズに関しては、ドキュメントを送信する多量または大量の属性がアサーション内に含まれている場合は、制限されたURLよりもHTTPペイロードが常に優れています。

ECP

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

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

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

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

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

OpenID Connect vs SAML

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

ほとんどの場合において、KeycloakではOIDCを使用することをお勧めします。

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

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

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

Dockerレジストリーv2認証

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

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

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レジストリーはトークンを検証し、必要に応じてリソースへのアクセスを許可します。

Dockerプロトコルによる認証が成功した後、Keycloak側にユーザー・セッションは作成されません。Dockerプロトコルは、ブラウザーSSOセッションの場合は使用されず、トークンを更新したり、特定のトークン/セッションがまだ有効かどうかをKeycloakサーバーに確認したりする方法がありません。したがって、セッションの作成は、このプロトコルにとって不要なオーバーヘッドです。詳細については、 transient session のセクションを参照してください。

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

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

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

クライアントの管理

クライアントは、ユーザーの認証を要求できるエンティティーです。クライアントには2つの形式があります。最初のタイプのクライアントは、シングル・サインオンに参加させるアプリケーションです。これらのクライアントはKeycloakにセキュリティーの提供を要求するだけです。もう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 を選択します。最後に、アプリケーションのベース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

ベアラーオンリーのアクセスタイプは、アプリケーションがベアラートークン・リクエストのみを許可することを意味します。これが有効になっている場合、このアプリケーションはブラウザー・ログインに参加できません。

Standard Flow Enabled

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

Implicit Flow Enabled

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

Direct Access Grants Enabled

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

Root URL

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

Valid Redirect URIs

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

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

Base URL

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

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 ボタンをクリックしなければならないことを覚えておいてください。

高度な設定

OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled

Mutual TLSは、アクセストークンとリフレッシュトークンを、TLSハンドシェイク中に交換されるクライアント証明書にバインドします。これは、これらのトークンを盗む方法を見つけた攻撃者がトークンを行使するのを防ぎます。このタイプのトークンは、holder-of-keyトークンと呼ばれます。ベアラートークンとは異なり、holder-of-keyトークンの受信者は、トークンの送信者が正当であるかどうかを検証することができます。

トークン・リクエストで次の条件が満たされた場合、Keycloakはアクセストークンとリフレッシュトークンをクライアント証明書でバインドし、holder-of-keyトークンとして発行します。すべての条件が満たされない場合、Keycloakはトークン・リクエストを拒否します。

  • この機能はオンになっている

  • トークン・リクエストが、認可コードフローまたはハイブリッド・フローでトークン・エンドポイントに送信される

  • TLSハンドシェイクで、Keycloakがクライアント証明書を要求し、クライアントがクライアント証明書を送信する

  • TLSハンドシェイクで、Keycloakがクライアント証明書を正常に検証する

KeycloakでMutual TLSを有効にするには、WildFlyでMutual SSLを有効にするを参照してください。

以下の場合、Keycloakはクライアントがアクセストークンまたはリフレッシュトークンを送信していることを確認します。検証に失敗した場合、Keycloakはトークンを拒否します。

  • トークン・リフレッシュ・リクエストが、holder-of-keyリフレッシュトークンを使用してトークン・エンドポイントに送信される

  • UserInfoリクエストは、holder-of-keyアクセストークンを使用してUserInfoエンドポイントに送信される

  • ログアウト・リクエストが、holder-of-keyリフレッシュトークンでログアウト・エンドポイントに送信される

詳細については、OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokensの Mutual TLS Client Certificate Bound Access Tokens を参照してください。

現在、Keycloakクライアント・アダプターのどれも、holder-of-keyトークンの検証をサポートしていません。代わりに、Keycloakアダプターはアクセストークンとリフレッシュトークンをベアラートークンとして扱います。

Proof Key for Code Exchange(PKCE)

攻撃者が正当なクライアントに発行された認可コードを盗んだとしても、PKCEは攻撃者がそのコードと引き換えてトークンを受信できないようにします。

管理者は、次の3つのオプションを選択できます。

Proof Key for Code Exchange Code Challenge Method

  • (blank) : クライアントがPKCEのパラメーターをKeycloakの認可エンドポイントに適切に送信しない限り、KeycloakはPKCEを適用しません。これがデフォルト設定です。

  • S256 : Keycloakは、コード・チャレンジ・メソッドがS256であるクライアントPKCEに適用します。

  • plain : Keycloakは、コード・チャレンジ・メソッドがプレーンなクライアントPKCEに適用します。

詳細については、 RFC 7636 Proof Key for Code Exchange by OAuth Public Clients を参照してください。

Signed and Encrypted ID Token Support

Keycloakは、 Json Web Encryption(JWE) の仕様に従ってIDトークンを暗号化できます。管理者は、クライアントごとにIDトークンを暗号化するかどうかを決定できます。この機能はデフォルトで無効になっています。

IDトークンを暗号化するためのキーは、Content Encryption Key (CEK)と呼ばれます。Keycloakとクライアントは、使用するCEKとその配信方法について交渉する必要があります。これを行う方法は、Key Management Modeと呼ばれます。

JWE仕様は、5種類のKey Management Modeを決定します。Keycloakはそれらの間で Key Encryptionをサポートします。

Key Encryptionでは、クライアントは非対称暗号化のキーペアを生成します。公開鍵はCEKの暗号化に使用されます。KeycloakはIDトークンごとにCEKを生成し、この生成されたCEKによってIDトークンを暗号化し、このクライアントの公開キーによってこのCEKを暗号化します。クライアントは、この暗号化されたCEKを自分の秘密鍵で復号し、復号されたCEKでIDトークンを復号します。したがって、クライアント以外の第三者はIDトークンを復号できません。

クライアントは、CEKを暗号化するための公開鍵をKeycloakに渡す必要があります。Keycloakは、クライアントが提供するURLからの公開鍵のダウンロードをサポートしています。クライアントは Json Web Keys (JWK) の仕様に従って公開鍵を提供する必要があります。その方法は、 Confidential Client CredentialsSigned JWT で定義されています。詳細な手順は次のとおりです。

  • クライアントの Credentials タブを開きます

  • Client Authenticator のプルダウン・メニューから Signed Jwt を選択します

  • JWKS URL スイッチをONに設定します

  • JWKS URL テキストボックスにURLを提供するクライアントの公開鍵を入力します

鍵暗号化のアルゴリズムは、 Json Web Algorithm(JWA) の仕様で定義されています。Keycloakは、RSAES-PKCS1-v1_5(RSA1_5)、デフォルトのパラメーター(RSA-OAEP)を使用したRSAES OAEPおよびSHA-256とMFG1(RSA-OAEP-256)を使用したRSAES OAEP 256をサポートします。このアルゴリズムを選択する詳細な手順は次のとおりです。

  • クライアントの Settings タブを開きます

  • Fine Grain OpenID Connect Configuration をオープンします

  • ID Token Encryption Key Management Algorithm のプルダウン・メニューから RSA1_5RSA-OAEP または RSA-OAEP-256 を選択します

CEKによるIDトークン暗号化アルゴリズムは、 JWA の仕様でも定義されています。Keycloakは、AES_CBC_HMAC_SHA2アルゴリズムとAES GCMアルゴリズムをサポートしています。このアルゴリズムを選択する詳細な手順は次のとおりです。

  • クライアントの Settings タブを開きます

  • Fine Grain OpenID Connect Configuration をオープンします

  • ID Token Encryption Content Encryption Algorithm のプルダウンメニューからアルゴリズムを選択します

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

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

Credentialsタブ

client credentials

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

また、シークレットではなく署名付きJSON Web Token(JWT)またはx509証明書検証(Mutual TLSとも呼ばれます)を使用することもできます。

署名付きJWT

client credentials jwt

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

鍵を生成する

generate client keys

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

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

証明書のインポート

import client cert

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

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

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

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

Client Authenticator リストボックスでこのオプションを選択すると、秘密鍵の代わりにクライアント・シークレットで署名されたJWTを使うことができます。

このクライアント・シークレットは、クライアントによってJWTに署名するために使用されます。

X509証明書

このオプションを有効にすると、KeycloakはTLSハンドシェイク中にクライアントが適切なX509証明書を使用するかどうかを検証します。

このオプションは、KeycloakにMutual SSLが必要です。WildFlyでMutual SSLを有効にするを参照してください。
X509証明書

x509 client auth

バリデーターは、設定された正規表現の検証式を使用して、証明書のSubject DNフィールドもチェックします。いくつかのユースケースでは、すべての証明書を受け入れるだけで十分です。その場合、 (.*?)(?:$) 式を使うことができます。

KeycloakがリクエストからクライアントIDを取得するには、2つの方法があります。最初のオプションは、クエリーの client_id パラメーターです( OAuth 2.0 Specification のセクション2.2で説明されています)。2番目のオプションは、フォーム・パラメーターとして client_id を提供することです。

サービス・アカウント

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

サービス・アカウントを使用するには、有効な confidential クライアントを登録していなければなりません。また、そのクライアントのKeycloak管理コンソールの Service Accounts Enabled スイッチをオンにする必要があります。 Service Account Roles タブでは、このクライアントに代わって取得されたサービス・アカウントで使用可能なロールを設定できます。 Full Scope Allowed をオンにしない限り、このクライアントのロール・スコープ・マッピング( Scope タブ)でロールを利用可能にする必要があることに注意してください。通常のログインと同様に、アクセストークンのロールは以下の論理積となります。

  • リンクされたクライアント・スコープから継承されたロール・スコープ・マッピングと結合された特定のクライアントのロール・スコープ・マッピング

  • サービス・アカウント・ロール

呼び出す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
}

デフォルトで返されるのはアクセストークンだけです。デフォルトではリフレッシュトークンは返されず、認証に成功した際にKeycloak側で作成されるユーザー・セッションもありません。リフレッシュトークンがないため、アクセストークンの有効期限が切れたときに再認証する必要がありますが、デフォルトではセッションが作成されないため、これはKeycloakサーバー側で追加のオーバーヘッドが発生することを意味しません。

このため、ログアウトする必要はありませんが、発行されたアクセストークンは、OpenID Connect Endpointsのセクションで説明されているOAuth2 Revocation Endpointにリクエストを送信することで取り消すことができます。

Audienceのサポート

Keycloakがデプロイされる典型的な環境は、一般に、認証にKeycloakを使用する confidential または public なクライアント・アプリケーション(フロントエンド・クライアント・アプリケーション)のセットで構成されています。

フロントエンドのクライアント・アプリケーションからのリクエストを処理し、リソースを提供する サービス(OAuth 2の仕様では リソースサーバー と呼ばれます)もあります。これらのサービスは通常、特定のリクエストに対して認証するためにサービスに送信される アクセストークン (ベアラートークン)を必要とします。このトークンは、クライアント・アプリケーションがKeycloakに対してログインを試行したときに取得されたものです。

サービス間の信頼性が低い環境では、次のシナリオが発生する可能性があります。

  1. my-app というフロントエンドのクライアント・アプリケーションはKeycloakによって認証される必要があります。

  2. ユーザーはKeycloakで認証されています。そしてKeycloakは my-app にトークンを発行しました。

  3. my-app はトークンを使って evil-service というサービスを呼び出しました。 evil-service は非常に有用なデータを提供することができるので、 my-appevil-service を呼び出す必要があります。

  4. evil-servicemy-app にレスポンスを返しました。ただし、同時に、以前に送信されたトークンを保持しました。

  5. そして evil-service は以前に保持したトークンを使って good-service という別のサービスを呼び出しました。呼び出しは成功し、 good-service はデータを返しました。 evil-servicemy-app に代わって他のサービスにアクセスするためにトークンを悪用したため、セキュリティーが破綻します。

このフローは、サービス間の信頼性が高い多くの環境では問題にならないかもしれません。しかし、サービス間の信頼性が低い他の環境では、これが問題になる可能性があります。

環境によっては、リクエストされたデータを元の呼び出し元(my-app)に正しく返せるように、 evil-servicegood-service から追加のデータを取得する必要があるかもしれないため、このワークフロー例は要求された動作でさえあるかもしれません。あなたは、Kerberos Credential Delegationとの類似点に気付くかもしれません。Kerberos Credential Delegationと同様に、サービス間に高い信頼レベルがある場合にのみ有用なため、無制限のAudienceは必ずしもいい事ずくめではないです。それ以外の場合は、次に説明するようにAudienceを制限することをお勧めします。Audienceを制限し、同時に evil-servicegood-service から必要なデータを取得することを許可することができます。この場合、トークンに evil-servicegood-service の両方がAudienceとして追加されていることを確認する必要があります。

上記の例のようにアクセストークンの誤用を防ぐために、トークンの Audience を制限し、トークンのAudienceを検証するようにサービスを設定することをお勧めします。これが行われると、上記のフローは次のように変わります。

  1. my-app というフロントエンドのクライアント・アプリケーションはKeycloakによって認証される必要があります。

  2. ユーザーはKeycloakで認証されています。そしてKeycloakは my-app にトークンを発行しました。 my-app はすでにサービス evil-service を呼び出す必要があることを知っているので、Keycloakサーバーに送信される認証リクエストで scope = evil-service を使いました。 scope パラメーターの詳細については、クライアント・スコープのセクションを参照してください。 my-app に発行されたトークンは "audience": [ "evil-service" ] のようにAudienceを含んでいます。これは my-app がこのアクセストークンを使って evil-service サービスだけを呼び出すことを望んでいることを宣言します。

  3. evil-servicemy-app からのリクエストを処理しました。同時に、以前に送信されたトークンを保持しました。

  4. それから evil-service は以前に保持されたトークンで good-service を呼び出しました。呼び出しは成功しませんでした。なぜなら、 good-service はトークン上のAudienceをチェックし、Audienceは単に evil-service であると見なしたためです。これは予想される動作であり、セキュリティーは破られていません。

my-app が後で good-service を呼び出したい場合は、 scope = good-service を指定してSSOログインを発行し、別のトークンを取得する必要があります。返されたトークンはAudienceとして good-service を含みます。

"audience": [ "good-service" ]

そして good-service を呼び出すために使うことができます。

セットアップ

Audienceチェックを正しく設定するには、次のようにします。

  • アダプター設定にフラグ verify-token-audience を追加して、サービスがそれらに送信されたアクセストークンでAudienceをチェックするように設定されていることを確認します。詳しくは、 アダプター構成 を参照してください。

  • アクセストークンがKeycloakによって発行されるときに、要求されたすべてのAudienceが含まれ、不要なAudienceが含まれていないことを確認してください。Audienceは、 次のセクション で説明されているようにクライアントロールによって自動的に追加されるか、または 以下 のようにハードコーディングされます。

Audienceを自動的に追加

デフォルトのクライアント・スコープ・ ロール には、 Audience Resolve プロトコル・マッパーが定義されています。このプロトコル・マッパーは、現在のトークンに使用可能なクライアントロールが少なくとも1つあるか、すべてのクライアントに対してチェックします。その後、それらの各クライアントのクライアントIDがAudienceとして自動的に追加されます。これは、サービス(通常はベアラーのみ)クライアントがクライアントロールに依存している場合に特に便利です。

例として、認証したいベアラー専用クライアント good-service とコンフィデンシャル・クライアント my-app があり、 good-service RESTサービスを呼び出すために、 my-app に対して発行されたアクセストークンを使用するとしましょう。以下が当てはまる場合、

  • good-service クライアントは、自身に定義された任意のクライアントロールを持つ

  • ターゲット・ユーザーには、これらのクライアントロールの少なくとも1つが割り当てられている

  • my-app クライアントは、割り当てられたロールに対してロール・スコープ・マッピングを持っている

good-servicemy-app に対して発行されたアクセストークンにAudienceとして自動的に追加されます。

Audienceが自動的に追加されないようにするには、ロール・スコープ・マッピングを直接 my-app クライアントに設定しないでください。代わりに、 good-service クライアントのクライアントロールのロール・スコープ・マッピングを含む専用のクライアント・スコープ(たとえば、 good-service )を作成してください。このクライアント・スコープがオプションのクライアント・スコープとして my-app クライアントに追加されると仮定すると、クライアントロールとAudienceは scope=good-service パラメーターによって明示的に要求された場合にのみトークンに追加されます。
フロントエンド・クライアント自体は、アクセストークンのAudienceに自動的に追加されません。アクセストークンには、トークンがAudienceとして発行されたクライアントが含まれないため、これによりアクセストークンとIDトークンを簡単に区別できます。したがって、上記の例では、 my-app はAudienceとして追加されません。クライアント自体をAudienceとして必要とする場合は、ハードコードされたAudienceのオプションを見てください。ただし、フロントエンドとRESTサービスの両方に同じクライアントを使用することはお勧めできません。
ハードコードされたAudience

サービスがレルムロールに依存している場合、またはトークン内のロールにまったく依存していない場合は、ハードコードされたAudienceを使用すると便利です。これはプロトコル・マッパーであり、指定されたサービス・クライアントのクライアントIDをAudienceとしてトークンに追加します。クライアントIDとは異なるユーザー層が必要な場合は、任意のカスタム値(たとえば、URL)を使用することもできます。

プロトコル・マッパーをフロントエンド・クライアントに直接追加できますが、Audienceは常に追加されます。よりきめ細かい制御が必要な場合は、専用のクライアント・スコープ(たとえば、 good-service )で、プロトコル・マッパーを作成できます。

Audience Protocol Mapper

audience mapper

  • good-service クライアントのInstallationタブから、アダプター設定を生成でき、 verify-token-audience オプションがtrueに設定されることを確認できます。この生成された設定を使用する場合、アダプターがAudienceの検証を必要とすることを示しています。

  • 最後に、 my-app フロントエンド・クライアントがそのトークンの中のAudienceとして good-service をリクエストできることを確認する必要があります。 my-app クライアントで、 Client Scopes タブをクリックしてください。それからオプションの(またはデフォルトの)クライアント・スコープとして good-service を割り当てます。詳しくはクライアント・スコープ・リンキングのセクションを参照してください。

  • オプションでクライアント・スコープの評価を実行してアクセストークンのサンプルを生成することもできます。その場合、 good-servicescope パラメーターに含まれている場合にのみ、生成されたアクセストークンのAudienceに good-service が追加されることに注意してください。

  • my-app アプリケーションで、 good-service にアクセスするためのトークンを発行したいときには、 scope パラメーターが必ず good-service の値とともに使われるようにしなければなりません。アプリケーションがサーブレット・アダプターを使用している場合は パラメーター転送のセクション を、アプリケーションがJavaScriptアダプターを使用している場合は JavaScriptアダプターのセクション を参照してください。

トークン内の正しいAudienceとロールがどのようなものになるのかわからない場合は、管理コンソールでクライアント・スコープの評価を実行し、それをテストすることをお勧めします。
AudienceAudience Resolve の両方のプロトコル・マッパーは、デフォルトでAudienceをアクセストークンだけに追加します。IDトークンには通常、単一のAudience(トークンが発行されたクライアントのクライアントID)しか含まれていません。これはOpenID Connectの仕様における要件です。一方、アクセストークンは、Audienceマッパーがそれを追加しない限り、必ずしもクライアントID(発行されたトークンであるクライアントのクライアントID)を持つ必要はありません。

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 SAML Endpoint URLを入力します。KeycloakサーバーがSAMLリクエストとレスポンスを送信するURLを入力します。通常、アプリケーションにはSAMLリクエストを処理するURLが1つしかありません。アプリケーションがバインディングのために異なるURLを持っている場合でも、心配する問題はありません。クライアントの Settings タブでこれを修正できます。 Save をクリックすると、クライアントが作成され、クライアントの Settings タブに移動します。

クライアントの設定

client settings saml

Client ID

この値は、AuthNRequestとともに送信されたissuer値と一致する必要があります。Keycloakはissuerを認証SAMLリクエストから取得し、この値でクライアントと照合します。

Name

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

Description

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

Enabled

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

Consent Required

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

Include AuthnStatement

SAMLログイン・レスポンスでは、使用される認証方法(パスワードなど)、ログインのタイムスタンプ、およびセッションの有効期限を指定できます。これはデフォルトで有効になっています。つまり、 AuthStatement 要素がログイン・レスポンスに含まれます。これをオフに設定すると、クライアントは最大セッション長を決定できなくなり、クライアント・セッションが期限切れにならないことに注意してください。

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認証レスポンスに埋め込まれます。

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。

IDP Initiated ログイン

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

IdP initiated loginの実装は、REDIRECT バインディングよりも POST バインディングを優先します(詳細についてはSAMLバインディングをチェックしてください)。したがって、最終的なバインディングとSPのURLは次のように選択されます。

  1. 特定の Assertion Consumer Service POST Binding URL が(クライアント設定の Fine Grain SAML Endpoint Configuration セクション内に)定義されている場合、POST バインディングはそのURLを介して使用されます。

  2. 一般的な Master SAML Processing URL が指定されている場合は、この一般的なURLを介して POST バインディングが再度使用されます。

  3. 最後の手段として、 Assertion Consumer Service Redirect Binding URL が( Fine Grain SAML Endpoint Configuration 内に)設定されている場合、このURLとともに REDIRECT バインディングが使用されます。

クライアントが特別なリレーステートを必要とする場合は、 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 URLbroker-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に追加します。

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 にアクセスすれば、これを取得することができます。

クライアントのリンク

あるクライアントから別のクライアントにリンクしたい場合のために、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 にリダイレクトします。

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

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

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

Mappersタブ

mappers oidc

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

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

マッパーの設定

mapper config

設定オプションについて学ぶ最も良い方法は、ツールチップにカーソルを合わせることです。

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

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

マッパーの追加

add mapper

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

優先順位

マッパーの実装には 優先順位 があります。この優先順位はマッパーの設定プロパティーではなく、むしろそれはマッパーの具体的な実装のプロパティーです。

マッパーは、管理コンソールにおけるマッパーのリストの順序に従ってソートされ、トークンまたはアサーションの変更はその順序で最も低いものが最初に適用されます。これは、他の実装に依存している実装が必要な順序で処理されることを意味します。

たとえば、最初にトークンに含まれるロールを割り出したい場合は、まずそれらのロールに基づいてオーディエンスを解決します。次に、トークンですでに利用可能なロールとオーディエンスを使用するJavaScriptのスクリプトを処理します。

OIDCユーザー・セッション・ノート・マッパー

ユーザー・セッションの詳細は、マッパーを介して定義され、さまざまな基準に依存します。クライアントである機能を使用または有効にすると、ユーザー・セッションの詳細が自動的に含まれます。セッションの詳細を含めるために、 Add builtin ボタンをクリックすることもできます。

代理ユーザー・セッションは、次の詳細を提供します。

  • IMPERSONATOR_ID: 代理ユーザーのID

  • IMPERSONATOR_USERNAME: 代理ユーザーのユーザー名

サービス・アカウント・セッションは、次の詳細を提供します。

  • clientId :サービス・アカウントのクライアントID

  • clientAddress :サービス・アカウントの認証済みデバイスのリモートホストIP

  • clientHost :サービス・アカウントの認証済みデバイスのリモートホスト名

Script Mapper

Script Mapper を使用すると、ユーザー定義のJavaScriptコードを実行して、クレームをトークンにマッピングできます。サーバーにスクリプトをデプロイする方法の詳細については、JavaScriptプロバイダーを参照してください。

スクリプトをデプロイしたら、使用可能なマッパーのリストからデプロイしたスクリプトを選択できるはずです。

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

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

client installation

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

クライアント・スコープ

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

クライアント・スコープは、OAuth 2の scope パラメーターもサポートしています。これにより、クライアント・アプリケーションは、アプリケーションのニーズに応じて、アクセストークン内のより多いまたはより少ないクレームまたはロールを要求できます。

クライアント・スコープを作成するには、次の手順を実行します。

  • Client Scopes の左メニュー項目をクリックします。この初期画面には、現在定義されているクライアント・スコープのリストが表示されます。

クライアント・スコープ一覧

client scopes list

  • Create ボタンをクリックします。クライアントのスコープに名前を付けて保存します。 クライアント・スコープ は、通常のクライアントと同様のタブを持ちます。プロトコル・マッパーおよびロール・スコープ・マッピングを定義することができます。これは他のクライアントによって継承でき、このクライアント・スコープから継承するように設定されています。

プロトコル

クライアント・スコープを作成するときは、 Protocol を選択する必要があります。同じプロトコルを使用するクライアントだけがこのクライアント・スコープにリンクできます。

新しいレルムを作成すると、あらかじめ定義された(ビルトインの)クライアント・スコープの一覧がメニューに表示されます。

  • SAMLプロトコルには、ビルトインのクライアント・スコープの1つである roles_list があります。これには、SAMLアサーション内でロールリストを示すためのプロトコル・マッパーが含まれています。

  • OpenID Connectプロトコルには、 profileemailaddressphoneoffline_accessrolesweb-originsmicroprofile-jwt のクライアント・スコープがあります。

クライアント・スコープの offline_access は、クライアントがオフライントークンを取得したいときに便利です。オフライントークンについては、オフライン・アクセスのセクションまたは OpenID Connect仕様 を参照してください。ここでは、スコープ・パラメーターは offline_access 値で定義されています。

クライアント・スコープの profileemailaddress および phoneOpenID Connect仕様 で定義されています。これらのクライアント・スコープには、ロール・スコープ・マッピングは定義されていませんが、いくつかのプロトコル・マッパーが定義されています。これらのマッパーは、OpenID Connect仕様で定義されたクレームに対応しています。

たとえば、 phone のクライアント・スコープを開き、Mappers タブを開くためにクリックすると、 phone スコープの仕様で定義されているクレームに対応するプロトコル・マッパーが表示されます。

クライアント・スコープ・マッパー

client scopes phone

phone クライアント・スコープがクライアントにリンクされると、そのクライアントは自動的に phone クライアント・スコープで定義されたすべてのプロトコル・マッパーを継承します。このクライアント用に発行されたアクセストークンには、ユーザーに関する電話番号情報が格納されます(定義された電話番号をユーザーが持っていると仮定する場合)。

ビルトインのクライアント・スコープには、仕様に従って定義されたプロトコル・マッパーが完全に含まれていますが、クライアント・スコープの編集やプロトコル・マッパー(またはロール・スコープ・マッピング)の作成/更新/削除は自由にでできます。

クライアント・スコープの roles はOpenID Connectの仕様では定義されておらず、アクセストークンの scope のクレームにも自動的に追加されません。このクライアント・スコープにはいくつかのマッパーがあります。マッパーは、ユーザーのロールをアクセストークンに追加し、オーディエンスのセクションで説明されているように少なくとも1つのクライアントロールを持つクライアントにオーディエンスを追加するために使用されます。

クライアント・スコープ web-origins もOpenID Connect仕様で定義されておらず、scope クレームに追加されていません。これは、許可されたWebオリジンをアクセストークンの allowed-origins クレームに追加するために使用されます。

クライアント・スコープ microprofile-jwt は、 MicroProfile/JWT Auth Specification で定義されているクレームを処理するために作成されました。このクライアント・スコープは、 upn クレーム用のユーザー・プロパティー・マッパーと groups クレーム用のレルム・ロール・マッパーを定義します。MicroProfile/JWT固有のクレームを作成するためさまざまなプロパティーを使用できるように、これらのマッパーは必要に応じて変更できます。

同意関連の設定

クライアント・スコープには、同意画面に関連するオプションが含まれています。これらのオプションは、リンクされたクライアントが同意を要求するように設定されている場合(クライアント上で Consent Required スイッチが有効になっている場合)にのみ有効です。

同意画面での表示

オンで、かつ同意が必要なクライアントにこのクライアント・スコープが追加された場合、同意画面に同意画面テキストで指定されたテキストが表示されます。同意画面は、ユーザーが認証され、Keycloakからクライアントへリダイレクトされる直前に一度表示されます。スイッチがオフの場合、このクライアント・スコープは同意画面に表示されません。

同意画面テキスト

このクライアント・スコープが一部の同意が必要なクライアントに加えられたときに、同意画面に表示されるテキストは、デフォルトでクライアント・スコープの名前になります。このテキストの値は、 ${var-name} 文字列で置換変数を指定することによってローカライズ可能です。ローカライズされた値は、テーマのプロパティー・ファイル内で設定されます。ローカリゼーションの詳細については、Server Developer Guideを参照してください。

クライアントとクライアント・スコープをリンクする

クライアント・スコープとクライアントとの間のリンクは、特定のクライアントの Client Scopes タブで設定されます。クライアント・スコープとクライアントをリンクする方法は2つあります。

デフォルトのクライアント・スコープ

これは、OpenID ConnectとSAMLの両方のクライアントに適用されます。このクライアントに対してOpenID ConnectトークンまたはSAMLアサーションを発行するときは、デフォルトのクライアント・スコープが常に適用されます。クライアントは、クライアント・スコープで定義されたプロトコル・マッパーとロール・スコープ・マッピングを継承します。OpenID Connectプロトコルでは、OpenID Connect認可リクエストのスコープ・パラメーターに使用されている値に関係なく、マッパーとロールスコープのマッピングが常に適用されます。

オプションのクライアント・スコープ

これは、OpenID Connectクライアントにのみ適用されます。オプションのクライアント・スコープは、このクライアントに対してトークンを発行するときに適用されますが、OpenID Connect認可リクエストの scope パラメーターによって要求された場合に限られます。

この例では、クライアントにはデフォルトのクライアント・スコープとして profileemail がリンクされており、オプションのクライアント・スコープとして profileemail がリンクされていると仮定します。クライアントは、OpenID Connect認可エンドポイントにリクエストを送信するときに、scopeパラメーターの値を使用します。

scope=openid phone

scopeパラメーターには、スコープの値をスペースで区切った文字列が含まれます(これが、クライアント・スコープ名にスペース文字を含めることができない理由です)。値 openid はすべてのOpenID Connectリクエストに使用されるメタ値なので、この例では無視します。トークンには、クライアント・スコープの profileemail (デフォルト・スコープ)、 phone (スコープ・パラメーターによって要求されるオプションのクライアント・スコープ)のマッパーとロールスコープのマッピングが含まれます。

クライアント・スコープの評価

クライアントの MappersScope タブには、このクライアント用に宣言されたプロトコル・マッパーとロールスコープのマッピングが含まれています。クライアント・スコープから継承されたマッパーとスコープ・マッピングは含まれていません。ただし、特定のクライアントのトークンを生成するときに、有効なプロトコル・マッパー(クライアント自体で定義され、リンクされたクライアント・スコープから継承されたプロトコル・マッパー)がどれであるか、有効なロール・スコープ・マッピングが使用されているかを確認すると便利です。

クライアントの Client Scopes タブをクリックし、 Evaluate サブタブを開くと、これらのすべてを見ることができます。ここから、適用するオプションのクライアント・スコープを選択できます。これは scope パラメーターの値も表示します。このパラメーターは、アプリケーションからKeycloak OpenID Connect認可エンドポイントに送信する必要があります。

クライアント・スコープの評価

client scopes evaluate

アプリケーションから scope パラメーターのカスタム値を送信する方法を知りたい場合、アプリケーションでサーブレット・アダプターを使用していれば、パラメーター・フォワーディングのセクションを、アプリケーションでJavaScriptアダプターを使用していれば、JavaScriptアダプターのセクションを参照してください。
サンプルトークンの生成

特定のユーザーに対して生成され、特定のクライアントに対して発行された scope パラメーターの指定された値を持つ実際のアクセストークンのサンプルを見るには、 Evaluate 画面からユーザーを選択してください。これにより、使用されているすべてのクレームおよびロールマッピングが含まれているトークンのサンプルが生成されます。

クライアント・スコープ・パーミッション

特定のユーザーに対してトークンを発行する場合、そのユーザーがそのトークンの使用を許可されている場合にのみクライアント・スコープが適用されます。クライアント・スコープにロール・スコープ・マッピングが定義されていない場合、各ユーザーはこのクライアント・スコープの使用を自動的に許可されます。ただし、クライアント・スコープにそれ自体で定義されているロール・スコープ・マッピングがある場合、そのユーザーは少なくとも1つのロールのメンバーである必要があります。つまり、ユーザーロールとクライアント・スコープのロールの間には共通部分がなければなりません。この共通部分を評価するときには、複合ロールが考慮されます。

ユーザーがクライアント・スコープの使用を許可されていない場合、トークンの生成時にプロトコル・マッパーまたはロール・スコープ・マッピングは使用されず、クライアント・スコープはトークンの scope 値に表示されません。

レルムのデフォルトのクライアント・スコープ

Realm Default Client Scopes は、新しく作成されたクライアントに自動的にリンクされるクライアント・スコープのセットを定義することを可能にします。

左側のメニュー項目の Client Scopes を開き、Default Client Scopes を選択します。

ここから、新しく作成したクライアントに Default Client ScopesOptional Client Scopes として追加するクライアント・スコープを選択します。

デフォルトのクライアント・スコープ

client scopes default

クライアントが作成されると、必要に応じてデフォルトのクライアント・スコープのリンクを解除できます。これは、デフォルトロールを削除する方法と似ています。

スコープの説明

スコープ という用語は、Keycloakのいくつかの場所で使用されています。これらのスコープはお互いに関連していますが、異なるコンテキストと意味を持つことがあります。ここでは、Keycloakで使用されるさまざまな スコープ について説明します。

クライアント・スコープ

この章を参照してください。クライアント・スコープは、Keycloakのエンティティーで、レルムレベルで設定され、クライアントにリンクできます。クライアント・スコープは、 scope パラメーターの対応する値とともにKeycloak認可エンドポイントにリクエストが送信されるときに、その名前で参照されます。詳細については、クライアント・スコープのリンクを参照してください。

ロール・スコープ・マッピング

クライアントまたはクライアント・スコープの Scope タブを開いたときに表示されます。ロール・スコープ・マッピングを使用すると、アクセストークンで使用できるロールを制限できます。詳細は、ロール・スコープ・マッピングのセクションで説明しています。

認可スコープ

これは認可機能によって使用されます。 Authorization Scope はアプリケーションで実行できるアクションです。詳細はAuthorization Services Guideを参照してください。

ロール

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

レルムロール

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

roles

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

ロールの追加

role

description フィールドの値は、置換変数に文字列 ${var-name} を指定することによってローカライズ可能です。 ローカライズされた値は、テーマのプロパティー・ファイル内で設定されます。ローカライゼーションの詳細については、Server Developer Guideを参照してください。

クライアントロール

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

複合ロール

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

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

複合ロール

composite role

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

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

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

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

ロールマッピング

user role mappings

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

有効なロールマッピング

effective role mappings

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

デフォルトロール

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

デフォルトロール

default roles

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

ロール・スコープ・マッピング

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

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

フルスコープ

full client scope

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

部分的なスコープ

client scope

グループ

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

グループ

groups

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

グループ

group

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

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

ユーザーグループ

user groups

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

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

group membership

グループ VS ロール

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

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

デフォルト・グループ

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

デフォルト・グループ

default groups

管理コンソールのアクセス・コントロールとパーミッション

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

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

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

グローバルロール

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

  • admin

  • create-realm

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

レルム特有のロール

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 ロールを持っていない管理者は、このロールを割り当てることはできません。

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

各レルムには専用の管理コンソールがあり、 /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

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

きめ細かい管理パーミッション

Fine Grain Admin Permissionsは、 テクノロジー・プレビュー であり、完全にはサポートされていません。この機能はデフォルトで無効になっています。

有効にするには、 -Dkeycloak.profile=preview を使用してサーバーを起動します。 または、 -Dkeycloak.profile.feature.admin_fine_grained_authz=enabled を使用してサーバーを起動します。 . 詳しくは、 Profiles を参照してください。

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

  • 特定のクライアントの管理

  • 特定のグループに属するユーザーの管理

  • グループのメンバーシップの管理

  • 制限付きのユーザー管理

  • きめ細かい代理ログイン制御

  • 特定の制約付きロールセットをユーザーに割り当てる

  • 特定の制約付きロールセットを複合ロールに割り当てる

  • 特定の制約付きロールセットをクライアントのスコープに割り当てる

  • ユーザー、グループ、ロール、およびクライアントの表示と管理のための新しい一般ポリシー

きめ細かい管理パーミッションについて、いくつか注意すべき点があります。

  • きめ細かい管理パーミッションは、認可サービス上に実装されています。きめ細かいパーミッションを設定する前に、それらの機能を読んでおくことを強くお勧めします。

  • きめ細かいパーミッションは、専用の管理コンソールおよびレルム管理者のみ使用できます。レルム間のきめ細かいパーミッションは、定義することはできません。

  • きめ細かいパーミッションは、追加のパーミッションを付与するために使用されます。組み込みの管理者ロールのデフォルトの動作を上書きすることはできません。

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

最初に、管理者が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-adminquery-clients ロールを割り当てる必要があります。

query-clientsの割り当て

fine grain assign query clients

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

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

テストする

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

Sales Adminのログイン

fine grain sales admin login

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

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

もう一つは、管理者がユーザーへの割り当てを許可したロールを制限することです。最後の例に続けて、 sales-admin ユーザーのパーミッション・セットを拡張して、このアプリケーションにアクセスできるユーザーを制御できるようにしましょう。きめ細かいパーミッションを使用して、 sales-adminsales-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-adminviewLeads ロールを割り当て可能とすることです。これから行うことは、管理者がこのロールをどのように割り当てることができるかを指定することです。これを行うには、このレルムの管理コンソールの 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

テストする

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

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

viewLeadsの追加

fine grain add view leads

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

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

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

クライアントのmap-rolesパーミッション

fine grain client permissions tab on

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

パーミッションの一覧

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

ロール

特定のロールの 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

管理者がグループのメンバーシップを変更することが可能であるかを決定するポリシーです。グループにメンバーを追加または削除することができます。

レルム鍵

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

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

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

レルムでアクティブな鍵を表示するには、管理コンソールでレルムを選択し、 Realm settings から Keys をクリックします。これにより、レルムの現在有効な鍵が表示されます。

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

鍵のローテーション

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

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

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

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

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

鍵ペアの追加

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

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

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

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

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

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

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

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

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

KeystoreKeystore PasswordKey AliasKey Password の値を入力し、 Save をクリックします。

鍵をパッシブにする

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

鍵の無効化

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

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

鍵の漏洩

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

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

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

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

ユーザーの観点から、アイデンティティー・ブローカーは、異なるセキュリティー・ドメインまたはレルム間のアイデンティティーを管理するための、ユーザー中心かつ一元的な方法を提供します。既存のアカウントは、異なるアイデンティティー・プロバイダーの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

ブローカリングの概要

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

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

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

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

identity broker flow

  1. ユーザーは認証しておらず、クライアント・アプリケーションの保護されたリソースを要求します。

  2. クライアント・アプリケーションは、ユーザーを認証するためにKeycloakにリダイレクトさせます。

  3. この時点で、レルムに設定されているアイデンティティー・プロバイダーのリストがあるログインページがユーザーに表示されます。

  4. ユーザーは、各ボタンまたはリンクをクリックしてアイデンティティー・プロバイダーの1つを選択します。

  5. Keycloakは、ターゲットのアイデンティティー・プロバイダーに認証を要求する認証リクエストを発行し、ユーザーはアイデンティティー・プロバイダーのログイン・ページにリダイレクトされます。アイデンティティー・プロバイダーの接続プロパティーとその他の設定オプションは、管理者が管理コンソールで前もって設定したものになります。

  6. ユーザーは、アイデンティティー・プロバイダーで認証するために自分のクレデンシャルか同意を提供します。

  7. アイデンティティー・プロバイダーによる認証が成功すると、ユーザーは認証レスポンスとともにKeycloakにリダイレクトされます。通常、このレスポンスには、Keycloakによって使用されるセキュリティー・トークンが含まれています。セキュリティー・トークンは、アイデンティティー・プロバイダーによって実行された認証を信頼し、そのユーザーに関する情報を取得するために使用されます。

  8. Keycloakは、アイデンティティー・プロバイダーからのレスポンスが有効かどうかを確認します。有効な場合は、新しいユーザーをインポートして作成するか、ユーザーがすでに存在する場合はそれをスキップします。新しいユーザーである場合、そのユーザーに関する情報がまだトークンに存在しなければ、Keycloakはその情報をアイデンティティー・プロバイダーに要求することがあります。これが アイデンティティー・フェデレーション と呼ばれるものです。ユーザーがすでに存在している場合、Keycloakは、アイデンティティー・プロバイダーから返されたアイデンティティーを既存のアカウントとリンクするように依頼する可能性があります。このプロセスを アカウントリンク と呼びます。正しく行われるように設定可能であり、First Login Flowの設定によって指定することができます。このステップの終わりに、Keycloakはユーザーを認証し、サービス・プロバイダー内の要求されたリソースにアクセスするために独自のトークンを発行します。

  9. ユーザーがローカルで認証されると、Keycloakは、ローカル認証時に先に発行されたトークンを送信してユーザーをサービス・プロバイダーにリダイレクトします。

  10. サービス・プロバイダーはKeycloakからトークンを受け取り、保護されたリソースへのアクセスを許可します。

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

プロトコルが異なれば、異なる認証フローが必要になる場合があります。 現時点では、Keycloakでサポートされているすべてのアイデンティティー・プロバイダーは、上で説明したものと同様のフローを使用します。 ただし、使用しているプロトコルに関係なく、ユーザー・エクスペリエンスはほぼ同じになるはずです。

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

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

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

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

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

共通設定

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

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

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

identity providers

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

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

add identity provider

上記は、Facebookのソーシャル・ログイン・プロバイダーを設定する例です。IdPを設定すると、オプションとしてKeycloakのログイン・ページにそれが表示されます。アイデンティティー・プロバイダーごとにログイン画面にカスタムアイコンを表示することができます。詳細については、 カスタムアイコン を参照してください。

IDPログイン・ページ

identity provider login page

ソーシャル

ソーシャル・プロバイダーは、レルムでソーシャル認証を有効にすることができます。Keycloakは、ユーザーがソーシャル・ネットワークの既存アカウントを使用して、アプリケーションに簡単にログインできるようにします。現在、Twitter、Facebook、Google、LinkedIn、Instagram、Microsoft、PayPal、Openshift v3、GitHub、GitLab、Bitbucket、Stack Overflowがサポートされています。

プロトコル・ ベース

プロトコル・ベースのプロバイダーは、特定のプロトコルに依存してユーザーを認証および認可するものです。特定のプロトコルに準拠しているすべてのアイデンティティー・プロバイダーに接続できます。KeycloakはSAML v2.0とOpenID Connect v1.0プロトコルをサポートしています。これにより、これらのオープンスタンダードに基づいた任意のアイデンティティー・プロバイダーを簡単に設定および仲介できるようになります。

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

Table 1. 共通の設定
設定 説明

Alias

エイリアスは、アイデンティティー・プロバイダーの一意な識別子です。アイデンティティー・プロバイダーを内部的に参照するために使用されます。 OpenID Connectなどの一部のプロトコルでは、アイデンティティー・プロバイダーと通信するために、リダイレクトURIまたはコールバックURLが必要です。 この場合、エイリアスはリダイレクトURIを構築するために使用されます。 すべてのアイデンティティー・プロバイダーにエイリアスが必要です。例としては、 facebookgoogleidp.acme.com などです。

Enabled

プロバイダーのオン/オフの設定です。

Hide on Login Page

このスイッチがオンの場合、このプロバイダーはログイン・ページにログイン・オプションとして表示されません。クライアントは、ログインを要求するために使用するURLの 'kc_idp_hint' パラメーターを使用して、このプロバイダーの使用を引き続き依頼できます。

Account Linking Only

このスイッチをオンにすると、このプロバイダーはユーザーのログインでは使用することができず、ログイン・ページにはオプションとして表示されません。しかし、既存のアカウントはこのプロバイダーとリンクできます。

Store Tokens

アイデンティティー・プロバイダーから受け取ったトークンを保存するかどうか。

Stored Tokens Readable

ユーザーが保存されたアイデンティティー・プロバイダー・トークンを取得できるかどうか。 broker クライアント・レベルのロール read token にも適用されます。

Trust Email

アイデンティティー・プロバイダーがメールアドレスを提供する場合、このメールアドレスは信頼されます。レルムに電子メールの検証が必要な場合、このIDPからログインしたユーザーは電子メールの検証プロセスを経る必要はありません。

GUI Order

利用可能なIDPがログインページにどのように表示されるかを並べ替える順番設定です。

First Login Flow

このIDPを通じて、初めてKeycloakにログインするユーザーのためにトリガーされる認証フローです。

Post Login Flow

ユーザーが外部アイデンティティー・プロバイダーへのログインを完了した後にトリガーされる認証フロー。

Sync Mode

マッパーを通じてIdPからユーザー情報を更新する方法の戦略: legacy を選択すると、現在の動作が維持されます。 import はユーザーデータを更新しませんが、 force は常にユーザーデータを更新します。詳細については、アイデンティティー・プロバイダー・マッパーのドキュメントも参照してください。

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

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

Bitbucket

Bitbucketでログインできるようにするには、いくつかのステップを完了しなければなりません。

まず、 Identity Providers の左メニュー項目に移動し、Add provider ドロップダウン・リストから Bitbucket を選択します。これにより、 Add identity provider ページが表示されます。

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

bitbucket add identity provider

Save をクリックする前に、Bitbucketから Client IDClient Secret を取得する必要があります。

後で、クライアントとしてKeycloakを登録する際に、このページの Redirect URI をBitbucketに提供します。
Add a New App

Bitbucketでログインできるようにするには、まずアプリケーション・プロジェクトを OAuth on Bitbucket Cloud に登録する必要があります。

Bitbucketはアプリケーション登録のデザインを変更することが多いため、Bitbucketのサイトに表示される内容は異なる場合があります。疑わしい場合は、Bitbucketのドキュメントを参照してください。

bitbucket developer applications

Add consumer ボタンをクリックします。

アプリケーションの登録

bitbucket register app

Keycloakの Add Identity Provider ページから Redirect URI をコピーし、BitbucketのAdd OAuth ConsumerページのCallback URLフィールドに入力します。

同じページで、 Account の下の EmailRead のチェックボックスをマークして、アプリケーションがユーザーの電子メールを読めるようにします。

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

bitbucket app page

登録が完了したら、 Save をクリックしてください。これにより、Bitbucketのアプリケーション管理ページが開きます。このページからクライアントIDとシークレットを取得し、Keycloakの Add identity provider ページに入力する必要があります。 Save をクリックしてください。

Facebook

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

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

facebook add identity provider

Facebookから Client IDClient 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

facebook add new app

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

新しいApp IDの作成

facebook create app id

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

新しいApp IDの作成

facebook app settings

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

Webサイトの指定

facebook app settings website

この後、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 のスコープを使用します。

注意すべきもう1つの点は、Keycloakがデフォルトでプロファイル・リクエストを graph.facebook.com/me?fields=id,name,email,first_name,last_name に送信し、レスポンスには指定されたフィールドのみが含まれることです。Facebookプロファイルから追加のフィールド(誕生日など)を取得する場合は、上記の段落で説明したように対応するスコープを追加し、 Additional user’s profile fields の設定オプション・フィールドにフィールド名を追加する必要があります。 Facebook GraphQL API Explorer を調べると、使用可能なフィールド名と対応するスコープを見つけることができます。

GitHub

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

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

github add identity provider

GitHubから Client IDClient 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

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

GitLab

GitLabでログインできるようにするには、いくつかのステップを完了しなければなりません。

まず、 Identity Providers の左メニュー項目に移動し、Add provider ドロップダウン・リストから GitLab を選択します。これにより、 Add identity provider ページが表示されます。

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

gitlab add identity provider

Save をクリックする前に、GitLabから Client IDClient Secret を取得する必要があります。

後で、クライアントとしてKeycloakを登録する際に、このページの Redirect URI をGitLabに提供します。

GitLabでログインできるようにするには、まずアプリケーションを GitLab as OAuth2 authentication service provider に登録する必要があります。

GitLabはアプリケーション登録のデザインを変更することが多いため、GitLabのサイトに表示される内容は異なる場合があります。疑わしい場合は、GitLabのドキュメントを参照してください。
Add a New App

gitlab developer applications

Keycloakの Add Identity Provider ページから取得した Redirect URI をコピーし、GitLabのAdd new applicationページのRedirect URIフィールドに入力します。

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

gitlab app page

登録が完了したら、 Save application をクリックしてください。 これにより、GitLabのアプリケーション管理ページが開きます。このページからクライアントIDとシークレットを取得し、Keycloakの Add identity provider ページに入力する必要があります。

終了するには、Keycloakに戻り、それらを入力してください。 Save をクリックします。

Google

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

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

google add identity provider

Googleから Client IDClient 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 nameProject ID に任意の値を使用し、 Create ボタンをクリックします。プロジェクトが作成されるのを待ちます(これには時間がかかることがあります)。作成されると、プロジェクトのダッシュボードに遷移します。

ダッシュボード

google dashboard

次に、Googleデベロッパーコンソールの APIs & Services セクションに移動します。その画面で、 Credentials 管理に移動します。

ユーザーがKeycloakからGoogleにログインすると、Googleからの同意画面が表示され、Keycloakにユーザー・プロファイルに関する情報の表示が許可されているかどうかが尋ねられます。そのため、Googleはプロダクトのシークレットを作成する前に、プロダクトに関するいくつかの基本情報を必要とします。新しいプロジェクトのために、あなたは最初に OAuth同意画面 を設定しなければなりません。

非常に基本的な設定では、アプリケーション名を入力するだけで十分です。このページでは、Google APIのスコープなど、追加の詳細を設定することもできます。

OAuth同意画面の詳細を入力

google oauth consent screen

次のステップは、OAuthクライアントIDとクライアント・シークレットを作成することです。 Credentials 管理に戻り、Credentials タブに行き、 Create credentials ボタンの下の OAuth client ID を選択してください。

クレデンシャルの作成

google create credentials

そうすると Create OAuth client ID ページが表示されます。アプリケーション・タイプとして Web application を選択します。また、Keycloakの Add Identity Provider ページから Redirect URI をコピーし、 Authorized redirect URIs フィールドに貼り付ける必要があります。これを済ませたら、 Create ボタンをクリックします。

OAuthクライアントIDの作成

google create oauth id

Create をクリックすると、 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 のスコープを使用します。

あなたの組織がG Suiteを使用していて、組織のメンバーだけにアクセスを制限したい場合は、G Suiteに対して使用するドメインを Hosted Domain フィールドに入力して有効にする必要があります。

LinkedIn

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

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

linked in add identity provider

LinkedInから Client IDClient 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_basicprofiler_emailaddress を選択してください。Keycloakの Add Identity Provider ページから Redirect URI をコピーし、それをLinkedInアプリ設定ページの OAuth 2.0Authorized Redirect URLs フィールドに入力する必要があります。入力後、 Update ボタンをクリックすることを忘れないでください!

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

Microsoft

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

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

microsoft add identity provider

Microsoftから Client IDClient 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に戻り、それらの項目を入力します。

2018年11月以降、Microsoftは新しいMicrosoft Graph APIを支持して、Live SDK APIのサポートを削除しています。Keycloak Microsoft アイデンティティー・プロバイダーは新しいエンドポイントを使用するように更新されました。このプロバイダーを使用するには、必ずKeycloakバージョン4.6.0以降にアップグレードしてください。さらに、 Live SDKアプリケーション でMicrosoftに登録されているクライアント・アプリケーションは、 Microsoft Application Registration ポータルに再登録して、Microsoft Graph APIと互換性があるアプリケーションIDを取得する必要があります。

OpenShift 3

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 secretclient_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 を参照してください。

OpenShift 4

OpenShift 4 Identity Providerを設定する前に、正しいOpenShift 4 API URLを見つけてください。一部のシナリオでは、そのURLはユーザーから隠されている場合があります。これを取得する最も簡単な方法は、次のコマンドを呼び出すことです( jq コマンドを個別にインストールする必要がある場合があります) curl -s -k -H "Authorization: Bearer $(oc whoami -t)" https://<openshift-user-facing-api-url>/apis/config.openshift.io/v1/infrastructures/cluster | jq ".status.apiServerURL" ほとんどの場合、アドレスはHTTPSによって保護されます。したがって、コンテナで X509_CA_BUNDLE を設定し、 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt に設定することが不可欠です。そうしないと、KeycloakはAPIサーバーと通信できません。

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

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

openshift 4 add identity provider

OAuthクライアントの登録

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

$ oc create -f <(echo '
kind: OAuthClient
apiVersion: v1
metadata:
 name: keycloak-broker (1)
secret: "..." (2)
redirectURIs:
 - "<copy pasted Redirect URI from OpenShift 4 Identity Providers page>" (3)
grantMethod: prompt (4)
')
1 OAuthクライアントの name です。 <openshift_master>/oauth/authorize<openshift_master>/oauth/token へのリクエストを行うときに client_id リクエスト・パラメーターとして渡されます。 name パラメーターは、 OAuthClient オブジェクトとKeycloakの設定で同じにする必要があります。
2 secretclient_secret リクエスト・パラメーターとして使われます。
3 <openshift_master>/oauth/authorize および <openshift_master>/oauth/token へのリクエストで指定された redirect_uri パラメーターは、 redirectURIs のURIの1つと一致する(または前方一致する)必要があります。正しく設定する最も簡単な方法は、 Keycloak OpenShift 4 Identity Providerの設定ページから( Redirect URI フィールド)、コピー・アンド・ペーストすることです。
4 grantMethod は、このクライアントがトークンを要求し、ユーザーによってまだアクセスが許可されていないときに、行うアクションを決定するために使用されます。

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

OpenShift APIサーバーは、 OAuthClientnamesecret 、または redirectURIs が正しくない場合、 The client is not authorized to request a token using this method を返します。それらをKeycloak OpenShift 4 Identity Providerページに正しくコピー・アンド・ペーストしてください。

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

PayPal

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

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

paypal add identity provider

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

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

Add a New App

paypal developer applications

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

アプリケーションの登録

paypal register app

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

次の変更を行います。
  • 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をドメインのそれぞれのページを指すように追加してください。

Stack Overflow

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

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

stack overflow add identity provider

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

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

stack overflow app register

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

設定

stack overflow app settings

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

Twitter

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

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

twitter add identity provider

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

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

アプリケーションの登録

twitter app register

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

アプリケーションの登録

twitter app create

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

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

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

App Details

twitter details

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

Keys and Access Tokens

twitter keys

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

Instagram

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

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

instagram add identity provider

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

Instagramでのログインを可能にするには、まずプロジェクトとクライアントを作成する必要があります。Instagram APIは、 Facebook Developer Console を通じて管理されます。

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

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

Add a New App

instagram add new app

For Everything Else を選択します。

新しいApp IDの作成

instagram create app id

すべての必須フィールドに入力します。これを完了すると、アプリケーションのダッシュボードが表示されます。左側のナビゲーション・パネルのメニューで、 Settings の下の Basic を選択します。

プラットフォームの追加

instagram add platform

下部にある + Add Platform を選択し、地球のアイコンの付いた [Website] をクリックします。サイトのURLを指定します。

プロダクトの追加

instagram add product

左側のメニューから Dashboard を選択し、Instagramボックスの Set Up をクリックします。左側のメニューで、 Instagram の下の Basic Display を選択し、 Create New App をクリックします。

新しいInstagram App IDの作成

instagram create instagram app id

Display Name を指定します。

アプリのセットアップ

instagram app settings

Keycloakの Add identity provider ページから取得した Redirect URI をInstagramの Client OAuth Settings 設定ブロックの Valid OAuth Redirect URIs にコピー・アンド・ペーストします。

このURLは、 Deauthorize Callback URL にも Data Deletion Request URL にも使用できます。Keycloakは現在どちらもサポートしていませんが、Facebook Developer Consoleでは両方に入力する必要があります。

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

この後、Instagramアプリを公開する必要があります。左側のメニュー項目の App Review をクリックし、次に Requests をクリックします。その後、画面の指示に従ってください。

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エンドポイント。これは、ユーザー・プロファイル情報をダウンロードできるエンドポイントです。

クライアント認証

認可コードフローで使用されるクライアント認証方法を定義するために切り替えます。秘密鍵で署名されたJWTの場合、レルム秘密鍵が使用されます。それ以外の場合、クライアントシークレットを定義する必要があります。詳細については、 クライアント認証の仕様 を参照してください。

Client ID

このレルムは、外部IDPへのOIDCクライアントとして機能します。認可コードフローを使用して外部IDPと対話するときに、レルムにはOIDCのクライアントIDが必要になります。

Client Secret

このレルムには、認可コードフローを使用するときに使用するクライアント・シークレットが必要です。このフィールドの値は、外部ボールトの値を参照できます。

Issuer

IDPからのレスポンスには、発行者のクレームが含まれる場合があります。この設定値はオプションです。指定されている場合、提供する値に対してこのクレームが検証されます。

Default Scopes

認証リクエストとともに送信される、OIDCスコープのスペース区切りのリスト。デフォルトは openid です。

Prompt

オプションの項目。これは、OIDC仕様で定義されたプロンプト・パラメーターです。これにより、再認証やその他のオプションを強制することができます。詳細は、仕様を参照してください。

Accepts prompt=none forward from client

IDPが、転送されてきたprompt=noneクエリー・パラメーターを含む認証リクエストを受け入れるかどうかを指定します。レルムが prompt=none の認証リクエストを受信すると、ユーザーが現在認証されているかどうかを確認し、ユーザーがログインしていない場合は通常 login_required エラーを返します。ただし、認証リクエストのデフォルトIDP( kc_idp_hint クエリー・パラメーターを使用するか、レルムのデフォルトIDPを設定することにより) prompt=none で認証リクエストをデフォルトIDPに転送して、ユーザーが現在認証されているかどうかを確認できるようにする必要があります。すべてのIDPが prompt=none のリクエストをサポートするわけではないため、このスイッチはデフォルトのIDPが認証リクエストをリダイレクトする前にパラメーターをサポートするかどうかを示すために使用されます。

ユーザーがIDPで認証されていない場合、クライアントは依然として login_required エラーを受け取ることに注意することが重要です。ユーザーが現在IDPで認証されている場合でも、ユーザーの操作を必要とする認証または同意ページが表示されると、クライアントは依然として interaction_required エラーを受け取る可能性があります。これには、必須アクション(パスワードの変更など)、同意画面、および first broker login フローまたは post broker login フローによって表示されるように設定された画面が含まれます。

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ドキュメントです。

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の設定
設定 説明

Service Provider Entity ID

これは必須フィールドであり、リモート・アイデンティティー・プロバイダーがこのサービス・プロバイダーからのリクエストを識別するために使用するSAMLエンティティーIDを指定します。デフォルトでは、レルムベースURL <root>/auth/realms/{realm-name} に設定されています。

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 です。

Principal Type

SAMLアサーションのどの部分を外部ユーザー・アイデンティティを一意に特定しトラックするのに使用するかを指定します。Subject NameID、SAML attributeのいずれか(名前もしくはフレンドリー名)です。

Principal Attribute

プリンシパルが"Attribute [Name]"、もしくは"Attribute [Friendly Name]"に設定された場合、このフィールドには対応する識別する属性の名前もしくはフレンドリー名を指定します。

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リクエストとレスポンスの署名を検証するために使用される公開証明書。

Sign Service Provider Metadata

trueの場合、レルムのキーペアを使用して、 SAML Service Provider Metadata descriptor に署名します。

Pass subject

login_hint クエリー・パラメーターをIdPに転送する必要があるかどうか。指定すると、このlogin_hintパラメーターがAuthnRequestのサブジェクトに追加されます。これにより、宛先のプロバイダーはログインフォームに事前に入力できます。login_hintが指定されていない場合、AuthnRequestサブジェクトとして何も転送されません。

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

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

Requesting specific AuthnContexts

一部のアイデンティティー・プロバイダーでは、クライアントがユーザーIDの検証に使用される認証方法に特定の制約を指定できます(MFA、Kerberos認証、セキュリティー要件などの要求など)。これらの制約は、特定のAuthnContext基準を使用して指定されます。クライアントは、1つ以上の基準を要求し、アイデンティティー・プロバイダーが要求されたAuthnContextに正確に一致する方法を指定することも、同等またはそれ以上の基準を満たすことによって指定することもできます。

Requested AuthnContext Constraintsのセクションに1つ以上のClassRefまたはDeclRefを追加することにより、サービス・プロバイダーが必要とする基準を一覧表示できます。通常、ClassRefsまたはDeclRefsのいずれかを提供する必要があります。サポートされている値をアイデンティティー・プロバイダーのドキュメントで確認する必要があります。ClassRefまたはDeclRefが存在しない場合、アイデンティティー・プロバイダーは追加の制約を適用しません。

Table 4. Requested AuthnContext Constraints
設定 説明

Comparison

アイデンティティー・プロバイダーがコンテキスト要件を評価するために使用する必要がある比較方法。使用可能な値は、 ExactMinimumMaximum または Better です。デフォルト値は Exact です。

AuthnContext ClassRefs

必要な基準を説明する1つ以上のAuthnContext ClassRefs。

AuthnContext DeclRefs

必要な基準を説明する1つ以上のAuthnContext DeclRefs。

SP記述子

プロバイダーのSAML SPメタデータにアクセスする必要がある場合は、アイデンティティー・プロバイダーの構成設定で Endpoints の設定を探します。これには、サービス・プロバイダーのSAMLエンティティー記述子を生成する SAML 2.0 Service Provider Metadata と呼ばれるリンクが含まれています。ダウンロードするか、URLをコピーして、リモート・アイデンティティー・プロバイダーにインポートすることができます。

このメタデータは、次のURLにアクセスしてパブリックに利用することもできます。

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

記述子にアクセスする前に、設定の変更を必ず保存してください。保存しないと、メタデータに反映されません。

Send Subject in SAML requests

デフォルトでは、SAMLアイデンティティー・プロバイダーを指すソーシャルボタンは、ユーザーをログインURLにリダイレクトします。

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

このURLに login_hint という名前のクエリー・パラメーターを追加すると、その値がSubject属性としてSAMLリクエストに追加されます。このクエリー・パラメーターが存在しないか空のままの場合、Subjectはリクエストに追加されません。

"Pass subject" オプションを有効にする必要があります。

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

使用したいアイデンティティー・プロバイダーのヒントを指定することで、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 クエリー・パラメーターを空の値に設定することによって自動リダイレクトを無効にすることもできます。

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

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

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

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

identity provider mappers

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

identity provider mapper

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

以下の Sync Mode Override の設定により、ユーザーがログインするとマッパーはユーザー情報を更新します。

  • 以前のバージョンのKeycloakの動作を使用するには、 legacy を選択します。

  • 特定のアイデンティティー・プロバイダーを使用してKeycloakへの初回ログイン中に、ユーザーがKeycloakで最初に作成されたときのデータのみをインポートするには、 import を選択します。

  • ユーザーのログインごとにユーザーデータを更新するには、 force を選択します。

  • アイデンティティー・プロバイダーで設定された同期モードを使用するには、 inherit を選択します。他のすべてのオプションは、この同期モードをオーバーライドします。

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

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

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

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

identity_provider

ログインを実行するために使用されるブローカーのIDPエイリアスです。

identity_provider_identity

現在認証されているユーザーのIDPユーザー名です。これはKeycloakユーザー名と同じことが多いですが、必ずしもそうである必要はありません。たとえば、Keycloakのユーザー john は、Facebookのユーザー john123@gmail.com にリンクできます。その場合、ユーザー・セッション・ノートの値は john123@gmail.com になります。

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

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を参照してください。

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

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がユーザー・アカウントに設定されている場合にのみ使用されます。

自動リンクの初回ログインフロー

AutoLinkオーセンティケーターは、ユーザーが任意のユーザー名/電子メールアドレスを使用して自分自身を登録できる一般的な環境では危険です。ユーザーの登録が慎重に行われ、ユーザー名/電子メールアドレスが(要求されるのではなく)割り当てられていない限り、このオーセンティケーターを使用しないでください。

プロンプトを表示せずにユーザーを自動的にリンクする最初のログインフローを設定するには、次の2つのオーセンティケーターを使用して新しいフローを作成します。

Create User If Unique

このオーセンティケーターは、一意にユーザーが処理されることを保障します。オーセンティケーターの要件は"Alternative"に設定します。

Automatically Set Existing User

検証なしで、既存のユーザーを認証コンテキストに自動的に設定します。オーセンティケーターの要求は"Alternative"に設定します。

記載されたセットアップでは2つのオーセンティケーターが使用されます。このセットアップは最も簡単なものですが、必要に応じて他のオーセンティケーターを使用することもできます。たとえば、エンドユーザーにプロファイル情報の確認を依頼したい場合は、フローの先頭にReview Profileオーセンティケーターを追加することができます。また、このフローに認証メカニズムを追加して、ユーザーにクレデンシャルの確認を強制することもできます。これには、より複雑なフローが必要になります。たとえば、"Alternative"サブフローで"Automatically Set Existing User"と"Password Form"を"Required"に設定します。

自動ユーザー作成の無効化

デフォルトの最初のログインフローは、外部アイデンティティーと一致するKeycloakアカウントを検索し、それらをリンクすることを提案します。一致するKeycloakアカウントがない場合は、自動的に作成されます。このデフォルトの動作は、たとえば読み取り専用のLDAPユーザーストアを使用する場合(つまり、すべてのユーザーが事前に作成されている場合)など、設定によっては適さない場合があります。この場合、自動ユーザー作成をオフにする必要があります。ユーザーの作成を無効にするには以下を実施します。

  • First Broker Login フロー設定を開く。

  • Create User If UniqueDISABLED に設定する。

  • Confirm Link Existing AccountDISABLED に設定する。

この設定は、Keycloak自体が、外部アイデンティティーに対応する内部アカウントを判別できないことも意味します。したがって、 Verify Existing Account By Re-authentication オーセンティケーターは、ユーザーにユーザー名とパスワードの両方を提供するように要求します。

外部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を使用して再確立できます。

アイデンティティー・ブローカー・ログアウト

Keycloakからのログアウトがトリガーされると、KeycloakはKeycloakへのログインに使用されていた外部アイデンティティー・プロバイダーにリクエストを送信し、ユーザーはこのアイデンティティー・プロバイダーからもログアウトされます。この動作をスキップして外部アイデンティティー・プロバイダーでのログアウトを回避することは可能です。詳細については、 アダプター・ログアウトのドキュメント を参照してください。

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

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

セッションの管理

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

Sessions

sessions

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

Logout all 操作の制限事項

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

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

アプリケーションのドリルダウン

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

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

application sessions

ユーザーのドリルダウン

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

ユーザー・セッション

user sessions

失効ポリシー

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

失効

revocation

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

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

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

Tokensタブ

tokens tab

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

設定 説明

デフォルトの署名アルゴリズム

このレルムでトークンの割り当てに使用されるデフォルトのアルゴリズム。

Revoke Refresh Token

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

SSO Session Idle

OIDCクライアントにも関係します。ユーザーがこのタイムアウトよりも長くアクティブでない場合、ユーザー・セッションは無効になります。アイドル・タイムアウトはクライアントが認証を要求するか、リフレッシュ・トークンを要求することでリセットされます。 セッションが無効になる前にアイドル・タイムアウトに常に追加される小さなウィンドウがあります(下記の注釈を参照)。

SSO Session Max

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

SSO Session Idle Remember Me

標準のSSOセッション・アイドル設定と同じですが、リメンバーミーを有効にしたログインに固有の設定です。ログイン処理中にリメンバーミーが選択されている場合は、より長いセッション・アイドル・タイムアウトを指定できます。これはオプションの設定であり、0より大きい値に設定されていない場合は、SSO Session Idleで設定されているものと同じアイドル・タイムアウトが使用されます。

SSO Session Max Remember Me

標準のSSO Session Maxの設定と同じですが、リメンバーミーの有効化とともにログインに固有の設定です。ログイン処理中にリメンバーミーが選択されている場合は、より長い存続期間のセッションを指定できます。これはオプションの設定であり、0より大きい値に設定されていない場合は、SSO Session Maxで設定されているものと同じセッション存続期間が使用されます。

Offline Session Idle

オフライン・アクセスでは、これはオフライントークンが取り消される前にセッションがアイドル状態を維持できる時間です。セッションが無効になる前に、アイドル・タイムアウトに常に追加されるわずかな時間のウインドウがあります(下記の注意を参照)。

Offline Session Max Limited

オフライン・アクセスでは、このフラグがオンの場合、Offline Session Maxを有効にして、ユーザー・アクティビティーに関係なくオフライントークンをアクティブなままにできる最大時間を制御します。また、Client Offline Session IdleおよびClient Offline Session Maxは有効になっています。

Offline Session Max

オフライン・アクセスでは、これは対応するオフライントークンが取り消されるまでの最大時間です。このオプションはユーザー・アクティビティーに関係なく、オフライントークンがアクティブのままになる最大時間を制御します。

Offline Session Idle

オフライン・アクセスにおいて、ユーザーがこのタイムアウトよりも長くアクティブになっていない場合、オフライントークン・リクエストはアイドル・タイムアウトになります。これにより、セッションのオフライン・アイドル・タイムアウトよりも短いオフライントークンのアイドル・タイムアウトを指定できます。ただし、個々のクライアントでオーバーライドできます。これはオプションの設定であり、0より大きい値に設定されていない場合は、Offline Session Maxで設定されたものと同じアイドル・タイムアウトを使用します。

Offline Session Idle

オフライン・アクセスにおいて、オフライントークンが期限切れになり無効になるまでの最大時間。オフライン・セッション・タイムアウトよりも短いオフライントークンのタイムアウトを指定できます。ただし、個々のクライアントでオーバーライドできます。これはオプションの設定であり、0より大きい値に設定されていない場合は、Offline Session Maxで設定されたものと同じアイドル・タイムアウトを使用します。

Client Session Idle

ユーザーがこのタイムアウトよりも長くアクティブになっていない場合、リフレッシュトークン・リクエストはアイドル・タイムアウトになります。これにより、セッションのアイドル・タイムアウトよりも短いリフレッシュトークンのアイドル・タイムアウトを指定できます。また、個々のクライアントでオーバーライドできます。これはオプションの設定であり、0より大きい値に設定されていない場合は、SSO Session Maxで設定されたものと同じアイドル・タイムアウトを使用します。

Client Session Max

リフレッシュトークンが期限切れになり無効になるまでの最大時間。セッション・タイムアウトよりも短いリフレッシュトークンのタイムアウトを指定できます。また、個々のクライアントでオーバーライドできます。これはオプションの設定であり、0より大きい値に設定されていない場合は、SSO Session Maxで設定されたものと同じアイドル・タイムアウトを使用します。

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 で設定された値がデフォルトになります。

アイドル・タイムアウトには、セッションが期限切れにならないようにするためのわずかな時間のウインドウ(2分)があります。たとえば、タイムアウトを30分に設定した場合、セッションが期限切れになるまでに実際には32分かかります。これは、有効期限が切れる前にトークンが1つのクラスターノードで非常に短時間に更新され、リフレッシュを行ったノードからリフレッシュの成功についてのメッセージをまだ受け取っていないため、その間に他のクラスターノードがセッションを誤ってセッションを期限切れと見なしてしまうような、クラスターおよびクロス・データセンター環境における一般的なシナリオで必要とされます。

オフライン・アクセス

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

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

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

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

オフライントークンを発行できるようにするには、レルムレベルのロール offline_access のロールマッピングが必要です。クライアントはその役割を果たす必要もあります。最後に、クライアントは offline_access クライアントスコープを Optional client scope として追加する必要があります。これはデフォルトで行われます。

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

Transient sessions

Keycloakには一時的セッションの概念があります。一時的セッションが使用される場合、認証が成功した後に作成される実際のユーザー・セッションはありません。ユーザーの認証に成功した現在のリクエストのスコープに対して、一時的セッションのみが作成されます。この一時的なセッションにより、Keycloakは認証後にprotocol mappersを実行できます。

一時的セッションが使用されている場合、クライアント・アプリケーションには、トークンをリフレッシュまたはイントロスペクトしたり、特定のセッションが有効かどうかを確認したりする方法がありません。状況によっては、これらのアクションが不要な場合があるため、ユーザー・セッションを永続化するための追加のオーバーヘッドを回避できます。これは、パフォーマンス、メモリ、およびネットワーク通信の節約を意味します(クラスターおよびクロスデータセンター環境の場合)。

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

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

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

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

プロバイダーの追加

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

User Federation

user federation

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

プロバイダー障害の対応

ユーザー・ストレージ・プロバイダーに障害が発生した場合(たとえば、LDAPサーバーが停止している場合)、ログインに問題があったり、管理コンソールでユーザーを表示できないことがあります。Keycloakは、ストレージ・プロバイダーを使用してユーザーを検索しても失敗を捕捉せず、呼び出しを中止します。したがって、ユーザー検索中に優先順位の高いストレージ・プロバイダーが失敗した場合、ログインまたはユーザー・クエリーは例外なく完全に失敗し、中止されます。次の設定済みプロバイダーにはフェールオーバーされません。

LDAPまたはカスタムのユーザー・ストレージ・プロバイダーの前に、ローカルKeycloakユーザー・データベースが常に最初に検索され、ユーザーを解決します。LDAPへの接続やカスタム・バックエンドに問題が発生した場合に備えて、ローカルKeycloakユーザー・データベースに保存される管理者アカウントを作成することを検討してください。

LDAPとカスタムのそれぞれのユーザー・ストレージ・プロバイダーには、管理コンソールページに enable スイッチがあります。ユーザー・ストレージ・プロバイダーを無効にすると、ユーザークエリーを実行するときにそのプロバイダーがスキップされ、優先度の低い別のプロバイダーに保存されている可能性のあるユーザーを表示したり、ログインできるようにします。プロバイダーが import 戦略を使用していて、それを無効にしている場合、インポートされたユーザーは引き続き参照可能ですが、読み取り専用モードでのみ利用できます。プロバイダーを再度有効にするまで、これらのユーザーを変更することはできません。

ストレージ・プロバイダーの検索が失敗した場合にKeycloakがフェイルオーバーしない理由は、ユーザー・データベースにユーザー名が重複したり、メールが重複したりすることがよくあるためです。これにより、セキュリティー上の問題や予期しない問題が発生する可能性があります。これは、ユーザーが別の外部ストアから読み込まれることを管理者が期待しているときに、ユーザーがまた別の外部ストアから読み込まれる可能性があるためです。

LDAPとActive Directory

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

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

ストレージモード

デフォルトでは、KeycloakはLDAPからローカルのKeycloakユーザー・データベースにユーザーをインポートします。このユーザーのコピーは、オンデマンドで同期されるか、定期的なバックグラウンド・タスクを通じて同期されます。これに対する唯一の例外は、パスワードの同期です。パスワードはインポートされません。それらの検証は常にLDAPサーバーに委任されます。このアプローチの利点は、必要な追加のユーザーごとのデータをローカルに保存できるため、すべてのKeycloakの機能が機能することです。このアプローチの欠点は、特定のユーザーが初めて照会されるたびに、対応するKeycloakデータベースの挿入が実行されることです。インポートは、LDAPサーバーと同期する必要がある場合もあります。ただし、LDAPマッパーが常にデータベースからではなくLDAPから特定の属性を読み取るように設定されている場合、インポートの同期は必要ありません。

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

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

ユーザーのインポートが無効になっている場合、ユーザー・プロファイル属性をKeycloakのデータベースに保存できません。また、LDAPにマップされているユーザー・プロファイルのメタデータ以外のメタデータは保存できません。これに対する唯一の例外は、LDAPにマップされるユーザー・プロファイルのメタデータです。これには、ロールマッピング、グループ・マッピング、およびLDAPマッパーの設定に基づくその他のメタデータが含まれる可能性があります。LDAPにマップされていないユーザーデータの一部を変更しようとした場合、ユーザーの更新はできません。たとえば、ユーザーの enabled フラグが何らかのLDAP属性にマップされていない限り(通常はそうではありません)、LDAPにマップされたユーザーを無効にすることはできません。

編集モード

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

READONLY

ユーザー名、電子メール、姓、名、およびその他のマップされた属性は変更できません。いつでも誰でも、これらのフィールドを更新しようとすると、Keycloakはエラーを表示します。また、パスワードの更新はサポートされません。

WRITABLE

ユーザー名、電子メール、姓、名、およびその他のマップされた属性とパスワードはすべて更新でき、LDAPストアと自動的に同期されます。

UNSYNCED

ユーザー名、電子メール、姓、パスワードの変更はKeycloakローカル・ストレージに保存されます。LDAPに同期する方法は、あなた次第です。これにより、Keycloakデプロイメントは、読み取り専用LDAPサーバー上のユーザー・メタデータの更新をサポートできます。このオプションは、LDAPからローカルのKeycloakユーザー・データベースにユーザーをインポートする場合にのみ適用されます。

LDAPプロバイダーが作成されると、最初のLDAPマッパーのセットが作成されます。マッパーは、 VendorEdit Mode および Import Users スイッチの選択された組み合わせに基づいて、 "best-effort" ベースで設定されます。たとえば、UNSYNCED編集モードの場合、マッパーは、特定のユーザー属性がLDAPではなくデータベースから読み取られるように事前設定されています。ただし、後で編集モードを変更しても、マッパーの設定が変更されることはありません。その間、マッパーの設定が手動で変更されたかどうかを簡単に検出することができないためです。これは、 Edit Mode スイッチを更新しないことをお勧めしますが、LDAPプロバイダーを作成するときは常に Edit Mode にすることをお勧めします。これは Import Users スイッチにも適用されます。

その他の設定オプション

Console Display Name

このプロバイダーが管理コンソールで参照されるときに使用される名前。

Priority

ユーザーを検索したり、追加したりするときのこのプロバイダーの優先順位。

Sync Registrations

LDAPが新規ユーザーの追加をサポートするかどうか。管理コンソールまたは登録ページでKeycloakによって作成された新規ユーザーをLDAPに追加する場合は、このスイッチをクリックします。

Allow Kerberos authentication

LDAPからプロビジョニングされたユーザーデータを使用し、レルム内でKerberos/SPNEGO認証を有効にします。詳細はKerberosのセクションにあります。

その他のオプション

残りの設定オプションは自明のはずです。管理コンソールでツールチップにマウスポインターをのせると、それらの詳細が表示されます。

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への接続URLが ldaps で始まる場合にのみ使用されます。

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のデータベースに同期します。LDAPで直接更新されたLDAPユーザーがKeycloakにも存在する場合、Keycloakのデータベースも更新されます。たとえば、ユーザー Mary Kelly がLDAPで Mary Smith に変更された場合。

定期的な変更ユーザーの同期

同期が行われると、最後の同期後に作成または更新されたユーザーのみがインポートまたは更新されます。

同期を処理する最善の方法は、LDAPプロバイダーを最初に作成するときに Synchronize all users ボタンをクリックして、その後、変更されたユーザーの定期的な同期を設定することです。

LDAPマッパー

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

User Attribute Mapper

これにより、Keycloakユーザーの属性にマップされるLDAP属性を指定できます。たとえば、Keycloakデータベースの属性 email にLDAP属性 mail を設定することができます。このマッパー実装では、常に1対1のマッピングとなります(1つのLDAP属性が1つのKeycloak属性にマップされます)。

フルネーム・マッパー

これにより、一部のLDAP属性(通常は cn )に保存されているユーザーのフルネームがKeycloakデータベースの firstName 属性と lastname 属性にマップされるように指定することができます。 cn にユーザーのフルネームを含めることは、いくつかのLDAPデプロイメントにおいて一般的なケースです。

Keycloakで新しいユーザーを登録し、LDAPプロバイダーの Sync Registrations がONの場合、fullNameマッパーはユーザー名へのフォールバックの可能性を許可します。このフォールバックは、Microsoft Active Directoryの場合に特に役立ちます。MSADの一般的な設定は、 cn LDAP属性をfullNameとして設定することです。同時に、cn は通常、LDAPプロバイダーの設定で RDN LDAP 属性として使用されます。この設定では、ユーザー名へのフォールバックが使用されます。たとえば、Keycloakユーザー "john123" を作成し、firstNameとlastNameを空のままにすると、フルネームマッパーは "john123" をLDAPの cn の値として保存します。 後でfirstNameとlastNameに "John Doe" と入力すると、フルネームマッパーはLDAPの cn を値 "John Doe" に更新するため、ユーザー名へのフォールバックは不要になります。
Hardcoded Attribute Mapper

このマッパーはLDAPにリンクされた各Keycloakユーザーにハードコードされた属性値を追加します。このマッパーは enabled あるいは emailVerified ユーザープロパティの値を強制することもできます。

ロールマッパー

これにより、LDAPから取得したロールマッピングをKeycloakのロールマッピングに設定できます。1つのロールマッパーを使用して、LDAPロール(通常はLDAPツリーの特定のブランチから取得したグループ)を、レルムロールまたはクライアントロールのいずれかにマップできます。同じLDAPプロバイダーに対してさらにロールマッパーを設定することも問題ありません。たとえば、 ou=main,dc=example,dc=org のグループから取得したロールマッピングをレルムロール・マッピングにマップし、 ou=finance,dc=example,dc=org のグループから取得したロールマッピングをクライアント finance のクライアントロール・マッピングにマップするように指定できます。

ハードコードされたロールマッパー

このマッパーは、LDAPプロバイダーからの各Keycloakユーザーに特定のKeycloakロールを付与します。

グループマッパー

これにより、LDAPツリーの特定のブランチから取得したLDAPグループをKeycloakのグループにマップできます。また、LDAPから取得したユーザーグループ・マッピングをKeycloakのユーザーグループ・マッピングに伝播します。

MSADユーザー・アカウント・マッパー

このマッパーは、Microsoft Active Directory(MSAD)固有のものです。MSADユーザー・アカウントの状態をKeycloakアカウントの状態(アカウントが有効、パスワードが期限切れなど)に緊密に統合できます。 userAccountControlpwdLastSet のLDAP属性を使っています。どちらもMSAD固有のものであり、LDAP標準ではありません。たとえば pwdLastSet0 の場合、Keycloakユーザーはパスワードを更新する必要があり、UPDATE_PASSWORD必須アクションがユーザーに追加されます。 userAccountControl514 (無効なアカウント)の場合、Keycloakユーザーも無効になります。

Certificate Mapper

このマッパーは、X.509証明書のマッピング専用です。通常、X.509認証と Full certificate in PEM format をアイデンティティー・ソースとして使用します。 User Attribute Mapper と同じように動作しますが、KeycloakはPEMまたはDER形式で証明書を保存するLDAP属性をフィルター処理できます。通常、このマッパーで Always Read Value From LDAP を有効にすることをお勧めします。

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

パスワード・ハッシング

ユーザーのパスワードは、Keycloakから更新されてLDAPに送信される際に、常にプレーンテキストで送信されます。これは、ハッシュ化とソルト付与がDBに送信される前のパスワードに適用される、組み込みKeycloakデータベースへのパスワード更新とは異なります。LDAPの場合、Keycloakは、パスワードのハッシュ化とソルト付与をLDAPサーバーに任せています。

Microsoft Active Directory、RHDS、FreeIPAなどのLDAPサーバーは、デフォルトでこれを提供します。 RFC3062 のように LDAPv3 Password Modify Extended Operation を使用しない限り、OpenLDAPやApacheDSなどの他のLDAPサーバーはデフォルトでパスワードをプレーンテキストで保存する場合があります。LDAPv3パスワード変更拡張操作は、LDAP設定ページで明示的に有効にする必要があります。詳細については、LDAPサーバーのドキュメントを参照してください。

ldapsearch を使用して変更されたディレクトリー・エントリーを検査し、userPassword 属性値をbase64デコードすることにより、ユーザーパスワードが適切にハッシュ化され、プレーンテキストとして保存されていないことを常に確認してください。

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サーバーの設定方法に関する情報は、次のとおりです。

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

パラメーター -hserver.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 --password

ユーザーのパスワードを強制的に設定するには、kinitを使用します。ユーザーjohnを指定して、次のコマンドを入力します。

kinit john

通常のIPA操作を復元するには、次のコマンドを入力します。

kdestroy -A
kinit admin

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 に必要な変更を行います。

[domain/your-hostname.local]
...
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 ファイルに含まれていることを確認してください。

[ifp]
allowed_uids = root, your_username

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

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

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

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

  1. 管理コンソールに移動します。

  2. 左のメニューから User Federation を選択します。

  3. Add Provider ドロップダウン・リストから、 sssd を選択します。sssd設定ページが開きます。

  4. Save をクリックします。

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

カスタム・プロバイダー

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

監査とイベント

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

ログインイベント

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

Event Configuration

login events config

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

イベントの保存

login events settings

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

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

ログインイベント

login events

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

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

login events filter

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

イベントの種類

ログインイベント:

  • 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 - アカウントのメールアドレスが検証されました。

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

イベントリスナー

イベントリスナーは、イベントを待ち受け、そのイベントに基づいてアクションを実行します。 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に与えます。

ロギング・イベントリスナーは、イベントを org.keycloak.events ロガーカテゴリーに記録します。デフォルトでは、デバッグログ・イベントはサーバーログに含まれません。

サーバーログにデバッグログ・イベントを含めるには、 standalone.xml ファイルを編集し、ロギング・イベントリスナーで使用されるログレベルを変更します。または、 org.keycloak.events のログレベルを設定できます。

たとえば、ログレベルを変更するには、以下を追加します。

<subsystem xmlns="urn:jboss:domain:logging:...">
    ...
    <logger category="org.keycloak.events">
        <level name="DEBUG"/>
    </logger>
</subsystem>

ロギング・イベントリスナーが使用するログレベルを変更するには、以下を追加します。

<subsystem xmlns="urn:jboss:domain:keycloak-server:...">
    ...
    <spi name="eventsListener">
      <provider name="jboss-logging" enabled="true">
        <properties>
          <property name="success-level" value="info"/>
          <property name="error-level" value="error"/>
        </properties>
      </provider>
    </spi>
</subsystem>

ログレベルの有効な値は、 debuginfowarnerror 、および fatal です。

電子メール・イベントリスナーは、イベントが発生したときにユーザーのアカウントに電子メールを送信します。

現在、電子メール・イベントリスナーは次のイベントをサポートしています。

  • Login Error

  • Update Password

  • Update TOTP

  • Remove TOTP

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

1つまたは複数のイベントを除外するには、配布物に付属している standalone.xmlstandalone-ha.xmldomain.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.xmlstandalone-ha.xml 、または domain.xml を編集して、データベースに保存されるイベントの詳細の最大長を設定することもできます。この設定は、一部のフィールド(redirect_uriなど)が非常に長い場合に役立ちます。以下に、最大長を定義する例を示します。

<spi name="eventsStore">
    <provider name="jpa" enabled="true">
        <properties>
            <property name="max-detail-length" value="1000"/>
        </properties>
    </provider>
</spi>

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

管理イベント

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

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

Event Configuration

login events config

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

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

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

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

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

  • ファイルシステム上の単一のJSONファイル

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

  • <REALM_NAME>-realm.json("acme-roadrunner-affairs"という名前のレルムの場合は、"acme-roadrunner-affairs-realm.json")

  • <REALM_NAME>-users-<INDEX>.json("acme-roadrunner-affairs"という名前のレルムにおける1つ目のユーザーファイルの場合は、"acme-roadrunner-affairs-users-0.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>

一つのJSONファイルにエクスポートするには、次のようにします。

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

同様にインポートするには export の代わりに -Dkeycloak.migration.action=import を使います。次はインポートの例です。

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

keycloak.import に基づくメカニズムは、 keycloak.migration.X プロパティーに基づく他のメカニズムとともに使用できません。一緒に使用すると、 keycloak.import は無視されます。 keycloak.import メカニズムは、すでにKeycloakに存在するレルムを常に無視します。一般的に、 keycloak.import メカニズムは開発目的には便利ですが、より柔軟性が必要な場合は、 keycloak.migration.X プロパティーに基づくメカニズムを使用することをお勧めします。

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

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

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

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

管理コンソールでのエクスポート/インポートでは、ファイルごとに1つのレルムしか使用できません。
管理コンソールでのインポートにより、リソースを"上書き"することができます(そのように選択した場合)。この機能は、特に実動システムでは注意して使用してください。管理コンソールのエクスポート操作からエクスポートした.jsonファイルは、シークレットに対して無効な値が含まれているため、通常データのインポートには適切ではありません。
管理コンソールでのエクスポートでは、クライアント、グループ、およびロールをエクスポートできます。レルム内にこれらの数が多い場合、操作には時間がかかることがあります。この間、サーバーはユーザーのリクエストに応答しない可能性があります。この機能は、特にプロダクション・システムでは注意して使用してください。

ボールトを使用してシークレットを取得する

管理のいくつかのフィールドは、外部ボールトからのシークレット値の取得をサポートしています。

直接入力する代わりにボールトからシークレットを取得するには、次の特別に細工された文字列を適切なフィールドに入力します。 ${vault.key}key をボールトによって認識されるシークレットの名前で置き換えます。)

シークレットがレルム間で漏洩するのを防ぐために、実装では、レルム名をボールト式から取得した key と組み合わせる場合があります。つまり、 key はボールト内のエントリーに直接マップされず、レルム名と組み合わせるために使用されるアルゴリズムに従って最終的なエントリー名を作成するために使用されます。

現在、次のフィールドについてはボールトからシークレットを取得できます。

SMTPパスワード

レルムのSMTP設定

LDAPバインド・クレデンシャル

LDAPベースのユーザー・フェデレーションのLDAP設定内。

OIDCアイデンティティー・プロバイダー・シークレット

アイデンティティー・プロバイダーOpenID Connect設定内の Client Secret 内。

ボールトを使用するには、Keycloak内にボールト・プロバイダーを登録する必要があります。以下で説明する組み込みプロバイダーを使用するか、独自のプロバイダーを実装することができます。詳細については、リンクServer Developer Guideを参照してください。

Keycloakインスタンスごとにアクティブなボールト・プロバイダーは常に最大1つであり、クラスター内の各インスタンスのボールト・プロバイダーは一貫して設定される必要があります。

Kubernetes / OpenShift Files Plaintext ボールト・プロバイダー

Keycloakは、 Kubernetes secrets のボールト実装をサポートしています。これらのシークレットはデータボリュームとしてマウントでき、フラットファイル構造のディレクトリーとして表示されます。各シークレットは名前がシークレット名であり、そのファイルの内容がシークレット値です。

このディレクトリー内のファイルは、レルム名とアンダースコアを前に付けたシークレット名として命名する必要があります。シークレット名またはレルム名内のすべての下線は、ファイル名で二重にする必要があります。たとえば、 sso_realm というレルム内のフィールドの場合、 secret-name という名前のシークレットへの参照は ${vault.secret-name} と記述され、検索されるファイル名は sso__realm_secret-name (アンダースコアがレルム名で2重になっていることに注意してください)。

このタイプのシークレット・ストアを使用するには、standalone.xmlで files-plaintext ボールト・プロバイダーを宣言し、マウントされたボリュームを含むディレクトリーのパラメーターを設定する必要があります。次の例は、Keycloakベース・ディレクトリーに対して standalone/configuration/vault に設定されたボールトファイルが検索されるディレクトリーを持つ files-plaintext プロバイダーを示しています。

<spi name="vault">
    <default-provider>files-plaintext</default-provider>
    <provider name="files-plaintext" enabled="true">
        <properties>
            <property name="dir" value="${jboss.home.dir}/standalone/configuration/vault/" />
        </properties>
    </provider>
</spi>

CLIコマンドを使用した同等の設定は以下になります。

/subsystem=keycloak-server/spi=vault/:add
/subsystem=keycloak-server/spi=vault/provider=files-plaintext/:add(enabled=true,properties={dir => "${jboss.home.dir}/standalone/configuration/vault"})

Elytron Credential Storeボールト・プロバイダー

Keycloakは、Elytronクレデンシャル・ストアに保存されているシークレットを読み取るためのサポートも提供します。 elytron-cs-keystore ボールト・プロバイダーは、クレデンシャル・ストアのキーストア・ベースの実装からシークレットを取得できます。これは、Elytronが提供するデフォルトの実装でもあります。

このクレデンシャル・ストアはキーストア( JCEKS がデフォルトのフォーマットですが、 PKCS12 などの他のフォーマットを使用することもできます)に支えられており、ユーザーはWildFly/JBoss EAPの elytron サブシステムかを使用して(または elytron-tool.sh スクリプトを使用して)、ストアコンテンツを作成および管理できます。

このプロバイダーを使用するには、 keycloak-server サブシステムで elytron-cs-keystore を宣言し、Elytronによって作成されたキーストアの場所とマスター・シークレットを設定する必要があります。プロバイダーの最小設定の例を以下に示します。

<spi name="vault">
    <default-provider>elytron-cs-keystore</default-provider>
    <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="${jboss.home.dir}/standalone/configuration/vault/credential-store.jceks" />
            <property name="secret" value="secretpw1!"/>
        </properties>
    </provider>
</spi>

基になるキーストアの形式が JCEKS 以外の場合、この形式は keyStoreType を使用して通知する必要があります。

<spi name="vault">
    <default-provider>elytron-cs-keystore</default-provider>
    <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="${jboss.home.dir}/standalone/configuration/vault/credential-store.p12" />
            <property name="secret" value="secretpw1!"/>
            <property name="keyStoreType" value="PKCS12"/>
        </properties>
    </provider>
</spi>

シークレットのために、上記のような elytron-cs-keystore プロバイダーはクリアテキスト値と次のような elytron-tool.sh スクリプトを使用してマスクされた値の両方をサポートしています。

<spi name="vault">
   ...
            <property name="secret" value="MASK-3u2HNQaMogJJ8VP7J6gRIl;12345678;321"/>
   ...
</spi>

Elytronクレデンシャル・ストアを作成/管理する方法、およびキーストア・シークレットをマスクする方法の詳細については、Elytronのドキュメントを参照してください。

elytron-cs-keystore ボールト・プロバイダーはWildFly拡張機能として実装されているため、KeycloakサーバーがWildFly/JBoss EAPで実行されている場合にのみ使用できます。

キーリゾルバー

すべての組み込みプロバイダーは、1つ以上のキーリゾルバーの設定をサポートしています。キーリゾルバーは基本的に、レルム名とキー( ${vault.key} 式から得られる)を組み合わせて、ボールトからシークレットを取得するために使用される最終的なエントリー名を得るアルゴリズムまたは戦略を実装します。 keyResolvers プロパティーは、プロバイダーが使用するリゾルバーを設定するために使用されます。値はリゾルバー名のカンマ区切りのリストです。 files-plaintext プロバイダーの設定例は次のとおりです。

<spi name="vault">
    <default-provider>files-plaintext</default-provider>
    <provider name="files-plaintext" enabled="true">
        <properties>
            <property name="dir" value="${jboss.home.dir}/standalone/configuration/vault/" />
            <property name="keyResolvers" value="REALM_UNDERSCORE_KEY, KEY_ONLY"/>
        </properties>
    </provider>
</spi>

リゾルバーは、設定で宣言されている順序で実行されます。各リゾルバーについて、レルムとボールトキーを組み合わせたリゾルバーによって生成された最終エントリー名は、ボールト内のシークレットを検索するために使用されます。シークレットが見つかると、すぐに返されます。そうでない場合は、次のリゾルバーが使用され、空でないシークレットが見つかるか、すべてのリゾルバーが試行されるまでこれが続きます。この場合、空のシークレットが返されます。上記の例では、最初に REALM_UNDERSCORE_KEY リゾルバーが使用されます。ボールトで生成された名前のエントリーが見つかった場合、そのエントリが返されます。そうでない場合、 KEY_ONLY リゾルバーが使用されます。繰り返しになりますが、ボールトで生成された名前のエントリーが見つかった場合、そのエントリーが返されます。そうでない場合は、使用するリゾルバーがなくなるため、空のシークレットが返されます。

現在利用可能なリゾルバーのリストは次のとおりです。

  • KEY_ONLY :レルム名は無視され、ボールト式のキーがそのまま使用されます。

  • REALM_UNDERSCORE_KEY :レルムとキーは、アンダースコア _ 文字を使用して結合されます。レルムまたはキーでのアンダースコアの出現は、別のアンダースコア文字によってエスケープされます。したがって、レルムが master_realm と呼ばれ、キーが smtp_key である場合、結合されたキーは master__realm_smtp__key になります。

  • REALM_FILESEPARATOR_KEY :レルムとキーは、プラットフォーム・ファイル・セパレーター文字を使用して結合されます。これは、キーがレルムによってディレクトリー構造を使用してグループ化されている状況で役立ちます。

  • FACTORY_PROVIDED :レルムとキーは、ボールト・プロバイダー・ファクトリーによって提供される VaultKeyResolver を使用して結合されます。これにより、既存のファクトリーを拡張し、 getFactoryResolver メソッドを実装することにより、カスタム・キーリゾルバーを作成できます。

組み込みプロバイダーにリゾルバーが設定されていない場合、デフォルトで REALM_UNDERSCORE_KEY が選択されます。

FACTORY_PROVIDED リゾルバーは、選択したプロバイダー・ファクトリーを拡張し、 getFactoryResolver メソッドをオーバーライドしてカスタム・リゾルバーを返すことにより、カスタム・リゾルバーを実装するために使用できるフックを提供します。たとえば、 elytron-cs-keystore プロバイダーを使用したいが、組み込みリゾルバーがキーストアで使用されている形式と一致しない場合、 ElytronCSKeystoreProvider を拡張して getFactoryResolver メソッドを実装できます。

    public class CustomElytronProviderFactory extends ElytronCSKeyStoreProviderFactory {
        ...
        @Override
        protected VaultKeyResolver getFactoryResolver() {
            return (realm, key) -> realm + "###" + key;
        }

        @Override
        public String getId() {
            return "custom-elytron-cs-keystore;
        }

        ...
    }

カスタム・ファクトリーは、レルムとキーを3つの 文字で組み合わせるキーリゾルバーを返します。たとえば、エントリーは master_realm##smtp_key のようになります。このファクトリーは、カスタム・プロバイダーと同じようにインストールする必要があります。

カスタム・ファクトリーは getFactoryResolvergetId メソッドの両方をオーバーライドする必要があることに注意してください。2番目のメソッドは、Keycloakでカスタム・ファクトリーを適切に設定するために必要です。

上記のカスタム・プロバイダーをインストールして使用する設定は、次のようになります。

<spi name="vault">
    <default-provider>custom-elytron-cs-keystore</default-provider>
    <provider name="custom-elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="${jboss.home.dir}/standalone/configuration/vault/credential-store.p12" />
            <property name="secret" value="MASK-3u2HNQaMogJJ8VP7J6gRIl;12345678;321"/>
            <property name="keyStoreType" value="PKCS12"/>
            <property name="keyResolvers" value="FACTORY_PROVIDED"/>
        </properties>
    </provider>
</spi>

上記の設定は、KeycloakにカスタムElytronプロバイダーをセットアップし、カスタム・ファクトリーによって作成されたキーリゾルバーを使用するように指示します。

ユーザー・アカウント・サービス

Keycloakには、すべてのユーザーがアクセスできるビルトインのユーザー・アカウント・サービスがあります。このサービスでは、ユーザーはアカウントの管理、クレデンシャルの変更、プロファイルの更新、ログイン・セッションの表示を行うことができます。このサービスのURLは <server-root>/auth/realms/{realm-name}/account です。

アカウント・サービス

account service profile

最初のページはユーザーのプロファイル(左メニュー項目の 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

テーマ設定が可能

KeycloakのすべてのUIと同様に、ユーザー・アカウント・サービスは完全にテーマ設定が可能であり、国際化も可能です。 詳細については、Server Developer Guideのリンクを参照してください。

脅威モデルの緩和

この章では、認証サーバーが持つ可能性のあるセキュリティーの脆弱性と、Keycloakがこれらの脆弱性を軽減する方法について説明します。潜在的な脆弱性の良いリストと、セキュリティー実装がそれらを緩和するために何をすべきかは、 OAuth 2.0 Threat Model のドキュメントと、その最新の拡張でIETFが発表した OAuth 2.0 Security Best Current Practice にあります。これらの脆弱性の多くは、ここで説明されています。

Host

Keycloakは、パブリックホスト名をさまざまな用途に使用します。たとえば、トークン発行者のフィールドやパスワードリセットの電子メールで送信されたURLなどです。

デフォルトでは、ホスト名はリクエスト・ヘッダーに基づいており、このホスト名が有効であることを確認するためのチェックはありません。

無効なホストヘッダーを防ぐために、Keycloakの前にロードバランサーまたはプロキシーを使用していない場合は、受け入れるホスト名を明示的に設定する必要があります。

Hostname SPIは、リクエストに対してホスト名を設定する方法を提供します。すぐに使用可能なプロバイダーを使用すると、フロントエンドのリクエストに対して固定のURLを設定でき、リクエストURIに基づいてバックエンドのリクエストを許可できます。ビルトイン・プロバイダーが必要な機能を提供しない場合、独自のプロバイダーを開発することもできます。

管理エンドポイントと管理コンソール

Keycloak管理REST APIとWebコンソールは、非管理用途と同じポートにデフォルトで公開されています。管理コンソールへのアクセスが外部から必要ない場合は、管理エンドポイントをインターネットに公開しないことをお勧めします。

これは、Keycloakで直接行うことも、ApacheやNginxなどのプロキシーで行うこともできます。

プロキシー・オプションについては、プロキシーのマニュアルを参照してください。 /auth/admin へのリクエストのアクセスを制御する必要があります。

これをKeycloakで直接実現するには、いくつかのオプションがあります。このドキュメントでは、IP制限とポートの分離の2つのオプションについて説明します。

KeycloakのフロントエンドURLで管理コンソールにアクセスできなくなったら、デフォルトのホスト名プロバイダーで固定値の管理URLを設定する必要があります。

IP制限

/auth/admin へのアクセスを特定のIPアドレスだけに制限することが可能です。

次の例では、 /auth/admin へのアクセスを 10.0.0.1 から 10.0.0.255 の範囲のIPアドレスに制限しています。

<subsystem xmlns="urn:jboss:domain:undertow:11.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を正しく設定することが重要です。

ポート制限

/auth/admin をインターネットに公開されていない別のポートに公開することが可能です。

次の例では、 /auth/admin をポート 8444 で公開しますが、デフォルトポート 8443 ではアクセスを許可しません。

<subsystem xmlns="urn:jboss:domain:undertow:11.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()

パスワード推測:ブルートフォース攻撃

ブルートフォース攻撃は、攻撃者がユーザーのパスワードを推測しようとしているときに発生します。Keycloakにはいくつかの限定的なブルートフォースの検出機能があります。オンにすると、ログイン失敗のしきい値に達した場合に、ユーザー・アカウントが一時的に無効になります。この機能を有効にするには、左側のメニューの Realm Settings に移動し、 Security Defenses タブをクリックし、さらに Brute Force Detection サブタブに移動します。

ブルートフォース検出はデフォルトで無効になっています。このタイプの攻撃から保護するには、この機能を有効にすることを強くお勧めします。
ブルートフォース検出

brute force

ブルートフォースの検出には2つの異なる設定があります。永続的なロックアウトと一時的なロックアウトです。永続的なロックアウトは、攻撃が検出されるとユーザーのアカウントを無効にします。管理者が再びアカウントを有効にするまで、アカウントは無効になります。一時的なロックアウトは、攻撃が検出されるとユーザーのアカウントを一定期間、無効にします。アカウントが無効になっている期間は、攻撃が継続する時間が長くなるほど長くなります。

一時的にロックされたユーザーがログインしようとすると、デフォルトのエラーメッセージ Invalid username or password が表示されます。これは、無効なユーザー名または無効なパスワードが指定されたときに表示されるメッセージと同じエラーメッセージです。ユーザーが一時的に無効にされていることを攻撃者に明らかにしたくないので、これは仕様によるものです。

共通パラメーター

Max Login Failures

許可されたログイン失敗の最大回数。デフォルト値は30です。

Quick Login Check Milli Seconds

ログイン試行の間に必要な最小時間。デフォルトは1000です。

Minimum Quick Login Wait

ログインの試行が Quick Login Check Milli Seconds より早い場合に、ユーザーが一時的に無効になる最小時間。デフォルトは1分です。

一時ロックアウト・パラメーター

Wait Increment

Max Login Failures に達するたびにユーザーが一時的に無効にされた時間に加算される時間。デフォルトは1分です。

Max Wait

ユーザーが一時的に無効になる最大時間。デフォルトは15分です。

Failure Reset Time

失敗回数がリセットされるまでの時間。タイマーは最後に失敗したログインから実行されます。デフォルトは12時間です。

永続的ロックアウト・アルゴリズム

  1. ログインに成功した場合

    1. count のリセット

  2. ログインに失敗した場合

    1. count のインクリメント

    2. countMax Login Failures より大きい場合 …​ ユーザーを永続的に無効にします

    3. そうでなければ、この失敗と最後の失敗との間の時間が Quick Login Check Milli Seconds 未満の場合

      1. Minimum Quick Login Wait の間、一時的にユーザーを無効にします

ユーザーが無効になっている場合、管理者がユーザーを有効にするまでログインできません。アカウントを有効にすると count がリセットされます。

一時的ロックアウト・アルゴリズム

  1. ログインに成功した場合

    1. count のリセット

  2. ログインに失敗した場合

    1. この失敗と最後の失敗との間の時間が Failure Reset Time より大きい場合 …​ count をリセットします

    2. count のインクリメント

    3. Wait Increment *( count / Max Login Failures )を使って wait を計算します。除算は整数除算なので、常に整数に切り捨てられます

    4. wait が0に等しく、この失敗と最後の失敗との間の時間が Quick Login Check Milli Seconds より小さい場合、 waitMinimum Quick Login Wait を設定します。…​ waitMax Wait 秒のうち小さい方の値を一時的に無効にします

ユーザーが一時的に無効になったときのログイン失敗に対しては、 count をインクリメントしません。

Keycloakのブルートフォース検出の欠点は、サーバーがDoS攻撃に対して脆弱になることです。攻撃者が、自分の知っているアカウントのパスワード推測を試みるだけで、アカウントは無効になります。最終的には、ユーザーをブロックするかどうかを決定する際にクライアントのIPアドレスを考慮に入れるように、この機能を拡張する予定です。

より良いオプションは、 Fail2Ban のようなツールです。このサービスに、Keycloakサーバーのログファイルを指定できます。 Keycloakは、失敗したすべてのログイン失敗とクライアントIPアドレスを記録します。攻撃を検出した後、特定のIPアドレスからの接続をブロックするようにファイアウォールを変更するために、Fail2Banを使用できます。

パスワード・ポリシー

パスワード推測を防ぐために行うべきもう1つの作業は、推測が難しいパスワードをユーザーが選択するように、複雑なパスワードポリシーを持つことです。詳細については、パスワード・ポリシーの章を参照してください。

ただし、パスワードが推測されないようにする最善の方法は、ワンタイム・パスワード(OTP)を使用するようにサーバーを設定することです。

クリック・ジャッキング

クリック・ジャッキングは、悪意のあるサイトが標的サイトを透明なIFrameで読み込み、注意深く構築されたダミーボタンのセットを標的サイトの重要なボタンに位置するように上に重ねます。ユーザーが表示されているボタンをクリックすると、実際には隠されたページのボタン("ログイン" ボタンなど)をクリックしています。攻撃者は、ユーザーの認証クレデンシャル情報を盗み、リソースにアクセスできます。

デフォルトでは、Keycloakによるすべてのレスポンスは、これが起こらないように特定のブラウザー・ヘッダーを設定します。具体的には、 X-FRAME-OPTIONSContent-Security-Policy を設定します。細かい粒度のブラウザー・アクセスが制御できるので、これらのヘッダーの両方の定義を見てください。管理コンソールでは、これらのヘッダーに含める値を指定できます。左メニュー項目 Realm Settings に移動し、 Security Defenses タブをクリックし、 Headers サブタブにいることを確認します。

security headers

デフォルトでは、KeycloakはIFrameの same-origin ポリシーのみを設定します。

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の中間者攻撃に脆弱です。

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と照合されて、呼び出しがユーザーによって行われたことを検証します。

不特定のリダイレクトURI

認可コードフローでは、あまりにも一般的なリダイレクトURIを登録すると、不正なクライアントがより広い範囲のアクセス権を持つ別のクライアントに偽装する可能性があります。たとえば、2つのクライアントが同じドメインの下にある場合にこれが起こります。したがって、登録されたリダイレクトURIを可能な限り具体的なものにすることをお勧めします。

セキュリティー侵害されたアクセストークンとリフレッシュトークン

アクセストークンとリフレッシュトークンが盗まれることを軽減するためにできることがいくつかあります。最も重要なことは、Keycloakとそのクライアントとアプリケーションの間でSSL/HTTPS通信を強制することです。明らかなことだと思われるかもしれませんが、KeycloakはデフォルトでSSLが有効になっていないため、管理者はそれが必要であると認識していない可能性があります。

アクセストークンのリークを軽減するために実行できるもう1つの方法は、寿命を短くすることです。これはタイムアウト・ページ内で指定できます。短時間でクライアントとアプリケーションがアクセストークンをリフレッシュするように、アクセストークンは短い寿命(数分)とします。管理者がリークを検出した場合には、すべてのユーザー・セッションをログアウトしてこれらのリフレッシュトークンを無効にするか、失効ポリシーを設定することができます。リフレッシュトークンが常にクライアントでプライベートに保たれ、決して送信されないことを確認することは非常に重要です。

これらのトークンをholder-of-keyトークンとして発行することによって、アクセストークンとリフレッシュトークンの漏洩を軽減することもできます。方法については、OAuth 2.0 Mutual TLS Client Certificate Bound Access Tokenを参照してください。

アクセストークンまたはリフレッシュトークンが侵害された場合、最初に行うべきことは管理コンソールに行き、not-before失効ポリシーをすべてのアプリケーションにプッシュすることです。これにより、その日時以前に発行されたトークンは無効になります。新しいnot-beforeポリシーを適用することで、アプリケーションがKeycloakから新しい公開鍵をダウンロードするように強制されるので、レルムの署名鍵が侵害されたと思われる場合にも有用です。より詳しい情報は鍵の章にあります。

特定のアプリケーション、クライアント、およびユーザーのいずれかが完全に侵害されたと思われる場合は、そのエンティティーを無効にすることもできます。

侵害された認可コード

OIDC認可コードフローでは、攻撃者がKeycloak認可コードを侵害することは非常に困難です。Keycloakは、認可コードに対して暗号的に強いランダムな値を生成するので、アクセストークンを推測することは非常に困難です。認可コードは、アクセストークンを取得するために1回しか使用できません。管理コンソールのタイムアウト・ページで認可コードの有効期間を指定できます。この値は、実際には数秒と短く、クライアントがコードからトークンを取得するリクエストを行うのに十分な長さでなければなりません。

また、クライアントにPKCEを適用することにより、認可コードの漏洩を軽減できます。方法については、 Proof Key for Code Exchange(PKCE) を参照してください。

オープン・リダイレクター

攻撃者は、エンドユーザーの認可エンドポイントとリダイレクトURIパラメーターを使用して、認可サーバーをオープン・リダイレクターとして悪用する可能性があります。オープン・リダイレクターは、パラメーターを使用してユーザー・エージェントをパラメーター値で指定された場所に自動的にリダイレクトするエンドポイントです。攻撃者は、認可サーバーに対するユーザーの信頼を利用して、フィッシング攻撃を開始する可能性があります。

Keycloakは、登録されたすべてのアプリケーションとクライアントが少なくとも1つのリダイレクトURIパターンを登録することを要求します。クライアントがKeycloakにリダイレクト(ログインやログアウトなど)を依頼すると、KeycloakはリダイレクトURIと有効な登録済みURIパターンのリストをチェックします。オープン・リダイレクターの攻撃を軽減するために、クライアントとアプリケーションができるだけ具体的なURIパターンを登録することが重要です。

パスワード・データベースの侵害

Keycloakはパスワードを生のテキストで保存しません。PBKDF2アルゴリズムを使用して、それらのハッシュを保存します。実際には、デフォルトの20,000回のハッシング反復を使用します。これは、セキュリティー・コミュニティが推奨する反復回数です。設計上、PBKDF2が大量のCPUを浪費するため、システムにかなり大きな負荷がかかる可能性があります。パスワード・データベースをどの程度保護したいのかは、要件次第です。

スコープの制限

デフォルトでは、新しいクライアント・アプリケーションごとに無制限の role scope mappings があります。つまり、そのクライアント用に作成されたすべてのアクセストークンには、ユーザーが持つすべてのパーミッションが含まれます。クライアントが侵害されてアクセストークンが漏洩した場合、ユーザーがパーミッションを持つ各システムも侵害されます。クライアントごとにスコープメニューを使用してアクセストークンが割り当てられるロールを制限することを強くお勧めします。または、クライアント・スコープ・レベルでロール・スコープ・マッピングを設定し、クライアント・スコープ・メニューを使用してクライアント・スコープをクライアントに割り当てることができます。

トークンのAudienceの制限

サービス間の信頼度が低い環境では、トークンのAudienceを制限することをお勧めします。その背後にある動機は、 OAuth2 Threat Model ドキュメントで説明されており、より多くの詳細はAudienceのサポート・セクションにあります。

SQLインジェクション攻撃

現時点では、KeycloakのSQLインジェクションの脆弱性に関するナレッジはありません。

管理CLI

前の章では、Keycloak管理コンソールを使用して管理タスクを実行する方法について説明しました。管理CLIツールを使用して、コマンドライン・インターフェイス(CLI)からこれらの管理タスクを実行することもできます。

管理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の例を示しています。

管理CLIの利用

管理CLIは、管理RESTエンドポイントへのHTTPリクエストを作成することによって動作します。エンドポイントへのアクセスは保護されており、認証が必要です。

特定のエンドポイントのJSON属性の詳細については、管理REST APIのドキュメントを参照してください。

  1. クレデンシャルを提供すること、つまりログインすることで、認証セッションを開始します。作成、読み取り、更新、および削除(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
      $ CID=$(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
  2. プロダクション環境では、ネットワーク・スニファーによりトークンが漏洩しないように、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

認証

管理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 コマンドを実行してください。

代替設定の使用

デフォルトでは、管理CLIはユーザーのホーム・ディレクトリーにある kcadm.config という設定ファイルを自動的に維持します。Linuxベースのシステムでは、フルパス名は $HOME/.keycloak/kcadm.config です。 Windowsでは、フルパス名は %HOMEPATH%\.keycloak\kcadm.config です。 --config オプションを使うと、別のファイルや場所を指し示すことができるので、複数の認証されたセッションを並行して維持することができます。

単一のスレッドから単一の設定ファイルに結び付けられた操作を実行することが最善の方法です。

システム上の他のユーザーが設定ファイルを参照できないようにしてください。プライベートにしておくべきアクセストークンとシークレットが含まれています。デフォルトでは、~/.keycloak ディレクトリーとその内容は適切なアクセス制限で自動的に作成されます。ディレクトリーがすでに存在する場合、そのパーミッションは更新されません。

特殊な状況で、シークレットを設定ファイルに保管しないようにする必要がある場合は、そうすることが可能です。この方法はあまり便利ではなく、トークン・リクエストが多くなります。シークレットを保存しないためには、すべてのコマンドで --no-config オプションを使用し、 config credentials コマンドで必要とされるすべての認証情報を kcadm 呼び出しごとに指定します。

基本操作とリソースURI

管理CLIでは、特定のタスクの実行を簡略化するために追加されたコマンドを使用して、管理REST APIエンドポイントに対してCRUD操作を実行できます。

主な使用パターンを以下に示します。 creategetupdatedelete コマンドは、それぞれHTTP動詞の POSTGETPUTDELETE に該当します。

$ 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呼び出しを実行します。

createupdate コマンドは、デフォルトで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 コマンドを実行する"マージしない"更新を実行することができます。

レルム操作

新しいレルムを作成する

realms エンドポイントで create コマンドを使用して新しいレルムを作成し、 realmenabled に属性を設定します。

$ 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

レルムの更新

  1. レルムの属性の一部だけを変更したい場合は、 -s オプションを使用して属性の新しい値を設定します。

    例:

    $ kcadm.sh update realms/demorealm -s enabled=false
  2. 書き込み可能なすべての属性を新しい値に設定するには、 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

新しいレルム鍵の生成

  1. 新しいRSA生成キーペアを追加する前に、対象レルムのIDを取得します。

    例:

    $ kcadm.sh get realms/demorealm --fields id --format csv --noquotes
  2. 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\"]"
  3. parentId 属性を対象レルムのIDの値に設定します。

    新しく追加された鍵は、 kcadm.sh get keys -r demorealm によって取得したとおり、アクティブな鍵になります。

Javaキーストア・ファイルから新しいレルム鍵を追加する

  1. 新しい鍵プロバイダーを追加して、すでにサーバー上に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.keyAlias=["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.keyAlias=[\"localhost\"]"
  2. 特定のキーストアに一致するように、 keystorekeystorePasswordkeyPassword 、および alias の属性値を変更してください。

  3. parentId 属性を対象レルムのIDの値に設定します。

鍵をパッシブにする、または無効にする

  1. パッシブにしたい鍵を特定する

    $ kcadm.sh get keys -r demorealm
  2. 鍵の providerId 属性を使用して、 components/PROVIDER_ID のようなエンドポイントURIを構築します。

  3. 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\"]"

      他のキー属性を更新することができます。

  4. たとえば、 config.enabled=["false"] のように、鍵を無効にするために enabled の値を設定してください。

  5. 鍵の優先度を変更するために新しい priority 値を設定します。たとえば、 config.priority=["110"] です。

古い鍵を削除する

  1. 削除している鍵がパッシブで無効になっていることを確認して、アプリケーションやユーザーが保持している既存のトークンを無効にします。

  2. パッシブにする鍵を特定します。

    $ kcadm.sh get keys -r demorealm
  3. その鍵の 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

キャッシュのフラッシュ

  1. create コマンドと、 clear-realm-cacheclear-user-cacheclear-keys-cache のいずれかのエンドポイントを使用します。

  2. 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

エクスポートされた.jsonファイルからのレルムのインポート

  1. partialImport エンドポイントで create コマンドを使用します。

  2. ifResourceExistsFAILSKIPOVERWRITE のいずれかに設定します。

  3. エクスポートされたレルム .json ファイルを送信するには、 -f を使います。

    例:

    $ kcadm.sh create partialImport -r demorealm2 -s ifResourceExists=FAIL -o -f demorealm.json

    レルムが存在しない場合は、まずレルムを作成する必要があります。

    例:

    $ kcadm.sh create realms -s realm=demorealm2 -s enabled=true

ロール操作

レルムロールの作成

レルムロールを作成するには、 roles エンドポイントを使用します。

$ kcadm.sh create roles -r demorealm -s name=user -s 'description=Regular user with limited set of permissions'

クライアントロールの作成

  1. クライアントロールを作成するときは、最初にクライアントを特定し、 get コマンドを使用して使用可能なクライアントを一覧表示します。

    $ kcadm.sh get clients -r demorealm --fields id,clientId
  2. 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 コマンドがあります。これは get コマンドの拡張です。

クライアントロールを一覧表示するには、 get-roles コマンドを使用します。 clientId または id 属性を渡すことで( --cclientid または --cid オプションを介して)、クライアントを指定します。

例:

$ kcadm.sh get-roles -r demorealm --cclientid realm-management

特定のレルムロールを取得する

roles/ROLE_NAME のように特定のレルムロールのエンドポイントURIを構築するには、 get コマンドとロール name を使用します。ここで、 user は既存のロールです。

例:

$ kcadm.sh get roles/user -r demorealm

get-roles コマンドを使用することもできます。 --rolename オプションでロール名を渡すか、 --roleid オプションでIDを渡します。

例:

$ kcadm.sh get-roles -r demorealm --rolename user

特定のクライアントロールを取得する

専用の get-roles コマンドを使用します。クライアントを識別するためにclientId属性( --cclientid オプションで)またはID( --cid オプションで)を渡し、クライアントロールを識別するためにロール名( --rolename オプションで)またはID( --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 コマンドを使用して、複合ロールに割り当てられた、利用可能な、有効なレルムロールを一覧表示します。

  1. 複合ロールに 割り当てられた レルムロールを一覧表示するには、name( --rname オプションで)またはID( --rid オプションで)のいずれかで対象の複合ロールを指定します。

    例:

    $ kcadm.sh get-roles -r demorealm --rname testrole
  2. 有効な レルムロールを一覧表示するには、 --effective オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --rname testrole --effective
  3. 複合ロールに追加できるレルムロールを一覧表示するには、 --available オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --rname testrole --available

複合ロールに割り当てられた、利用可能な、有効なクライアントロールの一覧表示

専用の get-roles コマンドを使用して、複合ロールに割り当てられた、利用可能な、有効なクライアントロールを一覧表示します。

  1. 複合ロールの 割り当てられた クライアントロールを一覧表示するには、 --rname オプションでロール名を指定するか、または --rid オプションでIDを指定します。また、クライアントを特定するために、 --cclientid オプションでclientId属性、または --cid オプションでIDのいずれかを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management
  2. 有効な レルムロールを一覧表示するには、 --effective オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --effective
  3. 対象の複合ロールにまだ追加できるレルムロールを一覧表示するには、 --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

クライアントロールへのクライアントロールの追加

  1. get-roles コマンドを使用して複合クライアントロールのIDを特定します。

    例:

    $ kcadm.sh get-roles -r demorealm --cclientid test-client --rolename operations
  2. test-client のclientId属性をもつクライアントと、 support というクライアントロール、および operations という別のクライアントロールがあり、IDが "fc400897-ef6a-4e8c-872b-1581b7fa8a71" という複合ロールになると仮定します。

  3. 次の例を使用して、複合ロールに別のロールを追加します。

    $ kcadm.sh add-roles -r demorealm --cclientid test-client --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --rolename support
  4. get-roles --all コマンドを使用して、複合ロールのロールを一覧表示します。

    例:

    $ kcadm.sh get-roles --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --all

複合ロールからのクライアントロールの削除

複合ロールからクライアントロールを削除するには、専用の remove-roles コマンドを使用します。

次の例を使用して、 realm-management クライアントに定義された create-clientview-users の2つのロールを複合ロール testrole から削除します。

$ kcadm.sh remove-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users

グループへのクライアント・ロールの追加

レルムロールとクライアントロールを追加するために使用できる専用の add-roles コマンドを使用します。

次の例では、 realm-management クライアントに定義された create-client ロールと view-users ロールを Group グループに追加します。( --gid オプションを使用して、)グループはグループ名の代わりにIDで指定できます。

グループに対して実行できるその他の操作については、グループ操作を参照してください。

$ kcadm.sh add-roles -r demorealm --gname Group --cclientid realm-management --rolename create-client --rolename view-users

グループからのクライアントロールの削除

グループからクライアントロールを削除するには、専用の remove-roles コマンドを使用します。

次の例を使用して、クライアント realm-management で定義された2つのロール( create-clientview-users )を Group グループから削除します。

グループに対して実行できるその他の操作については、グループ操作を参照してください。

$ kcadm.sh remove-roles -r demorealm --gname Group --cclientid realm-management --rolename create-client --rolename view-users

クライアント操作

クライアントの作成

  1. clients エンドポイントで create コマンドを実行して、新しいクライアントを作成します。

    例:

    $ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true
  2. 認証するアダプターのシークレットを設定したい場合は、シークレットを指定します。

    例:

    $ 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

特定のクライアントの新しいシークレットを生成する

クライアントのIDを使用して、 clients/ID/client-secret のようなエンドポイントURIを構築します。

例:

$ kcadm.sh create clients/$CID/client-secret

特定のクライアントの現在のシークレットを更新する

クライアントのIDを使用して、 clients/ID のようなエンドポイントURIを構築します。

例:

$ kcadm.sh update clients/$CID -s "secret=newSecret"

特定のクライアントのアダプター設定ファイル(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

特定のクライアントのためのDocker-v2のサンプル設定の取得

クライアントIDを使用して、 clients/ID/installation/providers/docker-v2-compose-yaml のような特定のクライアントを対象とするエンドポイントURIを構築します。

レスポンスは .zip 形式であることに注意してください。

例:

$ kcadm.sh get http://localhost:8080/auth/admin/realms/demorealm/clients/8f271c35-44e3-446f-8953-b0893810ebe7/installation/providers/docker-v2-compose-yaml -r demorealm > keycloak-docker-compose-yaml.zip

クライアントの更新

特定のクライアントを取得するために使用した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

クライアントのサービス・アカウントのロールの追加または削除

クライアントのサービス・アカウントは、ユーザー名 service-account-CLIENT_ID を持つ特別な種類のユーザー・アカウントです。このアカウントでは、通常のユーザーと同様にユーザー操作を実行できます。

ユーザー操作

ユーザーの作成

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

usernamefirstNamelastNameemail でユーザーをフィルタリングできます。

例:

$ 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 コマンドを使用して、ユーザーに割り当てられた、利用可能で、有効なレルムロールを一覧表示することができます。

  1. ユーザーの 割り当てられた レルムロールを一覧表示するには、ユーザー名またはIDのどちらかを使用して対象ユーザーを指定します。

    例:

    $ kcadm.sh get-roles -r demorealm --uusername testuser
  2. 有効な レルムロールを一覧表示するには、 --effective オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --uusername testuser --effective
  3. ユーザーに追加できるレルムロールを一覧表示するには、 --available オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --uusername testuser --available

ユーザーに割り当てられた、利用可能な、有効なクライアントロールの一覧表示

専用の get-roles コマンドを使用して、ユーザーに割り当てられた、利用可能で、有効なクライアントロールを一覧表示します。

  1. ユーザーに 割り当てられた クライアントロールを一覧表示するには、--uusername オプションでユーザー名を指定するか、 --uid オプションでIDを指定して対象ユーザー特定し、 --cclientid オプションでclientId属性を指定するか、 --cid オプションでIDを指定して対象クライアントを特定します。

    例:

    $ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management
  2. 有効な レルムロールを一覧表示するには、 --effective オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --effective
  3. ユーザーに追加できるレルムロールを一覧表示するには、 --available オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --available

ユーザーにレルムロールを追加する

レルムロールをユーザーに追加するには、専用の add-roles コマンドを使用します。

次の例を使用して、 user ロールをユーザー testuser に追加します。

$ kcadm.sh add-roles --uusername testuser --rolename user -r demorealm

ユーザーからレルムロールを削除する

ユーザーからレルムロールを削除するには、専用の remove-roles コマンドを使用します。

以下の例を使用して、ユーザー testuser から user ロールを削除します。

$ kcadm.sh remove-roles --uusername testuser --rolename user -r demorealm

ユーザーにクライアントロールを追加する

クライアントロールをユーザーに追加するには、専用の add-roles コマンドを使用します。

次の例を使用して、クライアント 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

ユーザー・セッションの一覧表示

  1. ユーザーのIDを特定し、それを利用して users/ID/sessions などのエンドポイントURIを作成します。

  2. ユーザーのセッションの一覧を取得するには、 get コマンドを使用します。

    例:

    $kcadm get users/6da5ab89-3397-4205-afaa-e201ff638f9e/sessions

特定のセッションからユーザーをログアウトする

  1. 上記のようにセッションのIDを決定します。

  2. セッションIDを使用して、 sessions/ID のようなエンドポイントURIを作成します。

  3. セッションを無効にするには、 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

グループの操作

グループの作成

新しいグループを作成するには、 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

グループを別のグループの下に移動する

  1. 既存の親グループと既存の子グループのIDを検索します。

  2. 親グループのIDを使用して、 groups/PARENT_GROUP_ID/children のようなエンドポイントURIを作成します。

  3. このエンドポイントで 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 コマンドを使用します。

  1. 対象グループを、 --gname オプションで名前を指定するか、 --gpath オプションでパスをを指定する、または --gid オプションでIDを指定することにとり、そのグループの 割り当てられた レルムロールを一覧表示します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group
  2. 有効な レルムロールを一覧表示するには、 --effective オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --effective
  3. グループに追加できるレルムロールを表示するには、 --available オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --available

グループに割り当てられた、利用可能で、有効なクライアントロールの一覧表示

グループに割り当てられた、利用可能で、有効なクライアントロールを一覧表示するには、専用の get-roles コマンドを使用します。

  1. --gname オプションで名前指定するか、 --gid オプションでIDを指定することでグループを指定します。また、 --cclientid オプションでclientId属性を指定するか、 --id オプションでIDを指定することでクライアントを特定し、ユーザーの 割り当てられた クライアントロールを一覧表示します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management
  2. 有効な レルムロールを一覧表示するには、 --effective オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --effective
  3. グループに追加できるレルムロールを表示するには、 --available オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --available

アイデンティティー・プロバイダーの操作

使用可能なアイデンティティー・プロバイダー の一覧表示

使用可能なアイデンティティー・プロバイダーを一覧表示するには、 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 アイデンティティー・プロバイダーの設定

  1. 新しいアイデンティティー・プロバイダー・インスタンスを作成するときは、 providerId として keycloak-oidc を使用してください。

  2. authorizationUrltokenUrlclientIdclientSecretconfig 属性として指定します。

    例:

    $ 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 アイデンティティー・プロバイダーの設定

  1. providerId として saml を使います。

  2. singleSignOnServiceUrlnameIDPolicyFormatsignatureAlgorithmconfig 属性として指定します。

例:

$ 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アイデンティティー・プロバイダーの設定

  1. providerId として facebook を使用します。

  2. clientIdclientSecret の[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アイデンティティー・プロバイダーの設定

  1. providerId として google を使用します。

  2. clientIdclientSecretconfig 属性として指定します。これらの属性は、アプリケーションの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アイデンティティー・プロバイダーの設定

  1. providerId として twitter を使用します。

  2. clientIdclientSecretconfig 属性として指定します。これらの属性は、アプリケーションの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アイデンティティー・プロバイダーの設定

  1. providerId として github を使用します。

  2. clientIdclientSecretconfig 属性として指定します。これらの属性は、アプリケーションの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アイデンティティー・プロバイダーの設定

  1. providerId として linkedin を使用します。

  2. clientIdclientSecretconfig 属性として指定します。これらの属性は、アプリケーションの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 アイデンティティー・プロバイダーの設定

  1. providerId として microsoft を使用します。

  2. clientId and clientSecretconfig 属性として指定します。これらの属性は、アプリケーションの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

Stack Overflowアイデンティティー・プロバイダーの設定

  1. providerId として stackoverflow を使用します。

  2. clientIdclientSecretkeyconfig として提供します。これらの属性は、アプリケーションの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

ストレージ・プロバイダーの操作

Kerberosストレージ・プロバイダーの設定

  1. components エンドポイントに対して create コマンドを使用します。

  2. parentId 属性の値としてレルムIDを指定します。

  3. providerId 属性の値として kerberos を指定し、 providerType 属性の値として org.keycloak.storage.UserStorageProvider を指定します。

  4. 例:

    $ kcadm.sh create components -r demorealm -s parentId=demorealmId -s id=demokerberos -s name=demokerberos -s providerId=kerberos -s providerType=org.keycloak.storage.UserStorageProvider -s 'config.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"]' -s 'config.cachePolicy=["DEFAULT"]'

LDAPユーザー・ストレージ・プロバイダーの設定

  1. components エンドポイントに対して create コマンドを使用します。

  2. providerId 属性の値として ldap を指定し、 providerType 属性の値として org.keycloak.storage.UserStorageProvider を指定します。

  3. レルムIDを parentId 属性の値として指定します。

  4. 次の例を使用して、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"]'

ユーザー・ストレージ・プロバイダー・インスタンスの削除

  1. ストレージ・プロバイダー・インスタンスの id 属性を使用して、 components/ID のようなエンドポイントURIを作成します。

  2. このエンドポイントに対して delete コマンドを実行します。

    例:

    $ kcadm.sh delete components/3d9c572b-8f33-483f-98a6-8bb421667867 -r demorealm

特定のユーザー・ストレージ・プロバイダーのすべてのユーザーの同期をトリガーする

  1. ストレージ・プロバイダーの id 属性を使用して、 user-storage/ID_OF_USER_STORAGE_INSTANCE/sync のようなエンドポイントURIを作成します。

  2. action=triggerFullSync クエリー・パラメーターを追加し、 create コマンドを実行します。

    例:

    $ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerFullSync

特定のユーザー・ストレージ・プロバイダーに対して、変更されたユーザーの同期をトリガーする

  1. ストレージ・プロバイダーの id 属性を使用して、 user-storage/ID_OF_USER_STORAGE_INSTANCE/sync のようなエンドポイントURIを作成します。

  2. action=triggerChangedUsersSync クエリー・パラメーターを追加し、 create コマンドを実行します。

    例:

    $ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerChangedUsersSync

LDAPユーザー・ストレージの接続をテストする

  1. testLDAPConnection エンドポイントで get コマンドを実行します。

  2. bindCredentialbindDnconnectionUrluseTruststoreSpi をクエリー・パラメーターとして指定します。action クエリー・パラメーターに testConnection を設定します。

    例:

    $ kcadm.sh create testLDAPConnection -s action=testConnection -s bindCredential=secret -s bindDn=uid=admin,ou=system -s connectionUrl=ldap://localhost:10389 -s useTruststoreSpi=ldapsOnly

LDAPユーザー・ストレージ認証をテストする

  1. testLDAPConnection エンドポイントで get コマンドを実行します。

  2. bindCredentialbindDnconnectionUrluseTruststoreSpi をクエリー・パラメーターに指定します。 action クエリー・パラメーターに testAuthentication を指定します。

    例:

    $ kcadm.sh create testLDAPConnection -s action=testAuthentication -s bindCredential=secret -s bindDn=uid=admin,ou=system -s connectionUrl=ldap://localhost:10389 -s useTruststoreSpi=ldapsOnly

マッパーの追加

ハードコードされたロールLDAPマッパーの追加

  1. components エンドポイントで create コマンドを実行します。

  2. providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。

  3. parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

  4. 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マッパーの追加

  1. components エンドポイントで create コマンドを実行します。

  2. providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。

  3. parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

  4. 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マッパーの追加

  1. components エンドポイントで create コマンドを実行します。

  2. providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。

  3. parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

  4. 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マッパーの追加

  1. components エンドポイントで create コマンドを実行します。

  2. providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。

  3. parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

  4. 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マッパーの追加

  1. components エンドポイントで create コマンドを実行します。

  2. providerType 属性を org.keycloak.storage.ldap.mappers.LDAPStorageMapper に設定します。

  3. parentId 属性にLDAPプロバイダー・インスタンスのIDを設定します。

  4. 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"]'

認証の操作

パスワード・ポリシーの設定

  1. レルムの passwordPolicy 属性に、特定のポリシー・プロバイダーIDとオプション設定を含む列挙表現を設定します。

  2. 次の例を使用して、パスワード・ポリシーをデフォルト値に設定します。デフォルト値は次のとおりです。

    • 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"'
  3. デフォルトと異なる値を使用する場合は、設定を大括弧で囲みます。

  4. パスワードポリシーを次のように設定するには、以下の例を使用します。

    • 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

特定の認証フローの取得

authentication/flows/FLOW_ID エンドポイントで get コマンドを実行します。

例:

$ kcadm.sh get authentication/flows/febfd772-e1a1-42fb-b8ae-00c0566fafb8 -r demorealm

フローのエグゼキューションの一覧表示

authentication/flows/FLOW_ALIAS/executions エンドポイントで get コマンドを実行します。

例:

$ kcadm.sh get authentication/flows/Copy%20of%20browser/executions -r demorealm

エグゼキューションに対する設定の追加

  1. フローのエグゼキューションを取得し、そのIDを記録します。

  2. authentication/executions/{executionId}/config エンドポイントで create コマンドを実行します。

例:

$ kcadm create "authentication/executions/a3147129-c402-4760-86d9-3f2345e401c7/config" -r examplerealm -b '{"config":{"x509-cert-auth.mapping-source-selection":"Match SubjectDN using regular expression","x509-cert-auth.regular-expression":"(.*?)(?:$)","x509-cert-auth.mapper-selection":"Custom Attribute Mapper","x509-cert-auth.mapper-selection.user-attribute-name":"usercertificate","x509-cert-auth.crl-checking-enabled":"","x509-cert-auth.crldp-checking-enabled":false,"x509-cert-auth.crl-relative-path":"crl.pem","x509-cert-auth.ocsp-checking-enabled":"","x509-cert-auth.ocsp-responder-uri":"","x509-cert-auth.keyusage":"","x509-cert-auth.extendedkeyusage":"","x509-cert-auth.confirmation-page-disallowed":""},"alias":"my_otp_config"}'

エグゼキューションの設定の取得

  1. フローのエグゼキューションを取得し、設定IDを含む authenticationConfig 属性を取得します。

  2. authentication/config/ID エンドポイントで get コマンドを実行します。

例:

$ kcadm get "authentication/config/dd91611a-d25c-421a-87e2-227c18421833" -r examplerealm

エグゼキューションの設定の更新

  1. フローのエグゼキューションを取得し、設定IDを含む authenticationConfig 属性を取得します。

  2. authentication/config/ID エンドポイントで update コマンドを実行します。

例:

$ kcadm update "authentication/config/dd91611a-d25c-421a-87e2-227c18421833" -r examplerealm -b '{"id":"dd91611a-d25c-421a-87e2-227c18421833","alias":"my_otp_config","config":{"x509-cert-auth.extendedkeyusage":"","x509-cert-auth.mapper-selection.user-attribute-name":"usercertificate","x509-cert-auth.ocsp-responder-uri":"","x509-cert-auth.regular-expression":"(.*?)(?:$)","x509-cert-auth.crl-checking-enabled":"true","x509-cert-auth.confirmation-page-disallowed":"","x509-cert-auth.keyusage":"","x509-cert-auth.mapper-selection":"Custom Attribute Mapper","x509-cert-auth.crl-relative-path":"crl.pem","x509-cert-auth.crldp-checking-enabled":"false","x509-cert-auth.mapping-source-selection":"Match SubjectDN using regular expression","x509-cert-auth.ocsp-checking-enabled":""}}'

エグゼキューションの設定の削除

  1. フローのエグゼキューションを取得し、設定IDを含む authenticationConfig 属性を取得します。

  2. authentication/config/ID エンドポイントで delete コマンドを実行します。

例:

$ kcadm delete "authentication/config/dd91611a-d25c-421a-87e2-227c18421833" -r examplerealm