Keycloakの機能と概念

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

機能

Keycloakは次の機能を提供します。

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

  • 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、Tomcat、Jetty、Springなどのクライアント・アダプター。

  • OpenID Connectのリライング・パーティー・ライブラリー、もしくは、SAML 2.0のサービス・プロバイダー・ライブラリーをもつ、あらゆるプラットフォーム/言語のサポート。

基本的なKeycloakの操作

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

コアコンセプトと用語

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

ユーザー

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

認証

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

認可

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

クレデンシャル

クレデンシャルは、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テンプレートとスタイルシートを定義します。

最初の管理者の作成

Keycloakをインストールした後、Keycloakを管理するための完全なパーミッションを持つ super 管理者として動作する管理者アカウントが必要です。このアカウントでは、Keycloakの管理コンソールにログインできます。管理者コンソールにログインして、レルムやユーザーを作成したり、Keycloakで保護されたアプリケーションを登録したりすることができます。

ローカルホストでのアカウント作成

サーバーが localhost からアクセスできる場合は、以下の手順を実行してください。

手順
  1. Webブラウザーで、http://localhost:8080 URLにアクセスします。

  2. 思い出せるユーザー名とパスワードを入力してください。

    ウェルカムページ

    Welcome page

リモートでのアカウント作成

localhost アドレスからサーバーにアクセスできない場合や、コマンドラインからKeycloakを起動したい場合は、初期管理者アカウントを作成するために環境変数 KEYCLOAK_ADMINKEYCLOAK_ADMIN_PASSWORD を使用してください。

例:

export KEYCLOAK_ADMIN=<username>
export KEYCLOAK_ADMIN_PASSWORD=<password>

bin/kc.[sh|bat] start

レルムの設定

管理コンソール用に管理者アカウントを作成すると、レルムを設定することができます。レルムとは、ユーザー、アプリケーション、ロール、グループなどのオブジェクトを管理するための空間です。ユーザーはレルムに所属し、ログインします。1 つのKeycloakのデプロイメントで、データベースの空き容量と同じ数のレルムを定義、保存、管理できます。

管理コンソールの使用

レルムを設定し、ほとんどの管理作業はKeycloakの管理コンソールで行います。

前提条件
手順
  1. 管理コンソールのURLにアクセスします。

    たとえば、ローカルホストの場合、http://localhost:8080/admin/のURLを使用します。

    ログインページ

    Login page

  2. ウェルカムページで作成したユーザー名とパスワード、またはbinディレクトリーにある add-user-keycloak スクリプトを入力します。このアクションは、管理コンソールを表示します。

    管理コンソール

    Admin Console

  3. 使えるメニューや他のオプションをメモします。

    • Master と書かれたメニューをクリックして、管理したいレルムを選択するか、新しいレルムを作成します。

    • 右上のリストをクリックすると、自分のアカウントを確認したり、ログアウトしたりできます。

    • クエスチョン・マーク ? のアイコンにカーソルを合わせると、そのフィールドを説明するツールチップ・テキストが表示されます。上の画像は、ツールチップの動作を示しています。

    • クエスチョン・マーク ? のアイコンをクリックすると、そのフィールドを説明するツールチップ・テキストが表示されます。上の画像は、ツールチップの動作を示しています。

masterレルム

管理コンソールには、2種類のレルムが存在します。

  • Master realm - このレルムはKeycloakを最初に起動したときに作成されたものです。最初のログイン時に作成した管理者アカウントが含まれています。 master レルムは、システム内のレルムの作成と管理にのみ使用してください。

  • Other realms - これらのレルムは、masterレルムの管理者によって作成されます。これらのレルムでは、管理者は組織内のユーザーと、そのユーザーが必要とするアプリケーションを管理します。アプリケーションはユーザーによって所有されます。

レルムとアプリケーション

Realms and applications

レルムは互いに隔離されており、自分が管理しているユーザーのみを管理、認証することができます。このセキュリティー・モデルに従うことで、誤った変更を防ぐことができます。また、ユーザー・アカウントには、現在のタスクを正常に完了するために必要な特権と権限のみへのアクセスを許可するという伝統に従っています。

追加のリソース
  • master レルムを無効にして、新しく作成するレルムに管理者アカウントを定義したい場合は、Dedicated Realm Admin Consolesを参照してください。各レルムには専用の管理コンソールがあり、ローカル・アカウントでログインすることができます。

レルムの作成

レルムを作成することで、ユーザーを作成し、アプリケーションを使用するためのパーミッションを与えることができる管理空間を提供することができます。最初のログインでは、通常 master レルム(他のレルムを作成する際の最上位レルム)に入ります。

どのようなレルムが必要かを決定するには、ユーザーとアプリケーションをどのように分離したいかを検討します。たとえば、会社の従業員用のレルムと、顧客用の別のレルムを作成するとします。 従業員は従業員用のレルムにログインし、社内のアプリケーションにのみアクセスできるようにします。顧客は顧客用レルムにログインし、顧客向けアプリケーションにのみアクセスできるようにします。

手順
  1. 左ペインの上部をマウスオーバーします。

  2. Create Realm をクリックします。

    レルムメニューの追加

    Add realm menu

  3. レルムの名前を入力します。

  4. Create をクリックします。

    レルムを作成する

    Create realm

    現在のレルムは、先ほど作成したレルムに設定されています。メニューのレルム名をクリックすることで、レルムを切り替えることができます。

レルムにSSLを設定する

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

手順
  1. メニューの Realm settings をクリックします。

  2. General タブをクリックします。

    Generalタブ

    General Tab

  3. 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を必要としません。この選択は、開発時に実験的に使用し、このデプロイメントのサポートを予定していない場合にのみ適用されます。

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

レルムに電子メールを設定する

Keycloakは、ユーザーが電子メールアドレスを確認するとき、パスワードを忘れたとき、あるいは管理者がサーバーイベントに関する通知を受け取る必要があるときに、電子メールを送信します。Keycloakが電子メールを送信できるようにするには、KeycloakにSMTPサーバーの設定を提供します。

手順
  1. メニューの Realm settings をクリックします。

  2. Email タブをクリックします。

    Emailタブ

    Email Tab

  3. 必要に応じてフィールドに入力し、スイッチを切り替えてください。

テンプレート
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 displayname では、ユーザー・フレンドリーなメールアドレスのエイリアスを設定することができます(オプション)。設定されていない場合は、通常の Reply To のメールアドレスが表示されます。

Envelope from

Envelope from は、送信されるメールの Return-Path SMTPヘッダーに使用される Bounce Address を示します(オプション)。

コネクションと認証
ホスト

Host は、電子メール送信時に使用するSMTPサーバーのホスト名を示します。

Port

Port はSMTPサーバーのポートを示します。

Encryption

特にSMTPサーバーが外部ネットワーク上にある場合は、これらのチェックボックスのいずれかにチェックを入れて、ユーザー名とパスワードを回復するための電子メールの送信をサポートします。ほとんどの場合、 Port をSSL/TLSのデフォルトポートである465に変更する必要があります。

認証

SMTPサーバーで認証が必要な場合は、このスイッチを ON に設定してください。プロンプトが表示されたら、 UsernamePassword を入力してください。 Password フィールドの値は、外部のボールトからの値を参照することができます。

Configuring themes

あるレルムに対して、Keycloakでは、テーマを使うことで、あらゆるUIの見た目を変更することができます。

手順
  1. メニューの Realm setting をクリックします。

  2. Themes タブをクリックします。

    Themesタブ

    Themes tab

  3. UIカテゴリーごとに必要なテーマを選び、 Save をクリックします。

    Login theme

    ユーザー名・パスワード入力、OTP入力、新規ユーザー登録、その他ログインに関連する画面。

    Account theme

    各ユーザーのアカウント管理UI

    Admin console theme

    Keycloak管理コンソールのスキン。

    Email theme

    Keycloakが電子メールを送信する場合に、このテーマで定義されたテンプレートを使用して電子メールを作成します。

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

国際化の有効化

Keycloakでは、すべてのUI画面が国際化されます。デフォルトの言語は英語ですが、どのロケールに対応するか、またどれをデフォルトのロケールにするかを選択できます。

手順
  1. メニューの Realm Settings をクリックします。

  2. Localization タブをクリックします。

  3. Internationalization の有効化

  4. 対応する言語を選択します。

    Localizationタブ

    Localization tab

    次回ログイン時に、ログイン画面、アカウントコンソール、管理コンソールで使用する言語を選択できます。

追加のリソース
  • Server Developer Guide では、追加の言語を提供する方法について説明しています。テーマによって提供されるすべての国際化テキストは、Localization タブでレルム固有のテキストに上書きすることができます。

ユーザーロケールの選択

ロケール・セレクター・プロバイダーは、入手した情報から最適なロケールを提案します。しかし、ユーザーが誰であるかは不明なことが多いため、以前に認証されたユーザーのロケールを永続化されたCookieに記憶させます。

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

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

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

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

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

  • Accepted language - Accept-Language ヘッダーから取得したロケール

  • レルムのデフォルト

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

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

ロケールを選択するためのロジックを変更する場合は、カスタムの LocaleSelectorProvider を作成するオプションがあります。詳細については、 Server Developer Guide を参照してください。

ログイン・オプションの制御

Keycloakには、いくつかのログインページ機能が組み込まれています。

パスワード忘れを有効にする

Forgot password を有効にすると、ユーザーがパスワードを忘れたり、OTPジェネレーターを紛失した場合に、ログイン・クレデンシャルをリセットすることができます。

手順
  1. メニューの Realm settings をクリックします。

  2. Login タブをクリックします。

    ログインタブ

    Login Tab

  3. Forgot passwordON に切り替えてください。

    ログインページにこれらのチェックボックスのいずれかにチェックを入れます。というリンクが表示されます。

    パスワード忘れリンク

    Forgot Password Link

  4. このリンクをクリックすると、ユーザーはユーザー名またはメールアドレスを入力し、クレデンシャルをリセットするためのリンクが記載されたメールを受け取ることができます。

    パスワード忘れページ

    Forgot Password Page

電子メールで送信されるテキストは設定可能です。詳しくはServer Developer Guideを参照してください。

ユーザーがメールのリンクをクリックすると、Keycloakのパスワードを更新するように求められ、OTPジェネレーターを設定している場合は、KeycloakのOTPジェネレーターを再設定するように求められます。 組織のセキュリティー要件によっては、ユーザーに電子メールでOTPジェネレーターをリセットさせたくない場合もあります。

この動作を変更するには、以下の手順を実行します。

手順
  1. メニューの Authentication をクリックします。

  2. Flows タブをクリックします。

  3. Reset Credentials フローを選択します。

    リセット・クレデンシャル・フロー

    Reset Credentials Flow

    OTPをリセットしたくない場合は、 Reset OTP のRequirementを Disabled に設定してください。

  4. メニューの Authentication をクリックします。

  5. Required actions タブをクリックします。

  6. Update Password が有効になっていることを確認します。

    必須アクション

    Required Actions

Remember Meの有効化

ログインしたユーザーがブラウザーを閉じると、セッションが破棄され、再度ログインする必要があります。Keycloakを設定すると、ログイン時に Remember Me のチェックボックスをクリックした場合に、ユーザーのログインセッションを維持することができます。このアクションは、ログインCookieをセッションのみのCookieから永続的なCookieに変えます。

手順
  1. メニューの Realm settings をクリックします。

  2. Login タブをクリックします。

  3. Remember Me スイッチを On にする。

    ログインタブ

    Login Tab Remember Me

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

    Remember Me

    Remember Me

ACRとLevel of Authentication(LoA)のマッピング

レルムのログイン設定では、どの Authentication Context Class Reference (ACR) 値をどの Level of Authentication (LoA) に対応させるかを定義することができます。ACRはどのような値でも良いが、LoAは数値である必要がある。ACRクレームは、OIDCリクエストで送られる claims または acr_values パラメーターで要求でき、アクセストークンとIDトークンにも含まれる。マッピングされた番号は、認証フローの条件で使用されます。

特定のクライアントがレルムと異なる値を使用する必要がある場合、クライアントレベルでマッピングを指定することも可能です。しかし、ベスト・プラクティスはレルムのマッピングに固執することです。

ACR to LoA mapping

詳細については、ステップアップ認証および オフィシャルのOIDC仕様を参照してください。

電子メールのワークフローの更新 (UpdateEmail)

このワークフローでは、ユーザーは自分のメールアドレスを変更するためにUPDATE_EMAILアクションを使用する必要があります。

このアクションは、単一の電子メール入力フォームに関連付けられます。レルムが電子メール検証を無効にしている場合、このアクションは検証なしで電子メールを更新することを許可します。もしレルムがメール検証を有効にしている場合は、 このアクションはアカウントのメールを変更せずに、 新しいメールアドレスにメール更新用のアクショントークンを送信します。アクショントークンが起動した時点で、メールの更新が完了します。

アプリケーションは、UPDATE_EMAILをAIA(Application Initiated Action)として活用することで、ユーザーをメール更新フォームに送ることができます。

Update Email Workflowのサポートは開発中であることにご注意ください。この機能は実験的に使用してください。

この機能を有効にし、以前のバージョンから移行する場合は、レルムで Update Email の必須アクションを有効にしてください。そうでない場合、ユーザーはメールアドレスを更新することができません。

レルム鍵の設定

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

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

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

手順
  1. メニューの Realm settings をクリックします。

  2. Keys をクリックします。

  3. フィルター・ドロップダウンから Passive keys を選択すると、パッシブキーが表示されます。

  4. フィルター・ドロップダウンから Disabled keys を選択すると、無効なキーが表示されます。

鍵ペアのステータスが Active であっても、そのレルムで現在アクティブな鍵ペアとして選択されないことがあります。署名に使用されるアクティブな鍵ペアは、アクティブな鍵ペアを提供できる、 優先順位の高い最初の鍵プロバイダーに基づき選択されます。

鍵のローテーション

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

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

古い鍵を削除する頻度は、セキュリティーとすべてのCookieとトークンの更新を確認することとのトレードオフになります。新しい鍵は3〜6カ月ごとに作成し、古い鍵は新しい鍵を作成してから1〜2カ月後に削除することを検討してください。新しい鍵が追加されてから古い鍵が削除されるまでの間にユーザーが活動していなかった場合、そのユーザーは再認証を行う必要があります。

鍵のローテーションは、オフライントークンにも適用されます。確実に更新されるように、アプリケーションは古い鍵が削除される前にトークンをリフレッシュする必要があります。

鍵ペアの追加

手順
  1. 管理コンソールでレルムを選択します。

  2. メニューの Realm settings をクリックします。

  3. Keys タブをクリックします。

  4. Providers タブをクリックします。

  5. Add provider をクリックし、 rsa-generated を選択します。

  6. Priority の欄に数字を入力します。この番号によって、新しい鍵ペアがアクティブな鍵ペアになるかどうかが決まります。

  7. AES Key size の値を選択します。

  8. Save をクリックします。

この操作により、自己署名入り証明書を含む新しいキーペアが生成されます。

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

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

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

前提条件
  • 秘密鍵のファイルです。PEM形式のファイルである必要があります。

手順
  1. 管理コンソールでレルムを選択します。

  2. Realm settings をクリックします。

  3. Keys タブをクリックします。

  4. Providers タブをクリックします。

  5. Add provider をクリックし、 rsa を選択します。

  6. Priority の欄に数字を入力します。この番号によって、新しい鍵ペアがアクティブな鍵ペアになるかどうかが決まります。

  7. Private RSA Key の横にある Browse…​ をクリックし、秘密鍵ファイルをアップロードします。

  8. 秘密鍵の署名付き証明書がある場合は、 X509 Certificate の横にある Browse…​ をクリックして、証明書ファイルをアップロードしてください。証明書をアップロードしない場合、Keycloakは自動的に自己署名証明書を生成します。

  9. Save をクリックします。

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

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

関連する証明書チェーンを読み込むためには、キーペアを読み込むために使用したのと同じ Key Alias を使って、JavaのKeystoreファイルにインポートする必要があります。

手順
  1. 管理コンソールでレルムを選択します。

  2. メニューの Realm settings をクリックします。

  3. Keys タブをクリックします。

  4. Providers タブをクリックします。

  5. Add provider をクリックし、 java-keystore を選択します。

  6. Priority の欄に数字を入力します。この番号によって、新しい鍵ペアがアクティブな鍵ペアになるかどうかが決まります。

  7. Keystore に値を入力します。

  8. Keystore Password に値を入力します。

  9. Key Alias に値を入力します。

  10. Key Password に値を入力します。

  11. Save をクリックします。

鍵をパッシブにする

手順
  1. 管理コンソールでレルムを選択します。

  2. メニューの Realm settings をクリックします。

  3. Keys タブをクリックします。

  4. Providers タブをクリックします。

  5. パッシブ化したい鍵のプロバイダーをクリックします。

  6. ActiveOff に切り替えます。

  7. Save をクリックします。

鍵の無効化

手順
  1. 管理コンソールでレルムを選択します。

  2. メニューの Realm settings をクリックします。

  3. Keys タブをクリックします。

  4. Providers タブをクリックします。

  5. パッシブ化したい鍵のプロバイダーをクリックします。

  6. EnabledOff に切り替えます。

  7. Save をクリックします。

鍵の漏洩

Keycloakは、署名鍵をローカルにのみ保存し、クライアント・アプリケーションやユーザーまたは他のエンティティーと共有することはありません。しかし、レルムの署名鍵が漏洩したと思われる場合は、まず上記のように新しい鍵ペアを生成し、漏洩した鍵ペアを直ちに削除する必要があります。

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

手順
  1. メニューの Clients をクリックします。

  2. security-admin-console をクリックします。

  3. Capability config のセクションまでスクロールダウンしてください。

  4. Admin URL フィールドに入力します。

  5. Advanced タブをクリックします。

  6. Revocation のセクションで Set to now をクリックします。

  7. Push クリックします。

not-beforeポリシーをプッシュすることで、クライアント・アプリケーションは、漏洩した鍵によって署名された既存のトークンを受け入れないようにすることができます。クライアント・アプリケーションは、Keycloakから新しいキーペアをダウンロードすることを強制されるので、漏洩した鍵によって署名されたトークンは無効となります。

RESTとコンフィデンシャル・クライアントは、Keycloakがプッシュされたnot-beforeポリシー・リクエストをクライアントに送信できるように、 Admin URL を設定する必要があります。

外部ストレージの使用

組織は、情報、パスワード、およびその他のクレデンシャルを含むデータベースを持つことができます。通常、既存のデータストレージをKeycloakの配備に移行することはできないため、Keycloakでは既存の外部ユーザー・データベースを連携させることができます。KeycloakはLDAPとActive Directoryをサポートしていますが、Keycloakのユーザー・ストレージSPIを使用して任意のカスタム・ユーザー・データベース用の拡張機能をコード化することもできます。

ユーザーがログインしようとすると、Keycloakはそのユーザーのストレージを調べて、そのユーザーを見つけます。Keycloakがユーザーを見つけられなかった場合、Keycloakは一致するユーザーが見つかるまで、レルムの各ユーザー・ストレージのプロバイダーを繰り返し検索します。外部データストレージからのデータは、Keycloakのランタイムが消費する標準的なユーザーモデルにマップされます。このユーザーモデルは、OIDCのトークンクレームとSAMLのアサーション属性にマッピングされます。

外部のユーザー・データベースがKeycloakの全機能をサポートするために必要なデータを持っていることは稀なので、ユーザー・ストレージ・プロバイダーはKeycloakのローカルのユーザー・データ・ストレージにアイテムを保存することを選択することができます。プロバイダーは、ローカルにユーザーをインポートし、外部データストレージと定期的に同期することができます。この方法は、プロバイダーの機能とプロバイダーの設定に依存します。たとえば、外部のユーザー・データ・ストレージがOTPをサポートしていない場合があります。プロバイダーによっては、OTPをKeycloakで処理し、保存することができます。

プロバイダーの追加

ストレージ・プロバイダーを追加するには、次の手順を実行します。

手順
  1. メニューの User Federation をクリックします。

    ユーザー・フェデレーション

    User federation

  2. 表示されているカードから、プロバイダー・タイプのカードを選択します。

    Keycloakで、そのプロバイダーの設定ページに移動します。

プロバイダー障害への対応

ユーザー・ストレージ・プロバイダーに障害が発生すると、管理コンソールにログインしてユーザーを表示できなくなる場合があります。Keycloakは、ストレージ・プロバイダーを使用してユーザーを検索するときに失敗を検出しないため、呼び出しをキャンセルします。優先度の高いストレージ・プロバイダーがユーザー検索中に失敗すると、ログインまたはユーザークエリーが例外的に失敗し、次に設定されたプロバイダーにフェイルオーバーされなくなります。

Keycloakは、LDAPやカスタムのユーザー・ストレージ・プロバイダーよりも先に、ローカルのKeycloakユーザー・データベースを検索して、ユーザーを解決します。LDAP やバックエンドへの接続に問題がある場合に備えて、ローカルのKeycloakユーザー・データベースに保存される管理者アカウントの作成を検討してください。

LDAPとカスタムのそれぞれのユーザー・ストレージ・プロバイダーには、管理コンソール画面で enable のトグルがあります。ユーザー・ストレージ・プロバイダーを無効にすると、クエリーを実行するときにプロバイダーをスキップするので、より低い優先度で別のプロバイダーにあるユーザー・アカウントを表示したりログインしたりすることができます。プロバイダーが import 戦略を使用していて無効化されている場合、インポートされたユーザーは読み取り専用モードで検索可能です。

ストレージ・プロバイダーの検索に失敗した場合、Keycloakはフェイルオーバーしません。なぜなら、ユーザー・データベースには、ユーザー名や電子メールが重複していることが多いからです。ユーザー名や電子メールの重複は、管理者が別のデータストアから読み込むことを想定しているのに、ユーザがある外部データストアから読み込むために問題を引き起こす可能性があります。

LDAP(Lightweight Directory Access Protocol)とActive Directory

Keycloakには、LDAP/ADプロバイダーが含まれています。複数の異なるLDAPサーバーを1つのKeycloakのレルムで連携させ、LDAPのユーザー属性をKeycloak共通ユーザーモデルにマッピングすることが可能です。

デフォルトでは、Keycloakはユーザー・アカウントのユーザー名、電子メール、名、姓をマップしますが、追加のマッピングを設定することもできます。KeycloakのLDAP/ADプロバイダーは、LDAP/ADプロトコルと保存、編集、同期モードを使用してパスワード検証をサポートしています。

連携したLDAPストレージの設定

手順
  1. メニューの User Federation をクリックします。

    ユーザー・フェデレーション

    User federation

  2. Add LDAP providers をクリックします。

    KeycloakのLDAPの設定画面に遷移します。

ストレージモード

Keycloakは、LDAP からローカルのKeycloakユーザー・データベースにユーザーをインポートします。このユーザー・データベースのコピーは、オンデマンドまたは定期的なバックグラウンド・タスクによって同期されます。パスワードの同期については例外が存在します。Keycloakは決してパスワードをインポートしません。パスワードの検証は常にLDAPサーバー上で行われます。

同期の利点は、ユーザーごとに必要な追加のデータがローカルに保存されるため、すべてのKeycloakの機能が効率的に動作することです。欠点は、Keycloakが特定のユーザーに初めて問い合わせるたびに、Keycloakが対応するデータベースの挿入を実行することです。

インポートをLDAPサーバーと同期させることができます。LDAPマッパーが常にデータベースではなくLDAPから特定の属性を読み取る場合、インポートの同期は不要です。

Keycloakのユーザー・データベースにユーザーをインポートすることなく、KeycloakでLDAPを使用することができます。LDAP サーバーは、Keycloakのランタイムが使用する共通ユーザーモデルをバックアップします。あるKeycloakの機能が必要とするデータをLDAPがサポートしていない場合、その機能は動作しません。この方法の利点は、LDAPユーザーのコピーをKeycloakユーザー・データベースにインポートして同期させるというリソース利用がないことです。

LDAP設定ページの Import Users スイッチは、このストレージモードを制御します。ユーザーをインポートするには、このスイッチを ON に切り替えます。

Import Users を無効にすると、ユーザー・プロフィールの属性を Keycloakのデータベースに保存することができなくなります。また、LDAPにマッピングされたユーザー・プロフィール・メタデータ以外のメタデータを保存することもできま せん。このメタデータには、ロールマッピング、グループマッピング、およびLDAPマッパーの設定に基づくその他のメタデータを含めることができます。

LDAPにマッピングされていないユーザーデータを変更しようとすると、ユーザーの更新ができなくなります。たとえば、ユーザーの enabled フラグがLDAP属性にマップされていない限り、LDAPにマップされたユーザーを無効にすることはできません。

編集モード

ユーザのメタデータは、ユーザーはアカウント・コンソールから、管理者は管理コンソールから修正することができます。LDAP設定ページの Edit Mode の設定は、ユーザーのLDAP更新権限を定義します。

READONLY

ユーザー名、電子メール、姓、名、その他のマッピングされた属性は変更できません。ユーザーがこれらのフィールドを更新しようとすると、いつでも Keycloak エラーが表示されます。パスワードの更新はサポートされていません。

WRITABLE

ユーザー名、電子メール、姓、名などのマッピングされた属性やパスワードを変更し、LDAPストアと自動的に同期させることはできます。

UNSYNCED

Keycloakは、ユーザー名、電子メール、名、姓、パスワードの変更を Keycloakのローカル・ストレージに保存するため、管理者はこのデータをLDAPに同期して戻さなければなりません。このモードでは、Keycloakが読み取り専用のLDAPサーバー上のユーザー・メタデータを更新することができます。このオプションは、LDAPからローカルのKeycloakのユーザー・データベースにユーザーをインポートする場合にも適用されます。

KeycloakがLDAPプロバイダーを作成するとき、Keycloakは初期LDAPマッパーのセットも作成します。Keycloak は、 VendorEdit Mode 、および Import Users スイッチの組み合わせに基づいて、これらのマッパーを構成します。たとえば、編集モードがUNSYNCEDの場合、Keycloakは、特定のユーザー属性をLDAPサーバーからではなく、データベースから読み取るようにマッパーを構成します。しかし、後で編集モードを変更した場合、UNSYNCEDモードでは設定の変更を検出することができないため、マッパーの設定は変更されません。LDAPプロバイダー作成時に Edit Mode を決定してください。この注意事項は、 Import Users スイッチにも適用されます。

その他の設定オプション

Console Display Name

管理コンソールに表示するプロバイダー名です。

Priority

ユーザーを検索するとき、またはユーザーを追加するときのプロバイダーの優先順位です。

Sync Registrations

Keycloakで作成した新規ユーザーをLDAPに追加したい場合は、このスイッチを ON に切り替えてください。

Allow Kerberos authentication

LDAPからプロビジョニングされたユーザーデータでレルム内のKerberos/SPNEGO認証を有効にします。詳細については、Kerberosのセクションを参照してください。

その他のオプション

管理コンソールのツールチップにマウスポインターを合わせると、これらのオプションの詳細が表示されます。

SSLでLDAPに接続する

LDAPストアへのセキュアな接続URL (例: ldaps://myhost.com:636 ) を設定すると、KeycloakはLDAPサーバーとの通信にSSLを使用します。KeycloakがLDAPへのSSL接続を信頼できるように、Keycloakサーバー側でトラストストアを設定します。

Truststore SPIを使用してKeycloakのグローバル・トラストストアを設定します。グローバル・トラストストアの設定の詳細については、[トラストストアの設定](https://www.keycloak.org/server/keycloak-truststore) ガイドを参照してください。これは、 javax.net.ssl.trustStore システム・プロパティーが提供するファイル、またはシステム・プロパティーが未設定の場合はJDKのcacertsファイルである場合があります。

LDAPフェデレーション・プロバイダーの設定にある Use Truststore SPI の設定プロパティーは、トラストストアのSPIを制御します。デフォルトでは、Keycloakはこのプロパティーを Only for ldaps に設定しており、ほとんどの配備で適切な値になっています。Keycloakは、LDAPへの接続URLが ldaps のみで始まっている場合、Truststore SPI を使用します。

LDAPユーザーをKeycloakに同期させる。

ImportUsers オプションを設定すると、LDAPプロバイダーはLDAPユーザーのKeycloakローカル・データベースへのインポートを処理するようになります。ユーザーが初めてログインするとき、LDAPプロバイダーはLDAPユーザーをKeycloakデータベースにインポートし、LDAPパスワードを検証します。Keycloakがユーザーをインポートするのは、この初回ログイン時のみです。管理コンソールの Users メニューをクリックし、 View all users ボタンをクリックすると、Keycloakによって少なくとも一度は認証されたLDAPユーザーだけが表示されます。Keycloakはこの方法でユーザーをインポートするため、この操作によってLDAPユーザーデータベース全体のインポートが開始されることはありません。

すべてのLDAPユーザーをKeycloakデータベースに同期させたい場合は、LDAPプロバイダーの設定ページで Sync Settings を設定し、有効にしてください。

同期には次の2つのタイプが存在します。

定期的な完全同期

このタイプは、すべてのLDAPユーザーをKeycloak データベースに同期させます。すでにKeycloakにあるLDAPユーザーのうち、LDAPと異なるユーザーは、Keycloakのデータベースに直接更新されます。

定期的な変更ユーザーの同期

同期時にKeycloakが作成または更新するのは、前回の同期以降に作成または更新されたユーザーだけです。

LDAPプロバイダーを最初に作成する際に、 Synchronize all users をクリックし、変更されたユーザーを定期的に同期させるように設定するのが最も良い方法です。

LDAPマッパー

LDAPマッパーはLDAPプロバイダーによって起動される listeners です。LDAPマッパーはLDAP統合のためのもう一つの拡張ポイントを提供します。LDAPマッパーは以下のような場合に起動されます。

  • ユーザーはLDAPを利用してログインします。

  • ユーザーの初期登録。

  • 管理コンソールがユーザーに問い合わせをします。

LDAPフェデレーションプロバイダーを作成すると、Keycloakは自動的にこのプロバイダー用の mappers セットを提供します。このセットはユーザーが変更可能であり、ユーザーはマッパーを開発したり、既存のマッパーを更新・削除したりすることができます。

User Attribute Mapper

このマッパーは、どのLDAP属性をKeycloakのユーザー属性にマッピングするかを指定します。たとえば、mail というLDAP属性をKeycloakデータベースの email 属性に設定することができます。このマッパーの実装では、常に一対一のマッピングが存在します。

フルネーム・マッパー

このマッパーはユーザーのフルネームを指定します。Keycloakはその名前をLDAP属性 (通常は cn ) に保存し、その名前をKeycloakのデータベース内の firstNamelastname 属性にマップします。ユーザーのフルネームを cn に格納することは、LDAP の配備では一般的なことです。

Keycloakで新規ユーザーを登録する際、LDAPプロバイダーの Sync Registrations がオンになっていると、 fullName マッパーはユーザー名へのフォールバックを許可します。このフォールバックはMicrosoft Active Directory (MSAD)を使用するときに便利です。MSADの一般的な設定は、cn LDAP属性をfullNameとして設定し、同時にLDAPプロバイダーの設定で cn LDAP属性を RDN LDAP Attribute として使用することです。この設定では、Keycloakはユーザー名にフォールバックします。たとえば、Keycloakでユーザー"john123"を作成し、firstNameとlastNameを空にした場合、フルネームマッパーはLDAPの cn の値として"john123"を保存します。後でfirstNameとlastNameに"John Doe"を入力すると、ユーザ名にフォールバックする必要がないため、フルネームマッパーはLDAPの cn を "John Doe" の値に更新します。

Hardcoded Attribute Mapper

このマッパーはLDAPとリンクしている各Keycloakユーザーにハードコードされた属性値を追加します。このマッパーは enabledemailVerified というユーザー・プロパティーに値を強制することもできます。

ロールマッパー

このマッパーは、LDAPから取得したロールマッピングをKeycloakのロールマッピングに設定します。1つのロールマッパーで、LDAPロール(通常はLDAPツリーの特定のブランチのグループ)を、指定されたクライアントのレルムロールまたはクライアントロールに対応するロールにマッピングすることができます。同じLDAPプロバイダーに対して、より多くのロールマッパーを設定することができます。たとえば、 ou=main,dc=example,dc=org のグループからのロールマッピングはレルムロールマッピングにマッピングし、 ou=finance,dc=example,dc=org のグループからのロールマッピングはクライアント finance のクライアント・ロールマッピングにマッピングすると指定することができます。

ハードコードされたロールマッパー

このマッパーは、LDAPプロバイダーからの各Keycloakユーザーに対して、指定されたKeycloakロールを付与します。

グループマッパー

このマッパーは、LDAPツリーのブランチからKeycloak内のグループにLDAPグループをマッピングします。このマッパーはまた、LDAP からのユーザー・グループ・マッピングを Keycloak 内のユーザー・グループ・マッピングに伝搬させます。

MSADユーザー・アカウント・マッパー

このマッパーは Microsoft Active Directory (MSAD)に特化したものです。MSADのユーザー・アカウントの状態を、有効なアカウントや期限切れのパスワードのようなKeycloakのアカウントの状態に統合することができます。このマッパーは userAccountControlpwdLastSet というLDAP属性を使用しますが、これはMSADに特有の属性で、LDAPの標準的なものではありません。たとえば、pwdLastSet の値が 0 の場合、Keycloakのユーザーはパスワードを更新する必要があります。その結果、UPDATE_PASSWORD必須アクションがそのユーザーに追加されます。 userAccountControl の値が 514 (アカウント無効)の場合、Keycloakのユーザーはアカウント無効となります。

Certificate Mapper

このマッパーはX.509の証明書をマッピングします。KeycloakはX.509認証と Full certificate in PEM format と組み合わせてアイデンティティー・ソースとして使用します。このマッパーは User Attribute Mapper と同様の動作をしますが、KeycloakはPEMまたはDER形式の証明書を格納したLDAP属性をフィルタリングすることができます。このマッパーでは Always Read Value From LDAP を有効にしてください。

ユーザー属性マッパー。ユーザー名、名、姓、電子メールなどの基本的な Keycloakのユーザー属性を、対応するLDAP属性にマッピングします。これらを拡張して、独自の属性マッピングを追加することができます。管理コンソールは、対応するマッパーの設定を支援するツールチップを提供します。

パスワードハッシュ

Keycloakがパスワードを更新するとき、Keycloakはパスワードをプレーンテキスト形式で送信します。この動作は、組み込みのKeycloakデータベースでパスワードを更新する場合、Keycloakがパスワードをデータベースに送信する前にハッシュとソルトを行う場合とは異なります。LDAPの場合、KeycloakはLDAPサーバに依存して、パスワードをハッシュし、ソルトします。

デフォルトでは、MSAD、RHDS、FreeIPAなどのLDAPサーバーは、パスワードをハッシュおよびソルトします。OpenLDAPやApacheDSなどの他のLDAPサーバーは、 RFC3062 で説明されている LDAPv3 Password Modify Extended Operation を使用しない限り、パスワードをプレーンテキストで保存します。LDAP設定ページでLDAPv3 Password Modify Extended Operationを有効にしてください。詳細は、LDAPサーバーのドキュメントを参照してください。

ldapsearch を使用して変更されたディレクトリー・エントリーを検査し、userPassword 属性値をbase64デコードすることにより、ユーザーパスワードが適切にハッシュ化され、プレーンテキストとして保存されていないことを常に確認してください。

トラブルシューティング

カテゴリー org.keycloak.storage.ldap のログレベルをTRACEに上げると便利です。この設定では、LDAPサーバーへのすべてのクエリーのログと、クエリーの送信に使用されたパラメーターを含む、多くのログメッセージが TRACE レベルでサーバー・ログファイルに送信されます。ユーザー・フォーラムまたはJIRAでLDAPの質問を作成する場合は、TRACEログを有効にしてサーバーログを添付することを検討してください。大きすぎる場合は、問題が発生する操作の際にログに追加されたメッセージとサーバーログのスニペットだけを含めることをお勧めします。

  • LDAPプロバイダーを作成すると、サーバーログに次のINFOレベルでメッセージが表示されます。

Creating new LDAP Store for the LDAP storage provider: ...

LDAPプロバイダーの設定が表示されます。質問したりバグを報告したりする前に、このメッセージを含めてLDAPの設定を表示するとよいでしょう。最終的には、含めたくない設定の変更をいくつかのプレースホルダー値で自由に置き換えてください。 一例は bindDn=some-placeholder です。 connectionUrl についても、同様に自由に置き換えることができますが、少なくとも使用されたプロトコル ( ldapldaps ) を含めることは一般的に役立ちます。同様に、DEBUGレベルで次のようなメッセージとともに表示されるLDAPマッパーの設定の詳細を含めると便利です。

Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ...

これらのメッセージは、DEBUGロギングが有効になっている場合にのみ表示されることに注意してください。

  • パフォーマンスまたは接続プーリングの問題を追跡するには、LDAPプロバイダーのプロパティー Connection Pool Debug Level の値を all に設定することを検討してください。これにより、サーバーログにLDAP接続プーリングのログが含む多くのメッセージが追加されます。これは、接続プーリングまたはパフォーマンスに関連する問題を追跡するために使用できます。

接続プーリングの設定を変更した後、LDAPプロバイダー接続の再初期化を強制するために、Keycloakサーバーを再起動する必要がある場合があります。

サーバーを再起動しても接続プールに関するメッセージが表示されない場合は、接続プールがLDAPサーバーで機能していないことを示している可能性があります。

  • LDAPの問題を報告する場合、あなたの環境で問題を起こす可能性がある対象のデータとLDAPツリーの一部を添付することを検討してください。たとえば、あるユーザーのログインに時間がかかる場合、様々な"group"エントリーの member 属性の数を示すLDAPエントリーを添付することを検討できます。この場合、これらのグループ・エントリーがKeycloakのグループLDAPマッパー (またはロールLDAPマッパー) などにマップされるように追加すると有益かもしれません。

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

Keycloakには System Security Services Daemon (SSSD) プラグインが含まれています。SSSDは FedoraとRed Hat Enterprise Linux (RHEL)に含まれており、複数のアイデンティティーと認証プロバイダーへのアクセスを提供します。また、SSSD はフェイルオーバーやオフラインのサポートなどの利点も提供します。詳細については、 Red Hat Enterprise Linux Identity Managementのドキュメント を参照してください。

SSSDはFreeIPA Identity Management (IDM) serverと統合され、認証とアクセス・コントロールを提供します。この統合により、Keycloakは特権アクセス管理 (PAM) サービスに対して認証を行い、SSSDからユーザーデータを取得することができます。Linux環境でのRed Hat Identity Managementの使用に関する詳細は、 the Red Hat Enterprise Linux Identity Managementのドキュメント を参照してください。

keycloak sssd freeipa integration overview

KeycloakとSSSDは、読み取り専用のD-Busインターフェイスで通信します。このため、ユーザーの設定や更新はFreeIPA/IdMの管理インターフェイスで行うことになります。デフォルトでは、このインターフェイスはユーザー名、電子メール、名、姓をインポートします。

Keycloakはグループとロールを自動的に登録しますが、同期を取りません。Keycloakの管理者がKeycloakで行った変更は、SSSDと同期されません。

FreeIPA/IdMサーバー

FreeIPA Dockerイメージは、Docker Hubで公開されています。FreeIPAサーバーのセットアップは、 FreeIPAのドキュメント を参照してください。

手順
  1. このコマンドを使用して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

    The parameter -h with server.freeipa.local represents the FreeIPA/IdM server hostname. Change YOUR_PASSWORD to a password of your own.

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

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

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

  3. 以下のコマンドでLinuxサーバーをIPAドメインに登録し、SSSDフェデレーション・プロバイダーがKeycloak上で起動・実行されるようにします。

     ipa-client-install --mkhomedir -p admin -w password
  4. クライアントで以下のコマンドを実行し、インストールが正常に行われることを確認します。

     kinit admin
  5. パスワードを入力してください。

  6. このコマンドを使用して、IPAサーバーにユーザーを追加します。

    $ ipa user-add <username> --first=<first name> --last=<surname> --email=<email address> --phone=<telephoneNumber> --street=<street> \      --city=<city> --state=<state> --postalcode=<postal code> --password
  7. kinitを使用してユーザーのパスワードを強制的に設定します。

     kinit <username>
  8. 以下を入力すると、IPAの正常な動作に戻ります。

    kdestroy -A
    kinit admin

SSSDとD-Bus

フェデレーション・プロバイダーはD-BUSを用いてSSSDからデータを取得し、PAMを用いてデータを認証します。

手順
  1. sssd-dbusのRPMをインストールします。

    $ sudo yum install sssd-dbus
  2. 以下のプロビジョニング・スクリプトを実行します。

    $ 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
  3. セットアップが成功したことを確認するために、 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サービスにアクセスするパーミッションを持っていないために発生します。

    SSSDサービスにアクセスするパーミッションがない場合、Keycloak サーバーを実行しているユーザーが /etc/sssd/sssd.conf ファイルに以下のように記述されていることを確認します.

    [ifp]
    allowed_uids = root, your_username

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

KeycloakはDBus-Javaを使ってD-Busと低レベルで通信します。D-Bus は Unix Sockets Library に依存しています。

このライブラリーのRPMは、 Keycloakのリポジトリーで見つけることができます。この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)

このコマンドでRPMをインストールします。

$ sudo yum install libunix-dbus-java-0.8.0-1.fc24.x86_64.rpm

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

$ sudo yum install jna

設定を確認するには、 ssctl user-checks コマンドを使用します。

  $ sudo sssctl user-checks admin -s keycloak

フェデレーションされたSSSDストアの設定

インストール後、フェデレーションされたSSSDストアを設定します。

手順
  1. メニューの User Federation をクリックします。

  2. Add Provider の一覧から sssd を選択します。Keycloakで、sssdの設定ページに移動します。

  3. Save をクリックします。

これで、FreeIPA/IdMのクレデンシャルを使って Keycloakに対する認証ができるようになりました。

カスタム・プロバイダー

Keycloakには、ユーザー・ストレージ・フェデレーション用のカスタム・プロバイダーを開発するためのService Provider Interface (SPI)があります。カスタム・プロバイダーの開発に関するドキュメントは、 Server Developer Guide にあります。

ユーザーの管理

管理コンソールから、ユーザーを管理するために実行できるアクションは多岐にわたります。

ユーザーの作成

ユーザーは、そのユーザーが必要とするアプリケーションを持つ予定のレルムに作成します。他のレルムを作成するためだけのmasterレルムにユーザーを作成することは避けてください。

前提条件
  • masterレルム以外のレルムを選択します。

手順
  1. メニューの Users をクリックします。

  2. Add User をクリックします。

  3. 新しいユーザーの詳細を入力します。

    Username は唯一の必須項目です。
  4. Save をクリックします。詳細を保存すると、新しいユーザーの Management ページが表示されます。

ユーザーのクレデンシャルの定義

ユーザーのクレデンシャルは、 Credentials タブで管理できます。

クレデンシャル管理

user credentials

行をドラッグ&ドロップすることで、クレデンシャルの優先順序を変更します。新しい順序は、そのユーザーのクレデンシャルの優先順序を決定します。最上位のクレデンシャルが最も高い優先度を持ちます。この優先順序により、ユーザーがログインした後にどのクレデンシャルが最初に表示されるかが決定されます。

Type

この欄には、"password"や"OTP"など、クレデンシャルの種類が表示されます。

User Label

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

Data

これは、クレデンシャルに関する非機密の技術情報です。デフォルトでは非表示になっています。 Show data…​ をクリックすると、クレデンシャルのデータを表示することができます。

Actions

ユーザーのパスワードを変更するには Reset password を、クレデンシャルを削除するには Delete をクリックしてください。

特定のユーザーに対して、他のタイプのクレデンシャルを管理コンソールで設定することはできません。

ユーザーがOTPデバイスを紛失した場合や、クレデンシャルが漏洩した場合に、ユーザーのクレデンシャルを削除することができます。ユーザーのクレデンシャルの削除は、 Credentials タブでのみ可能です。

ユーザーのパスワードの設定

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

すでにパスワードが設定されている場合は、 Reset Password の項目で再設定することができます。

手順
  1. メニューの Users をクリックします。 Users ページが表示されます。

  2. ユーザーを選択します。

  3. 認証情報」タブをクリックします。

  4. Set Password のセクションに新しいパスワードを入力します。

  5. Set Password をクリックします。

    TemporaryON の場合、ユーザーは初回ログイン時にパスワードを変更する必要があります。ユーザーがパスワードを保持できるようにするには、 TemporaryOFF に設定し、ユーザーが Set Password をクリックしてパスワードを変更する必要があります。
  6. または、ユーザーにパスワードの再設定を依頼する電子メールを送信することもできます。

    1. Credential Reset をクリックします。

    2. リストから Update Password を選択します。

    3. Send Email をクリックします。送信された電子メールには、ユーザーを Update Password ウィンドウに誘導するリンクが含まれています。

    4. オプションで、メールリンクの有効期限を設定することができます。これは、 Realm SettingsTokens タブにあるデフォルトのプリセットに設定されています。

OTPの作成

OTPが条件付きである場合、ユーザーはKeycloakに移動する必要があります。アカウントコンソールで新しいOTPジェネレーターを再設定してください。OTPが必要な場合、ユーザーはログイン時に新しいOTPジェネレーターを再設定する必要があります。

または、ユーザーにOTPジェネレーターのリセットを要求するメールを送信することもできます。次の手順は、ユーザーがすでに OTP クレデンシャルを持っている場合にも適用されます。

前提条件
  • 適切なレルムにログインしている。

手順
  1. メインメニューの Users をクリックします。 Users ページが表示されます。

  2. ユーザーを選択します。

  3. 認証情報」タブをクリックします。

  4. Credential Reset をクリックします。

  5. Configure OTP を選択します。

  6. Reset Actions のリストに移動します。

  7. Configure OTP をクリックします。

  8. Send Email をクリックします。送信されたメールには、ユーザーを OTP設定ページ に誘導するリンクが含まれています。

ユーザー属性の設定

ユーザー属性は、各ユーザーにカスタマイズされた体験を提供します。ユーザー属性を設定することで、コンソールで各ユーザーにパーソナライズされたアイデンティティーを作成することができます。

Users

user attributes

前提条件
  • ユーザーが存在するレルムにいます。

手順
  1. メニューの Users をクリックします。

  2. 管理するユーザーを選択します。

  3. Attributes タブをクリックします。

  4. Key フィールドに属性名を入力します。

  5. Value フィールドに属性値を入力します。

  6. Save をクリックします。

読み取り専用の属性の中には、管理者が更新してはいけないものがあります。これには、たとえば、 LDAP_ID のように、LDAPプロバイダーが自動的に入力するような、設計上読み取り専用になっている属性が含まれます。他のいくつかの属性は、セキュリティー上の理由から、典型的なユーザー管理者のために読み取り専用にする必要があります。詳細は セキュリティー上の脅威の軽減 の章を参照してください。

ユーザーの自己登録ができるようにする

Keycloak をサードパーティー認可サーバーとして使用して、自己登録したユーザーを含むアプリケーションのユーザーを管理することができます。自己登録を有効にすると、ログインページに登録リンクが表示され、ユーザーがアカウントを作成できるようになります。

登録リンク

registration link

ユーザーが登録を完了するには、登録フォームにプロファイルル情報を追加する必要があります。登録フォームは、ユーザーが入力しなければならないフィールドを削除または追加することでカスタマイズできます。

追加のリソース
  • ユーザー登録のカスタマイズについては、 Server Developer Guide を参照してください。

ユーザー登録の有効化

ユーザーの自己登録を有効にします。

手順
  1. メインメニューの Realm Settings をクリックします。

  2. Login タブをクリックします。

  3. User RegistrationON に切り替えます。

  4. Save をクリックします。

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

新規ユーザーとして登録する

新規ユーザーとして初めてログインするには、登録フォームに記入する必要があります。プロフィール情報とパスワードを入力して登録します。

登録フォーム

registration form

前提条件
  • ユーザー登録が可能です。

手順
  1. ログインページの Register のリンクをクリックすると、登録ページが表示されます。

  2. ユーザー・プロフィール情報を入力します。

  3. 新しいパスワードを入力します。

  4. Save をクリックします。

ログイン時に必要なアクションを定義する

初回ログイン時にユーザーが実行しなければならないアクションを設定することができます。これらのアクションは、ユーザーがクレデンシャルを提供した後に必要となります。最初のログイン後、これらのアクションは必要なくなります。必須アクションは、そのユーザーの Details タブで追加します。

以下は、必須アクションの種類の例です。

Update Password

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

Configure OTP

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

Verify Email

ユーザーは、自分のEメールアカウントを確認する必要があります。検証用リンクが記載された電子メールがユーザーに送信されますので、クリックしてください。このワークフローが正常に完了すると、ユーザーはログインできるようになります。

Update Profile

ユーザーは、名前、住所、電子メール、電話番号などのプロフィール情報を更新する必要があります。

一人のユーザーに対する必須アクションの設定

どのユーザーに対しても必須アクションを設定できます。

手順
  1. メニューの Users をクリックします。

  2. 一覧からユーザーを選択します。

  3. Required User Actions の一覧に移動します。

    user required action

  4. アカウントに追加したいアクションをすべて選択します。

  5. アクション名の横にある X をクリックすると、削除されます。

  6. 追加するアクションを選択したら、 Save をクリックします。

全ユーザーへの必須アクションの設定

すべての新規ユーザーの初回ログイン前に必要なアクションを指定することができます。この条件は、 Users ページの Add User ボタン、またはログインページの Register リンクで作成されたユーザーに適用されます。

手順
  1. メニューの Authentication をクリックします。

  2. Required Actions タブをクリックします。

  3. 1つ以上の必須アクションの Set as default action 列のチェックボックスをクリックします。新規ユーザーの初回ログイン時には、選択したアクションを実行する必要があります。

必須アクションとしての利用規約の有効化

新規ユーザーがKeycloakに初めてログインする前に、利用規約に同意しなければならないという必須アクションを有効にすることができます。

手順
  1. メニューの Authentication をクリックします。

  2. Required Actions タブをクリックします。

  3. Terms and Conditions のアクションを有効にします。

  4. ベースとなるログインテーマ内の terms.ftl ファイルを編集します。

追加のリソース
  • テーマの拡張と作成の詳細については、 Server Developer Guide を参照してください。

ユーザーの検索

ユーザーを検索すると、そのユーザーのグループやロールなどの詳細情報が表示されます。

前提条件
  • ユーザーが存在するレルムにいます。

手順
  1. メインメニューの Users をクリックします。この Users ページが表示されます。

  2. 検索ボックスに、検索したいユーザーの氏名、姓、名、Eメールアドレスのいずれかを入力します。検索では、条件に一致するすべてのユーザーが返されます。

  3. また、 View all users をクリックすると、システム内の全ユーザーを一覧表示することもできます。

    このアクションは、ローカルKeycloakのデータベースのみを検索し、LDAPなどの連携データベースは検索しません。連携データベースのバックエンドには、ユーザーを検索するためのページネーション機構がありません。
    1. 連携バックエンドからユーザーを検索するには、ユーザーリストをKeycloakのデータベースに同期させる必要があります。検索条件を調整して、バックエンドのユーザーをKeycloakのデータベースに同期させます。

    2. または、左メニューの User Federation をクリックします。

      1. 選択したユーザーに変更を適用するには、フェデレーション・プロバイダーと のページで Sync changed users をクリックします。

      2. データベース内のすべてのユーザーに変更を適用するには、フェデレーション・プロバイダーのページで Sync all users をクリックします。

追加のリソース

ユーザーの削除

アプリケーションへのアクセスが不要になったユーザーを削除することができます。ユーザーを削除すると、ユーザー・プロフィールやデータも削除されます。

手順
  1. メニューの Users をクリックします。 Users ページが表示されます。

  2. View all users をクリックして、削除するユーザーを探します。

  3. メニューの Users をクリックします。 Users ページが表示されます。

    または、検索バーを使ってユーザーを探すこともできます。
  4. 削除したいユーザーの横にあるアクションメニューから Delete をクリックし、削除を確認します。

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

管理コンソールでこの機能を有効にすると、エンドユーザーやアプリケーションはアカウント・コンソールでアカウントを削除することができます。この機能を有効にすると、その機能を特定のユーザーに与えることができます。

アカウント削除機能の有効化

この機能を有効にするには、 Required Actions タブで設定します。

手順
  1. メニューの Authentication をクリックします。

  2. Required Actions タブをクリックします。

  3. Delete Account の行で Enabled を選択します。

    必須アクションタブでのアカウント削除

    enable delete account action

ユーザーに delete-account ロールを与える

特定のユーザーにアカウントの削除を許可するロールを与えることができます。

手順
  1. メニューの Users をクリックします。

  2. ユーザーを選択します。

  3. Role Mappings タブをクリックします。

  4. Assign role ボタンをクリックします。

  5. account delete-account をクリックします。

  6. Assign をクリックします。

    Delete-accountロール

    delete-account role

アカウントの削除

delete-account ロールを取得すると、自分のアカウントを削除できるようになります。

  1. アカウントコンソールにログインします。

  2. Delete-accountページの下部にある Delete Account をクリックします。

    アカウント削除ページ

    Delete account page

  3. クレデンシャルを入力し、削除を確認します。

    削除の確認

    delete account confirm

    このアクションは不可逆的です。Keycloakにあるデータはすべて削除されます。

ユーザーへのなりすまし

適切なパーミッションを持つ管理者は、ユーザーに成りすますことができます。たとえば、あるユーザーがアプリケーションのバグに遭遇した場合、管理者はそのユーザーに成りすまして問題を調査したり、再現したりすることができます。

レルム内で impersonation ロールを持つすべてのユーザーが、あるユーザーになりすますことができます。

手順
  1. メニューの Users をクリックします。

  2. なりすますユーザーをクリックします。

  3. Actions の一覧から、 Impersonate を選択します。

    user details

    • 管理者とユーザーが同じレルムにいる場合は、管理者がログアウトし、成りすましをされるユーザーとして自動的にログインします。

    • 管理者とユーザーが異なるレルムにいる場合、管理者はログインしたままで、さらにそのユーザーのレルムのユーザーとしてログインします。

いずれの場合も、なりすましたユーザーの User Account Management ページが表示されます。

追加のリソース

reCAPTCHAの有効化

ボットからの登録を保護するために、KeycloakはGoogle reCAPTCHA と統合しています。

reCAPTCHAを有効にすると、ログインテーマ内の register.ftl を編集して、登録ページでのreCAPTCHAボタンの配置とスタイルを設定することができます。

手順
  1. ブラウザーで次のURLを入力します。

    https://developers.google.com/recaptcha/
  2. APIキーを作成し、reCAPTCHAサイトのキーとシークレットを取得します。この手順で使用するため、reCAPTCHAサイトのキーとシークレットをメモしておいてください。

    localhostはデフォルトで動作します。ドメインは指定する必要はありません。
  3. Keycloakの管理コンソールに移動します。

  4. メニューの Authentication をクリックします。

  5. Flows タブをクリックします。

  6. 一覧から Registration を選択します。

  7. reCAPTCHA のRequirementを Required に設定します。これにより、reCAPTCHAが有効になります。

  8. reCAPTCHA の行にある 歯車のアイコン ⚙️ をクリックします。

  9. Config のリンクをクリックします。

    Recaptchaの設定ページ

    recaptcha config

    1. Google reCAPTCHAのウェブサイトから生成された Recaptcha Site Key を入力してください。

    2. Google reCAPTCHAのウェブサイトから生成された Recaptcha Secret を入力してください。

  10. Googleが登録ページをiframeとして使用することを認可します。

    Keycloakでは、Webサイトがiframe内にログインページのダイアログを含めることができません。この制限は、クリックジャッキング攻撃を防止するためのものです。Keycloakで設定されているデフォルトのHTTPレスポンス・ヘッダーを変更する必要があります。
    1. メニューの Realm Settings をクリックします。

    2. Security Defenses タブをクリックします。

    3. X-Frame-Options ヘッダーのフィールドに https://www.google.com と入力します。

    4. Content-Security-Policy ヘッダーのフィールドに https://www.google.com と入力します。

追加のリソース
  • テーマの拡張と作成の詳細については、 Server Developer Guide を参照してください。

Defining a user profile

Keycloakでは、ユーザーは一連の属性と関連付けられています。これらの属性は、Keycloak内のユーザーをより適切に説明、識別するため、また、アプリケーションにユーザーに関する追加情報を渡すために使用されます。

ユーザー・プロフィールは、ユーザー属性を表現するための明確なスキーマを定義し、それらがレルム内でどのように管理されるかを定義するものです。ユーザー情報を一貫して表示することで、管理者は属性の管理方法を様々な角度から制御することができます。また、Keycloakを拡張して追加の属性をサポートすることも容易になります。

他の機能の中でも、ユーザー・プロフィールを使用すると、管理者は次のことができます。

  • ユーザー属性のスキーマを定義します

  • コンテキスト情報に基づいて、属性が必要かどうかを定義します(例:ユーザーだけ必要か、管理者だけか、両方か、要求されるスコープに依存するか。)

  • 第三者(管理者を含む)がユーザー属性を参照・変更できないような強いプライバシー要件に対応することができるように、ユーザー属性の参照・編集用のパーミッションを定義します

  • ユーザー情報が常に更新され、属性に関連するメタデータやルールに準拠するように、ユーザー・プロフィールのコンプライアンスを動的に強化します

  • 組み込みのバリデーターを活用したり、カスタムのバリデーターを作成することで、属性ごとに検証ルールを定義します

  • アカウント・コンソールの登録、プロフィールの更新、ブローカリング、個人情報など、ユーザーが操作するフォームを、属性定義に従って動的にレンダリングし、テーマを手動で変更する必要がありません。

ユーザー・プロフィールの機能は、ユーザー・プロフィールSPIによってバックアップされています。デフォルトでは、これらの機能は無効化されており、レルムはレガシー動作との後方互換性を保つためにデフォルトの構成を使用するように設定されています。

レガシーな動作は、ユーザー名、電子メール、姓名などのユーザーのルート属性を管理する際にKeycloakで使用されるデフォルトの制約を維持することであり、カスタム属性を管理する方法については何の制約もありません。登録、プロフィール更新、ブローカリング、アカウント・コンソールによるアカウント管理などのユーザーフローについては、ユーザーは前述の属性を使用するように制限され、テーマ・テンプレートを変更して追加の属性をサポートすることが可能です。

すでにKeycloakを使用している場合は、これまで使用していたレガシーな動作となります。

レガシーな動作とは異なり、Declarativeプロバイダーでは、管理コンソールと明確に定義されたJSONスキーマを通じて、レルムに対するユーザー・プロフィールの構成をより柔軟に定義することができます。

次のセクションでは、Declarativeプロバイダを使用して独自のユーザー・プロフィール構成を定義する方法について見ていきます。

将来的には、Keycloakではレガシーな動作はサポートされなくなります。理想的には、ユーザー・プロフィールによって提供される新しい機能に目を向け始め、それに従ってレルムを移行すべきです。

ユーザー・プロフィールを有効にする

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

有効にするには、 --features=preview または --features=declarative-user-profile と入力してサーバーを起動します。

declarative_user_profile 機能を有効にすることに加えて、レルムに対してユーザー・プロフィールを有効にする必要があります。これを行うには、左サイドメニューの Realm Settings リンクをクリックし、 User Profile Enabled スイッチをオンにします。

user profile enabling

この機能を有効にし、 Save ボタンをクリックすると、 User Profile タブにアクセスすることができ、ここからユーザー属性の設定を管理できるようになります。

レルムのユーザー・プロフィールを有効にすることで、Keycloakはユーザー・プロフィールの構成に基づいて、属性を管理する方法について追加の制約を課そうとします。まとめると、この機能が有効になった際に期待されることは以下の通りです。

  • 管理者視点では、ユーザー詳細ページの Attributes タブには、ユーザー・プロフィールの構成で定義された属性のみが表示されます。また、属性ごとに定義された条件も、属性を管理する際に考慮されます。

  • 登録、プロフィールの更新、ブローカリング、アカウント・コンソールの個人情報などのユーザー向けフォームは、ユーザー・プロフィールの構成に基づいて動的にレンダリングされる予定です。そのため、Keycloak はこれらのフォームを動的にレンダリングするために、異なるテンプレートに依存する予定です。

次のトピックでは、ユーザー・プロフィールの構成を管理する方法と、それがレルムにどのような影響を与えるかを探ります。

ユーザー・プロフィールの管理

ユーザー・プロフィールの設定は、レルム単位で管理されます。そのためには、左サイドメニューの Realm Settings リンクをクリックし、User Profile タブをクリックします。

User Profileタブ

user profile tab

Attributes サブタブには、ユーザー・プロフィールに現在関連付けられている属性のリストが表示されます。デフォルトでは、ユーザーのルート属性に基づいて作成され、各属性はバリデーションとパーミッションの観点からいくつかのデフォルト設定がされています。

Attribute Groups のサブタブでは、属性グループを管理することができます。属性グループは、ユーザー向けフォームをレンダリングする際に、属性を関連付けて表示することができます。

今のところ、属性グループはレンダリングの目的にのみ使用されていますが、将来的には、リンク先の属性にトップレベルの設定を定義することも可能になる予定です。

JSON Editor サブタブでは、明確に定義されたJSONスキーマを使用して設定を表示および編集することができます。他のタブで行った変更は、このタブで表示されるJSON設定に反映されます。

次のセクションでは、 Attributes サブタブで設定を管理する方法を学びます。

属性の管理

Attributes サブタブでは、ユーザー・プロフィールに関連する属性の作成、編集、削除を行うことができます。

新しい属性を定義し、ユーザー・プロファイルに関連付けるには、属性リストの上部にある Create attribute ボタンをクリックします。

属性の設定

user profile create attribute

属性を設定する際に、以下の設定を定義することができます。

名前

属性の名前です。

Display name

主にユーザー向けのフォームをレンダリングする際に使用される、属性のユーザー・フレンドリーな名前です。国際化をサポートしており、メッセージ・バンドルから値を読み込むことができます。

Attribute Group

属性が属する属性グループがある場合、そのグループを設定します。

Enabled when scope

属性を動的に有効にするためのスコープのリストを定義できるようにします。設定されていない場合、属性は常に有効であり、ユーザー・プロフィールの管理およびユーザー向けフォームのレンダリング時にその制約が常に適用されます。そうでない場合は、リスト内のスコープのいずれかがクライアントから要求されたときにのみ、同じ制約が適用されます。

Required

属性を必須として設定します。有効ではない場合、その属性はオプションです。それ以外の場合、属性はユーザーと管理者によって提供されなければなりません。また、クライアントが要求するスコープに基づいて、ユーザーまたは管理者のみに属性を必須とすることも可能です。

Permission

このセクションでは、ユーザーと管理者の参照と書き込みのパーミッションを定義することができます。

Validation

このセクションでは、属性値を管理する際に実行されるバリデーションを定義することができます。Keycloakは組み込みのバリデータのセットを提供し、そこから選んで独自のバリデータを追加することができます。

Annotation

このセクションでは、属性にアノテーションを関連付けることができます。アノテーションは主に、レンダリング目的でフロントエンドに追加のメタデータを渡すのに便利です。

パーミッションの管理

Permission セクションでは、ユーザーと管理者が属性に対して読み書きできるアクセスレベルを定義することができます。

属性のパーミッション

user profile permission

そのために、以下のような設定を行います。

Can user view?

有効にすると、ユーザーはその属性を参照することができます。そうでなければ、ユーザーはその属性にアクセスできません。

Can user edit?

有効にすると、ユーザーはその属性を表示および編集することができます。そうでない場合、ユーザーはその属性に書き込むアクセス権を持ちません。

Can admin view?

有効にすると、管理者はその属性を参照することができます。そうでなければ、管理者はその属性にアクセスできません。

Can admin edit?

有効にすると、管理者はその属性を表示および編集することができます。そうでない場合、管理者はその属性に書き込むアクセス権を持ちません。

属性を作成すると、その属性には何のパーミッションも設定されません。事実上、ユーザーも管理者もその属性にアクセスすることはできません。属性を作成したら、その属性が対象者のみに表示されるように、適宜パーミッションを設定するようにしてください。

パーミッションは、属性の管理方法と管理者、およびユーザー向けフォームでの属性の表示方法に直接的な影響を及ぼします。

たとえば、ある属性をユーザーしか参照できないように設定すると、管理者は管理コンソールからユーザーを管理する際に、その属性にアクセスできなくなります(User APIからもアクセスできなくなります)。また、ユーザーは自分のプロフィールを更新する際に、その属性を変更することができなくなります。ユーザー属性が既存のアイデンティティー・ストア(フェデレーション)から取得され、ソース・アイデンティティー・ストアを介する以外に属性を更新する可能性がなく、ユーザーに属性を単に表示したい場合、興味深い構成となります。

同様に、ある属性を管理者のみ書き込み可能で、ユーザーは読み取り専用にすることもできます。この場合、管理者だけがその属性を管理できるようになります。

プライバシーに関する要件によっては、管理者はアクセスできないが、ユーザーには読み書き権限がある属性が必要な場合もあります。

ユーザー・プロフィールの設定に新しい属性を追加する場合は、必ず正しいパーミッションを設定してください。

バリデーションの管理

Validation セクションでは、属性値が特定のルールに適合していることを確認するために、さまざまな形式のバリデーションを選択することができます。

属性のバリデーション

user profile validation

Keycloakはすぐに利用できる異なるバリデーターを提供します。

名前 説明 設定

length

文字列値の長さを最小値と最大値で確認します。

min :許容される最小の長さを定義する整数です。

max :許容される最大の長さを指定する整数です。

trim-disabled :バリデーション前に値をトリミングするかどうかを定義するBoolean値です。

integer

値が整数であり、下限および/または上限の範囲内にあるかどうかを確認します。範囲が定義されていない場合は、値が有効な数値であるかどうかだけをチェックします。

min :下限の範囲を指定する整数です。

max :上限の範囲を指定する整数です。

double

値がdoubleであり、下限および/または上限の範囲内であるかどうかを確認します。範囲を指定しなかった場合、バリデータは値が有効な数値であるかどうかだけをチェックします。

min :下限の範囲を指定する整数です。

max :上限の範囲を指定する整数です。

uri

値が有効なURIであるかどうかを確認します。

なし

pattern

値が特定の正規表現パターンにマッチするかどうかを確認します。

pattern :値を検証する際に使用する正規表現パターン。

error-message :国際化バンドルでのエラーメッセージのキーを設定します。設定されていない場合、汎用メッセージが使用されます。

email

値が有効な電子メール形式であるかどうかを確認します。

なし

local-date

値がレルムおよび/あるいはユーザーのロケールに基づいた有効な形式であるかどうかを確認します。

なし

person-name-prohibited-characters

スクリプト・インジェクションなどの攻撃に対する追加の防壁として、値が有効な人名であるかどうかをチェックします。この検証は、人名に一般的でない文字をブロックするデフォルトの正規表現パターンに基づいています。

error-message :国際化バンドルでのエラーメッセージのキーを設定します。設定されていない場合、汎用メッセージが使用されます。

username-prohibited-characters

スクリプト・インジェクションなどの攻撃に対する追加の防壁として、値が有効なユーザー名であるかどうかをチェックします。この検証は、ユーザー名に一般的でない文字をブロックするデフォルトの正規表現パターンに基づいています。

error-message :国際化バンドルでのエラーメッセージのキーを設定します。設定されていない場合、汎用メッセージが使用されます。

オプション

値が定義された許容値のセットから外れていないかどうかをチェックします。セレクト・フィールドやマルチセレクト・フィールドで入力された値を検証するのに便利です。

options: 許可された値を含む文字列の配列。

アノテーションの管理

フロントエンドに追加情報を渡すために、属性にアノテーションを付与し、属性のレンダリング方法を指定することができます。この機能は主にKeycloakのテーマを拡張して、属性に関連付けられたアノテーションに基づいてページを動的にレンダリングする際に役立ちます。この仕組みは、たとえば 属性のForm入力フィールドを設定する に使われています。

属性のアノテーション

user profile annotation

属性グループの管理

Attribute Groups サブタブでは、属性グループの作成、編集、削除を行うことができます。属性グループは、関連する属性のコンテナーを定義することができ、ユーザー向けフォームに表示される際に一緒に表示されます。

属性グループ一覧

user profile attribute group list

属性にバインドされている属性グループを削除することはできません。そのためには、まず属性を更新してバインディングを削除する必要があります。

新しいグループを作成するには、属性グループ一覧の上部にある Create attributes group ボタンをクリックします。

属性グループの設定

user profile create attribute group

グループを構成する際に、以下の設定を定義することができます。

名前

グループ名です。

Display name

主にユーザー向けのフォームをレンダリングする際に使用される、グループのユーザー・フレンドリーな名前です。国際化をサポートしており、メッセージ・バンドルから値を読み込むことができます。

Display description

ユーザー向けフォームをレンダリングする際に、ツールチップとして表示されるユーザー・フレンドリーなテキストです。

Annotation

このセクションでは、属性にアノテーションを関連付けることができます。アノテーションは主に、レンダリング目的でフロントエンドに追加のメタデータを渡すのに便利です。

JSON設定の使用

ユーザー・プロフィールの設定は、明確に定義されたJSONスキーマを使用して保存されます。 JSON Editor サブタブをクリックすることで、ユーザー・プロフィールの設定を直接編集することができます。

JSON設定

user profile json config

JSONスキーマは以下のように定義されています。

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "roles": [ "user", "admin" ],
        "scopes": [ "foo", "bar" ]
      },
      "permissions": {
        "view": [ "admin", "user" ],
        "edit": [ "admin", "user" ]
      },
      "validations": {
        "email": {},
        "length": {
          "max": 255
        }
      },
      "annotations": {
        "myannotation": "myannotation-value"
      }
    }
  ],
  "groups": [
    {
      "name": "personalInfo",
      "displayHeader": "Personal Information"
    }
  ]
}

スキーマは必要な数だけ属性をサポートします。

各属性には name と、オプションで requiredpermissionannotations の設定を定義する必要があります。

必須プロパティー

required 設定は、属性が必須であるかどうかを定義します。Keycloakでは、様々な条件に基づいて属性を必須とすることができます。

required 設定が空のオブジェクトとして定義されている場合、その属性は常に必須となります。

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {}
  ]
}

一方、ユーザー、管理者、またはその両方に対してのみ属性を必須とすることも可能です。また、ユーザーがKeycloakで認証する際に、特定のスコープを要求された場合のみ、この属性を必須とすることもできます。

ユーザーや管理者に必要な属性をマークするには、 roles プロパティーを次のように設定します。

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "roles": ["user"]
      }
  ]
}

roles プロパティーには、値が user または admin である配列を指定します。これは、その属性がユーザーまたは管理者のどちらに必須とされるかによります。

同様に、ユーザー認証の際にクライアントから1つ以上のスコープのセットが要求された場合に、その属性を必須にすることも可能です。そのためには、次のように scopes プロパティを使用します。

{
  "attributes": [
    {
      "name": "myattribute",
      "required": {
        "scopes": ["foo"]
      }
  ]
}

scopes プロパティーは配列で、その値にはクライアント・スコープを表す任意の文字列を指定することができます。

パーミッション・プロパティー

属性レベルの permissions プロパティーを使用して、属性に対する参照と書き込み権限を定義することができます。パーミッションは、ユーザー、管理者、またはその両方が属性に対してこれらの操作を実行できるかどうかに基づいて設定されます。

{
  "attributes": [
    {
      "name": "myattribute",
      "permissions": {
        "view": ["admin"],
        "edit": ["user"]
      }
  ]
}

viewedit の両プロパティーは、その値が user または admin である配列を期待します。これは、その属性がユーザーまたは管理者のどちらによって参照または編集可能であるかによります。

edit パーミッションが付与されると、view パーミッションも暗黙のうちに付与されます。

アノテーション・プロパティー

属性レベルの annotation プロパティ=は、属性に追加のメタデータを関連付けるために使用することができます。アノテーションは主に、ユーザー・プロフィールの設定に基づいてユーザー属性をレンダリングするフロントエンドに、属性に関する追加情報を渡すのに便利です。各アノテーションはキーと値のペアで構成されます。

{
  "attributes": [
    {
      "name": "myattribute",
      "annotations": {
        "foo": ["foo-value"],
        "bar": ["bar-value"]
      }
  ]
}

動的フォームの使用

ユーザー・プロフィールの主な機能の1つは、属性のメタデータに基づいてユーザー向けのフォームを動的にレンダリングする可能性です。この機能をレルムで有効にすると、登録やプロフィールの更新などのフォームが特定のテーマ・テンプレートを使ってレンダリングされ、ユーザー・プロフィールの設定に基づいたページが動的にレンダリングされます。

ですから、デフォルトのレンダリング機構がニーズに合っていれば、テンプレートをカスタマイズする必要は全くありません。それでもなお、テーマのカスタマイズが必要な場合は、以下のテンプレートを参照してください。

テンプレート 説明

base/login/update-user-profile.ftl

プロフィールの更新ページをレンダリングするテンプレートです。

base/login/register-user-profile.ftl

登録ページをレンダリングするテンプレートです。

base/login/idp-review-user-profile.ftl

ブローカリングによるユーザー連携時に、ユーザー・プロフィールの確認・更新ページをレンダリングするテンプレートです。

base/login/user-profile-commons.ftl

属性の設定に基づいて、フォームの入力フィールドをレンダリングするテンプレートです。前述の3つのページテンプレートすべてから使用されます。新しい入力タイプをここに実装することができます。

デフォルトのレンダリング機構は、以下の機能を提供します。

  • 属性に設定されたパーミッションに基づき、フィールドを動的に表示します。

  • 属性に設定された制約に基づき、必須フィールドのマーカーを動的にレンダリングします。

  • 属性に設定されたフィールド入力タイプ(テキスト、日付、数字、セレクト、マルチセレクト)を動的にレンダリングします。

  • 属性に設定されたパーミッションに応じて、読み取り専用のフィールドを動的にレンダリングします。

  • 属性に設定された順序に応じて、フィールドを動的に順序付けします。

  • 同じ属性グループに属するフィールドを動的にグループ化することができます。

属性の順序付け

属性の順番は、属性一覧ページで属性行をドラッグ&ドロップすることで設定します。

属性の順序付け

user profile attribute list order

このページで設定した順序は、動的なフォームでフィールドがレンダリングされる際に利用されます。

属性のグループ化

動的なフォームがレンダリングされる際、同じ属性グループに属する属性をグループ化しようとします。

動的なプロフィールの更新フォーム

user profile update profile

属性が属性グループにリンクされている場合、同じグループ内の属性が同じグループヘッダー内で近接していることを確認するために、属性の順序も重要です。そうしないと、グループ内の属性に順序がない場合、同じグループヘッダーがダイナミックフォームに複数回レンダリングされる可能性があります。

属性のためのフォーム入力ファイルの設定

Keycloakは、動的なフォームで属性に使用される入力タイプを設定するためのアノテーションを内蔵しており、属性の視覚化の他の側面を提供しています。

利用可能なアノテーションは以下です。

名前 説明

inputType

フォームの入力フィールドのタイプ。利用可能なタイプを以下の表に示します。

inputHelperTextBefore

入力フィールドの前(上)に表示されるヘルパーテキストです。ここでは直接テキストや国際化パターン( ${i18n.key} など)を使用することができます。 テキストはページにレンダリングされるときにはhtmlエスケープされないので、htmlタグを使ってテキストをフォーマットすることができますが、html制御文字も正しくエスケープしなければなりません。

inputHelperTextAfter

入力フィールドの後(下)に表示されるヘルパーテキストです。ここでは直接テキストや国際化パターン( ${i18n.key} など)を使用することができます。テキストはページにレンダリングされるときにはhtmlエスケープされないので、htmlタグを使ってテキストをフォーマットすることができますが、html制御文字も正しくエスケープしなければなりません。

inputOptionsFromValidation

selectおよびmultiselectタイプのためのアノテーション。入力オプションを取得するカスタム属性検証の名前(オプション)。以下の 詳細な説明 を参照してください。

inputOptionLabelsI18nPrefix

selectおよびmultiselectタイプのアノテーション。UIでオプションを表示するための国際化キーのプレフィックス。以下の detailed description を参照してください。

inputOptionLabels

selectおよびmultiselectタイプのためのアノテーション。オプションマップで、オプションのUIラベルを定義します(直接または国際化を使用して)。以下の 詳細な説明 を参照してください。

inputTypePlaceholder

HTMLの入力 placeholder 属性がフィールドに適用されます - 入力フィールドに期待される値を記述する短いヒントを指定します(例:サンプル値または期待される書式の短い説明)。短いヒントは、ユーザーが値を入力する前に入力フィールドに表示されます。

inputTypeSize

フィールドに適用されるHTMLのinputの size 属性 - 単一行の入力フィールドの幅を文字数で指定します。HTMLの select タイプに基づくフィールドの場合、オプションが表示される行数を指定します。 使用するテーマのCSSによっては、動作しない場合があります。

inputTypeCols

フィールドに適用されるHTMLのinputの cols 属性 - textarea タイプの幅を文字数で指定します。使用しているテーマのCSSによっては動作しない場合があります。

inputTypeRows

HTMLのinputの rows 属性がフィールドに適用されます - textarea 型の高さを文字数で指定します。セレクト・フィールドの場合、オプションが表示される行数を指定します。使用するテーマの CSS によっては動作しない場合があります。

inputTypePattern

HTMLのinputの pattern 属性は、クライアント・サイドのバリデーションを行うフィールドに適用されます - 入力フィールドの値を正規表現で指定すると照合されます。一行入力に便利です。

inputTypeMaxLength

HTMLのinputの maxlength 属性は、クライアントサイドのバリデーションを行うフィールドに適用されます。 - 入力フィールドに入力可能なテキストの最大長。テキストフィールドに便利です。

inputTypeMinLength

HTMLのinputの minlength 属性は、クライアントサイドのバリデーションを行うフィールドに適用されます。 - 入力フィールドに入力可能なテキストの最少長。テキストフィールドに便利です。

inputTypeMax

HTMLのinputの max 属性は、フィールドに適用し、クライアント・サイドのバリデーションを行います。 - 入力フィールドに入力できる最大値。数値フィールドに入力できる最大値。

inputTypeMin

HTMLのinputの min 属性は、フィールドに適用し、クライアント・サイドのバリデーションを行います。 - 入力フィールドに入力できる最小値。数値フィールドに入力できる最大値。

inputTypeStep

HTMLのinputの step 属性がフィールドに適用されます - 入力フィールドで有効な数値の間隔を指定します。数値フィールドに便利です。

フィールドタイプは、HTMLのフォーム・フィールドのタグや属性を適用したもので、HTMLの仕様やブラウザーのサポートに基づいた動作をします。

視覚的なレンダリングは、使用するテーマで適用されるCSSスタイルにも依存します。

利用可能な inputType アノテーションの値。

名前 説明 使用するHTMLタグ

text

一行のテキスト入力。

input

textarea

複数行のテキスト入力が可能。

textarea

select

一般的な単一選択入力です。以下の オプションの設定方法の説明 を参照してください。

select

select-radiobuttons

ラジオボタンによる単一選択入力。以下の オプションの設定方法の説明 を参照してください。

入力のグループ

multiselect

一般的な複数選択入力です。以下の オプションの設定方法の説明 を参照してください。

select

multiselect-checkboxes

チェックボックスのグループによる多項目入力。以下の オプションの設定方法の説明 を参照してください。

入力のグループ

html5-email

HTML5仕様に基づく、メールアドレス用の1行テキスト入力。

input

html5-tel

HTML 5仕様に基づく電話番号の1行テキスト入力。

input

html5-url

HTML5仕様に基づくURLの1行テキスト入力。

input

html5-number

HTML5仕様に基づく数値( step に依存する整数または浮動小数点)の一行入力です。

input

html5-range

HTML5仕様に基づく数字入力用スライダー。

input

html5-datetime-local

HTML5仕様に基づく日付時刻入力。

input

html5-date

HTML5仕様に基づく日付入力。

input

html5-month

HTML5仕様に基づく月入力。

input

html5-week

HTML5仕様に基づく週間入力。

input

html5-time

HTML5仕様に基づく時刻入力。

input

単一選択・複数選択フィールドのオプションの定義

単一選択と複数選択のフィールドのオプションは、UIに表示されるバリデーションとフィールドのオプションが常に一貫していることを確認するために、属性に適用されるバリデーションから取得されます。デフォルトでは、オプションは組み込みの options のバリデーションから取得されます。

選択項目や複数選択項目に対して、人間が読みやすいラベルを提供するには、さまざまな方法があります。最も単純なケースは、属性値が UI ラベルと同じである場合です。この場合、特別な設定は必要ありません。

オプション値はUIラベルと同じ

user profile select options simple

属性値がUIに適さないIDのような場合、 inputOptionLabelsI18nPrefix アノテーションが提供する簡単な国際化サポートを使用することができます。これは国際化キーのプレフィックスを定義し、オプションの値はこのプレフィックスにドットで追加されます。

国際化キープレフィックスを用いたUIラベルの簡易国際化機能

user profile select options simple i18n

オプション値のためのローカライズされたUIラベルテキストは、共通のローカライゼーション機構を使用して、 userprofile.jobtitle.swenguserprofile.jobtitle.swarch キーで提供されなければなりません。

また、inputOptionLabels アノテーションを使用して、個々のオプションのラベルを提供することができます。マップのキーはオプションの値 (バリデーションで定義) で、マップの値はそのオプションのUIラベルテキストそのもの、またはその国際化パターン ( ${i18n.key} のような) です。

ユーザー・プロフィールの JSON Editor を使用して、 inputOptionLabels アノテーションの値としてマップを入力する必要があります。

国際化を行わず、個々のオプションにラベルを直接入力した例。

"attributes": [
<...
{
  "name": "jobTitle",
  "validations": {
    "options": {
      "options":[
        "sweng",
        "swarch"
      ]
    }
  },
  "annotations": {
    "inputType": "select",
    "inputOptionLabels": {
      "sweng": "Software Engineer",
      "swarch": "Software Architect"
    }
  }
}
...
]

個々のオプションの国際化されたラベルの例。

"attributes": [
...
{
  "name": "jobTitle",
  "validations": {
    "options": {
      "options":[
        "sweng",
        "swarch"
      ]
    }
  },
  "annotations": {
    "inputType": "select-radiobuttons",
    "inputOptionLabels": {
      "sweng": "${jobtitle.swengineer}",
      "swarch": "${jobtitle.swarchitect}"
    }
  }
}
...
]

ローカライズされたテキストは、共通のローカライズ機構を使用して jobtitle.swengineerjobtitle.swarchitect のキーで提供される必要があります。

カスタム・バリデーターは inputOptionsFromValidation 属性アノテーションのおかげで、オプションを提供するために使用することができます。このバリデーションでは、オプションの配列を提供する options の設定が必要です。国際化は、組み込みの options のバリデーションで提供されるオプションと同じように動作します。

カスタム・バリデーターが提供するオプション

user profile select options custom validator

ユーザー・プロフィールの強制遵守

ユーザーのプロフィールが設定に準拠していることを確認するために、管理者は VerifyProfile 必須アクションを使用して、最終的にKeycloakで認証する際にユーザーのプロフィールを強制的に更新させることができます。

VerifyProfile アクションは UpdateProfile アクションと似ています。しかし、ユーザー・プロフィールが提供するすべての機能を利用して、ユーザー・プロフィールの設定に自動的に準拠するようにします。

VerifyProfile アクションを有効にすると、ユーザー認証の際に次のような処理を行います。

  • ユーザー・プロフィールがレルムに設定されたユーザー・プロフィールの構成に完全に準拠しているかどうかを確認します。

  • そうでない場合は、認証時に追加のステップを実行し、ユーザーが不足または無効な属性を更新できるようにします。

  • ユーザー・プロフィールが設定に適合している場合、追加のステップは実行されず、ユーザーは認証プロセスを続行します。

デフォルトでは、 VerifyProfile アクションは無効になっています。これを有効にするには、左サイドメニューの Authentication リンクをクリックし、 Required Actions タブをクリックします。このタブで、 VerifyProfile アクションの Enabled スイッチを選択します。

VerifyProfile必須アクションの登録

user profile register verify profile action

ユーザー・プロフィールへの移行

レルムに対してユーザー・プロフィール機能を有効にする前に、注意すべき重要な点がいくつかあります。属性メタデータを管理するための単一の場所を提供することで、この機能はユーザーに設定できる属性とその管理方法について非常に厳格なものとなっています。

ユーザー管理に関しては、管理者はユーザー・プロフィールの構成で定義された属性のみを管理することができます。ユーザーに設定された他の属性で、まだユーザー・プロフィール構成で定義されていないものは、アクセスできません。ユーザーまたは管理者のいずれかに公開したい、すべてのユーザー属性を定義したユーザー・プロフィール構成に更新することをお勧めします。

ユーザー情報を照会するためにUser REST APIにアクセスする場合にも、同様の推奨事項が適用されます。

LDAP_IDLDAP_ENTRY_DNKERBEROS_PRINCIPAL などのKeycloak内部ユーザー属性に関して、これらの属性にアクセスしたい場合は、ユーザー・プロフィール構成に属性として設定する必要があります。推奨は、これらの属性を管理者のみ参照可能とし、管理コンソールでユーザー属性を管理する際や、User APIでユーザーを照会する際に参照できるようにすることです。

テーマに関して、従来のテンプレート(ユーザーのルート属性でハードコードされたもの)をカスタマイズしている場合、ユーザー向けのフォームをレンダリングする際に、そのカスタム・テンプレートは使われず、これらのフォームを動的にレンダリングする新しいテンプレートが使用されます。理想的には、テンプレートのカスタマイズを避け、新しいテンプレートが提供する動的にフォームをレンダリングする動作を維持するようにします。それでも不十分な場合は、テンプレートをカスタマイズするか、新しいテンプレートを強化するかどうかを検討しますので、ご意見をお聞かせください。

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

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

  • ユーザーの電子メール、姓、名前などの基本的なユーザー・プロフィール・データ

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

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

Keycloakで収集された情報は高度にカスタマイズできます。カスタマイズを行う場合は、次のガイドラインが適用されます。

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

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

  • 認可サービスとUMAサポートを有効にすると、Keycloakは、特定のユーザーがオーナーであるいくつかのオブジェクトに関する情報を保持することができます。

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

ユーザーがレルムにログインすると、Keycloakは各ユーザーのユーザー・セッションを維持し、セッション内でユーザーがアクセスした各クライアントを記憶します。レルム管理者は、各ユーザー・セッションに対して以下のような複数のアクションを実行することができます。

  • レルムのログイン統計情報を表示する。

  • アクティブなユーザーとログインした場所を表示する。

  • ユーザーをセッションからログアウトさせる。

  • トークンを失効させる。

  • トークンのタイムアウトを設定する。

  • セッションのタイムアウトを設定する。

セッションの管理

Keycloakでアクティブなクライアントとセッションのトップレベルのビューを表示するには、メニューから Sessions をクリックします。

Sessions

Sessions tab

アクティブなセッションをすべてサインアウトする

レルム内のすべてのユーザーをサインアウトすることができます。 Action リストから、 Sign out all active sessions を選択します。すべてのSSO Cookieが無効になります。Keycloakは、Keycloak OIDCクライアント・アダプターを使用して、ログアウト・イベントをクライアントに通知します。アクティブなブラウザー・セッションで認証を要求するクライアントは、再度ログインする必要があります。SAMLなどのクライアント・タイプは、バックチャネルのログアウト・リクエストを受信しません。

Sign out all active sessions をクリックしても、未使用のアクセストークンは無効化されません。未使用のトークンは自然に失効する必要があります。OIDCクライアント・アダプターを使用しているクライアントの場合、無効化ポリシーをプッシュしてトークンを無効化させることができますが、他のアダプターの場合はうまくいきません。

クライアントセッションの表示

手順
  1. メニューの Clients をクリックします。

  2. Sessions タブをクリックします。

  3. クライアントをクリックすると、そのクライアントのセッションが表示されます。

    クライアント・セッション

    Client sessions

ユーザー・セッションの表示

手順
  1. メニューの Users をクリックします。

  2. Sessions タブをクリックします。

  3. ユーザーをクリックすると、そのユーザーのセッションが表示されます。

    ユーザー・セッション

    User sessions

アクティブなセッションを取り消す

システムが侵害された場合、すべてのアクティブなセッションとアクセストークンを失効させることができます。

手順
  1. メニューの Sessions をクリックします。

  2. Actions の一覧から、 Sign out all active sessions を選択します。

    失効

    Revocation

  3. その日時以前に発行されたセッションやトークンが本コンソールで無効となる日時を指定します。

    • Set to now をクリックすると、ポリシーが現在の時刻と日付に設定されます。

    • Push をクリックすると、Keycloak OIDCクライアント・アダプターで登録されたOIDCクライアントにこの失効ポリシーがプッシュされます。

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

Keycloakの Realm settings メニューの Sessions タブと Tokens タブには、セッション、Cookie、トークンのタイムアウトの制御が含まれています。

Sessionsタブ

Sessions Tab

設定 説明

SSO Session Idle

この設定は、OIDCクライアントのみです。このタイムアウト時間を超えてユーザーがアクティブでない場合、そのユーザーセッションは無効になります。このタイムアウト値は、クライアントが認証を要求するか、リフレッシュトークン・リクエストを送信するとリセットされます。Keycloakは、セッションが無効化になるまでの時間を、アイドル・タイムアウトに追加します。このセクションの後の注意事項を参照してください。

SSO Session Max

ユーザーセッションが失効するまでの最大時間。

SSO Session Idle Remember Me

この設定は、標準のSSOセッション・アイドルの設定と似ていますが、 Remember Me を有効にしたログインに固有のものです。ユーザーは、ログイン時に Remember Me をクリックすると、より長いセッションアイドルのタイムアウトを指定することができます。この設定はオプションで、値が0より大きくない場合は、SSOセッション・アイドルの設定と同じアイドル・タイムアウトが使用されます。

SSO Session Max Remember Me

この設定は、標準のSSO Session Maxに似ていますが、 Remember Me ログインに固有のものです。ユーザーは、ログイン時に Remember Me をクリックすると、より長いセッションを指定できます。この設定はオプションで、値が0より大きくない場合、SSO Session Maxの設定と同じセッション寿命が使用されます。

Client Session Idle

ユーザーがこのタイムアウトより長く非アクティブの場合、リフレッシュトークン・リクエストはアイドル・タイムアウトになります。この設定では、リフレッシュトークンのアイドル・タイムアウトをセッション・アイドル・タイムアウトよりも短く指定しますが、ユーザーが個々のクライアントに対してオーバーライドすることができます。この設定はオプションで、0に設定すると、SSO Session Idleの設定と同じアイドル・タイムアウトが使用されます。

Client Session Max

リフレッシュトークンが期限切れで無効になるまでの最大時間。この設定は、セッション・タイムアウトよりも短いリフレッシュトークンのタイムアウトを指定しますが、ユーザーが個々のクライアントに対してオーバーライドすることができます。この設定はオプションで、0に設定すると、SSO Session Maxの設定のアイドル・タイムアウトと同じものが使用されます。

Offline Session Idle

この設定はオフライン・アクセスのためのものです。Keycloak がオフライン トークンを無効にするまでに、セッションがアイドル状態のままである時間を指定します。Keycloakは、セッションが無効になるまでのアイドル・タイムアウトに時間のウィンドウを追加します。このセクションの後の注意事項を参照してください。

Offline Session Max Limited

この設定は、オフライン・アクセスのためのものです。このフラグが ON の場合、Offline Session Maxは、ユーザーの活動に関係なく、オフライントークンがアクティブである最大時間を制御することができます。Client Offline Session Idleおよび Client Offline Session Max が有効になります。

Offline Session Max

この設定はオフライン・アクセス,に対するもので、Keycloakが対応するオフライントークンを取り消すまでの最大時間です。このオプションは、ユーザーの活動に関係なく、オフライントークンが有効であり続ける最大時間を制御します。

Login timeout

ログインにかかる合計時間です。認証にこの時間以上かかる場合は、再度認証を開始する必要があります。

Login action timeout

認証プロセスにおいて、ユーザーが1つのページに滞在できる最大時間。

Tokensタブ

Tokens Tab

設定 説明

デフォルトの署名アルゴリズム

レルムにトークンを割り当てるために使用するデフォルトのアルゴリズム。

Revoke Refresh Token

Enabled の場合、Keycloakはリフレッシュトークンを取り消し、クライアントが使用しなければならない別のトークンを発行します。このアクションは、リフレッシュトークン・フローを実行するOIDCクライアントに適用されます。

Access Token Lifespan

KeycloakがOIDCのアクセストークンを作成する際に、この値でトークンの有効期間を制御します。

Access Token Lifespan For Implicit Flow

インプリシット・フローでは、Keycloakはリフレッシュトークンを提供しません。インプリシット・フローで作成されたアクセストークンには、別途タイムアウトが存在します。

Client login timeout

クライアントがOIDCの認可コードフローを終了するまでの最大時間。

User-Initiated Action Lifespan

ユーザーのアクション・パーミッションが失効するまでの最大時間です。一般的に、ユーザーは自分で作成したアクションにすぐに反応するため、この値は短くしてください。

Default Admin-Initiated Action Lifespan

管理者がユーザーに送信したアクション・パーミッションが期限切れになるまでの最大時間です。オフラインのユーザーに管理者がメールを送信できるように、この値は長くしてください。管理者はトークンを発行する前に、デフォルトのタイムアウトをオーバーライドすることができます。

電子メール検証

電子メール認証の独立したタイムアウトを指定します。

IdPアカウントのメール認証

IdPアカウントのメール検証の独立したタイムアウトを指定します。

パスワード忘れ

パスワード忘れ時の独立したタイムアウトを指定します。

アクションの実行

実行アクションの独立したタイムアウトを指定します。

アイドル・タイムアウトの場合、セッションがアクティブである2分間のウィンドウが存在します。たとえば、タイムアウトを30分に設定した場合、セッションが終了するのは32分後となります。

このアクションは、クラスターおよびクロス・データセンター環境において、あるクラスターノードで有効期限より少し前にトークンがリフレッシュされ、他のクラスターノードがリフレッシュノードからリフレッシュ成功のメッセージをまだ受け取っていないため、誤ってセッションを期限切れと見なす場合に必要です。

オフライン・アクセス

オフライン・アクセス ログイン時、クライアント・アプリケーションはリフレッシュトークンの代わりにオフライントークンを要求します。クライアント・アプリケーションはこのオフライントークンを保存し、ユーザーがログアウトした場合、次回以降のログインに使用できます。このアクションは、ユーザーがオンラインでないときでも、アプリケーションでユーザーに代わってオフライン・アクションを実行する必要がある場合に便利です。たとえば、定期的なデータのバックアップなどです。

クライアント・アプリケーションは、オフライントークンをストレージに永続化し、それを使用してKeycloakサーバーから新しいアクセストークンを取得する責任を負います。

リフレッシュトークンとオフライントークンの違いは、オフライントークンは有効期限がなく、 SSO Session Idle タイムアウトと SSO Session Max ライフタイムの対象外であることです。オフライントークンは、ユーザーによるログアウトやサーバーの再起動後も有効です。オフライントークンは、少なくとも30日間に1回、トークン更新アクションに使用するか、Offline Session Idleの値に対して使用する必要があります。

Offline Session Max Limitedを有効にすると、オフライントークンをトークン更新アクションに使用した場合でも、オフライントークンは60日後に失効します。この値は、管理コンソールのOffline Session Maxで変更することができます。

Revoke Refresh Tokenオプションを有効にすると、1つのオフライントークンは1回だけ使用することができます。リフレッシュ後は、以前のオフライントークンではなく、リフレッシュ時のレスポンスから新しいオフライントークンを保存する必要があります。

ユーザーは、Keycloakが自分に付与したオフライン・トークンをユーザー・アカウント・コンソールで表示したり取り消したりすることができます。管理者は、管理コンソールの 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など)にアクセスすると、このパラメーターが自動的に追加されます。Direct Access Grant and Service Accountsでは、認証リクエストのボディーに scope=offline_access を含めるとオフライントークンをサポートします。

オフライン・セッションの事前読み込み

Infinispanキャッシュに加えて、オフライン・セッションはデータベースに保存されます。つまり、サーバーの再起動後もオフライン・セッションを利用できます。デフォルトでは、オフライン・セッションは、サーバーの起動時にデータベースからInfinispanキャッシュにプリロードされません。なぜなら、プリロードするオフライン・セッションが多数ある場合、このアプローチには欠点があるためです。サーバーの起動時間が大幅に遅くなる可能性があります。そのため、デフォルトではオフライン・セッションはデータベースから遅延取得されます。

しかし、Keycloakは、サーバー起動時にオフライン・セッションをデータベースからInfinispanキャッシュにプリロードするように設定することができます。これは、 userSessions SPIの preloadOfflineSessionsFromDatabase プロパティーを trie に設定することで実現できます。

次の例はオフライン・セッションのプリローディングを設定する方法を示しています。

bin/kc.[sh|bat] start --spi-user-sessions-infinispan-preload-offline-sessions-from-database=true

トランジェント・セッション

Keycloakでは、トランジェント・セッションを使用することができます。トランジェント・セッションを使用する場合、Keycloakは認証に成功した後にユーザー・セッションを作成しません。Keycloakは、ユーザー認証に成功した現在のリクエストのスコープに一時的なトランジェント・セッションを作成します。Keycloakは、認証後にトランジェント・セッションを使用してプロトコル・マッパーを実行することができます。

トランジェント・セッションの間、クライアント・アプリケーションはトークンのリフレッシュ、トークンのイントロスペクト、または特定のセッションの検証を行うことができません。これらのアクションが不要な場合もあるため、ユーザー・セッションを永続化することによるリソースの追加使用を避けることができます。このセッションは、パフォーマンス、メモリー、およびネットワーク通信(クラスターおよびクロス・データセンター環境)のリソースを節約します。

ロールやグループを使ったパーミッションの割り当て

ロールとグループは、アプリケーションを使用するためのアクセスやパーミッションをユーザーに与えるという、似たような目的を持っています。グループは、ロールや属性を適用するユーザーの集合体です。ロールは、特定のアプリケーションのパーミッションとアクセス・コントロールを定義します。

ロールは通常、1種類のユーザーに適用されます。たとえば、ある組織では  adminusermanager 、 そして employee というロールがあります。アプリケーションはロールにアクセスやパーミッションを割り当て、複数のユーザーをそのロールに割り当てて、ユーザーが同じアクセスやパーミッションを持てるようにすることができます。たとえば、管理コンソールには、管理コンソールのさまざまな部分にアクセスするためのパーミッションをユーザーに与えるロールがあります。

ロールのためのグローバルな名前空間があり、各クライアントもロールを定義できる専用の名前空間を持っています。

レルムロールの作成

レルムレベルのロールは、ロールを定義するための名前空間です。ロールの一覧を表示するには、メニューの Realm Roles をクリックします。

roles

手順
  1. Create Role をクリックします。

  2. Role Name を入力します。

  3. Description を入力します。

  4. Save をクリックします。

ロールの追加

Add role

description フィールドは、置換変数に $${var-name}} という文字列を指定することでローカライズすることができます。ローカライズされた値は、テーマのプロパティー・ファイルの中で、あなたのテーマに設定されます。詳しくは Server Developer Guide を参照してください。

クライアントロール

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

ロールを複合ロールに変換する

レルムレベルまたはクライアントレベルのロールはすべて、 複合ロール にすることができます。複合ロールとは、1つ以上のロールを関連付けたロールのことです。複合ロールがユーザーにマップされると、そのユーザーは複合ロールに関連付けられたロールを継承します。この継承は再帰的であるため、ユーザーは複合ロールの複合ロールをも継承します。ただし、複合ロールは使いすぎないようにすることをお勧めします。

手順
  1. メニューの Realm Roles をクリックします。

  2. 変換するロールをクリックします。

  3. Actions の一覧から、 Add associated roles を選択します。

複合ロール

Composite role

ロールを選択するUIが表示され、作成中の複合ロールにレルムレベルとクライアントレベルのロールを関連付けることができます。

この例では、 employee レルムレベルロールは developer 複合ロールと関連付けられています。 developer ロールを持つユーザーは、 employee ロールも継承します。

トークンおよびSAMLアサーションを作成する場合、どの複合ロールでも、関連するロールがクライアントに返される認証レスポンスのクレームおよびアサーションに追加されます。

ロールマッピングの割り当て

ロールマッピングは、そのユーザーの Role Mappings タブで割り当てることができます。

手順
  1. メニューの Users をクリックします。

  2. ロールマッピングを実行したいユーザーをクリックします。

  3. Role mappings タブをクリックします。

  4. Assign role をクリックします。

  5. ユーザーに割り当てるロールをダイアログから選択します。

  6. Assign をクリックします。

ロールマッピング

Role mappings

この例では、あるユーザーに対して複合ロール developer を割り当てています。このロールは複合ロールのトピックで作成されました。

効果的なロールマッピング

Effective role mappings

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

デフォルトロールの使用

デフォルトロールを使用すると、アイデンティティー・ブローカリングでユーザーを作成またはインポートしたときに、ユーザー・ロール・マッピングを自動的に割り当てることができます。

手順
  1. メニューの Realm settings をクリックします。

  2. User registration タブをクリックします。

    デフォルトロール

    Default roles

このスクリーン・ショットは、いくつかの default roles が既に存在していることを示しています。

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

OIDCのアクセストークンまたはSAMLのアサーションの作成時に、ユーザー・ロール・マッピングはトークンまたはアサーション内のクレームとなります。アプリケーションはこれらのクレームを使用して、アプリケーションによって制御されるリソースへのアクセスを決定します。Keycloakはアクセストークンにデジタル署名を行い、アプリケーションはそれを再利用してリモートでセキュリティー保護されたRESTサービスを呼び出します。しかし、これらのトークンにはリスクが伴います。攻撃者はこれらのトークンを入手し、そのパーミッションを使用してネットワークを侵害することができます。このような状況を防ぐには、ロール・スコープ・マッピング を使用します。

ロール・スコープ・マッピング は、アクセストークン内で宣言されるロールを制限します。クライアントがユーザーに認証を要求すると、 受け取ったアクセストークンには、クライアントのスコープに対して 明示的に指定されたロールマッピングのみが含まれます。その結果、クライアントにすべてのユーザー・パーミッションへのアクセスを与える代わりに、個々のアクセストークンのパーミッションを制限することになります。

デフォルトでは、各クライアントは、そのユーザーのすべてのロールマッピングを取得します。クライアントのロールマッピングを表示することができます。

手順
  1. メニューの Clients をクリックします。

  2. クライアントをクリックすると、詳細が表示されます。

  3. Client scopes タブをクリックします。

  4. Dedicated scope and mappers for this client の行のリンクをクリックします。

  5. Scope タブをクリックします。

Full scope

Full scope

デフォルトでは、スコープの有効なロールはレルム内で宣言されたすべてのロールになります。このデフォルトの動作を変更するには、Full Scope AllowedON に切り替えて、各クライアントで必要な特定のロールを宣言します。また、クライアント・スコープ を使用して、一連のクライアントに対して同じロール・スコープ・マッピングを定義できます。

Partial scope

Partial scope

グループ

Keycloakのグループは、各ユーザーの属性とロールマッピングの共通セットを管理します。ユーザーは任意の数のグループのメンバーになることができ、各グループに割り当てられた属性とロールマッピングを継承します。

グループを管理するには、メニューの Groups をクリックします。

グループ

groups

グループは階層構造になっています。グループは複数のサブグループを持つことができますが、1つのグループは1つの親を持つことができるだけです。サブグループは、親グループの属性とロールマッピングを継承します。ユーザーは、その親から属性とロールマッピングを継承します。

親グループと子グループがあり、子グループにのみ所属するユーザーがいる場合、子グループのユーザーは、親グループと子グループの両方の属性とロールマッピングを継承します。

次の例では、トップレベルの Sales グループと子グループの North America サブグループが含まれています。

グループを追加するには、以下のようにします。

  1. グループをクリックします。

  2. Create group をクリックします。

  3. グループ名を入力します。

  4. Create をクリックします。

  5. グループ名をクリックします。

    グループ管理ページが表示されます。

    グループ

    group

定義した属性とロールマッピングは、グループのメンバーであるグループとユーザーに継承されます。

ユーザーをグループに追加するには、以下のようにします。

  1. メニューの Users をクリックします。

  2. ロールマッピングを行いたいユーザーをクリックします。ユーザーが表示されていない場合は、 View all users をクリックします。

  3. Groups をクリックします。

    ユーザーグループ

    user groups

  4. Join Group をクリックします。

  5. ダイアログからグループを選択します。

  6. Available Groups ツリーからグループを選択します。

  7. Join をクリックします。

ユーザーからグループを削除するには、以下のようにします。

  1. メニューの Users をクリックします。

  2. グループから削除するユーザーをクリックします。

  3. グループの表の Leave をクリックします。

この例では、ユーザー_jimlincoln_ は North America グループに所属しています。グループの Members タブに jimlincoln が表示されているのが確認できます。

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

group membership

グループとロールの比較

グループとロールには、いくつかの類似点と相違点があります。Keycloakでは、グループはユーザーの集まりで、これにロールと属性を適用します。ロールはユーザーの種類を定義し、アプリケーションはロールにパーミッションとアクセス・コントロールを割り当てます。

複合ロールは、同じ機能を提供するため、グループと似ています。両者の違いは概念的なものです。複合ロールは、一連のサービスおよびアプリケーションにパーミッション・モデルを適用します。アプリケーションとサービスを管理するには、複合ロールを使用します。

グループは、組織内のユーザーとそのロールの集合体にフォーカスします。ユーザーを管理するには、グループを使用します。

デフォルト・グループの使用

作成されたユーザーやアイデンティティー・ブローカリングでインポートされたユーザーに自動的にグループメンバーを割り当てるには、デフォルト・グループを使用します。

  1. メニューの Realm settings をクリックします。

  2. User registration タブをクリックします。

  3. Default Groups タブをクリックします。

    デフォルト・グループ

    Default groups

このスクリーン・ショットは、いくつかの default groups が既に存在していることを示しています。

認証の設定

この章では、いくつかの認証に関するトピックを取り上げます。これらのトピックは以下のとおりです。

  • 厳格なパスワードとワンタイム・パスワード(OTP)ポリシーの実施

  • 異なるクレデンシャル・タイプの管理

  • Kerberosによるログイン

  • 組み込みのクレデンシャル・タイプの無効化および有効化

パスワードポリシー

Keycloakがレルムを作成するとき、パスワード・ポリシーをレルムに関連付けません。長さ、セキュリティー、複雑さに制限のない単純なパスワードを設定できます。単純なパスワードは、プロダクション環境では受け入れられません。Keycloakには、管理コンソールで利用可能なパスワード・ポリシーのセットがあります。

手順
  1. メニューの Authentication をクリックします。

  2. Policies タブをクリックします。

  3. 追加するポリシーを Add policy ドロップダウン・ボックスで選択します。

  4. 選択したポリシーに適用される値を入力します。

  5. Save をクリックします。

    パスワードポリシー Password Policy

ポリシーを保存した後、Keycloakは新しいユーザーに対してポリシーを適用し、既存のユーザーに対しては、次回ログイン時にパスワードが変更されるようにパスワードの更新アクションを設定します。たとえば、次のようになります。

Failed password policy

Failed Password Policy

Password policy types

HashAlgorithm

パスワードは平文で保存されません。保存や検証の前に、Keycloakは標準的なハッシュ・アルゴリズムでパスワードをハッシュします。PBKDF2 は、組み込みで利用可能な唯一のデフォルトのアルゴリズムです。独自のハッシュアルゴリズムを追加する方法については、 Server Developer Guide を参照してください。

ハッシュ・アルゴリズムを変更した場合、ユーザーがログインするまで、ストレージ内のパスワード・ハッシュは変更されません。

Hashing iterations

保存または検証前にKeycloakがパスワードをハッシュ化する回数を指定します。初期値は27,500回です。

Keycloakは、パスワード・データベースにアクセスできる敵対的な行為者がリバース・エンジニアリングによってパスワードを読み取れないようにするためにパスワードをハッシュ化します。

ハッシュ化の繰り返し値が大きいと、より高いCPUパワーを必要とするため、パフォーマンスに影響を与える可能性があります。

Digits

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

Lowercase characters

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

Uppercase characters

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

Special characters

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

Not username

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

Not email

パスワードは、ユーザーの電子メールアドレスと同じにはできません。

Regular expression

パスワードは、定義された1つ以上の正規表現パターンに一致する必要があります。

Expire password

パスワードの有効日数です。日数が過ぎると、ユーザーはパスワードを変更する必要があります。

Not recently used

パスワードは、ユーザーが既に使用しているものではありません。Keycloakは、使用されたパスワードの履歴を保存します。古いパスワードの保存数はKeycloakで設定可能です。

Password blacklist

パスワードは、ブラックリスト・ファイルに含まれていてはいけません。

  • ブラックリスト・ファイルは、UTF-8のプレーンなテキストファイルで、Unixの行末を使用しています。各行はブラックリストに登録されたパスワードを表します。

  • Keycloakは、大文字と小文字を区別せずにパスワードを比較します。ブラックリストに登録するパスワードはすべて小文字でなければなりません。

  • ブラックリスト・ファイルの値は、ブラックリスト・ファイルの名前でなければならない。

  • ブラックリストファイルは、デフォルトで ${jboss.server.data.dir}/password-blacklists/ に対して解決されます。このパスをカスタマイズするには次のプロパティーを使用します。

    • keycloak.password.blacklists.path プロパティー。

    • passwordBlacklist ポリシーSPIの設定の blacklistsPath プロパティー。

ワンタイムパスワード(OTP)ポリシー

Keycloakには、FreeOTPやGoogle Authenticatorのワンタイム・パスワード・ジェネレーターを設定するためのポリシーがいくつかあります。 Authentication メニューをクリックし、 OTP Policy タブをクリックします。

OTPポリシー

OTP Policy

Keycloakは、 OTP Policy タブで設定した情報を元に、OTP設定画面でQRコードを生成します。FreeOTPとGoogle Authenticatorは、OTP設定時にこのQRコードを読み取ります。

タイムベースまたはカウンターベースのワンタイムパスワード

OTPジェネレーターに使用できるKeycloakのアルゴリズムは、タイムベースとカウンターベースがあります。

タイムベースのワンタイムパスワード(TOTP)では、トークン生成器が現在の時刻と共有のシークレットをハッシュ化します。サーバーは、時間枠内のハッシュと提出された値を比較することで、OTPを検証します。TOTPは、短い時間枠の中で有効です。

カウンターベースのワンタイムパスワード(HOTP)では、Keycloak は現在時刻ではなく、共有カウンターを使用します。project_name}サーバーは、OTPログインが成功するたびにカウンターを増加させる。有効なOTPはログインに成功すると変化します。

TOTPは、HOTPのOTPが不定期に有効なのに対し、マッチング可能なOTPが短時間で有効なため、HOTPよりも安全性が高い。HOTPは、OTPの入力に時間制限がないため、TOTPよりもユーザーフレンドリーである。

HOTPは、サーバーがカウンターをインクリメントするたびに、データベースの更新を必要とします。この更新は、高負荷時に認証サーバーのパフォーマンスを低下させる。効率を上げるため、TOTPは使用したパスワードを記憶しないので、データベースの更新を行う必要はありません。欠点は、有効時間内にTOTPを再利用することが可能なことである。

TOTPの設定オプション

OTP hash algorithm

デフォルトのアルゴリズムはSHA1です。他の、より安全なオプションは、SHA256とSHA512です。

Number of digits

OTPの長さ。 短いOTPはユーザーフレンドリーで、入力が簡単で、覚えやすい。長いOTPは、短いOTPよりも安全です。

Look around window

サーバーがハッシュの照合を試みる間隔数です。このオプションは、TOTP生成器または認証サーバの時計が同期していない場合のためにKeycloakに存在しています。デフォルトの1が適切です。たとえば、トークンの時間間隔が30秒の場合、デフォルト値の1は、90秒のウィンドウ(時間間隔30秒 + 前方間隔30秒 + 後方監視30秒)で有効なトークンを受け入れることを意味します。この値を1つ増やすごとに、有効なウィンドウが60秒ずつ増加します(時間間隔30秒 + 後方監視30秒)。

OTP token period

サーバーがハッシュを照合する時間間隔(秒)。この間隔が経過するたびに、トークン生成器はTOTPを生成する。

再利用可能なコード

OTPトークンを認証プロセスで再利用できるか、ユーザーが次のトークンを待つ必要があるかを判断します。デフォルトでは、ユーザーはこれらのトークンを再利用できないので、管理者はこれらのトークンを再利用できるように明示的に指定する必要があります。

HOTP configuration options

OTP hash algorithm

デフォルトのアルゴリズムはSHA1です。他の、より安全なオプションは、SHA256とSHA512です。

Number of digits

OTPの長さ。 短いOTPはユーザーフレンドリーで、入力が簡単で、覚えやすい。長いワンタイムパスワードは、短いワンタイムパスワードよりも安全です。

Look ahead window

サーバーがハッシュの照合を試みる間隔数。このオプションは、TOTP生成器または認証サーバの時計が同期していない場合にKeycloak に存在する。デフォルトの1が適切である。このオプションは Keycloak にあり、ユーザのカウンタがサーバより先に進んでしまった場合に対応する。

Initial counter

初期カウンターの値。

認証フロー

認証フローとは、ログインや登録などのKeycloakのワークフローにおける、認証、画面、アクションのコンテナーのことです。すべてのフロー、アクション、およびチェックを表示するには、各フローに以下が必要です。

組み込みフロー

Keycloakには、いくつかの組み込みフローがあります。これらのフローを変更することはできませんが、フローのRequirementを自分のニーズに合わせて変更することは可能です。

手順
  1. メニューの Authentication をクリックします。

  2. リスト内の ブラウザー の項目をクリックすると、詳細が表示されます。

ブラウザーフロー

Browser Flow

Auth type

認証または実行するアクションの名前。認証がインデントされている場合は、サブフローに含まれます。これは、親の動作によって実行される場合とされない場合があります。

  1. Cookie

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

  2. Kerberos

    このオーセンティケーターはデフォルトで無効になっており、ブラウザーフローではスキップされます。

  3. Identity Provider Redirector

    このアクションは Actions > Config のリンクから設定します。アイデンティティー・ブローカリングの別のIdPにリダイレクトします。

  4. Forms

    このサブフローは alternative とマークされているため、 Cookie 認証タイプが渡された場合は実行されません。このサブフローには、実行する必要がある追加の認証タイプが含まれています。Keycloakは、このサブフローのエグゼキューションをロードして処理します。

最初のエグゼキューションは Username Password Form で、ユーザー名とパスワードのページをレンダリングする認証タイプです。これは required とマークされているので、ユーザーは有効なユーザー名とパスワードを入力しなければなりません。

2番目のエグゼキューションは、Browser - Conditional OTP サブフローです。このサブフローは _conditional_であり、 Condition - User Configured エグゼキューションによって実行されます。結果がtrueの場合、Keycloakはこのサブフローのエグゼキューションをロードして処理します。

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

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

Requirement

アクションのエグゼキューションを制御する一連のラジオボタンが実行されます。

Required

フロー内のすべての Required 要素が順次正常に実行される必要があります。必須要素が失敗した場合、フローは終了します。

Alternative

フローが成功したと評価されるには、1つの要素だけが正常に実行される必要があります。フローが成功したと評価されるには、 Required フロー要素があれば十分なので、 Required フロー要素を含むフロー内の Alternative フロー要素は、実行されません。

Disabled

この要素は、フローを成功としてマークするためにカウントされません。

Conditional

このRequirementタイプは、サブフローにのみ設定されます。

  • Conditional サブフローはエグゼキューションを含みます。これらのエグゼキューションは、論理文として評価されなければなりません。

  • すべてのエグゼキューションが true と評価された場合、 Conditional サブフローは Required として動作します。

  • すべてのエグゼキューションが false と評価された場合、 Conditional サブフローは Disabled として動作します。

  • エグゼキューションを設定しない場合、 Conditional サブフローは Disabled として動作します。

  • フローがエグゼキューションを含み、フローが Conditional に設定されていない場合、Keycloakはエグゼキューションを評価せず、エグゼキューションは機能的に Disabled とみなされます。

フローの作成

フローを設計する際には、重要な機能性とセキュリティーに関する考慮事項が適用されます。

フローを作成するには、以下を実行します。

手順
  1. メニューの Authentication をクリックします。

  2. Create flow をクリックします。

既存のフローをコピーしてから修正することができます。 "Action list" (行末の3つの点)をクリックし、 Duplicate をクリックし、新しいフローの名前を入力します。

新しいフローを作成する場合、まず次のオプションでトップレベルのフローを作成する必要があります。

Alias

フローの名前。

説明

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

トップレベル・フロー・タイプ

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

トップレベル・フローの作成

Top Level Flow

Keycloakがフローを作成すると、Keycloakは Add stepAdd flow ボタンを表示します。

空の新しいフロー

New Flow

フローとサブフローの挙動は3つの要因で決まります。

  • フローとサブフローの構造。

  • フロー内のエグゼキューション

  • Requirementはサブフローとエグゼキューションの中で設定されます。

リセットメールの送信からワンタイムパスワードの認証まで、さまざまなアクションを実行できます。実行を追加するには、 Add step ボタンをクリックします。 Provider の横にあるクエスチョン・マークにカーソルを合わせると、実行の説明が表示されます。

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

認証エグゼキューションを追加する

自動エグゼキューション対話型エグゼキューション の2種類が存在します。 自動エグゼキューションCookie エグゼキューションと同様で、フロー内で自動的にアクションを実行します。 対話型エグゼキューション は、入力を得るためにフローを停止させます。実行が成功すると、ステータスが success に設定されます。フローが完了するには、ステータスが success である実行が少なくとも1つ必要です。

トップレベルのフローにサブフローを追加するには、 Add flow ボタンを使用します。 Add flow ボタンを押すと、 Create Execution Flow ページが表示されます。このページは、 Create Top Level Form ページと似ています。違いは、 Flow Typegeneric (デフォルト)または form を指定できることです。 form 型は、組み込みの Registration フローと同様に、ユーザー用のフォームを生成するサブフローを構築します。サブフローの成功は、含まれるサブフローを含め、そのエグゼキューションRequirementがどのように評価されるかに依存します。サブフローがどのように機能するかについての詳細な説明は、エグゼキューションのRequirementのセクションを参照してください。

エグゼキューションを追加した後、Requirementが正しい値であることを確認します。

フロー内のすべての要素には、 Actions メニューに Delete オプションがあります。このアクションは、フローから要素を削除するものです。エクゼキューションには、 ⚙️ メニュー項目(歯車アイコン)があり、エクゼキューションを設定することができます。また、 Add stepAdd flow のリンクを使用して、エクゼキューションとサブフローをサブフローに追加することが可能です。

エグゼキューションの順序が重要なです。エグゼキューションやサブフローは名前をドラッグすることで上下に移動させることができます。

認証フローを設定する際には、設定にセキュリティー・ホールが存在しないことを確認するために、適切にテストを行うようにしてください。様々なコーナーケースをテストすることをお勧めします。たとえば、認証前にユーザーのアカウントからさまざまなクレデンシャルを削除した場合の、そのユーザーの認証動作をテストすることを検討します。

たとえば、OTPフォームやWebAuthn認証などの2要素認証がフローでREQUIREDに設定されており、ユーザーが特定のタイプのクレデンシャルを持っていない場合、ユーザーは認証中に特定のクレデンシャルを設定することができるようになります。この場合、ユーザーは認証時にこのクレデンシャルを正しくセットアップしているため、このクレデンシャルでは認証されないことを意味します。したがって、ブラウザー認証では、パスワードやWebAuthn Passwordless Authenticatorなどの1要素クレデンシャルを使用して認証フローを設定するようにしてください。

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

フローの作成を説明するために、ここでは高度なブラウザー・ログイン・フローの作成について説明します。このフローの目的は、 WebAuthn を使ったパスワードレスでのログインと、パスワードとOTPによる二要素認証のどちらかをユーザーが選択できるようにすることです。

手順
  1. メニューの Authentication をクリックします。

  2. Flows タブをクリックします。

  3. Create flow をクリックします。

  4. 名前として Browser Password-less を入力します。

  5. Create をクリックします。

  6. Add execution をクリックします。

  7. リストから Cookie を選択します。

  8. Add をクリックします。

  9. 認証タイプ CookieAlternative を選択し、そのRequirementをAlternativeに設定します。

  10. Add step をクリックします。

  11. 一覧から Kerberos を選択します。

  12. Add をクリックします。

  13. Add step をクリックします。

  14. 一覧から Identity Provider Redirector を選択します。

  15. Add をクリックします。

  16. Identity Provider Redirector 認証タイプの Alternative を選択して、その要件を代替に設定します。

  17. Add sub-flow をクリックします。

  18. 名前として Forms を入力します。

  19. Add をクリックします。

  20. Forms 認証タイプの Alternative を選択して、そのRequirementをAlternativeに設定します。

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

    Passwordless browser login

  21. Forms エグゼキューションのメニューの + をクリックします。

  22. Add step を選択します。

  23. 一覧から Username Form を選択します。

  24. Add をクリックします。

この段階では、フォームにはユーザー名は必要ですが、パスワードは必要ありません。セキュリティー・リスクを回避するために、パスワード認証を有効にする必要があります。

  1. Forms サブフローのメニューの + をクリックします。

  2. Add sub-flow をクリックします。

  3. 名前として Authentication を入力します。

  4. Add をクリックします。

  5. Authentication 認証タイプの Required を選択して、そのRequirementをRequiredに設定します。

  6. Authentication サブフローの + メニューをクリックします。

  7. Add step をクリックします。

  8. リストから Webauthn Passwordless Authenticator を選択します。

  9. Add をクリックします。

  10. Webauthn Passwordless Authenticator の認証タイプの Alternative を選択して、そのRequirementをAlternativeに設定します。

  11. Authentication サブフローの + メニューをクリックします。

  12. Add sub-flow をクリックします。

  13. 名前に Password with OTP を入力します。

  14. Add をクリックします。

  15. Password with OTP 認証タイプの Alternative を選択して、そのRequirementをAlternativeに設定します。

  16. Password with OTP サブフローの + メニューをクリックします。

  17. Add step をクリックします。

  18. リストから Password Form を選択します。

  19. Add をクリックします。

  20. Password Form 認証タイプの Required を選択して、そのRequirementをRequiredに設定します。

  21. Password with OTP サブフローの + メニューをクリックします。

  22. Add step をクリックします。

  23. アイテムリストから OTP Form を選択します。

  24. Add をクリックします。

  25. OTP Form 認証タイプの Required をクリックして、そのRequirementをRequiredに設定します。

最後に、バインディングを変更します。

  1. 画面上部の Action メニューをクリックします。

  2. メニューから Bind flow を選択します。

  3. Browser Flow のドロップダウン・リストをクリックします。

  4. Save をクリックします。

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

Passwordless browser login

ユーザー名を入力すると、次のような流れで動作します。

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

WebAuthnパスワードレス認証で Try another way リンクを選択した場合、ユーザーは PasswordSecurity Key (WebAuthnパスワードレス)のどちらかを選択することができます。パスワードを選択した場合、ユーザーは割り当てられたワンタイムパスワードでログインを続ける必要があります。WebAuthnのクレデンシャルを持っていない場合、ユーザーはパスワードを入力し、次にOTPを入力する必要があります。ユーザーが OTP クレデンシャルを持っていない場合は、OTP を記録するように求められます。

WebAuthn Passwordlessのエグゼキューションが Required ではなく Alternative に設定されているため、このフローはユーザーにWebAuthnクレデンシャルの登録を要求することはありません。ユーザーにWebauthnクレデンシャルを持たせるためには、管理者がそのユーザーに必須アクションを追加する必要があります。これを行うには、以下のようにします。

  1. レルムで Webauthn Register Passwordless の必須アクションを有効にします( WebAuthn のドキュメントを参照してください)。

  2. ユーザーの Credentials 管理メニューの Credential Reset 部分を使用した必須アクションの設定。

このような高度なフローを作成すると、副作用が発生することがあります。たとえば、ユーザーのパスワードをリセットする機能を有効にした場合、パスワードフォームからアクセスできるようになります。デフォルトの Reset Credentials フローでは、ユーザーはユーザー名を入力しなければなりません。ユーザーは Browser Password-less フローですでにユーザー名を入力しているので、このアクションはKeycloakにとって不要であり、ユーザー・エクスペリエンスにとって最適とは言えません。この問題を修正するには、次のようにします。

  • Reset Credentials フローを複製します。その名前を、たとえば Reset Credentials for password-less に設定します。

  • Choose user ステップの Delete (ゴミ箱アイコン)をクリックします。

  • Action メニューで、 Bind flow を選択し、ドロップダウンから Reset credentials flow を選択し、 Save をクリックします。

ステップアップ・メカニズムのブラウザー・ログインフローの作成

このセクションでは、ステップアップ・メカニズムを利用して、高度なブラウザー・ログインフローを作成する方法について説明します。ステップアップ認証の目的は、ユーザーの特定の認証レベルに基づいて、クライアントやリソースへのアクセスを許可することです。

手順
  1. メニューの Authentication をクリックします。

  2. Flows タブをクリックします。

  3. Create flow をクリックします。

  4. 名前として Browser Incl Step up Mechanism を入力します。

  5. Save をクリックします。

  6. Add execution をクリックします。

  7. リストから Cookie を選択します。

  8. Add をクリックします。

  9. 認証タイプ CookieAlternative を選択し、そのRequirementをAlternativeに設定します。

  10. Add sub-flow をクリックします。

  11. 名前に Auth Flow を入力します。

  12. Add をクリックします。

  13. Auth Flow 認証タイプの Alternative をクリックして、そのRequirementをAlternativeに設定します。

ここで、最初の認証レベルのフローを設定します。

  1. Auth Flow+ メニューをクリックします。

  2. Add sub-flow をクリックします。

  3. 名前として 1st Condition Flow を入力します。

  4. Add をクリックします。

  5. 1st Condition Flow 認証タイプの Conditional をクリックして、そのRequirementをConditionalに設定します。

  6. 1st Condition Flow+ メニューをクリックします。

  7. Add condition をクリックします。

  8. リストから、 Conditional - Level Of Authentication を選択します。

  9. Add をクリックします。

  10. Conditional - Level Of Authentication 認証タイプの Required をクリックして、そのRequirementをRequiredに設定します。

  11. Conditional - Level Of Authentication+ メニューをクリックします。

  12. ⚙️ (歯車アイコン)をクリックします。

  13. エイリアスとして Level 1 を入力します。

  14. Level of Authentication (LoA) には 1 を入力します。

  15. Max Ageを 36000 に設定します。この値は秒単位で、レルムで設定されているデフォルトの SSO Session Max タイムアウトである10時間に相当します。その結果、ユーザーがこのレベルで認証すると、その後のSSOログインではこのレベルを再利用でき、ユーザーはユーザーセッションが終了するまでこのレベルで認証する必要はありません(デフォルトでは10時間です)。

  16. Save をクリックします。

    最初の認証レベルの条件設定

    Authentication step up condition 1

  17. 1st Condition Flow+ メニューをクリックします。

  18. Add step をクリックします。

  19. リストから Username Password Form を選択します。

  20. Add をクリックします。

次に、2つ目の認証レベルのフローを設定します。

  1. Auth Flow+ メニューをクリックします。

  2. Add sub-flow をクリックします。

  3. エイリアスとして 2nd Condition Flow を入力します。

  4. Add をクリックします。

  5. 2nd Condition Flow 認証タイプの Conditional をクリックして、そのRequirementをConditionalに設定します。

  6. 2nd Condition Flow+ メニューをクリックします。

  7. Add condition をクリックします。

  8. アイテムリストから、 Conditional - Level Of Authentication を選択します。

  9. Add をクリックします。

  10. Conditional - Level Of Authentication 認証タイプの Required をクリックして、そのRequirementをRequiredに設定します。

  11. ⚙️ (歯車アイコン)をクリックします。

  12. エイリアスとして Level 2 を入力します。

  13. Level of Authentication (LoA) には 2 を入力します。

  14. Max Ageを 0 に設定します。その結果、ユーザーが認証するとき、このレベルは現在の認証に対してのみ有効で、それ以降のSSO認証には有効ではありません。そのため、このレベルが要求された場合、ユーザーは常にこのレベルで再度認証する必要があります。

  15. Save をクリックします。

    2つ目の認証レベルの条件設定

    Autehtnication step up condition 2

  16. 2nd Condition Flow+ メニューをクリックします。

  17. Add step をクリックします。

  18. アイテムリストから OTP Form を選択します。

  19. Add をクリックします。

  20. OTP Form 認証タイプの Required をクリックして、そのRequirementをRequiredに設定します。

最後に、バインディングを変更します。

  1. 画面上部の Action メニューをクリックします。

  2. リストから Bind flow を選択します。

  3. ドロップダウンで Browser Flow を選択します。

  4. Save をクリックします。

ステップアップ・メカニズムのブラウザー・ログインフロー

Authentication step up flow

特定の認証レベルの要求

ステップアップ・メカニズムを利用するためには、認証リクエストで要求された認証レベル(LoA)を指定します。このために、 claims パラメーターが使用されます。

https://{DOMAIN}/realms/{REALMNAME}/protocol/openid-connect/auth?client_id={CLIENT-ID}&redirect_uri={REDIRECT-URI}&scope=openid&response_type=code&response_mode=query&nonce=exg16fxdjcu&claims=%7B%22id_token%22%3A%7B%22acr%22%3A%7B%22essential%22%3Atrue%2C%22values%22%3A%5B%22gold%22%5D%7D%7D%7D

claims パラメーターは、JSON形式で指定されます。

claims= {
            "id_token": {
                "acr": {
                    "essential": true,
                    "values": ["gold"]
                }
            }
        }

KeycloakのJavaScriptアダプターは、このJSONを簡単に構築し、ログイン・リクエストに送信するためのサポートを備えています。詳しくは、 JavaScriptアダプターのドキュメントを参照してください。

また、 claims パラメーターの代わりに、よりシンプルなパラメーター acr_values を使用することで、特定のレベルを非必須として要求することができます。これはOIDCの仕様に記載されています。

また、特定のクライアントのデフォルトレベルを設定することもできます。このレベルは、パラメーター acr_values または acr クレームを持つパラメーター claims が存在しない場合に使用されます。詳しくは、Client ACR設定を参照してください)。

acr_valuesを数値ではなくテキスト( gold など)で要求するには、ACRとLoAの間のマッピングを設定します。レルムレベル(推奨)またはクライアント・レベルで設定することが可能である。設定方法については、ACRからLoAへのマッピングを参照してください。

詳細については、 オフィシャルのOIDC仕様 を参照してください。

フローロジック

前回設定した認証フローのロジックは以下の通りです。
クライアントが高い認証レベル、つまり認証レベル2(LoA 2)を要求した場合、ユーザーは完全な2要素認証を実行する必要があります。ユーザー名/パスワード + OTPの2要素認証が必要です。しかし、ユーザーが既にKeycloakのセッションを持っていて、もしユーザー名とパスワードでログインしていた場合(LoA 1)、ユーザーは2つ目の認証要素(OTP)だけを要求されます。

条件のオプション Max Age は、後続の認証レベルが有効な時間(何秒)を決定します。この設定は、後続の認証時にユーザーが再び認証要素の提示を求められるかどうかを決定するのに役立ちます。もし claims または acr_values パラメーターによって特定のレベルXが要求され、ユーザーがすでにレベルXで認証しているにもかかわらず、その有効期限が切れている場合(たとえば、最大年齢が300に設定されていて、ユーザーが310秒以前に認証された場合)、ユーザーはそのレベルで再認証を要求されることになります。しかし、そのレベルがまだ有効期限切れでない場合、そのユーザーは自動的にそのレベルで認証されたとみなされます。

値0の Max Age を使用すると、その特定のレベルがこの 1 回の認証に対してのみ有効であることを意味します。したがって、そのレベルを要求する再認証のたびに、そのレベルで再度認証する必要があります。これは、アプリケーションでより高いセキュリティーを必要とし(例:支払いの送信)、常に特定のレベルでの認証を必要とする操作に便利です。

クライアントからユーザーのブラウザーを経由してKeycloakにログイン要求を送信する際、URL中の claimsacr_values などのパラメーターがユーザーによって変更される可能性があることに注意してください。このような事態は、クライアントがPAR(Pushed authorization request)、リクエスト・オブジェクト、またはURLのパラメーターをユーザーが書き換えることを防ぐ他のメカニズムを使用することで軽減することができます。したがって、認証後はIDトークンを確認し、トークン内の acr が期待されるレベルであることを再確認することが推奨されます。

パラメーターで明示的なレベルが要求されていない場合、Keycloakは、認証フローで最初に見つかったLoA条件(前述の例のUsername/Passwordなど)で認証を要求します。既にそのレベルで認証されているユーザーが、そのレベルの有効期限が切れた場合、ユーザーは再認証を要求されないが、トークンの acr は値0となります。この結果は、OIDC Core 1.0の仕様のセクション2にある long-lived browser cookie のみに基づく認証とみなされます。

管理者が複数のフローを指定し、それぞれに異なるLoAのレベルを設定し、異なるクライアントにフローを割り当てる場合、競合する状況が発生するおそれがあります。しかし、ルールは常に同じです。あるユーザーがあるレベルを持っていれば、そのレベルが必要なクライアントにだけ接続できます。LoAに一貫性があるかどうかは、管理者次第です。

サンプルのシナリオ

  1. レベル1条件ではMax Ageは300秒に設定されています。

  2. Acrを要求せずにログイン・リクエストを送信します。レベル1が使用されると、ユーザーはユーザー名とパスワードで認証される必要があります。トークンは acr=1 となります。

  3. 100秒後に別のログイン要求が送信されます。SSOによりユーザーは自動的に認証され、トークンは acr=1 を返します。

  4. さらに201秒後に別のログイン・リクエストが送信されます(ポイント2の認証から301秒後)。SSOによりユーザーは自動的に認証されますが、レベル1が期限切れであるため、トークンは acr=0 を返します。

  5. 別のログイン・リクエストが送信されますが、今度は claims パラメーターにレベル 1のACRを明示的に要求します。ユーザーはユーザー名/パスワードで再認証を求められ、トークンに acr=1 が 返されることになります。

トークン内のACRクレーム

ACRクレームは acr クライアント・スコープで定義された acr loa level プロトコル・マッパーによってトークンに追加されます。このクライアント・スコープはレルムのデフォルトのクライアント・スコープであるため、レルムで新しく作成されたすべてのクライアントに追加されます。

トークンの中に acr というクレームを入れたくない場合や、それを追加するためのカスタムロジックが必要な場合は、クライアントからクライアント・スコープを削除することができます。

ログイン・リクエストが claims パラメーターで acressential クレームとして要求するリクエストを開始した場合、Keycloakは常に指定されたレベルのいずれかを返すことに注意してください。指定されたレベルのいずれかを返すことができない場合(たとえば、要求されたレベルが不明であったり、認証フローで設定された条件よりも大きい場合)、Keycloakはエラーをスローします。

ユーザーセッションの制限

ユーザーが持つことができるセッション数の制限を設定することができます。セッションは、レルムごと、またはクライアントごとに制限することができます。

フローにセッション制限を追加するには、次の手順を実行します。

  1. フローの Add step をクリックします。

  2. アイテムリストから User session count limiter を選択します。

  3. Add をクリックします。

  4. User Session Count Limiter 認証タイプの Required をクリックし、その要件をrequiredに設定します。

  5. User Session Count Limiter⚙️ (歯車アイコン)をクリックします。

  6. この設定のエイリアスを入力します。

  7. ユーザーがこのレルムで持つことができるセッションの必要な最大数を入力します。たとえば、2が値である場合、2つのSSOセッションが、各ユーザーがこのレルムで持つことができる最大値です。0が値である場合、このチェックは無効です。

  8. ユーザーがクライアントのために持つことができるセッションの必要な最大数を入力します。たとえば、値が2であれば、このレルムでは各クライアントに対して2つのSSOセッションが最大となります。したがって、あるユーザーがクライアント foo に対して認証を行おうとしているが、そのユーザーはすでにクライアント foo に対して2つのSSOセッションで認証している場合、設定に基づいて、認証が拒否されるか、既存のセッションが強制終了されるかのどちらかになります。0を指定した場合、このチェックは無効になります。セッション制限とクライアント・セッション制限の両方が有効な場合、クライアント・セッション制限をセッション制限より常に低くすることは理にかなっています。クライアントごとの制限は、このユーザーのすべてのSSOセッションの制限を超えることはできません。

  9. 制限に達した後、ユーザーがセッションを作成しようとしたときに必要な動作を選択します。利用可能な動作は以下の通りです。

    • Deny new session - 新しいセッションが要求され、セッションの制限に達した場合、新しいセッションを作成することはできません。

    • Terminate oldest session - 新しいセッションが要求され、セッションの制限に達した場合、最も古いセッションが削除され、新しいセッションが作成されます。

  10. オプションで、制限に達したときに表示されるカスタム・エラー・メッセージを追加することができます。

ユーザー・セッションの制限は、 Browser flowDirect grant flowReset credentials に加え、 Post broker login flow にも追加する必要があることに留意してください。オーセンティケーターは、認証時にユーザーが既に知られている時点(通常は認証フローの最後)で追加する必要があり、通常はREQUIREDにする必要があります。ALTERNATIVEとREQUIREDを同じレベルで実行することは不可能であることに注意してください。たとえば、デフォルトのブラウザーフローでは、既存のフローをREQUIREDレベル1サブフローとしてラップし、この新しいサブフローと同じレベルに User Session Count Limiter を追加する必要があるかもしれません。このようなフローの例を以下に示します。

Authentication User Session Limits Flow

現状では、異なる設定間の整合性を維持するのは管理者の責任です。

また、CIBAではユーザー・セッションの制限機能は利用できませんのでご注意ください。

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

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

詳しくは、 JavaScript Providers を参照してください。

Kerberos

Keycloakは、Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) プロトコルによるKerberosチケットを使ったログインをサポートしています。SPNEGOは、ユーザーがセッションを認証した後、Webブラウザーを通じて透過的に認証します。Web以外の場合、またはログイン時にチケットが利用できない場合、KeycloakはKerberosのユーザー名とパスワードによるログインをサポートします。

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

  1. ユーザーはデスクトップにログインする。

  2. ユーザーはブラウザーを使ってKeycloakで保護されたWebアプリケーションにアクセスします。

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

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

  5. ブラウザーがデスクトップ・ログイン時のKerberosチケットを持っている場合、ブラウザーはデスクトップのサインオン情報を Authorization: Negotiate 'spnego-token' ヘッダーでKeycloakへ転送します。そうでなければ、標準的なログイン画面が表示され、ユーザーはログインクレデンシャルを入力します。

  6. Keycloakは、ブラウザーから送信されたトークンを検証し、ユーザーを認証します。

  7. Kerberos認証をサポートするLDAPFederationProviderを使用する場合、KeycloakはLDAPからユーザーデータをプロビジョニングします。KerberosFederationProviderを使用する場合、Keycloakは、ユーザーにプロフィールの更新とログインデータの事前入力をさせます。

  8. Keycloakはアプリケーションに戻ります。KeycloakとアプリケーションはOpenID ConnectまたはSAMLメッセージで通信します。Keycloakは、Kerberos/SPNEGOログインのブローカーとして動作します。そのため、KeycloakがKerberosで認証していることは、アプリケーションからは見えません。

以下の手順で、Kerberos認証を設定します。

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

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

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

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

Kerberosサーバーをセットアップする手順は、オペレーティング・システム(OS)とKerberosベンダーに依存します。Windows Active Directory、MIT Kerberos、およびお使いのOSのマニュアルを参照して、Kerberosサーバーのセットアップと設定を確認してください。

セットアップ時には、以下の手順で行ってください。

  1. Kerberosデータベースにユーザー・プリンシパルを追加します。また、KerberosをLDAPと統合し、LDAPサーバーからユーザー・アカウントをプロビジョニングすることも可能です。

  2. "HTTP" サービス用のサービス・プリンシパルを追加します。たとえば、Keycloakサーバーが www.mydomain.org で動作している場合、 HTTP/www.mydomain.org@<kerberos realm> というサービスプリンシパルを追加します。

    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

Keycloakが動作しているホストで、keytabファイル /tmp/http.keytab にアクセスできることを確認します。

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

マシンにKerberosクライアントをインストールします。

手順
  1. Kerberosクライアントをインストールします。Fedora、Ubuntu、または RHELを使用している場合は、Kerberosクライアントとその他のユーティリティーを含む freeipa-client パッケージをインストールします。

  2. Kerberosクライアントの設定(Linuxでは、 /etc/krb5.conf ファイルに設定されています)。

    Kerberosレルムを設定に追加し、サーバーが実行されるHTTPドメインを設定します。

    たとえば、MYDOMAIN.ORGレルムでは、 domain_realm のセクションを次のように設定します。

    [domain_realm]
      .mydomain.org = MYDOMAIN.ORG
      mydomain.org = MYDOMAIN.ORG
  3. HTTPプリンシパルでkeytabファイルをエクスポートし、そのファイルがKeycloakサーバーを実行しているプロセスからアクセス可能であることを確認します。実稼働環境では、このファイルがこのプロセスによってのみ読み取り可能であることを確認します。

    上記のMIT Kerberosの例では、keytabを /tmp/http.keytab ファイルにエクスポートしています。もし、Key Distribution Centre (KDC) とKeycloakが同じホストで動いていれば、このファイルはすでに利用可能です。

SPNEGO処理の有効化

デフォルトでは、KeycloakはSPNEGOプロトコルのサポートを無効にします。有効にするには、ブラウザーフローKerberos を有効にしてください。

ブラウザーフロー

Browser Flow

Kerberos のRequirementを Disabled から Alternative (Kerberosはオプション)または Required (ブラウザーでKerberosを有効にする必要がある)に設定します。SPNEGOまたはKerberosで動作するようにブラウザーを設定していない場合、Keycloakは通常のログイン画面に戻ります。

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

ここでユーザー・ストレージ・フェデレーションを使用して、KeycloakがKerberosチケットを解釈する方法を設定する必要があります。Kerberos認証をサポートする2つの異なるフェデレーション・プロバイダーが存在します。

LDAPサーバーにバックアップされたKerberosで認証するには、LDAPフェデレーション・プロバイダーを設定します。

手順
  1. LDAPプロバイダーの設定ページに移動します。

    LDAPとKerberosの統合

    LDAP Kerberos Integration

  2. Allow Kerberos authenticationON にします。

Kerberos認証 を許可すると、KeycloakはKerberosプリンシパル・アクセス・ユーザー情報を使用し、Keycloak 環境に情報をインポートできるようになります。

LDAPサーバーがKerberosソリューションをバックアップしていない場合、 Kerberos ユーザー・ストレージ・フェデレーション・プロバイダーを使用します。

手順
  1. メニューの User Federation をクリックします。

  2. Add provider セレクトボックスから Kerberos を選択します。

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

    Kerberos User Storage Provider

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

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

クライアントマシンはKerberosクライアントを持ち、で説明したように krb5.conf を設定する必要があります。また、クライアント・マシンは、ブラウザーでSPNEGOログインサポートを有効にしなければなりません。Firefoxを使用している場合は、Kerberos用にFirefoxを設定するを参照してください。

.mydomain.org のURI は network.negotiate-auth.trusted-uris 設定オプションに含まれていなければなりません。

Windowsドメインでは、クライアント側で設定を調整する必要はありません。Internet ExplorerとEdgeは、すでにSPNEGO認証に参加することができます。

設定例

KeycloakとFreeIPAのdockerイメージ

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

ApacheDSテストKerberosサーバー

クイックテストとユニットテストのために、単純な ApacheDS Kerberosサーバーを使用します。ソースからKeycloakをビルドし、私たちのテストスイートから取得したmaven-exec-pluginを使ってKerberosサーバーを実行する必要があります。詳細は ここ を参照してください。

クレデンシャルの委譲

Kerberosはクレデンシャルの委譲をサポートします。アプリケーションは、Kerberosチケットにアクセスする必要があり、Kerberosでセキュリティー保護された他のサービスと対話するためにそれを再使用することができます。KeycloakサーバーはSPNEGOプロトコルを処理したため、OpenID ConnectトークンのクレームまたはSAMLアサーションの属性内で GSSクレデンシャルをアプリケーションに伝搬させる必要があります。Keycloak は、これをKeycloakサーバーからアプリケーションに送信します。このクレームをトークンまたはアサーションに挿入するには、各アプリケーションは組み込みのプロトコル・マッパーである gss delegation credential を有効にする必要があります。このマッパーは、アプリケーションのクライアント・ページの Mappers タブで利用可能です。 詳細はプロトコル・マッパー の章を参照してください。

アプリケーションはKeycloakから受け取ったクレームを、他のサービスに対してGSSコールを行う前にデシリアライズする必要があります。アクセストークンから GSSCredential オブジェクトにクレデンシャルをデシリアライズしたら、 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 ファイルに forwardable Kerberosチケットを設定し、ブラウザーに委任されたクレデンシャルのサポートを追加します。

クレデンシャルの委譲はセキュリティー上の問題があるため、必要な場合のみ使用し、HTTPSでのみ使用してください。詳細と例については、 この記事 を参照してください。

クロスレルム・トラスト

Kerberosプロトコルにおいて、 realm はKerberosプリンシパルの集合です。これらのプリンシパルの定義はKerberosデータベースに存在し、それは通常LDAPサーバーです。

Kerberosプロトコルは、レルム間の信頼を可能にします。たとえば、2つのKerberosレルム、AとBが存在する場合、レルム間信頼はレルムAからのユーザがレルムBのリソースにアクセスすることを可能にします。レルムBはレルムAを信頼します。

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

kerberos trust basic

Keycloakサーバーは、クロス・レルム・トラストをサポートしています。これを実装するには、以下を実行します。

  • クロス・レルム・トラストのためにKerberosサーバを設定します。このステップの実装は、Kerberosサーバーの実装に依存します。このステップは、Kerberosプリンシパル krbtgt/B@A をレルムAとレルムBのKerberosデータベースに追加するために必要です。プリンシパルは両方のレルムで同じパスワード、鍵のバージョン番号、暗号を持たなければなりません。詳細については、Kerberos サーバーのドキュメントを参照してください。

クロス・レルム・トラストは、デフォルトでは一方向的です。レルムAとレルムBの間で双方向の信頼を行うには、両方のKerberosデータベースに krbtgt/A@B というプリンシパルを追加する必要があります。しかし、デフォルトでは信頼は推移的です。レルムBがレルムAを信頼し、レルムCがレルムBを信頼する場合、レルムCはプリンシパル krbtgt/C@A を使用せずにレルムAを信頼することになります。クライアントがトラストパスを見つけられるように、Kerberosのクライアントサイドで追加の設定 (たとえば capaths ) が必要かもしれません。詳細についてはKerberosのドキュメントを参照してください。

  • Keycloakサーバーの設定

    • KerberosをサポートするLDAPストレージ・プロバイダーを使用する場合、 HTTP/mydomain.com@B のようにレルムBのサーバー・プリンシパルを設定します。LDAPサーバーは、レルムAのユーザーがKeycloakの認証に成功するためには、レルムAのユーザーを見つけなければなりません。なぜなら、KeycloakはSPNEGOフローを実行してから、ユーザーを見つけなければならないからです。

たとえば、Kerberosのプリンシパル・ユーザーである john@A は、LDAPにおいて uid=john,ou=People,dc=example,dc=com といったLDAP DNで利用可能でなければなりません。レルムAとレルムBのユーザーを認証したい場合は、LDAPがレルムAとレルムBの両方のユーザーを見つけることができることを確認してください。

  • Kerberosユーザー・ストレージ・プロバイダー(通常、LDAP統合なしのKerberos)を使用する場合、サーバー主体を HTTP/mydomain.com@B と設定し、KerberosレルムAおよびレルムBのユーザーが認証できるようにする必要があります。

Kerberosユーザー保存プロバイダーを使用する場合、Kerberosレルム間でユーザーが競合することはできません。競合するユーザーが存在する場合、Keycloakはそれらを同じユーザーにマップします。

トラブルシューティング

問題が発生した場合は、追加のログを有効にしてデバッグしてください。

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

  • サーバーログでより多くの情報を受け取るために、 org.keycloak カテゴリのTRACEロギングを有効化します。

  • システム・プロパティー -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認証は失敗します。それ以外の場合、オーセンティケーターは証明書のアイデンティティーを抽出し、既存のユーザーにマッピングします。

証明書が既存のユーザーにマッピングされる場合、認証フローによって動作が分岐する。

  • Browser Flowでは、サーバーはユーザーにアイデンティティーの確認やユーザー名とパスワードによるサインインを求めるプロンプトを表示します。

  • Direct Grant Flowでは、サーバーがユーザーにサインインします。

証明書のPKIXパスを検証するのはWebコンテナーの責任であることに注意してください。Keycloak側のX.509オーセンティケーターは、証明書の有効期限、証明書の失効ステータス、およびキーの使用状況を確認するための追加サポートを提供します。リバース・プロキシーの背後にデプロイされたKeycloakを使用している場合は、リバース・プロキシーがPKIXパスを検証するように設定されていることを確認してください。リバース・プロキシーを使用せず、ユーザーがWildFlyに直接アクセスする場合は、WildFlyが、以下に説明するように設定されている限り、PKIXパスが検証されていることを確認するので問題ありません。

機能

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

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

  • X500のSubjectのe-mail属性

  • X500のSubject Alternative Name Extension(RFC822Name General Name)からのSubjectのemail

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

  • X500 Subject’s Common Name属性

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

  • 証明書のシリアル番号

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

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

  • PEM形式の完全な証明書

正規表現

Keycloakは、正規表現をフィルターとして使用し、Subject DNまたはIssuer DNから証明書のIDを抽出します。たとえば、この正規表現はemail属性にマッチします。

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

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

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

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

  • レルムの設定で Login with email を無効にすると、証明書認証と同じルールが適用されます。ユーザーは、email属性を使用してログインすることができません。

  • アイデンティティー・ソースとして Certificate Serial Number and IssuerDN を使用するには、シリアル番号用とIssuerDN用の2つのカスタム属性が必要です。

  • SHA-256 Certificate thumbprint は、SHA-256証明書のサムプリントの小文字での16進数表現です。

  • IDソースとして Full certificate in PEM format を使用すると、LDAPなどの外部フェデレーション・ソースにマッピングされたカスタム属性に制限されます。Keycloakは長さの制限により証明書をデータベースに保存できないため、LDAPの場合は Always Read Value From LDAP を有効にする必要があります。

拡張された証明書検証
  • CRLを使用した失効ステータスの確認

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

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

  • 証明書のKeyUsage検証

  • 証明書のExtendedKeyUsage検証

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

  1. メニューの Authentication をクリックします。

  2. Browser フローをクリックします。

  3. Action のリストから、 Duplicate を選択します。

  4. コピーの名前を入力します。

  5. Duplicate をクリックします。

  6. Add step をクリックします。

  7. "X509/Validate Username Form"をクリックします。

  8. Add をクリックします。

    X509エグゼキューション

    X509 Execution

  9. X509/Validate Username Form をクリックし、 Browser Forms エグゼキューションの上にドラッグします。

  10. 条件を "ALTERNATIVE" に設定します。

    X509ブラウザーフロー

    X509 Browser Flow

  11. Action メニューをクリックします。

  12. Bind flow をクリックします。

  13. ドロップダウン・リストの中から、 Browser flow をクリックします。

  14. Save をクリックします。

    X509ブラウザーフロー・バインディング

    X509 Browser Flow Bindings

X.509クライアント証明書認証の設定

X509の設定

X509 Configuration

User Identity Source

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

Canonical DN representation enabled

DNを決定するためにCanonical形式を使用するかどうかを定義します。公式リンク: Java APIドキュメント にフォーマットが記載されています。このオプションは、2つのユーザー・アイデンティティー・ソースの Match SubjectDN using regular expression および Match IssuerDN using regular expression にのみ影響します。このオプションは、新しいKeycloakインスタンスをセットアップするときに有効にします。このオプションを無効にすると、既存のKeycloakインスタンスとの後方互換性が保たれます。

Enable Serial Number hexadecimal representation

シリアル番号 を16進数で表現します。符号ビットを1に設定したシリアル番号は、00オクテットで左詰めをする必要があります。たとえば、10進数で 161 、16進数で a1 のシリアルナンバーは、RFC5280によれば 00a1 と符号化されます。詳細は RFC5280, appendix-B を参照してください。

A regular expression

証明書のIDを抽出するためのフィルターとして使用する正規表現。この式には1つのグループを含める必要があります。

User Mapping Method

証明書のIDを既存のユーザーと照合する方法を定義します。 Username or email は、ユーザー名または電子メールによって既存のユーザーを検索します。 Custom Attribute Mapper は、証明書のIDに一致するカスタム属性を持つ既存のユーザーを検索します。カスタム属性の名前は設定可能です。

A name of user attribute

証明書IDに対して値が一致するカスタム属性。たとえば、 'Certificate Serial Number and IssuerDN' のように、属性マッピングが複数の値に関連する場合、複数のカスタム属性を使用します。

CRL Checking Enabled

証明書失効リストを使用して、証明書の失効状況を確認します。リストの場所は、 CRL file path 属性で定義されます。

Enable CRL Distribution Point to check certificate revocation status

証明書の失効状況を確認するには、CDPを使用します。ほとんどのPKI機関は、CDPを証明書に含めています。

CRL file path

CRLのリストを含むファイルへのパス。この値は、 CRL Checking Enabled オプションが有効な場合、有効なファイルへのパスでなければなりません。

OCSP Checking Enabled

オンライン証明書ステータス・プロトコルを用いて、証明書の失効状況を確認します。

OCSP Fail-Open Behavior

デフォルトでは、認証に成功するためには、OCSPチェックが肯定的な応答を返す必要があります。たとえば、OCSPサーバーに到達できない、オーバーロードしている、クライアント証明書にOCSPレスポンダのURIが含まれていない、などの可能性があります。この設定をオンにすると、OCSPレスポンダーから明示的な否定応答を受信し、かつ証明書が確実に失効している場合にのみ、認証が拒否されます。有効なOCSP応答が得られない場合は、認証の試行が許可されます。

OCSP Responder URI

証明書に記載されているOCSPレスポンダー URI の値を上書きします。

Validate Key Usage

証明書のKeyUsage拡張ビットが設定されていることを確認します。たとえば、"digitalSignature,KeyEncipherment"は、KeyUsage拡張のビット0および2が設定されているかどうかを検証します。このパラメーターを空にすると、Key Usageの検証を無効にすることができます。詳細は RFC5280, Section-4.2.1.3 を参照。Keycloakは、鍵の使用法の不一致が発生した場合にエラーを発生させます。

Validate Extended Key Usage

拡張キー使用法の拡張で定義された1つ以上の目的を検証します。詳細は RFC5280, Section-4.2.1.12 を参照してください。拡張キー使用法の検証を無効にするには、このパラメーターを空にします。Keycloakは、発行元のCAがCriticalとフラグを立て、キー使用法の拡張の不一致が発生した場合にエラーを発生させます。

Validate Certificate Policy

証明書ポリシー拡張で定義された、1つ以上のポリシーOIDを検証します。 RFC5280、セクション-4.2.1.4 を参照してください。証明書ポリシーの検証を無効にするには、このパラメーターを空にします。複数のポリシーはカンマで区切る必要があります。

Certificate Policy Validation Mode

Validate Certificate Policy の設定で複数のポリシーが指定された場合、要求されたすべてのポリシーが存在することを確認するのか、それとも認証に成功するために1つのマッチングで十分なのかを決定します。デフォルト値は All で、要求されたすべてのポリシーがクライアント証明書に存在する必要があることを意味します。

Bypass identity confirmation

このオプションを有効にすると、X.509クライアント証明書認証で、証明書のアイデンティティーを確認するためのプロンプトが表示されなくなります。認証に成功すると、Keycloakがユーザーにサインインします。

Revalidate client certificate

設定すると、クライアント証明書のトラストチェーンは、設定されたトラストストアに存在する証明書を使用して、常にアプリケーション・レベルで検証されます。これは、たとえばWebサーバーが検証しないロードバランサーやリバース・プロキシーの背後にあるなどの理由でクライアント証明書チェーンの検証を実施しない場合や、許可されるCAの数がMutual SSLネゴシエーションに対して多すぎる場合(ほとんどのブラウザーは最大SSLネゴシエーション・パケット・サイズを32767バイトに制限しており、これは約200のアドバタイズCAに相当します)に有用となります。デフォルトでは、このオプションはオフになっています。

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

  1. メニューの Authentication をクリックします。

  2. Action list から Duplicate を選択し、組み込みの Direct grant フローのコピーを作成します。

  3. コピーの名前を入力します。

  4. Duplicate をクリックします。

  5. 作成したフローをクリックします。

  6. Username Validation のゴミ箱アイコン 🗑️ をクリックし、 Delete をクリックします。

  7. Password のゴミ箱アイコン(🗑️)をクリックし、 Delete をクリックします。

  8. Add step をクリックします。

  9. "X509/Validate Username"をクリックします。

  10. Add をクリックします。

    X509ダイレクト・グラント・エグゼキューション

    X509 Direct Grant Execution

  11. x509 Browser Flowに記載されている手順で、x509認証の設定を行います。

  12. Bindings をクリックします。

  13. Direct Grant Flow のドロップダウン・リストをクリックします。

  14. 新しく作成した"x509 Direct Grant"フローをクリックします。

  15. Save をクリックします。

    X509ダイレクト・グラント・バインディング

    X509 Direct Grant Flow Bindings

W3C Web Authentication(WebAuthn)

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

WebAuthnの運用がうまくいくかどうかは、ユーザーのWebAuthn対応オーセンティケーター、ブラウザー、プラットフォームに依存します。お使いのオーセンティケーター、ブブラウザー、プラットフォームが WebAuthn 仕様をサポートしていることを確認してください。

セットアップ

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

WebAuthnオーセンティケーターの登録の有効化
  1. メニューの Authentication をクリックします。

  2. Required Actions タブをクリックします。

  3. Webauthn Register スイッチを ON に切り替えます。

すべての新規ユーザーにWebAuthnのクレデンシャルの登録を要求する場合は、 Default Action スイッチを ON に切り替えます。

ブラウザーフローへのWebAuthn認証の追加

  1. メニューの Authentication をクリックします。

  2. Browser フローをクリックします。

  3. Action list から Duplicate を選択し、組み込みの Browser フローのコピーを作成します。

  4. コピーの名前に「WebAuthn Browser」と入力します。

  5. Duplicate をクリックします。

  6. 名前をクリックすると詳細へ移動します

  7. WebAuthn Browser Browser - Conditional OTP のゴミ箱アイコン 🗑️ をクリックし、 Delete をクリックします。

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

  1. WebAuthn Browser Forms+ メニューをクリックします。

  2. Add step をクリックします。

  3. Webauthn Authenticator をクリックします。

  4. Add をクリックします。

  5. WebAuthn Authenticator 認証タイプで Required を選択し、その要件を必須とします。

    Webauthn browser flow required

  6. 画面上部の Action メニューをクリックします。

  7. ドロップダウンリストから Bind flow を選択します。

  8. ドロップダウン・リストから Browser を選択します。

  9. Save をクリックします。

ユーザーがWebAuthnのクレデンシャルを持っていない場合、ユーザーはWebAuthnのクレデンシャルを登録する必要があります。

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

手順
  1. WebAuthn Browser Forms 行の + メニューをクリックします。

  2. Add sub-flow をクリックします。

  3. name フィールドに "Conditional 2FA" と入力します。

  4. WebAuthn Browser Forms の行で、プラス記号 + をクリックし、 Add step を選択します。

  5. Conditional 2FAConditional を選択し、その条件を条件付きに設定します。

  6. Conditional 2FA の行で、プラス記号 + をクリックし、 Add condition を選択します。

  7. Add condition をクリックします。

  8. Condition - User Configured を選択します。

  9. Add をクリックします。

  10. Condition - User ConfiguredRequired を選択し、その要件を必須に設定します。

  11. WebAuthn AuthenticatorConditional 2FA のフローにドラッグ&ドロップする。

  12. WebAuthn Authenticator の要件を択一的に設定するには、 Alternative を選択します。

    Webauthn browser flow conditional

2つ目の要素については、WebAuthnを使用するかOTPを使用するかをユーザーが選択できます。

手順
  1. Conditional 2FA の行で、プラス記号 + をクリックし、 Add step を選択します。

  2. Add step をクリックします。

  3. アイテムリストから OTP Form を選択します。

  4. Add をクリックします。

  5. OTP FormAlternative を選択し、その要件を択一的に設定します。

    WebAuthn browser flow conditional with OTP

WebAuthnオーセンティケーターを使用した認証

WebAuthnオーセンティケーターを登録した後、ユーザーは以下の操作を行います。

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

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

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

クレデンシャルの管理

Keycloakは、 ユーザークレデンシャル管理 の他のクレデンシャルと同様にWebAuthnのクレデンシャルを管理します。

  • Keycloakは、 Reset Actions の一覧からWebAuthnクレデンシャルを作成し、 Webauthn Register を選択するという必須アクションをユーザーに割り当てます。

  • 管理者は、 Delete をクリックして、WebAuthnのクレデンシャルを削除することができます。

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

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

ポリシーの管理

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

手順
  1. メニューの Authentication をクリックします。

  2. Policy タブをクリックします。

  3. WebAuthn Policy タブをクリックします。

  4. ポリシー内の項目を設定します(以下の説明を参照)。

  5. Save をクリックします。

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

設定 説明

Relying Party Entity Name

WebAuthn Relying Partyとしての読み取り可能なサーバー名。この項目は必須であり、WebAuthnオーセンティケーターの登録に適用されます。デフォルトは "keycloak" です。詳しくは WebAuthnの仕様 を参照してください。

Signature Algorithms

WebAuthnオーセンティケーターに Public Key Credentialに使用する署名アルゴ リズムを伝えるアルゴリズム。Keycloakは公開鍵クレデンシャルを使用して Authentication Assertions に署名および検証を行います。アルゴリズムが存在しない場合、デフォルトの ES256 が適応されます。ES256は、WebAuthnオーセンティケーターの登録に適用されるオプションの設定項目です。詳しくは WebAuthnの仕様をご覧ください。

Relying Party ID

Public Key Credentialsの範囲を決定する、WebAuthn Relying PartyのID。このIDは、オリジンの有効ドメインでなければなりません。このIDは、WebAuthnオーセンティケーターの登録に適用されるオプションの設定項目です。この項目が空白の場合、KeycloakはKeycloakのベースURLのホスト部分を適応します。詳しくは WebAuthnの仕様を参照してください。

Attestation Conveyance Preference

ブラウザー上のWebAuthn API実装( WebAuthn Client )は、Attestation文を生成するための優先的な方法です。この設定は、WebAuthnオーセンティケーターの登録に適用されるオプションの設定項目です。オプションがない場合は、 "none" を選択したのと同じ動作となります。詳しくは WebAuthnの仕様 を参照してください。

Authenticator Attachment

WebAuthnクライアントで使用可能なWebAuthnオーセンティケーターの添付ファイルパターン。このパターンは、WebAuthnオーセンティケーターの登録に適用されるオプションの設定項目です。詳しくは WebAuthn Specification を参照してください。

Require Resident Key

WebAuthnオーセンティケーターが公開鍵クレデンシャルを Client-side-resident Public Key Credential Sourceとして生成することを要求するオプショ ン。このオプションは、WebAuthnオーセンティケーターの登録に適用されます。空白のままだと、"No" を選択した場合と同じ動作になります。詳しくは、 WebAuthn 仕様 を参照してください。

User Verification Requirement

WebAuthnオーセンティケーターがユーザーの認証を確認することを要求するオプションです。これは、WebAuthnオーセンティケーターの登録および WebAuthnオーセンティケーターによるユーザーの認証に適用されるオプション設定項目です。オプションがない場合は、"preferred" を選択した場合と同じ動作となります。詳しくは、 WebAuthnオーセンティケーターの登録に関する仕様 および WebAuthnオーセンティケーターによるユーザー認証に関する仕様 を参照してください。

Timeout

WebAuthnオーセンティケーターを用いてユーザーを登録し、認証する際のタイムアウト値を秒単位で指定します。0を指定すると、その動作は WebAuthnオーセンティケーターの実装に依存します。デフォルトは 0 です。詳しくは WebAuthnオーセンティケーターの登録に関する仕様 および WebAuthnオーセンティケーターによるユーザー認証に関する仕様 を参照してください。

Avoid Same Authenticator Registration

有効な場合、Keycloakは既に登録されているWebAuthnオーセンティケーターを再登録することはできません。

Acceptable AAGUIDs

WebAuthnオーセンティケーターが登録しなければならないAAGUIDのホワイトリスト。

Attestation文の検証

WebAuthnオーセンティケーターを登録する際、KeycloakはWebAuthnオーセンティケーターが生成する証明書の信頼性を検証します。Keycloakは、 [トラストストア](https://www.keycloak.org/server/keycloak-truststore) にインポートされたトラストアンカーの証明書を必要とします。

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

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

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

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

新規ユーザー

レルムで WebAuthn Register の必須アクションが Default Action の場合、新規ユーザーは最初のログイン後にWebAuthnセキュリティー鍵をセットアップしなければなりません。

手順
  1. ログインフォームを開きます。

  2. Register をクリックします。

  3. フォームの項目を記入します。

  4. Register をクリックします。

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

既存のユーザー

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

手順
  1. ログインフォームを開きます。

  2. フォームに項目を入力します。

  3. Save をクリックします。

  4. Login をクリックします。

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

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

Keycloakは二要素認証にWebAuthnを使っていますが、一要素認証にWebAuthnを使うこともできます。この場合、 passwordless のWebAuthn のクレデンシャルを持つユーザーは、パスワードなしでKeycloakを認証することができます。Keycloakは、ひとつのレルムとひとつの認証フローで、WebAuthnをパスワードなし認証と二要素認証の両方の仕組みとして使うことができます。

管理者は通常、WebAuthnパスワードレス認証のためにユーザーが登録したセキュリティー鍵が、異なる要件を満たすことを要求します。たとえば、セキュリティー鍵は、ユーザーがPINを使用してセキュリティー鍵に認証することを要求したり、セキュリティー鍵がより強力な認証局で認証することを要求したりすることがあります。

このため、Keycloakは管理者に個別の WebAuthn Passwordless Policy を設定することを許可しています。 WebAuthn Register Passwordless のアクションが必要で、 WebAuthn Passwordless Authenticator タイプのオーセンティケーターが別途必要です。

セットアップ

WebAuthnのパスワードレス対応については、以下のように設定してください。

  1. (まだ存在しない場合)WebAuthnのパスワードレス対応に必須アクションを新規に登録します。WebAuthnオーセンティケーターの登録の有効化で説明した手順を使用してください。 Webauthn Register Passwordless アクションを登録します。

  2. ポリシーを設定します。ポリシーの管理で説明した手順と設定オプションが使用できます。管理コンソールのタブ WebAuthn Passwordless Policy で設定を実行します。通常、セキュリティー鍵の要件は、2要素ポリシーの要件よりも強くなります。たとえば、パスワードレスポリシーを設定する際に、User Verification RequirementRequired に設定します。

  3. 認証フローを設定します。ブラウザフローへのWebAuthnオーセンティケーターの追加で説明した WebAuthn Browser のフローを使用します。フローを以下のように設定します。

    • WebAuthn Browser Forms サブフローには、最初の認証子として Username Form が含まれています。デフォルトの Username Password Form 認証機能を削除して、 Username Form 認証機能を追加してください。このアクションでは、最初のステップとしてユーザーにユーザー名を提供するよう要求します。

    • たとえば、Passwordless Or Two-factor という名前の必須サブフローが存在します。このサブフローは、ユーザーがパスワードレスのWebAuthnクレデンシャルまたは2要素認証で認証できることを示します。

    • このフローには、最初の選択肢として WebAuthn Passwordless Authenticator が含まれています。

    • 2つ目の選択肢は、たとえば Password And Two-factor Webauthn という名前のサブフローになります。このサブフローには、 Password FormWebAuthn Authenticator が含まれます。

最終的なフローの設定はこのような感じになります。

パスワードレス・フロー

パスワードレス・フロー

すでにKeycloakに認識されているユーザーに、必須アクションとして WebAuthn Register Passwordless を追加し、これをテストすることができます。最初の認証では、ユーザーはパスワードと第2要素のWebAuthnクレデンシャルを使用する必要があります。WebAuthn Passwordlessクレデンシャルを使用する場合、ユーザーはパスワードと第2要素の WebAuthn クレデンシャルを提供する必要はありません。

ログインレスWebAuthn

Keycloakは二要素認証にWebAuthnを使用していますが、一要素認証にWebAuthnを使用することができます。この場合、WebAuthnの passwordless クレデンシャルを持つユーザーは、ログインやパスワードを送信することなくKeycloakに認証することができます。Keycloakは、WebAuthnをログインレス/パスワードレスと二要素認証の両方のメカニズムとして、レルムのコンテキストで使用することができます。

管理者は通常、WebAuthnのログインレス認証のためにユーザーによって登録されたセキュリティー・キーが、異なる要件を満たすことを要求します。ログインレス認証では、ユーザーがセキュリティー・キーに対して認証を行い(たとえば、PINコードや指紋を使用する)、ログインレス認証に関連する暗号鍵がセキュリティー・キー上に物理的に保存されることが必要です。すべてのセキュリティー・キーがそのような要件を満たすわけではありません。デバイスが 'user verification' と 'resident key' をサポートしているかどうかは、セキュリティ・キーのベンダーに確認してください。サポートされているセキュリティー・キーを参照してください。

Keycloakは、管理者が WebAuthn Passwordless Policy をログインレス認証を可能にするように設定することを許可します。ログインレス認証は WebAuthn Passwordless PolicyWebAuthn Passwordless クレデンシャルでのみ設定できることに注意してください。WebAuthn ログインレス認証と WebAuthn パスワードレス認証は同じレルムに設定できますが、同じポリシー WebAuthn Passwordless Policy を共有することになります。

セットアップ
手順

WebAuthnのログインレス・サポートを以下のように設定します。

  1. (まだ存在しない場合)WebAuthnのパスワードレス対応に必須アクションを新規に登録します。WebAuthnオーセンティケーターの登録の有効化で説明した手順を使用してください。 Webauthn Register Passwordless アクションを登録します。

  2. WebAuthn Passwordless Policy を設定します。管理コンソールの Authentication セクションの PoliciesWebAuthn Passwordless Policy タブで設定を行います。ログインレスのシナリオのポリシーを設定する場合、 User Verification Requirementrequired に、 Require Resident KeyYes に設定する必要があります。ログインレス専用のポリシーがないため、user verification=no/resident key=noの認証シナリオとログインレス・シナリオ(user verification=yes/resident key=yes)を混合することができないことに注意してください。通常、セキュリティー・キーのストレージ容量は非常に限られているため、セキュリティー・キーに多くのレジデントキーを保存することはできません。

  3. 認証フローを設定します。新しい認証フローを作成し、 "WebAuthn Passwordless" エグゼキューションを追加し、エグゼキューションの要件設定を Required に設定します。

最終的なフローの設定はこのような感じになります。

ログインレス・フロー

ログインレス・フロー

WebAuthn Register Passwordless という必須アクションをKeycloakで既に知られているユーザーに追加して、これをテストすることができるようになりました。必須アクションが設定されたユーザーは、(例えばユーザー名/パスワードで)認証する必要があり、その後、ログインレス認証に使用するセキュリティー・キーを登録するように促されます。

ベンダー固有の注意事項
互換性チェックリスト

Keycloakによるログインレス認証は、セキュリティー・キーが以下の機能を満たす必要があります。

  • FIDO2準拠(FIDO/U2Fと混同しないように)

  • User Verification:セキュリティー・キーがユーザーを認証する機能(誰かがセキュリティー・キーを見つけて、ログインレスやパスワードレスで認証できるようになるのを防ぐ)

  • Resident Key:セキュリティー・キーがログインとクライアント・アプリケーションに関連する暗号鍵を保存する機能

Windows Hello

Keycloakの認証にWindows Helloベースの認証情報を使用するには、 WebAuthn Passwordless PolicySignature Algorithms 設定に RS256 値を含めるよう設定します。ブラウザーによっては、プライベート・ウィンドウ内ではプラットフォーム・セキュリティー・キー(Windows Helloなど)へのアクセスを許可しないものがあることに注意してください。

サポートされるセキュリティー・キー

以下のセキュリティー・キーは、Keycloakでログインレス認証のテストに成功しました。

  • Windows Hello (Windows 10 21H1/21H2)

  • Yubico Yubikey 5 NFC

  • Feitian ePass FIDO-NFC

リカバリーコード(RecoveryCodes)

認証フローに二要素認証のオーセンティケーターとして Recovery Authentication Code Form を追加することで、二要素認証にRecoveryコードを設定することができます。この認証器の設定例については、 WebAuthn を参照してください。

リカバリーコードのサポートは開発中であることにご注意ください。この機能は実験的に使用してください。

条件付きフロー内のCondition

エグゼキューションのRequirementで述べたように、 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

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

Condition - User Attribute

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

Alias

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

Attribute name

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

Expected attribute value

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

Negate output

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

条件付きフローでのアクセスを明示的に拒否/許可する

条件付きフローでリソースへのアクセスを許可または拒否できます。2つのオーセンティケーター Deny AccessAllow Access は、条件によってリソースへのアクセスを制御します。

Allow Access

オーセンティケーターは常に正常に認証されます。このオーセンティケーターは設定できません。

Deny Access

アクセスは常に拒否されます。ユーザーに表示されるエラーメッセージを定義できます。次のフィールドを指定できます。

Alias

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

Error message

ユーザーに表示されるエラーメッセージ。エラーメッセージは、ローカリゼーションで使用するために、特定のメッセージまたはプロパティーとして提供できます(つまり、メッセージ・プロパティーに "You do not have the role 'admin'.", my-property-deny )。プロパティー access-denied として定義されているデフォルトのメッセージは空白のままにします。

これは、ロール role1 を持たないすべてのユーザーへのアクセスを拒否し、プロパティー deny-role1 で定義されたエラーメッセージを表示する方法の例です。この例には、 Condition - User Role および Deny Access のエグゼキューションが含まれます。

ブラウザーフロー

Deny access flow

条件 - ユーザーロールの設定

Deny access role settings

Deny Access の設定はとても簡単です。次のように、任意のエイリアスと必要なメッセージを指定できます。

Deny access execution settings

最後に、ログインテーマの messages_en.properties(英語の場合)でエラーメッセージを含むプロパティーを定義します。

deny-role1 = You do not have required role!

アイデンティティー・プロバイダーの統合

アイデンティティー・ブローカーは、サービス・プロバイダーとアイデンティティー・プロバイダーをつなぐ仲介サービスです。アイデンティティー・ブローカーは、外部のアイデンティティー・プロバイダーとの関係を構築し、プロバイダーのアイデンティティーを使用して、サービス・プロバイダーが公開している内部サービスにアクセスします。

ユーザーの視点から見ると、アイデンティティー・ブローカーは、ユーザーを中心とした、セキュリティー・ドメインやレルムのアイデンティティーを一元的に管理する方法を提供します。アカウントをアイデンティティー・プロバイダーから取得した1つまたは複数のアイデンティティーとリンクさせたり、アイデンティティー・プロバイダーから取得したアイデンティティー情報をもとにアカウントを作成することができます。

アイデンティティー・プロバイダーは、ユーザーを認証し、認証・認可情報を送信するために使用される特定のプロトコルに由来します。アイデンティティー・プロバイダーは、以下を行うことができます。

  • Facebook、Google、Twitterなどのソーシャル・プロバイダー

  • サービスにアクセスする必要があるユーザーの所属するビジネスパートナー

  • 統合したいクラウドベースのアイデンティティー・サービス

通常、Keycloakは、以下のプロトコルに基づいてアイデンティティー・プロバイダーを構築します。

  • SAML v2.0

  • OpenID Connect v1.0

  • OAuth v2.0

ブローカリングの概要

アイデンティティー・ブローカーとしてKeycloakを使用する場合、Keycloakは、特定のレルムで認証するためのクレデンシャルの提供をユーザーに強制しません。Keycloakは、ユーザーが認証できるアイデンティティー・プロバイダーのリストを表示します。

デフォルトのアイデンティティー・プロバイダーを設定している場合、Keycloakはユーザーをデフォルトのプロバイダーにリダイレクトします。

プロトコルによっては、異なる認証フローが必要になる場合があります。Keycloakがサポートするすべてのアイデンティティー・プロバイダーは、以下のフローを使用します。

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

Identity broker flow

  1. 認証されていないユーザーが、クライアント・アプリケーションで保護されたリソースを要求します。

  2. クライアント・アプリケーションは、ユーザーをKeycloak にリダイレクトし、認証を行います。

  3. Keycloakは、レルムに設定されているアイデンティティー・プロバイダーの一覧を含むログインページを表示します。

  4. ユーザーは、ボタンやリンクをクリックして、いずれかのアイデンティティー・プロバイダーを選択します。

  5. Keycloakは、対象のアイデンティティー・プロバイダーに認証を要求する認証リクエストを発行し、ユーザーをアイデンティティー・プロバイダーのログインページにリダイレクトします。管理者は、管理コンソールのアイデンティティー・プロバイダーの接続プロパティーやその他の設定オプションをすでに設定しています。

  6. ユーザーはアイデンティティー・プロバイダーを認証するためのクレデンシャルまたは同意を提供します。

  7. アイデンティティー・プロバイダーによる認証が成功すると、ユーザーは認証レスポンスとともにKeycloakにリダイレクトして戻ります。通常、このレスポンスにはKeycloakがアイデンティティー・プロバイダーの認証を信頼してユーザー情報を取得するために使用するセキュリティー・トークンが含まれています。

  8. Keycloakは、アイデンティティー・プロバイダーからのレスポンスが有効かどうかをチェックします。有効であれば、Keycloakは、ユーザーがまだ存在していない場合、ユーザーをインポートして作成します。Keycloakは、トークンにユーザー情報が含まれていない場合、アイデンティティー・プロバイダーにさらなるユーザー情報を求めることがあります。この動作が アイデンティティー・フェデレーション です。 ユーザーがすでに存在している場合、Keycloakは、アイデンティティー・プロバイダーから返されたアイデンティティーを既存のアカウントとリンクさせるようユーザーに求めることがあります。この動作は アカウント・リンキング です。Keycloakでは、_アカウント・リンキング_を設定し、First Login Flowで指定します。この段階で、Keycloakはユーザーを認証し、サービス・プロバイダーで要求されたリソースにアクセスするためのトークンを発行します。

  9. ユーザーが認証されると、Keycloakは、ローカル認証時に以前に発行されたトークンを送信して、ユーザーをサービス・プロバイダーにリダイレクトします。

  10. サービス・プロバイダーは Keycloakからトークンを受け取り、保護されたリソースへのアクセスを許可します。

このフローのバリエーションは可能です。たとえば、クライアント・アプリケーションは、特定のアイデンティティー・プロバイダーのリストを表示するのではなく、特定のアイデンティティー・プロバイダーを要求することができます。また、Keycloakを設定して、アイデンティティーを連携させる前にユーザーに追加情報の提供を強制することもできます。

認証プロセスの最後に、Keycloakはそのトークンをクライアント・アプリケーションに発行します。クライアント・アプリケーションは外部の アイデンティティー・プロバイダーとは別のものなので、クライアント・アプリケーショ ンのプロトコルや、ユーザーのアイデンティティーをどのように検証するかを見ることはできません。プロバイダーは Keycloakのことだけを知っていればよいのです。

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

Keycloakは、ログイン画面を表示するのではなく、アイデンティティー・プロバイダーにリダイレクトすることができます。このリダイレクトを有効にするには以下を行います。

手順
  1. メニューの Authentication をクリックします。

  2. Browser フローをクリックします。

  3. Identity Provider Redirector の行にある歯車アイコン ⚙️ をクリックします。

  4. Default Identity Provider に、ユーザーをリダイレクトしたいアイデンティティー・プロバイダーを設定します。

Keycloakが設定されたデフォルトのアイデンティティー・プロバイダーを見つけられない場合は、ログイン画面が表示されます。

このオーセンティケーターは、 kc_idp_hint のクエリー・パラメーターの処理を担当します。詳細はクライアント提案のアイデンティティー・プロバイダーのセクションを参照してください。

一般的な構成

アイデンティティー・ブローカーの設定の基礎となるのは、アイデンティティー・プロバイダー(IDP)です。Keycloakは、各レルムに対して アイデンティティー・プロバイダーを作成し、デフォルトですべてのアプリケーションに対して有効にします。レルムのユーザーは、アプリケーションにサインインする際に、登録されたアイデンティティー・プロバイダーのいずれかを使用できます。

手順
  1. メニューの Identity Providers をクリックします。

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

    Identity Providers

  2. アイデンティティー・プロバイダーを選択します。Keycloakが選択したアイデンティティー・プロバイダーの設定ページを表示します。

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

    Add Facebook Identity Provider

    アイデンティティー・プロバイダーを設定すると、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

エイリアスは、アイデンティティー・プロバイダーの一意の識別子であり、内部のアイデンティティー・プロバイダーを参照します。Keycloakは、エイリアスを使用して、アイデンティティー・プロバイダーとの通信にリダイレクトURIまたはコールバックURLを必要とするOpenID ConnectプロトコルのリダイレクトURIを構築します。すべてのアイデンティティー・プロバイダーにはエイリアスが必要です。エイリアスの例としては、 facebookgoogleidp.acme.com などがあります。

Enabled

プロバイダーのON/OFFを切り替えます。

Hide on Login Page

ON の場合、Keycloakは、ログインページのログイン・オプションとしてこのプロバイダーを表示しません。クライアントは、ログインを要求するURLに 'kc_idp_hint' パラメーターを使用して、このプロバイダーを要求できます。

Account Linking Only

ON の場合、Keycloakは既存のアカウントとこのプロバイダーをリンクします。このプロバイダーはユーザーをログインさせることができず、Keycloakはログインページのオプションとしてこのプロバイダーを表示しません。

Store Tokens

ON の場合、Keycloakはアイデンティティー・プロバイダーから取得したトークンを保存します。

Stored Tokens Readable

ON の場合、ユーザーは保存されているアイデンティティー・プロバイダーのトークンを取得できます。このアクションは、broker_クライアントレベル・ロールの _read token にも適用されます。

Trust Email

ON の場合、Keycloakはアイデンティティー・プロバイダーからの電子メールアドレスを信頼します。レルムが電子メールの検証を必要とする場合、このアイデンティティー・プロバイダーからログインするユーザーは、電子メールの検証プロセスを実行する必要はありません。

GUI Order

ログインページで利用可能なアイデンティティー・プロバイダーのソート順を指定します。

初回ログインフロー

ユーザーがこのアイデンティティー・プロバイダーを使用してKeycloakに初めてログインしたときにKeycloakがトリガーする認証フロー。

Post Login Flow

ユーザーが外部アイデンティティー・プロバイダーへのログインを終了したときにKeycloakがトリガーする認証フロー。

Sync Mode

アイデンティティー・プロバイダーからマッパーを介してユーザー情報を更新する戦略。 legacy を選択する際、Keycloakは現在の動作を使用します。 Import はユーザーデータを更新せず、 force は可能な限りユーザーデータを更新します。詳しくはアイデンティティー・プロバイダー・マッパー を参照してください。

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

ソーシャル・アイデンティティー・プロバイダーは、信頼され、評判の高いソーシャル・メディアのアカウントに認証を委ねることができます。Keycloakには、Google、Facebook、Twitter、GitHub、LinkedIn、Microsoft、Stack Overflowなどのソーシャル・ネットワークのサポートが含まれています。

Bitbucket

Bitbucketでログインするには、以下の手順で行います。

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider の一覧から Bitbucket を選択します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. ブラウザーの別のタブで、 OAuth on Bitbucket Cloud の処理を行います。 Add Consumer をクリックすると

    1. Callback URL フィールドに Redirect URI の値を貼り付けてください。

    2. アプリケーションがメールを読むことを許可するために、Account セクションで EmailRead を選択していることを確認してください。

  5. コンシューマーを作成する際に Bitbucket が表示する KeySecret の値に注意してください。

  6. Keycloakで、 Key の値を Consumer Key フィールドに貼り付けます。

  7. Keycloakでは、 Secret の値を Consumer Secret フィールドに貼り付けます。

  8. Add をクリックします。

Facebook

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider の一覧から Facebook を選択します。KeycloakはFacebookのアイデンティティー・プロバイダーの設定ページを表示します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. 別のブラウザータブで、 Facebook Developer Guide の指示に従って、Facebookでプロジェクトとクライアントを作成します。

    1. アプリがWebサイトタイプのアプリであることを確認します。

    2. Facebookの Website 設定ブロックの Site URL に、 Redirect URI の値を入力します。

    3. アプリが公開されていることを確認します。

  5. Client ID and Client Secret の値をFacebookアプリからKeycloakの Client IDClient Secret のフィールドに入力します。

  6. Add をクリックします。

  7. Default Scopes フィールドに必要なスコープを入力します。デフォルトでKeycloakは、 email のスコープを使用しています。Facebookのスコープの詳細については、 Graph API を参照してください。

Keycloak デフォルトでは、プロファイル・リクエストを graph.facebook.com/me?fields=id,name,email,first_name,last_name に送信します。レスポンスには、id、name、email、first_name、last_nameの各フィールドのみが含まれます。Facebookのプロフィールから追加のフィールドを取得するには、対応するスコープを追加して、 Additional user’s profile fields という設定オプションのフィールドにフィールド名を追加します。

GitHub

GitHubでログインするには、以下の手順で行います。

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから Github を選択します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. 別のブラウザータブで、 create an OAUTH app を実行します。

    1. アプリの作成時に、 Authorization callback URL フィールドに Redirect URI の値を入力してください。

    2. OAUTHアプリの管理画面で、Client IDとClient secretをメモします。

  5. Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。

  6. Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。

  7. Add をクリックします。

GitLab

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから GitLab を選択します。

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

    Add identity provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. 別のブラウザータブで、 add a new GitLab application を実行します。

    1. クリップボードにある Redirect URIRedirect URI として使用します。

    2. アプリケーションを保存する際には、 Client IDClient Secret をメモしてください。

  5. Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。

  6. Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。

  7. Add をクリックします。

Google

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから Google を選択します。

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

    Add Identity Provider

  3. ブラウザーの別のタブで、 Google Cloud Platformのコンソール を開きます。

  4. GoogleアプリのGoogleダッシュボードで、 OAuth consent screen メニューをクリックします。同意画面を作成し、同意画面のユーザータイプが外部であることを確認します。

  5. Googleのダッシュボードで以下を行います。

    1. Credentials メニューをクリックします。

    2. CREATE CREDENTIALS - OAuth Client ID をクリックします。

    3. Application type の一覧から Web application を選択します。

    4. Create をクリックします。

    5. Your Client IDYour Client Secret に注意してください。

  6. Keycloakでは、Your Client ID の値を Client ID フィールドに貼り付けます。

  7. Keycloakでは、Your Client Secret の値を Client Secret フィールドに貼り付けます。

  8. Add をクリックします。

  9. Default Scopes の欄に必要なスコープを入力してください。デフォルトでは、Keycloakは openidprofileemail のスコープを使用します。Googleのスコープの一覧は、 OAuth Playground を参照してください。

  10. GSuite組織のメンバーのみにアクセスを制限するには、 Hosted Domain フィールドにG Suiteドメインを入力します。

  11. Save をクリックします。

LinkedIn

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから LinkedIn を選択します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. 別のブラウザータブで、 create an app を実行します。

    1. アプリを作成した後、 Auth タブをクリックします。

    2. Authorized redirect URLs for your app フィールドに、 Redirect URI の値を入力してください。

    3. Your Client IDYour Client Secret に注意してください。

  5. Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。

  6. Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。

  7. Add をクリックします。

設定
  • Profile Projection では、プロファイル・リクエストの projection パラメーターを設定することができます。

  • たとえば、 (id,firstName,lastName,profilePicture(displayImage~:playableStreams)) は以下のようなプロファイル・リクエストURLを生成します。

https://api.linkedin.com/v2/me?projection=(id,firstName,lastName,profilePicture(displayImage~:playableStreams))

Microsoft

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider の一覧から Microsoft を選択します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. 別のブラウザータブで、 create a Microsoft app を実行します。

    1. Add URL をクリックして、MicrosoftアプリにリダイレクトURLを追加します。

    2. Application IDApplication Secret に注意してください。

  5. Keycloakでは、Application ID の値を Client ID フィールドに貼り付けます。

  6. Keycloakでは、Application Secret の値を Client Secret フィールドに貼り付けます。

  7. Add をクリックします。

OpenShift 3

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから Openshift を選択します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. コマンドライン・ツール 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 client_secret のリクエスト・パラメーターには、Keycloakの secret を使用します。
3 <openshift_master>/oauth/authorize および <openshift_master>/oauth/token へのリクエストで指定された redirect_uri パラメーターは、 redirectURIs のURIの1つと一致する(または前方一致する)必要があります。これは、アイデンティティー・プロバイダー画面の リダイレクトURI フィールドから取得できます。
4 grantMethod は、このクライアントがトークンを要求したがユーザーからのアクセスが許可されていない場合のアクションを決定するためにKeycloakが使用します 。
  1. Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。

  2. Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。

  3. Add をクリックします。

OpenShift 4

前提条件
  1. jq のインストール。

  2. コンテナーに設定された X509_CA_BUNDLE には、 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt が設定されています。

手順
  1. コマンドラインで以下のコマンドを実行し、OpenShift 4 APIのURLの出力をメモします。

    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"
  2. Keycloakのメニューの Identity Providers をクリックします。

  3. Add provider のリストから Openshift を選択します。

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

    Add Identity Provider

  4. Redirect URI* の値をクリップボードにコピーしてください。

  5. コマンドライン・ツール oc を使って、クライアントを登録します。

    $ oc create -f <(echo '
    kind: OAuthClient
    apiVersion: oauth.openshift.io/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 secret は Keycloak が client_secret のリクエスト・パラメーターとして使用します。
3 <openshift_master>/oauth/authorize<openshift_master>/oauth/token へのリクエストで指定される redirect_uri パラメーターは、redirectURIs に含まれる URI のいずれかと等しい (または前方一致している) 必要があります。正しく設定する最も簡単な方法は、Keycloakからコピーペーストすることです。OpenShift 4 Identity Providerの設定ページ( Redirect URI フィールド)からコピーペーストします。
4 grantMethod は、このクライアントがトークンを要求したがユーザーからのアクセスが許可されていない場合のアクションを決定するためにKeycloakが使用します 。
  1. Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。

  2. Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。

  3. Add をクリックします。

詳しくは、 OpenShiftの公式ドキュメント を参照してください。

PayPal

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから PayPal を選択します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. 別のブラウザータブで、 PayPal Developer applications area を開きます。

    1. Create App をクリックして、PayPalアプリを作成します。

    2. クライアントIDとクライアント・シークレットを確認します。 Show のリンクをクリックするとシークレットが表示されます。

    3. Connect with PayPal がチェックされていることを確認してください。

    4. Keycloakから取得した Redirect URI の値を*Return URL* フィールドに設定します。

  5. Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。

  6. Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。

  7. Add をクリックします。

スタックオーバーフロー

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから Stack Overflow を選択します。

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

    Add Identity Provider

  3. 別のブラウザータブで、 Stack Appsにアプリケーションを登録 にログインします。

    アプリケーションの登録

    Register Application

    1. Application Name フィールドにアプリケーション名を入力してください。

    2. OAuth Domain フィールドにOAuthドメインを入力してください。

    3. Register Your Application をクリックします。

      設定

      Settings

  4. Client IDClient Secret に注意してください。

  5. Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。

  6. Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。

  7. Add をクリックします。

Twitter

前提条件
  1. Twitterの開発者アカウントです。

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider "のリストから "Twitter "を選択します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. ブラウザーの別のタブで Twitter Application Management を開き、アプリを作成します。

    1. nameとdescriptionには任意の値を入力してください。

    2. Website の値には、 localhost を除く任意の有効なURLを指定します。

    3. Redirect URL の値を Callback URL フィールドに貼り付けてください。

    4. Twitterアプリを作成する際は、 Keys and Access Tokens のセクションの Consumer SecretKeys and Access Tokens の値に注意してください。

  5. Keycloakでは、 Client ID フィールドに Consumer Key の値を貼り付けます。

  6. Keycloakでは、 Client Secret フィールドに Consumer Secret の値を貼り付けます。

  7. Add をクリックします。

Instagram

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider の一覧から Instagram を選択します。KeycloakはInstagramのアイデンティティー・プロバイダーの設定ページを表示します。

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

    Add Identity Provider

  3. Redirect URI* の値をクリップボードにコピーしてください。

  4. 別のブラウザータブで、 Facebook Developer Console を開きます。

    1. My Apps をクリックします。

    2. Add a New App を選択します。

      Add a new app

      Add a New App

    3. For Everything Else を選択します。

      新規アプリIDの作成

      instagram create app id

    4. 必須項目をすべて入力してください。

    5. Create App をクリックすると、Facebookはダッシュボードを表示します。

    6. ナビゲーション・パネルで、 Settings - Basic を選択します。

      プラットフォームの追加

      Add Platform

    7. *+ Add Platform*を選択します。

    8. [Website] をクリックします。

    9. あなたのサイトのURLを入力してください。

      製品の追加

      instagram add product

    10. メニューから Dashboard を選択します。

    11. Instagramのボックスにある Set Up をクリックします。

    12. メニューから Instagram - Basic Display を選択します。

    13. Create New App をクリックします。

      インスタグラムのアプリIDを新規に作成します。

      Create a New Instagram App ID

    14. Display Name に値を入力してください。

      アプリのセットアップ

      Setup the App

    15. Keycloakの Redirect URLValid OAuth Redirect URIs フィールドに貼り付けてください。

    16. Keycloakの Redirect URLDeauthorize Callback URL フィールドに貼り付けてください。

    17. Keycloakの Redirect URLData Deletion Request URL フィールドに貼り付けてください。

    18. Instagram App Secret フィールドの Show をクリックします。

    19. Instagram App IDInstagram App Secret に注意してください。

    20. App Review - Requests をクリックします。

    21. 画面の指示に従ってください。

  5. Keycloakでは、Instagram App ID の値を Client ID フィールドに貼り付けます。

  6. Keycloakでは、 Instagram App Secret の値を Client Secret フィールドに貼り付けます。

  7. Add をクリックします。

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

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

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから OpenID Connect v1.0 を選択します。

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

    Add Identity Provider

  3. 初期設定のオプションを入力します。設定オプションの詳細はGeneral IDP Configurationを参照してください。

    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プロトコルが定義するエンドポイントです。このエンドポイントは、ユーザー・プロフィール情報を指します。

    クライアント認証

    Keycloakが認可コードフローで使用するクライアント認証方式を定義します。秘密鍵で署名されたJWTの場合、 Keycloakはレルムの秘密鍵を使用します。その他のケースでは、クライアント・シークレットを定義します。詳細は、 クライアント認証の仕様 を参照してください。

    Client ID

    外部IDPに対するOIDCクライアントとして動作するレルム。認可コードフローを使用して外部IDPとやり取りする場合、このレルムにはOIDCクライアントIDが必要です。

    Client Secret

    外部のボールトからのクライアント・シークレットです。このシークレットは、認可コードフローを使用する場合に必要です。

    Client Assertion Signature Algorithm

    クライアント認証としてJWTアサーションを作成するための署名アルゴリズム。秘密鍵で署名したJWTまたはJWTとしてのクライアント・シークレットの場合は必須です。アルゴリズムが指定されていない場合は、次のアルゴリズムが適用されます。秘密鍵で署名されたJWTの場合は、 RS256 が適用されます。 JWTとしてのクライアント・シークレットの場合は、HS256 が適用されます。

    Issuer

    KeycloakはIDPから返されるレスポンスに含まれる発行者のクレームを、この値に対して検証します。

    Default Scopes

    Keycloakが認証リクエストと一緒に送信するOIDCスコープのリストです。デフォルトの値は openid です。各スコープはスペースで区切られています。

    Prompt

    OIDC仕様のpromptパラメーター。このパラメーターを通じて、再認証などを強制的に行うことができます。詳しくは仕様書をご覧ください。

    Accepts prompt=none forward from client

    IDPが、 prompt=none のクエリー・パラメーターを含む転送された認証リクエストを受け入れるかどうかを指定します。あるレルムが prompt=none を含む認証リクエストを受信すると、そのユーザーが現在認証されているかどうかをチェックし、ユーザーがログインしていない場合は login_required エラーを返します。Keycloakが認証リクエストに対するデフォルトのIDPを決定した場合( kc_idp_hint のクエリー・パラメーターを使うか、レルムのデフォルトIDPを持っている)、 prompt=none の認証リクエストをデフォルトのIDPに転送することができます。デフォルトのIDPはそこでユーザーの認証をチェックします。すべてのIDPが prompt=none のリクエストをサポートしているわけではないので、Keycloakはこのスイッチを使って、認証リクエストをリダイレクトする前に、デフォルトのIDPがこのパラメーターをサポートしていることを示します。

    ユーザーがIDPで認証されていない場合、クライアントは依然として login_required エラーを受け取ります。ユーザーがIDPで認証されている場合でも、Keycloakがユーザーとの対話を必要とする認証ページを表示しなければならない場合、クライアントは interaction_required エラーを受け取る可能性があります。この認証には、必須アクション(たとえば、パスワードの変更)、同意画面、および first broker login フローまたは post broker login フローで表示するように設定された画面が含まれます。

    Validate Signatures

    Keycloak が、このIDPが署名した外部IDトークンの署名を検証するかどうかを指定します。 ON の場合、Keycloakは外部OIDCのアイデンティティー・プロバイダーの公開鍵を知っている必要があります。性能上、Keycloakは外部OIDCのアイデンティティー・プロバイダーの公開鍵をキャッシュします。

    Use JWKS URL

    このスイッチは、 Validate SignaturesON の場合に適用されます。 Use JWKS URLON の場合、KeycloakはJWKS URLからIdPの公開鍵をダウンロードします。アイデンティティー・プロバイダーが新しい鍵ペアを生成すると、新しい鍵がダウンロードされます。 OFF の場合、Keycloakはデータベースの公開鍵(または証明書)を使用するため、IdPのキーペアが変更された場合、新しい鍵をKeycloakのデータベースにもインポートします。

    JWKS URL

    IDPのJWKキーの場所を指すURL。詳細については、 JWK仕様 を参照してください。外部のKeycloakをIDPとして使用する場合、ブローカーの Keycloakが http://broker-keycloak:8180 上で動作しており、そのレルムが test であれば、 http://broker-keycloak:8180/realms//test/protocol/openid-connect/certs のような URL を使用することができます。

    Validating Public Key

    Keycloakが外部IDPの署名を検証するために使用するPEM形式の公開鍵です。この鍵は、 Use JWKS URLOFF の場合に適用されます。

    Validating Public Key Id

    この設定は、 Use JWKS URLOFF の場合に適用されます。この設定では、公開鍵のIDをPEM形式で指定します。鍵から鍵IDを計算する標準的な方法がないため、外部のアイデンティティー・プロバイダーはKeycloakが使用するものとは異なるアルゴリズムを使用できます。このフィールドの値が指定されていない場合、Keycloakは、外部のIDPから送信された鍵IDに関係なく、すべてのリクエストに検証用の公開鍵を使用します。 ON の場合、このフィールドの値はKeycloakがプロバイダーからの署名を検証するために使用する鍵IDであり、IDPが指定する鍵IDと一致しなければなりません。

OpenID Provider Metadataを指し示すURLやファイルを提供することで、これらの設定データをすべてインポートすることができます。Keycloakの外部IDPに接続する場合は、 <root>/realms/{realm-name}/.well-known/openid-configuration からIDPの設定をインポートできます。このリンクは、IDPに関するメタデータを記述したJSONドキュメントです。

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

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

手順
  1. メニューの Identity Providers をクリックします。

  2. Add provider のリストから SAML v2.0 を選択します。

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

    Add Identity Provider

  3. 初期設定のオプションを入力します。設定オプションの詳細はGeneral IDP Configurationを参照してください。

Table 3. SAMLの設定
設定 説明

Service Provider Entity ID

リモートのアイデンティティー・プロバイダーが、このサービス・プロバイダーからのリクエストを識別するために使用するSAMLエンティティーID。デフォルトでは、この設定はレルムベースのURL <root>/realms/{realm-name} に設定されています。

Single Sign-On Service URL

認証プロセスを開始するSAMLエンドポイント。SAML IDPがIDPエンティティー記述子を発行している場合、このフィールドの値はそこで指定されます。

Single Logout Service URL

SAMLログアウトのエンドポイント。SAML IDPがIDPエンティティー記述子を発行している場合、このフィールドの値はそこで指定されます。

Backchannel Logout

SAML IDP がバックチャネル・ログアウトをサポートする場合は、このスイッチを ON に切り替えます。

NameID Policy Format

名前識別子のフォーマットに対応するURI参照。デフォルトでは、Keycloak が urn:oasis:names:tc:SAML:2.0:nameid-format:persistent に設定する。

Principal Type

SAMLアサーションのどの部分を外部ユーザー・アイデンティティを一意に特定しトラックするのに使用するかを指定します。Subject NameID、SAML attributeのいずれか(名前もしくはフレンドリー名)です。Subject NameID値は、 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient' NameID Policy Format 値とともに設定することはできません。

Principal Attribute

Principal type が空白でない場合、識別属性の名前("Attribute [Name]")またはフレンドリー名("Attribute [Friendly Name]")を指定する。

Allow create

外部アイデンティティー・プロバイダーがプリンシパルを表す新しい識別子を作成できるようにします。

HTTP-POST Binding Response

外部IdPから送信されるSAML要求に応答するSAMLバインディングを制御します。 OFF の場合、KeycloakはREDIRECTバインディングを使用します。

HTTP-POST Binding for AuthnRequest

外部IdPに認証を要求する際のSAMLバインディングを制御します。 OFF の場合、KeycloakはREDIRECTバインディングを使用します。

Want AuthnRequests Signed

ON の場合、Keycloakは、外部のSAML IdPに送信されるリクエストに署名するために、レルムのキーペアを使用します。

Signature Algorithm

Want AuthnRequests SignedON の場合、使用する署名アルゴリズムを指定します。

SAML Signature Key Name

POST バインディングで送信される署名付き SAML ドキュメントは、KeyName 要素に署名鍵の識別情報を含む。この要素は、デフォルトでは Keycloak 鍵 ID を含む。外部の SAML IDP は、別のキー名を期待することができる。このスイッチは KeyName が含むかどうかを制御する。 * KEY_ID - キーID。 * CERT_SUBJECT - realm キーに対応する証明書のサブジェクト。Microsoft Active Directory フェデレーションサービスは CERT_SUBJECT を想定しています。 * NONE - Keycloak SAMLメッセージからキー名のヒントを省略する。

Force Authentication

ユーザーが既にログインしている場合でも、外部IDPで資格情報を入力する必要があります。

Validate Signature

ON*の場合、realmは外部IDPからのSAMLリクエストとレスポンスがデジタル署名されていることを期待します。

Validating X509 Certificate

公開証明書Keycloakは、外部IDPからのSAMLリクエストとレスポンスの署名を検証するために使用される。

Sign Service Provider Metadata

ON*の場合、Keycloakはレルムのキーペアを使用して<>に署名します<_identity_broker_saml_sp_descriptor, SAML Service Provider Metadata descriptor>。</_identity_broker_saml_sp_descriptor,>

Pass subject

project_name} が login_hint クエリパラメータを IDP に転送するかどうかを制御します。Keycloak はこのフィールドの値を AuthnRequest の Subject の login_hint パラメータに追加し、宛先プロバイダがログインフォームに事前入力できるようにします。

Attribute Consuming Service Index

リモートIdPに要求する属性セットを特定します。Keycloakは、アイデンティティー・プロバイダー構成にマッピングされた属性を、自動生成されたSPメタデータ・ドキュメントに自動的に追加します。

Attribute Consuming Service Name

自動生成されるSPメタデータ・ドキュメントで提示される一連の属性の説明的な名前です。

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

Requesting specific AuthnContexts

アイデンティティー・プロバイダーは、クライアントがユーザーのアイデンティティーを検証する認証方式に関する制約を指定することを容易にします。たとえば、MFA、Kerberos認証、またはセキュリティー要件を求めるなどです。これらの制約は、特定のAuthnContext基準を使用します。クライアントは1つまたは複数の基準を要求し、アイデンティティー・プロバイダーが要求されたAuthnContextに正確に、または他の同等物を満たすことでどのように一致しなければならないかを指定することができます。

Requested AuthnContext ConstraintsセクションにClassRefsまたはDeclRefsを追加することで、サービスプロバイダが要求する条件を列挙することができます。通常、ClassRefs あるいは DeclRefs のいずれかを指定する必要があるので、どの値がサポートされているかは ID プロバイダのドキュメントで確認してください。ClassRefs または DeclRefs が存在しない場合、ID プロバイダは追加の制約を適用しません。

Table 4. Requested AuthnContext Constraints
設定 説明

Comparison

アイデンティティー・プロバイダーがコンテキストの要件を評価するために使用する方法です。使用可能な値は ExactMinimumMaximum あるいは Better です。デフォルトは Exact です。

AuthnContext ClassRefs

必要な条件を記述した AuthnContext ClassRefs。

AuthnContext DeclRefs

必要な条件を記述した AuthnContext DeclRefs。

SP記述子

プロバイダの SAML SP メタデータにアクセスするときは、ID プロバイダ構成設定の中の Endpoints 項目を探す。これには SAML 2.0 Service Provider Metadata リンクがあり、サービスプロバイダの SAML エンティティディスクリプタが生成される。記述子をダウンロードするか、その URL をコピーして、リモート ID プロバイダにインポートすることができる。

また、このメタデータは以下のURLで公開されています。

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

ディスクリプターにアクセスする前に、設定変更を保存していることを確認してください。

SAMLリクエストでサブジェクトを送信する

デフォルトでは、SAML ID プロバイダを指すソーシャルボタンは、ユーザを以下のログイン URL にリダイレクトする。

http[s]://{host:port}/realms/${realm-name}/broker/{broker-alias}/login

このURLに login_hint というクエリーパラメータを追加すると、パラメータの値が Subject 属性として SAML リクエストに追加されます。このクエリパラメータが空の場合、Keycloak はリクエストに Subject を追加しません。

SAMLリクエストでサブジェクトを送信するために、"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 アダプターを使用している場合は、以下のようにして同じ動作を実現できます。

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

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

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

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

認証先の外部IDPから提供されるSAMLやOpenID Connectのメタデータをレルムにインポートすることができます。インポート後、ユーザー・プロフィールのメタデータなどを抽出して、アプリケーションで利用できるようにすることができます。

外部のアイデンティティー・プロバイダーを使用してレルムにログインする各ユーザーは、SAMLまたはOIDCのアサーションおよびクレームのメタデータに基づいて、ローカルのKeycloakデータベースにエントリーを持ちます。

手順
  1. メニューの Identity Providers をクリックします。

  2. リストの中からいずれかのアイデンティティー・プロバイダーを選択します。

  3. Mappers タブをクリックします。

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

    identity provider mappers

  4. Add mapper をクリックします。

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

    identity provider mapper

  5. Sync Mode Override の値を選択します。マッパーは、ユーザーが繰り返しログインする際に、この設定に従ってユーザー情報を更新します。

    1. 前のバージョンのKeycloakの動作を使用するには、 legacy を選択してください。

    2. 特定のアイデンティティー・プロバイダーを使用してKeycloakに初めてログインした際に、Keycloakにユーザーが初めて作成された時のデータをインポートする場合は、 import を選択します。

    3. ユーザーがログインするたびにユーザーデータを更新する場合は、 force を選択します。

    4. アイデンティティー・プロバイダーで設定された同期モードを使用するには、 inherit を選択します。他のすべてのオプションは、この同期モードを上書きします。

  6. Mapper Type のリストからマッパーを選択します。 Mapper Type にカーソルを合わせると、マッパーの説明とマッパーに入力する設定が表示されます。

  7. Save をクリックします。

JSONベースのクレームの場合、入れ子にはドット記法、配列のフィールドにインデックスでアクセスするには角括弧を使います。たとえば、 contact.address[0].country のようになります。

ソーシャル・プロバイダーが提供するユーザー・プロファイルJSONデータの構造を調査するために、サーバー起動時に DEBUG レベルのロガー org.keycloak.social.user_profile_dump を有効にすることができます。

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

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

identity_provider

ログインを実行するために使用されるブローカーのIDPエイリアス。

identity_provider_identity

現在認証されているユーザーのIDPのユーザー名です。多くの場合、Keycloakのユーザー名と同じですが、必ずしもそうとは限りません。たとえば、Keycloakは、ユーザー john をFacebookユーザー john123@gmail.com にリンクすることができます。この場合、ユーザーセッション・ノートの値は john123@gmail.com となります。

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

初回ログインフロー

ユーザーがアイデンティティー・ブローカリングによってログインするとき、 Keycloakはレルムのローカル・データベース内のユーザーの情報をインポートしてリンクします。Keycloakが外部のアイデンティティー・プロバイダーを通じてユーザーの認証に成功した場合、2つの状況が存在する可能性があります。

  • Keycloakは、すでにユーザー・アカウントをインポートし、認証されたアイデンティティー・プロバイダーのアカウントとリンクしています。この場合、Keycloakは既存のユーザーとして認証し、アプリケーションにリダイレクトして戻ります。

  • Keycloakにこのユーザーのアカウントが存在しません。通常、Keycloakのデータベースに新しいアカウントを登録してインポートしますが、同じ電子メールアドレスを持つ既存のKeycloakアカウントが存在する場合があります。既存のローカル・アカウントを外部のアイデンティティー・プロバイダーに自動的にリンクすることは、セキュリティー・ホールになる可能性があります。外部のアイデンティティー・プロバイダーから得られる情報を常に信用することはできません。

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

フローは、管理コンソールの Authentication タブにあります。 First Broker Login フローを選択すると、デフォルトで使用されるオーセンティケーターが表示されます。既存のフローを再設定することができます。たとえば、いくつかのオーセンティケーターを無効にしたり、いくつかのオーセンティケーターを Required とマークしたり、いくつかのオーセンティケーターを設定したりすることができます。

また、新しい認証フローを作成し、独自のオーセンティケーターの実装を記述し、フローで使用することもできます。詳しくはServer Developer Guideを参照してください。

デフォルトのFirst Login Flowオーセンティケーター

Review Profile
  • このオーセンティケーターは、プロファイル情報ページを表示するので、ユーザーはKeycloakがアイデンティティー・プロバイダーから取得した自分のプロファイルを確認することができます。

  • Actions メニューの Update Profile On First Login オプションで設定できます。

  • ON の場合は、ユーザーのアイデンティティーを連携させるための追加情報を要求するプロファイル・ページが表示されます。

  • missing の場合、アイデンティティー・プロバイダーが電子メール、姓、名などの必須情報を提供していない場合、ユーザーにはプロファイル・ページが表示されます。

  • OFF の場合、ユーザーが後の段階で Confirm Link Existing Account オーセンティケーターで表示されるページの Review profile info のリンクをクリックしない限り、プロファイル・ページは表示されません。

Create User If Unique

このオーセンティケーターは、アイデンティティー・プロバイダーのアカウントの電子メールまたはユーザー名が同じKeycloakアカウントが、すでに存在するかどうかをチェックします。存在しない場合、オーセンティケーターは新しいローカルのKeycloakアカウントを作成し、それをアイデンティティー・プロバイダーにリンクすることで、フロー全体が終了します。それ以外の場合は、次の Handle Existing Account サブフローに進みます。重複したアカウントがないことを常に確認したい場合は、このオーセンティケーターを REQUIRED にマークすることができます。この場合、既存のKeycloakアカウントが存在する場合は、エラーページが表示され、ユーザーはアカウント管理を通じてアイデンティティー・プロバイダーのアカウントをリンクする必要があります。

  • このオーセンティケーターは、アイデンティティー・プロバイダーのアカウントと同じ電子メールまたはユーザー名を持つKeycloakアカウントがすでに存在することを検証します。

  • アカウントが存在しない場合、オーセンティケーターはローカルの Keycloakアカウントを作成し、このアカウントをアイデンティティー・プロバイダーとリンクし、フローを終了します。

  • アカウントが存在する場合、オーセンティケーターは次の Handle Existing Account サブフローを実行します。

  • 重複するアカウントがないように、このオーセンティケーターを REQUIRED としてマークすることができます。Keycloakのアカウントが存在する場合、ユーザーにはエラーページが表示され、ユーザーはアカウント管理を通じてアイデンティティー・プロバイダーのアカウントをリンクする必要があります。

Confirm Link Existing Account
  • 情報ページで、ユーザーには同じ電子メールを使用したKeycloakのアカウントが表示されます。ユーザーは自分のプロファイルを再度確認し、異なる電子メールまたはユーザー名を使用できます。フローが再スタートして、Review Profile オーセンティケーターに戻ります。

  • あるいは、ユーザーは、アイデンティティー・プロバイダーのアカウントを既存のKeycloakアカウントとリンクさせることを確認することができます。

  • ユーザーにこの確認ページを表示させず、電子メール認証または再認証によるアイデンティティー・プロバイダーのアカウントのリンクに直行させたい場合は、このオーセンティケーターを無効にします。

Verify Existing Account By Email
  • このオーセンティケーターはデフォルトでは ALTERNATIVE です。Keycloakは、レルムにSMTPの設定がある場合、このオーセンティケーターを使用します。

  • オーセンティケーターは、ユーザーに電子メールを送信して、アイデンティティー・プロバイダーを自分のKeycloakアカウントとリンクさせることを確認します。

  • リンク確認を電子メールで行わず、ユーザーにパスワードで再認証させたい場合は、このオーセンティケーターを無効にします。

Verify Existing Account By Re-authentication
  • 電子メール・オーセンティケーターが利用できない場合に、このオーセンティケーターを使用します。たとえば、レルムにSMTPを設定していない場合などです。このオーセンティケーターは、Keycloakアカウントをアイデンティティー・プロバイダーにリンクするためにユーザーが認証するためのログイン画面を表示します。

  • ユーザーは、自分のKeycloakアカウントにすでにリンクされている別のアイデンティティー・プロバイダーで再認証することもできます。

  • ユーザーにOTPの使用を強制することができます。それ以外の場合はオプションで、ユーザー・アカウントにOTPを設定している場合に使用されます。

AutoLinkオーセンティケーターは、ユーザーが任意のユーザー名や電子メールアドレスを使って自分を登録できるような一般的な環境では危険です。ユーザーの登録を慎重に管理し、ユーザー名や電子メールアドレスを割り当てる場合を除き、このオーセンティケーターを使用しないでください。

プロンプトを表示せずにユーザーを自動的にリンクする初回ログインフローを構成するには、次の2つの認証子を持つ新しいフローを作成します。

Create User If Unique

このオーセンティケーターはKeycloakがユニークなユーザーを扱うことを保証します。オーセンティケーターのRequirementを Alternative に設定します。

Automatically Set Existing User

このオーセンティケーターは、既存のユーザーを検証なしで認証コンテキストに設定します。オーセンティケーターのRequirementを "Alternative" に設定します。

この設定は最もシンプルなものですが、他のオーセンティケーターを使用することも可能です。例: * エンドユーザーに自分のプロフィール情報を確認させたい場合は、フローの最初にReview Profileオーセンティケーターを追加することができます。 * このフローに認証メカニズムを追加して、ユーザーにクレデンシャルの確認を強制することもできます。認証メカニズムを追加するには、複雑なフローが必要です。たとえば、"Alternative"サブフローで"Automatically Set Existing User"と"Password Form"を"Required"に設定します。

ユーザーの自動作成を無効にする

デフォルトの初回ログインフローは、外部のアイデンティティーに一致するKeycloakアカウントを検索し、それらのリンクを提案します。一致するKeycloakアカウントが存在しない場合、フローは自動的にアカウントを作成します。

このデフォルトの動作は、いくつかのセットアップには適していないかもしれません。たとえば、読み取り専用のLDAPユーザーストアを使用していて、すべてのユーザーがあらかじめ作成されている場合です。このような場合には、ユーザーの自動作成をオフにする必要があります。

ユーザーの作成を無効にするには、以下を行います。

手順
  1. メニューの Authentication をクリックします。

  2. リストから First Broker Login を選択します。

  3. Create User If UniqueDISABLED に設定してください。

  4. Confirm Link Existing AccountDISABLED に設定してください。

この設定は、Keycloak自体が、外部アイデンティティーに対応する内部アカウントを判別できないことも意味します。したがって、 Verify Existing Account By Re-authentication オーセンティケーターは、ユーザーにユーザー名とパスワードの両方を提供するように要求します。

既存ユーザーの初回ログインフローの検出

次のような最初のログインフローを設定するには、

  • このレルムにすでに登録されているユーザーのみがログインできる

  • ユーザーはプロンプトなしで自動的にリンクされる

次の2つのオーセンティケーターを使用して新しいフローを作成します。

既存のブローカー・ユーザーを検出する

このオーセンティケーターは、一意にユーザーが処理されることを保障します。オーセンティケーターのRequirementを Mandatory に設定します。

Automatically Set Existing User

検証なしで、既存のユーザーを認証コンテキストに自動的に設定します。オーセンティケーターのRequirementを Mandatory に設定します。

アイデンティティー・プロバイダーの設定の First Login Flow にそのフローを設定する必要があります。アイデンティティー・プロバイダーの属性を使用してユーザー・プロファイル(姓、名など)を更新する場合は、 Sync Modeforce に設定することもできます。

このフローは、IDを他のアイデンティティー・プロバイダー(GitHub、Facebookなど)に委任したいが、ログインできるユーザーを管理したい場合に使用できます。

この設定では、Keycloakは、どの内部アカウントが外部アイデンティティーに対応するかを判断できません。 Verify Existing Account By Re-authentication オーセンティケーターは、プロバイダーにユーザー名とパスワードを要求します。

外部IDPトークンの取得

Keycloakでは、IDPの設定ページにある Store Token という設定オプションを使って、外部IDPでの認証プロセスから得たトークンとレスポンスを保存することができます。

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

GET /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 スイッチを ON に設定することで、新規にインポートしたユーザーにこのロールを割り当てることができます。

これらの外部トークンは、プロバイダーを介して再度ログインするか、クライアントが主導するアカウント・リンキングAPIを使用することで、再設定することができます。

アイデンティティー・ブローカー・ログアウト

ログアウトする際、Keycloakは、最初のログインに使用された外部の アイデンティティー・プロバイダーにリクエストを送信し、このアイデンティティー・プロバイダーからユーザーをログアウトさせます。この動作をスキップして、外部のアイデンティティー・プロバイダーからのログアウトを回避することができます。詳細は アダプター・ログアウトのドキュメント を参照してください。

SSOプロトコル

このセクションでは、認証プロトコル、Keycloak認証サーバー、およびKeycloak認証サーバーによって保護されたアプリケーションがこれらのプロトコルとどのように連動するかについて説明します。

OpenID Connect

OpenID Connect(OIDC)は、OAuth 2.0を拡張した認証プロトコルです。

OAuth 2.0は、認可プロトコルを構築するためのフレームワークであり、不完全なものです。しかし、OIDCは、 Json Web Token (JWT)標準を使用した完全な認証・認可プロトコルです。JWT標準は、IDトークンのJSONフォーマットと、コンパクトでウェブに適した方法でデータをデジタル署名・暗号化する方法を定義しています。

一般的に、OIDCは2つのユースケースを実装しています。1つ目のケースは、アプリケーションがKeycloakサーバーにユーザーの認証を要求する場合です。ログインに成功すると、アプリケーションは IDトークンアクセストークン を受け取ります。アイデンティティー・トークンには、ユーザー名、電子メール、プロフィール情報などのユーザー情報が含まれています。レルムは、ユーザーがアプリケーションでアクセスできるリソースを決定するためにアプリケーションが使用するアクセス情報(ユーザー・ロール・マッピングなど)を含む アクセストークン にデジタル署名します。

2つ目のユースケースは、クライアントがリモートサービスにアクセスする場合です。

  • クライアントは、ユーザーに代わってリモートサービスを呼び出すために、Keycloakに アクセストークン を要求します。

  • Keycloakはユーザーを認証し、リクエストしたクライアントにアクセスを許可することへの同意を求めます。

  • クライアントは、レルムによってデジタル署名された アクセストークン を受け取ります。

  • クライアントは、 アクセストークン を使ってリモートサービスにRESTリクエストを行います。

  • リモートRESTサービスは、 アクセストークン を抽出します。

  • リモートRESTサービスはトークンの署名を検証します。

  • リモートRESTサービスは、トークン内のアクセス情報に基づいて、リクエストを処理するか拒否するかを決定します。

OIDC認証フロー

OIDCには、クライアントやアプリケーションがユーザーを認証し、 IDトークン および アクセストークン を受け取るために使用できるいくつかの方法、またはフローがあります。その方法は、アクセスを要求するアプリケーションやクライアントの種類によって異なります。

認可コード・フロー

認可コードフローは、ブラウザーベースのプロトコルであり、ブラウザーベースのアプリケーションの認証と認可に適しています。ブラウザーのリダイレクトを利用して、 IDトークン および アクセストークン を取得します。

  1. ユーザーがブラウザーを使ってアプリケーションにアクセスします。アプリケーションは、ユーザーがアプリケーションにログインしていないことを検出します。

  2. アプリケーションは、認証のためにブラウザーをKeycloakにリダイレクトします。

  3. アプリケーションは、ブラウザーのリダイレクトのクエリー・パラメーターとしてコールバックURLを渡します。Keycloakは、認証に成功するとそのパラメーターを使用します。

  4. Keycloakは、ユーザーを認証し、1回限りの短命の一時的なコードを作成します。

  5. Keycloakは、コールバックURLを用いてアプリケーションにリダイレクトし、コールバックURLのクエリー・パラメーターとして一時コードを追加します。

  6. アプリケーションは一時的なコードを抽出し、バックグラウンドで Keycloak に REST 呼び出しを行い、コードを identity および accessrefresh トークンに交換します。 リプレイ攻撃を防ぐため、一時的なコードを複数回使用することはできません。

システムは、盗まれたトークンの有効期間中、そのトークンに対して脆弱です。セキュリティーとスケーラビリティーの観点から、アクセストークンは一般にすぐに期限切れになるように設定されており、それ以降のトークンリクエストには失敗します。トークンの有効期限が切れた場合、アプリケーションはログイン・プロトコルによって送信される追加の リフレッシュ トークンを使用して新しいアクセストークンを取得することができます。

コンフィデンシャル ・クライアントは、一時的なコードをトークンに交換する際にクライアント・シークレットを提供します。パブリック・クライアントは、クライアント・シークレットの提供は必要ありません。パブリック・クライアントは、HTTPSを厳密に実施し、クライアントに登録されるリダイレクトURIを厳密に管理することで安全性を確保します。HTML5/JavaScriptクライアントは、クライアント・シークレットを安全に送信する方法がないため、 パブリック クライアントである必要があります。詳しくは クライアントの管理 の章を参照してください。

Keycloakは、 Proof Key for Code Exchange の仕様にも対応しています。

インプリシット・フロー

インプリシット・フローは、ブラウザーベースのプロトコルです。認可コードフローと似ているが、リクエスト数が少なく、リフレッシュ・トークンもありません。

トークンをリダイレクトURIで送信する場合、 アクセス トークンがブラウザーの履歴に漏れる可能性があります(下記参照)。

また、このフローでは、クライアントにリフレッシュトークンを提供しません。したがって、アクセストークンは長寿命でなければならず、また、アクセストークンの有効期限が切れると、ユーザーは再認証をしなければならない。

このフローを使用することはお勧めしません。このフローがサポートされているのは、OIDCとOAuth 2.0の仕様に含まれているからです。

プロトコルは次のように動作します。

  1. ユーザーがブラウザーを使ってアプリケーションにアクセスします。アプリケーションは、ユーザーがアプリケーションにログインしていないことを検出します。

  2. アプリケーションは、認証のためにブラウザーをKeycloakにリダイレクトします。

  3. アプリケーションは、ブラウザーのリダイレクトにコールバックURLをクエリー・パラメーターとして渡します。Keycloakは、認証に成功すとクエリー・パラメーターを使用します。

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

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

リソース・オーナー・パスワード・クレデンシャル・グラント(Direct Access Grants)

Direct Access Grants は、RESTクライアントがユーザーの代わりにトークンを取得するために使用されます。これは、HTTP POSTリクエストで、以下を含みます。

  • ユーザーのクレデンシャル。クレデンシャルはフォームのパラメーターで送信されます。

  • クライアントのID。

  • クライアントのシークレット(コンフィデンシャル・クライアントの場合)。

HTTP レスポンスには、 ID トークン、 アクセス トークン、 リフレッシュ トークンが含まれます。

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

クライアント・クレデンシャル・グラント は、外部ユーザーの代わりに動作するトークンを取得するのではなく、クライアントに関連付けられたサービス・アカウントのメタデータとパーミッションに基づいてトークンを作成します。 クライアント・クレデンシャル・グラント は REST クライアントによって使用されます。

詳しくはサービス・アカウントの章を参照してください。

デバイス認可グラント

これは、入力機能が制限されているか、適切なブラウザーがない、インターネットに接続されたデバイスで実行されているクライアントによって使用されます。プロトコルの簡単な概要は次のとおりです。

  1. アプリケーションはKeycloakにデバイスコードとユーザーコードを要求します。Keycloakは、デバイスコードとユーザーコードを作成します。Keycloakは、デバイス コードとユーザーコードを含むレスポンスをアプリケーションに返します。

  2. アプリケーションは、ユーザーコードと検証URIをユーザーに提供します。ユーザーは、別のブラウザーを使用して、認証を受けるための検証URIにアクセスします。

  3. アプリケーションはKeycloakを繰り返しポーリングして、ユーザーがユーザー認証を完了したかどうかを調べます。ユーザー認証が完了すると、アプリケーションはデバイス コードを ID トークン、 access トークン、 および refresh トークンと交換します。

クライアント起点バックチャネル認証グラント

この機能は、OAuth 2.0の認可コードグラントのようにユーザーのブラウザーを通してリダイレクトすることなく、OpenIDプロバイダーと直接通信して認証フローを開始させたいクライアントが使用します。以下はプロトコルの概要です。

  1. クライアントは、クライアントによって行われた認証リクエストを識別するauth_req_idをKeycloakに要求します。Keycloakはauth_req_idを作成します。

  2. このauth_req_idを受信した後、このクライアントはKeycloakを繰り返しポーリングして、ユーザーが認証されるまでauth_req_idと引き換えにKeycloakからアクセストークン、リフレッシュトークン、IDトークンを取得する必要があります。

管理者は、Client Initiated Backchannel Authentication (CIBA) 関連の操作をレルムごとの CIBA Policy として設定できます。

また、Securing Applications and Services Guideの Backchannel Authentication Endpointのセクション やSecuring Applications and Services Guideの ClientInitiated Backchannel Authentication Grant のセクションなど、Keycloakドキュメントの他の場所も参照してください。

CIBAポリシー

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

  • Authentication → CIBA Policy タブを開きます.

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

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

設定 説明

Backchannel Token Delivery Mode

CD(Consumption Device)には認証結果と関連トークンを取得する方法を指定します。"poll"、"ping"、"push"の3つのモードがあります。Keycloakは"poll"のみをサポートします。デフォルト設定は"poll"です。この設定は必須です。詳細については、 CIBA Specification を参照してください。

Expires In

認証リクエストを受信してからの"auth_req_id"の有効期限(秒単位)。デフォルトの設定は120です。この設定は必須です。詳細については、 CIBA Specification を参照してください。

Interval

CD(Consumption Device)がトークン・エンドポイントへのポーリング・リクエスト間で待機する必要がある秒単位の間隔。デフォルト設定は5です。この設定はオプションです。詳細については、 CIBA Specification を参照してください。

Authentication Requested User Hint

認証が要求されているエンドユーザーを識別する方法。デフォルト設定は"login_hint"です。"login_hint"、"login_hint_token"、"id_token_hint"の3つのモードがあります。Keycloakは"login_hint"のみをサポートします。この設定は必須です。詳細については、 CIBA Specification を参照してください。

プロバイダー設定

CIBAグラントは、次の2つのプロバイダーを使用します。

  1. 認証チャネル・プロバイダー:Keycloakと、AD(Authentication Device)を介してユーザーを実際に認証するエンティティーとの間の通信を提供します。

  2. User Resolver Provider:クライアントから提供された情報からKeycloakの UserModel を取得して、ユーザーを識別します。

Keycloakには両方のデフォルト・プロバイダーがあります。ただし、管理者は次のように認証チャネル・プロバイダーを設定する必要があります。

kc.[sh|bat] start --spi-ciba-auth-channel-ciba-http-auth-channel-http-authentication-channel-uri=https://backend.internal.example.com

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

設定 説明

http-authentication-channel-uri

AD(Authentication Device)を介して実際にユーザーを認証するエンティティーのURIを指定します。

Authentication Channel Provider

CIBA標準ドキュメントでは、ADによるユーザーの認証方法は指定されていません。したがって、製品の判断で実装される可能性があります。Keycloakは、この認証を外部認証エンティティーに委任します。認証エンティティーと通信するために、Keycloakは認証チャネル・プロバイダーを提供します。

Keycloakの実装は、認証エンティティーがKeycloakの管理者の制御下にあることを前提としているため、Keycloakは認証エンティティーを信頼します。Keycloakの管理者が制御できない認証エンティティーを使用することはお勧めしません。

認証チャネル・プロバイダーはSPIプロバイダーとして提供されるため、Keycloakのユーザーは、環境に合わせて独自のプロバイダーを実装できます。Keycloakは、HTTPを使用して認証エンティティーと通信するHTTP認証チャネル・プロバイダーと呼ばれるデフォルトのプロバイダーを提供します。

KeycloakのユーザーがHTTP認証チャネル・プロバイダーを使用する場合、Keycloakと次の2つの部分で構成される認証エンティティーとの間のコントラクトを知る必要があります。

Authentication Delegation Request/Response

Keycloakは、認証リクエストを認証エンティティーに送信します。

Authentication Result Notification/ACK

認証エンティティーは、認証の結果をKeycloakに通知します。

認証委任リクエスト/レスポンスは、次のメッセージで構成されます。

Authentication Delegation Request

リクエストはKeycloakから認証エンティティーに送信され、ADによるユーザー認証を要求します。

POST [delegation_reception]
  • Headers

名前 説明

Content-Type

application/json

メッセージ本文はJSON形式です。

Authorization

Bearer [token]

[token]は、認証エンティティーが認証の結果をKeycloakに通知するときに使用されます。

  • Parameters

Type 名前 説明

Path

delegation_reception

委任リクストを受信するために認証エンティティーによって提供されるエンドポイント

  • Body

名前 説明

login_hint

ADによって認証された認証エンティティーに通知します。
デフォルトでは、これはユーザーの"username"です。
このフィールドは必須であり、CIBA標準ドキュメントによって定義されています。

scope

認証エンティティーが認証されたユーザーから同意を得るスコープを示します。
このフィールドは必須であり、CIBA標準ドキュメントによって定義されています。

is_consent_required

認証エンティティーがスコープについて認証されたユーザーから同意を得る必要があるかどうかを示します。
この項目は必須です。

binding_message

その値は、CDとADのUIの両方に表示され、ADによる認証がCDによってトリガーされたことをユーザーに認識させることを目的としています。
このフィールドはオプションであり、CIBA標準ドキュメントによって定義されています。

acr_values

CDから要求している認証コンテキストクラス参照を通知します。
このフィールドはオプションであり、CIBA標準ドキュメントによって定義されています。

Authentication Delegation Response

認証エンティティーからKeycloakにレスポンスが返され、認証エンティティーがKeycloakから認証リクエストを受信したことが通知されます。

  • Responses

HTTPステータスコード 説明

201

認証委任リクエストを受信したことをKeycloakに通知します。

認証結果通知/ACKは以下のメッセージで構成されています。

認証結果通知

認証エンティティーは、認証リクエストの結果をKeycloakに送信します。

POST /realms/[realm]/protocol/openid-connect/ext/ciba/auth/callback
  • Headers

名前 説明

Content-Type

application/json

メッセージ本文はJSON形式です。

Authorization

Bearer [token]

[token]は、認証エンティティーが認証委任リクエストでKeycloakから受信したものである必要があります。

  • Parameters

Type 名前 説明

Path

realm

レルム名

  • Body

名前 説明

status

ADによるユーザー認証の結果を示します。
以下のステータスのいずれかでなければなりません。
SUCCEED:ADによる認証が正常に完了しました。
UNAUTHORIZED:ADによる認証が完了していません。
CANCELLED:ADによる認証がユーザーによってキャンセルされました。

Authentication Result ACK

レスポンスはKeycloakから認証エンティティーに返され、認証エンティティーからADによるユーザー認証の結果をKeycloakが受信したことを通知します。

  • Responses

HTTPステータスコード 説明

200

認証結果の通知を受信したことを認証エンティティーに通知します。

User Resolver Provider

同じユーザーであっても、その表現はCD、Keycloak、および認証エンティティーごとに異なる場合があります。

CD、Keycloak、および認証エンティティーが同じユーザーを認識するために、このユーザー・リゾルバー・プロバイダーは、それらの間で独自のユーザー表現を変換します。

ユーザー・リゾルバー・プロバイダーはSPIプロバイダーとして提供されるため、Keycloakのユーザーは、環境に合わせて独自のプロバイダーを実装できます。Keycloakは、次の特性を持つDefault User ResolverProviderと呼ばれるデフォルト・プロバイダーを提供します。

  • login_hint パラメーターのみをサポートし、デフォルトとして使用されます。

  • KeycloakのUserModelの username は、CD、Keycloak、および認証エンティティーのユーザーを表すために使用されます。

OIDCログアウト

OIDCには、ログアウト機構に関連する4つの仕様があります。これらの仕様はドラフト状態です。

繰り返しになりますが、これはすべてOIDCの仕様で説明されているため、ここでは簡単な概要のみを示します。

Session Management

これはブラウザーベースのログアウトです。アプリケーションは、定期的にKeycloakからセッション・ステータス情報を取得します。セッションがKeycloakで終了すると、アプリケーションはそれに気づき、自身のログアウトをトリガーします。

RP-Initiated Logout

これはブラウザーベースのログアウトでもあり、ログアウトはユーザーをKeycloakの特定のエンドポイントにリダイレクトすることで始まります。このリダイレクトは通常、以前にKeycloakを使ってユーザーを認証していた何らかのアプリケーションのページで、ユーザーが Log Out リンクをクリックしたときに起こります。

ユーザーがログアウト・エンドポイントにリダイレクトされると、Keycloakはクライアントにログアウト・リクエストを送信して、ローカル・ユーザー・セッションを無効化させます。 id_token_hint パラメーターが使用されていない場合、ユーザはログアウトを確認するようオプションで要求されることがあります。ログアウト後、パラメーターとして post_logout_redirect_uri が指定されている限り、ユーザーは自動的に post_logout_redirect_uri へとリダイレクトされます。なお、 post_logout_redirect_uri が含まれる場合は、 client_id または id_token_hint パラメーターのいずれかを含める必要があります。また、 post_logout_redirect_uri パラメーターは、クライアントの設定で指定した Valid Post Logout Redirect URIs のいずれかに一致する必要があります。

クライアントの設定によって、ログアウト・リクエストはフロントチャネルまたはバックチャネルを通してクライアントに送信することができます。前のセクションで説明したセッション管理に依存するフロントエンド・ブラウザー・クライアントの場合、Keycloakはそれらにログアウト・リクエストを送信する必要はありません。これらのクライアントはブラウザーのSSOセッションがログアウトされたことを自動的に検出します。

フロントチャネル・ログアウト

フロントチャネルでログアウト・リクエストを受信するようにクライアントを設定するには、Front-Channel Logoutのクライアントの設定を見てください。この方法を使用する場合、以下の点を考慮してください。

  • Keycloakがクライアントに送信するログアウト・リクエストは、ブラウザーと、ログアウトページでレンダリングされる埋め込みの iframe に依存しています。

  • フロントチャネルのログアウトは、 iframe に基づいているため、コンテンツ・セキュリティー・ポリシー(CSP)の影響を受け、ログアウト・リクエストがブロックされる可能性があります。

  • ログアウトページを表示する前、またはログアウト・リクエストが実際にクライアントに送信される前にユーザーがブラウザーを閉じた場合、クライアントでのセッションが無効にならない可能性があります。

ユーザーをログアウトさせ、クライアント上のセッションを終了させるには、より信頼性が高く安全な方法であるバックチャネル・ログアウトの使用を検討してください。

クライアントがフロントチャネル・ログアウトを有効にしていない場合、KeycloakはまずBack-Channel Logout URLを使ってバックチャネルでログアウト・リクエストを送ろうとします。<_back-channel-logout-url, Back-Channel Logout URL>定義されていない場合、サーバーはAdmin URLの使用に戻ります。

Backchannel Logout

これは、Keycloakとクライアント間の直接バックチャネル通信を使用する非ブラウザーベースのログアウトです。Keycloakは、ログアウト・トークンを含むHTTP POSTリクエストをKeycloakにログインしているすべてのクライアントに送信します。これらのリクエストは、Keycloakの登録済みバックチャネル・ログアウトURLに送信され、クライアント側でログアウトをトリガーすることになっています。

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

Keycloakが公開しているOIDCエンドポイントの一覧を以下に示します。これらのエンドポイントは、Keycloak以外のクライアント・アダプターがOIDCを用いて認証サーバーと通信する際に利用することができます。これらはすべて相対URLです。URLのルートは、HTTP(S)プロトコル、ホスト名、そしてオプションとしてパスからなります。たとえば、以下です。

https://localhost:8080
/realms/{realm-name}/protocol/openid-connect/auth

認可コードフローで一時的なコードを取得したり、インプリシット・フロー、ダイレクト・グラント、クライアント・グラントでトークンを取得する際に使用します。

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

認可コードフローで、一時的なコードをトークンに変換するために使用されます。

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

ログアウトを実行するために使用します。

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

OIDC仕様に記載されているUser Infoサービスに使用されます。

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

RFC7009 に記載されているOAuth 2.0 Token Revocationに使用されます。

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

JSON Web Token (jwks_uri) を検証するために使用する公開鍵を含むJSON Web Key Set (JWKS) に使用します。

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

デバイス認可グラントで、デバイスコードとユーザーコードを取得するために使用します。

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

Client Initiated Backchannel Authentication GrantのURLエンドポイントで、クライアントが行った認証リクエストを識別するauth_req_idを取得します。

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

OIDC仕様に記載されているバックチャネル・ログアウトを実行するためのURLエンドポイントです。

いずれも{realm-name}をレルムの名前に置き換えてください。

SAML

SAML 2.0は、OIDCと同様の仕様ですが、より成熟しています。SAML 2.0は、SOAPやWebサービスのメッセージング仕様の流れを汲んでいるため、一般にOIDCよりも冗長です。 SAML 2.0は、認証サーバーとアプリケーションの間でXML文書を交換する認証プロトコルです。リクエストとレスポンスの検証には、XML署名と暗号化が用いられます。

一般に、SAMLは2つのユースケースを実装しています。

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

2つ目のユースケースは、クライアントがリモート・サービスにアクセスする場合です。クライアントは、KeycloakからSAMLアサーションを要求して、ユーザーに代わってリモート・サービスを呼び出します。

SAMLバインディング

Keycloakは、3つのバインディング・タイプに対応しています。

REDIRECTバインディング

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

  1. あるユーザーがブラウザーを使ってアプリケーションに接続します。アプリケーションは、ユーザーが認証されていないことを検出します。

  2. アプリケーションはXML認証要求文書を生成し、URIのクエリー・パラメーターとしてエンコードします。このURIは、Keycloakサーバーへのリダイレクトに使用されます。設定によっては、アプリケーションはXMLドキュメントにデジタル署名し、その署名をKeycloakへのリダイレクトURIのクエリー・パラメーターとして含めることもできます。この署名は、リクエストを送信したクライアントを検証するために使用されます。

  3. ブラウザーはKeycloakにリダイレクトされます。

  4. サーバーはXML認証要求文書を抽出し、必要であれば電子署名を検証します。

  5. ユーザーは認証クレデンシャルを入力します。

  6. 認証後、サーバーはXML認証応答文書を生成します。この文書には、名前、住所、電子メール、およびユーザーが持つすべてのロールマッピングなど、ユーザーに関するメタデータを保持するSAMLアサーションが含まれます。この文書は、通常、XML署名を使用してデジタル署名され、暗号化されることもあります。

  7. XML認証応答文書は、リダイレクトURIのクエリー・パラメーターとしてエンコードされます。このURIにより、ブラウザーはアプリケーションに戻ります。デジタル署名もクエリー・パラメーターとして含まれます。

  8. アプリケーションはリダイレクトURIを受け取り、XMLドキュメントを抽出します。

  9. アプリケーションはレルムの署名を検証し、有効な認証応答を受け取っていることを確認します。SAMLアサーション内の情報は、アクセスの判断やユーザーデータの表示に使用されます。

POSTバインディング

POST バインディングは Redirect バインディングと似ていますが、 POST バインディングはGETリクエストの代わりにPOSTリクエストを使ってXMLドキュメントを交換します。 POST バインディングは、ドキュメントを交換する際にJavaScriptを使用して、ブラウザーがKeycloakサーバーやアプリケーションにPOSTリクエストを送信するようにします。HTTPは、JavaScriptが埋め込まれたHTMLフォームを含むHTMLドキュメントで応答します。ページがロードされると、JavaScriptは自動的にフォームを呼び出します。

2つの制約があるため、 POST バインディングを推奨します。

  • セキュリティー — Redirect バインディングにおいて、SAMLレスポンスはURLの一部となります。これは、ログにレスポンスを記録する可能性があるため、安全性が低いです。

  • サイズ — HTTPペイロードでドキュメントを送信することで、限られたURLで送信するよりも大量のデータに対してより広い範囲を提供します。

ECP

拡張クライアントまたはプロキシー(ECP)は、SAML v.2.0プロファイルであり、Webブラウザーのコンテキスト外でSAML属性の交換を可能にするものです。これは、RESTまたはSOAPベースのクライアントでよく使用されます。

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

Keycloakは、すべてのSAMLリクエストに対して1つのエンドポイントを持ちます。

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

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

OpenID ConnectとSAMLの比較

以下に、プロトコルを選択する際に考慮すべきいくつかの要素を列挙します。

ほとんどの場合、KeycloakはOIDCの使用を推奨しています。

OIDC

  • OIDCはウェブとの連携に特化して設計されています。

  • OIDCは、SAMLに比べてクライアント側での実装が容易なため、HTML5/JavaScriptアプリケーションに向いています。

  • OIDCのトークンはJSON形式であるため、JavaScriptで簡単に利用することができます。

  • OIDCは、セキュリティーの実装を容易にするための機能を備えています。たとえば、ユーザーのログイン状態を判断するために仕様が使用している iframe trick を参照してください。

SAML

  • SAMLは、Webの上で動作するレイヤーとして設計されています。

  • SAMLは、OIDCよりも冗長である可能性があります。

  • ユーザーがOIDCよりSAMLを選ぶのは、SAMLが成熟しているという認識があるからです。

  • ユーザーは、SAMLで保護されたOIDCの既存アプリケーションよりも、SAMLを選ぶのです。

Dockerレジストリv2認証

Docker認証はデフォルトで無効になっています。Docker認証を有効にするには、 Enabling and disabling features ガイドを参照してください。

Docker Registry V2 Authenticationは、OIDCに似た、Dockerレジストリに対してユーザを認証するプロトコルです。 Keycloakの実装では、DockerクライアントがKeycloak認証サーバを使用してレジストリに対して認証を行うことができます。このプロトコルは標準的なトークンと署名のメカニズムを使用していますが、真のOIDCの実装からは逸脱しています。それは、リクエストとレスポンスに非常に特殊なJSONフォーマットを使用することと、リポジトリ名とパーミッションをOAuthスコープ機構にマッピングすることで逸脱しています。

Dockerの認証フロー

認証の流れは、 Docker APIドキュメント に記載されています。以下はKeycloak認証サーバーの立場からまとめたものです。

  • docker login を実行します。

  • DockerクライアントはDockerレジストリにリソースを要求します。 リソースが保護されており、認証トークンがリクエストに含まれていない場合、Dockerレジストリサーバーは、必要なパーミッションと認証サーバーの場所に関するいくつかの情報を含む401 HTTPメッセージで応答します。

  • Dockerクライアントは、Dockerレジストリからの401 HTTPメッセージに基づいて、認証リクエストを構築します。クライアントはローカルにキャッシュされた認証情報( docker login コマンドによる)を、Keycloak 認証サーバへの HTTP Basic Authentication リクエストの一部として使用します。

  • project_name}認証サーバーは、ユーザーの認証を試み、OAuthスタイルのBearerトークンを含むJSONボディを返します。

  • DockerクライアントはJSONレスポンスからベアラートークンを受け取り、それをauthorizationヘッダーに使用して保護されたリソースを要求します。

  • Dockerレジストリは、Keycloakサーバーからトークン付きの保護されたリソースに対する新しいリクエストを受信します。レジストリはトークンを検証し、要求されたリソースへのアクセスを許可します (適切な場合)。

Keycloakは、Dockerプロトコルで認証に成功した後、ブラウザのSSOセッションを作成しない。ブラウザSSOセッションは、トークンのリフレッシュや、トークンやセッションの状態をKeycloak サーバから取得できないため、Dockerプロトコルを使用しません。したがって、ブラウザSSOセッションは必要ありません。詳しくは、<>の<_transient-session, transient session>項を</_transient-session,>ご覧ください。

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

Keycloakは、すべてのDocker auth v2リクエストに対して1つのエンドポイントを持ちます。

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

管理コンソールへのアクセス制御

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

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

各レルムには専用の管理コンソールがあり、 /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は、 テクノロジー・プレビュー であり、完全にはサポートされていません。この機能はデフォルトで無効になっています。

有効にするには、 --features=preview または --features=admin-fine-grained-authz と入力してサーバーを起動します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

クライアント管理

Fine grain client

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

クライアント・パーミッション・タブ

Fine grain client permissions tab

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

Permissions Enabled スイッチをOFFにすると、このクライアントに対して定義したすべてのパーミッションが削除されます。
クライアント・パーミッション・タブ

Fine grain permission tab

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

クライアント管理パーミッション

Fine grain client manage permission

最初に初期化されたとき、 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 レルムの専用の管理コンソールに再ログインします。専用の管理コンソールは /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

そのタブをクリックし、 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 user permissions

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

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

view-usersの追加

Fine grain add view users

テストする

次に、masterレルムからログアウトし、 sales-admin ユーザーで test レルムの専用の管理コンソールに再ログインします。専用の管理コンソールは /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

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

パーミッションの一覧

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

ロール

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

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

OpenID ConnectおよびSAMLのクライアントの管理

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

OpenID Connectクライアントの管理

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

OpenID Connectクライアントの作成

OpenID Connectプロトコルを使用するアプリケーションを保護するために、クライアントを作成します。

手順
  1. メニューの Clients をクリックします。

  2. Create client をクリックします。

    クライアントの作成

    Create Client

  3. Client typeOpenID Connect に設定したままにしてください。

  4. Client ID を入力してください。

    このIDは、OIDCのリクエストやKeycloakデータベースで、クライアントを識別するために使用される英数字の文字列です。

  5. クライアントの Name を入力します。

    この名前をローカライズする予定がある場合は、代替となる文字列値を設定します。たとえば、 ${myapp} のような文字列値です。詳しくは、 Server Developer Guide を参照してください。

  6. Save をクリックします。

この操作により、クライアントが作成され、 Settings タブが表示され、 基本設定を実行できます。

基本設定

Settings タブには、このクライアントを設定するための多くのオプションが含まれています。

Settingsタブ

Settings tab

一般的な設定
Client ID

OIDCリクエストおよびKeycloakデータベースでクライアントを識別するために使用される英数字のID文字列です。

Name

Keycloakにおけるクライアントの名前。UI画面での名称。名前をローカライズするには、置換文字列値を設定します。たとえば、${myapp}のような文字列値です。詳しくは、 Server Developer Guide を参照してください。

説明

クライアントの説明文です。この設定はローカライズすることも可能です。

Always Display in Console

このユーザーがアクティブなセッションを持っていない場合でも、常にこのクライアントをアカウント・コンソールにリストアップします。

アクセス設定
Root URL

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

Home URL

認証サーバーがクライアントにリダイレクトまたはリンクバックする必要がある場合のデフォルトのURLを提供します。

Valid Redirect URIs

必須項目です。URLパターンを入力し、 + で追加、 - で既存のURLを削除して Save をクリックします。URLパターンの末尾にワイルドカードを使用することができます。例) http://host.com/*

排他的リダイレクトURLパターンは、通常、より安全です。詳しくは Unspecific Redirect URIs を参照してください。

Web Origins

URLパターンを入力し、+をクリックして追加し、-をクリックして既存のURLを削除します。Saveをクリックします。

このオプションは、 Cross-Origin Resource Sharing (CORS) を処理します。ブラウザーのJavaScriptが、JavaScriptコードが由来するドメインとは異なるサーバーにAJAX HTTPリクエストを試みる場合、そのリクエストはCORSを使用する必要があります。サーバーはCORSリクエストを処理する必要があり、そうでない場合、ブラウザーはそのリクエストを表示しないか、処理することを許可しません。このプロトコルは、XSS、CSRF、およびその他のJavaScriptベースの攻撃から保護します。

ここに記載されているドメインURLは、クライアント・アプリケーションに送信されるアクセストークンの中に埋め込まれています。クライアント・アプリケーションは、この情報を使用して、CORSリクエストの呼び出しを許可するかどうかを決定します。この機能をサポートしているのは、Keycloakクライアント・アダプターのみです。詳しくは、 Securing Applications and Services Guide を参照してください。

Admin URL

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

キャパシティー設定
Client authentication

OIDCクライアントの種類を表します。

  • ON

    ブラウザー・ログインを行い、アクセストークン・リクエストの際にクライアント・シークレットを要求するサーバーサイド・クライアント用。この設定は、サーバーサイドのアプリケーションで使用する必要があります。

  • OFF

    ブラウザー・ログインを行うクライアントサイドのクライアント用。クライアントサイドのクライアントでは、シークレットの保持を確実に行うことができないため、正しいリダイレクトURIを設定することでアクセスを制限することが重要です。

Authorization

このクライアントのきめ細かな認可サポートを有効または無効にします。

Standard Flow

有効な場合、このクライアントはOIDCの 認証コードフロー を使用することができます。

Direct Access Grants

有効な場合、このクライアントはOIDCの ダイレクトアクセスグラント を使用することができます。

Implicit Flow

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

Service account roles

有効な場合、このクライアントはKeycloakに対して認証を行い、このクライアント専用のアクセストークンを取得することができます。OAuth2仕様では、このクライアントの Client Credentials Grant のサポートが可能になります。

Auth 2.0 Device Authorization Grant

有効な場合、このクライアントは、OIDCの デバイス認可グラントを使用できます。

OIDC CIBA Grant

有効な場合、このクライアントは、OIDCの Client Initiated Backchannel Authentication Grant を使用できる。

ログイン設定
Login theme

ログイン、ワンタイム・パスワード、グラント登録、パスワード忘れなどのページに使用するテーマです。

Consent required

有効な場合、ユーザーはクライアントのアクセスに同意する必要があります。

ブラウザー・ログインを行うクライアントサイドのクライアント用。クライアントサイドのクライアントでは、シークレットの保持を確実に行うことができないため、正しいリダイレクトURIを設定することでアクセスを制限することが重要です。

Display client on screen

このスイッチは、 Consent RequiredOff の場合に適用されます。

  • Off

    同意画面には、設定されたクライアント・スコープに対応する同意のみが表示されます。

  • On

    また、同意画面には、このクライアント自身についての項目が1つあります。

Client consent screen text

Consent requiredDisplay client on screen が有効な場合に適用されます。このクライアントの許可について、同意画面に表示されるテキストが含まれています。

ログアウト設定
Front channel logout

Front Channel Logout が有効な場合、アプリケーションは OpenID Connect Front-Channel Logout の仕様に従って、フロントチャネルを通してユーザーをログアウトできるようにする必要があります。有効にした場合、 Front-Channel Logout URL も提供する必要があります。

Front-channel logout URL

Keycloakがフロントチャネルを通じてクライアントにログアウト・リクエストを送信するために使用するURL。

Backchannel logout URL

ログアウト・リクエストがこのレルムに(end_session_endpoint経由で) 送られたときに、クライアントが自分自身をログアウトさせるためのURL。省略された場合、ログアウト・リクエストはクライアントに送信されません。

Backchannel logout session required

Backchannel Logout URL を使用した場合に、ログアウトトークンにセッションIDクレームを含めるかどうかを指定します。

Backchannel logout revoke offline sessions

Backchannel Logout URLを使用する際に、ログアウト・トークンにrevoke_offline_accessイベントを含めるかどうかを指定します。このイベントを含むログアウト・トークンを受け取った場合、Keycloakはオフラインセッションを取り消します。

高度な設定

Settings タブのフィールドを完了した後、他のタブを使用して高度な設定を行うことができます。たとえば、 Permissions および Roles タブを使用して、管理者用のきめ細かい認証を設定することができます。Fine grain admin permissionsを参照してください。 また、その他の機能については、本章の残りのセクションを参照してください。

Advancedタブ

Advanced タブをクリックすると、追加のフィールドが表示されます。特定のフィールドの詳細については、そのフィールドのクエスチョン・マーク・アイコンをクリックしてください。 ただし、特定のフィールドについては、このセクションで詳しく説明しています。

Fine grain OpenID Connect configuration

Logo URL

クライアント・アプリケーション用のロゴを参照するURL。

Policy URL

プロファイル・データがどのように使用されるかについて読むために、Relying Partyがエンドユーザーに提供するURL。

Terms of Service URL

Relying Partyが、エンドユーザーにRelying Partyの利用規約を提供するURL。

Signed and Encrypted ID Token Support

Keycloakは、 Json Web Encryption (JWE) の仕様に従ってIDトークンを暗号化することができます。管理者は、クライアントごとにIDトークンを暗号化するかどうかを決定します。

IDトークンの暗号化に使用される鍵は、コンテンツ暗号化鍵(CEK)です。どのCEKを使うか、どのように配信するかは、Keycloakとクライアントが交渉する必要があります。CEKを決定するために使用される方法は、Key Management Modeです。KeycloakがサポートするKey Management ModeはKey Encryptionです。

Key Encryptionは以下のようになります。

  1. クライアントは、非対称暗号鍵ペアを生成する。

  2. 公開鍵は、CEK を暗号化するために使用される。

  3. Keycloak IDトークンごとにCEKを生成する。

  4. Keycloak この生成されたCEKを用いてIDトークンを暗号化する。

  5. Keycloakは、クライアントの公開鍵を用いてCEKを暗号化する。

  6. クライアントは、この暗号化されたCEKを自分の秘密鍵で復号化する。

  7. クライアントは復号化されたCEKを使用してIDトークンを復号化する。

クライアント以外の第三者は、IDトークンを復号化することはできません。

クライアントは、CEKを暗号化するための公開鍵をKeycloakに渡す必要があります。Keycloakは、クライアントが提供するURLからの公開鍵のダウンロードに対応しています。クライアントは、 Json Web Keys (JWK) の仕様に従った公開鍵を提供する必要があります。

手順を以下に示します。

  1. クライアントの Keys タブを開きます。

  2. JWKS URL をONに切り替えます。

  3. JWKS URL テキストボックスに、クライアントの公開鍵のURLを入力します。

Key Encryptionのアルゴリズムは、 Json Web Algorithm (JWA) 仕様で定義されています。Keycloakは以下に対応しています。

  • RSAES-PKCS1-v1_5(RSA1_5)

  • デフォルト・パラメータを使用したRSAES OAEP(RSA-OAEP)。

  • SHA-256とMFG1を用いたRSAES OAEP 256 (RSA-OAEP-256)

アルゴリズムを選択する手順としては

  1. クライアントの Advanced タブを開きます。

  2. Fine Grain OpenID Connect Configuration*を開きます。

  3. IDトークン暗号化コンテンツ暗号化アルゴリズム*のプルダウンメニューから、アルゴリズムを選択します。

Open ID Connect互換モード

この項目は後方互換性のために存在します。各項目の詳細については、クエスチョン・マークのアイコンをクリックしてください。

OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled

Mutual TLSは、アクセストークンとリフレッシュトークンを、TLSハンドシェイク中に交換されるクライアント証明書とともにバインドする。この結合により、攻撃者が盗んだトークンを使用することを防ぐことができます。

このタイプのトークンは、Holder-of-Keyトークンです。ベアラ・トークンと異なり、Holder-of-Key トークンの受信者は、トークンの送信者が正当であるかどうかを検証することができます。

この設定がオンの場合、ワークフローは次のようになります。

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

  2. Keycloak は、クライアント証明書を要求する。

  3. Keycloak は、クライアント証明書を受信する。

  4. Keycloak は、クライアント証明書の検証に成功しました。

検証に失敗した場合、Keycloak はトークンを拒否する。

以下の場合、Keycloakはアクセストークンまたはリフレッシュトークンを送信するクライアントを確認します。

  • トークン更新リクエストは、Holder-of-Keyのリフレッシュトークンと共にトークンエンドポイントに送信されます。

  • UserInfoリクエストは、Holder-of-Keyアクセストークンを伴ってUserInfoエンドポイントに送信される。

  • ログアウト要求は、Holder-of-keyリフレッシュトークンと共にLogoutエンドポイントに送信されます。

詳しくは、OAuth 2.0 相互TLSクライアント認証と証明書バウンドアクセストークンの Mutual TLS Client Certificate Bound Access Tokensをご覧ください。

現在、Keycloakクライアントアダプタは、Holder-of-Keyトークン検証をサポートしていない。Keycloak アダプタは、アクセス・トークンとリフレッシュ・トークンをベアラ・トークンとし て扱います。

Proof Key for Code Exchange Code Challenge Method

攻撃者が正規のクライアントの認証コードを盗んだ場合、Proof Key for Code Exchange(PKCE)により、そのコードに該当するトークンを攻撃者が受け取ることを防ぐことができます。

管理者は、これらのオプションのいずれかを選択することができます。

(blank)

Keycloakは、クライアントがKeycloakの認可エンドポイントに適切なPKCEパラメータを送信しない限り、PKCEを適用しない。

S256

Keycloakは、コードチャレンジ方式がS256であるクライアントPKCEに適用される。

plain

Keycloakは、コードチャレンジ方式がplainであるクライアントPKCEに適用される。

ACRとLevel of Authentication(LoA)のマッピング

クライアントの詳細設定では、どの Authentication Context Class Reference (ACR) 値がどの Level of Authentication (LoA) にマッピングされるかを定義することができます。このマッピングは、ACRからLoAへのマッピングで述べたように、レルムでも指定することができます。ベスト・プラクティスは、このマッピングをレルムレベルで設定することで、複数のクライアントで同じ設定を共有することができます。

このクライアントからKeycloakに acr_values パラメーターなしで、かつ acr クレームが付加された claims パラメーターなしでログイン・リクエストを送信した場合のデフォルト値を Default ACR Values で指定することができます。 公式のOIDC動的クライアント登録の仕様 を参照してください。

デフォルトのACR値はデフォルトのレベルとして使用されますが、特定のレベルでのログインを強制するために確実に使用することはできないことに注意してください。たとえば、 Default ACR Values をレベル2に設定したとします。すると、デフォルトでは、ユーザーはレベル2で認証することが要求されます。しかし、ユーザーが明示的に acr_values=1 のようなパラメーターをログイン・リクエストに付加した場合、レベル1が使用されることになります。そのため、クライアントが本当にレベル2を必要とする場合、クライアントはIDトークン内の acr クレームの存在を確認し、要求されたレベル2が含まれているかどうかダブルチェックすることが推奨されます。

ACR to LoA mapping

詳細については、ステップアップ認証および オフィシャルのOIDC仕様を参照してください。

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

クライアントのClient authenticationON に設定されている場合、 Credentials タブでクライアントのクレデンシャルを設定する必要があります。

Credentialsタブ

Credentials Tab

Client Authenticator ドロップダウン・リストでは、クライアントに使用するクレデンシャルの種類を指定します。

クライアントIDとシークレット

この選択肢はデフォルトの設定です。シークレットは自動的に生成されます。必要に応じて Regenerate をクリックして、シークレットを再作成してください。

署名付きJWT

Signed JWT

Signed JWT は "Signed Json Web Token"

このクレデンシャル・タイプを選択した場合、 Keys タブでクライアントの秘密鍵と証明書も生成する必要があります。秘密鍵はJWTに署名するために使われ、一方、証明書はサーバーが署名を検証するために使われます。

Keysタブ

Keys tab

Generate new keys ボタンをクリックすると、この処理が開始されます。

鍵を生成する

generate client keys

  1. 使用するアーカイブ形式を選択します。

  2. Key Password を入力します。

  3. store password を入力します。

  4. Generate をクリックします。

鍵を生成すると、Keycloakが証明書を保存するので、クライアント用に秘密鍵と証明書をダウンロードします。

また、外部ツールを使って鍵を生成し、 Import Certificate をクリックしてクライアントの証明書をインポートすることも可能です。

証明書のインポート

Import Certificate

  1. 証明書のアーカイブ形式を選択します。

  2. ストアパスワードを入力します。

  3. Import File をクリックして、証明書ファイルを選択します。

  4. Import をクリックします。

Use JWKS URL をクリックすると、証明書のインポートは不要になります。この場合、公開鍵が公開されているURLを JWK 形式で指定します。このオプションを使用すると、鍵が変更されることがあっても、Keycloakは鍵を再インポートできます。

Keycloakアダプターでセキュリティー保護されたクライアントを使用している場合、https://myhost.com/myapp をクライアント・アプリケーションのルートURLと仮定して、この形式でJWKS URLを設定することが可能です。

https://myhost.com/myapp/k_jwks

詳しくは Server Developer Guide を参照してください。

クライアントシークレットで署名されたJWT

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

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

X509 Certificate

Keycloakは、TLSハンドシェイク時にクライアントが適切なX509証明書を使用しているかどうかを検証します。

X509証明書

x509 client auth

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

KeycloakがリクエストからクライアントIDを取得する方法は2つ存在します。

  • クエリーの client_id パラメーターです( OAuth 2.0仕様 のセクション 2.2 で説明されています)。

  • フォームのパラメーターとして client_id を指定します。

クライアント・シークレットのローテーション

クライアント・シークレットのローテーションのサポートは開発中であることにご注意ください。この機能は実験的に使用してください。

コンフィデンシャルクライアント認証のKeycloakのクライアントについては、クライアント・ポリシーを通じてクライアント・シークレットをローテーションする機能をサポートしています。

クライアント・シークレットのローテーション・ポリシーは、シークレットの漏洩などの問題を軽減するための、より高いセキュリティーを提供します。有効にすると、Keycloakは各クライアントで同時に2つまで有効なシークレットをサポートします。このポリシーは、以下の設定に従ってローテーションを管理します。

  • Secret expiration: [seconds] - シークレットがローテーションされたとき、新しいシークレットの有効期限を示します。シークレット作成日に加算される 秒数 。ポリシー実行時に計算されます。

  • Rotated secret expiration: [seconds] - シークレットがローテーションされたとき、この値は古いシークレットの残りの有効期限となります。この値は、常にシークレットの有効期限よりも小さくする必要があります。この値が0の場合、クライアントのローテーション時に古いシークレットは即座に削除されます。シークレットローテーションの日付に加算される 秒数 です。ポリシー実行時に計算されます。

  • Remaining expiration time for rotation during update: [seconds] - 動的なクライアントへのアップデートでクライアント・シークレットのローテーションを行うべき期間です。ポリシー実行時に計算されます。

クライアント・シークレットのローテーションが発生すると、新しいメインシークレットが生成され、古いクライアントのメインシークレットは新しい有効期限を持つセカンダリー・シークレットとなる。

クライアント・シークレットのローテーションに関するルール

ローテーションは、自動的またはバックグラウンド・プロセスで行われることはありません。ローテーションを行うには、クライアントで更新アクションが必要です。Keycloakの管理コンソールの シークレットの再生成 機能、クライアントのクレデンシャルタブ、または 管理REST APIのいずれかを使用してください。クライアントの更新アクションを呼び出すと、ルールに従ってシークレットローテーションが行われます。

  • Secret expiration の値が現在の日付より小さい場合。

  • 動的クライアント登録のクライアント・アップデート・リクエスト時に、Remaining expiration time for rotation during update*の値が、現在の日付から *Secret expiration までの期間と一致する場合、クライアント・シークレットは自動的にローテーションされます。

さらに、管理REST APIを通じて、いつでもクライアント・シークレットのローテーションを強制することが可能です。

新規クライアントの作成時に、クライアント・シークレットのローテーション・ポリシーが有効な場合、この動作は自動的に適用されます。

既存のクライアントにシークレットのローテーションの動作を適用するには、ポリシーを定義した後にそのクライアントを更新して、動作が適用されるようにします。

OIDCクライアントのシークレットのローテーション・ポリシーの作成

以下は、シークレット・ローテーション・ポリシーを定義する例です。

手順
  1. メニューの Realm Settings をクリックします。

  2. Client Policies タブをクリックします。

  3. Profiles ページで Create client profile をクリックします。

    プロファイルの作成

    Create Client Profile

  4. Name には任意の名前を入力してください。

  5. Description には、プロファイルの目的を特定するのに役立つ説明を入力します。

  6. Save をクリックします。

    この操作でプロファイルが作成され、エクゼキューターが設定できるようになります。

  7. このプロファイルのエクゼキューターを設定するには、 Add executor をクリックします。

    プロファイル・エグゼキューターの作成

    Client Profile Executor

  8. Executor Typesecret-rotation を選択します。

  9. Secret Expiration には、各シークレットの最大継続時間を秒単位で入力します。

  10. ローテーションされた各シークレットの最大継続時間を、 Rotated Secret Expiration に秒単位で入力します。

    なお、 Rotated Secret Expiration の値は、常に Secret Expiration の値より小さくなければならないことを忘れないでください。
  11. あらゆるアップデート・アクションが Remain Expiration Time のクライアントをアップデートするまでの時間を、秒単位で入力します。

  12. Add をクリックします。

    上の例では以下になります。

    • 各シークレットの有効期限は1週間です。

    • ローテーションされたシークレットは、2日後に失効します。

    • 動的クライアントの更新ウィンドウは、シークレットの有効期限が切れる1日前から始まります。

  13. Client Policies タブに戻ります。

  14. Policies をクリックします。

  15. Create client policy をクリックします。

    クライアント・シークレット・ローテーション・ポリシーの作成

    Client Rotation Policy

  16. Name には任意の名前を入力してください。

  17. Description には、ポリシーの目的を特定するのに役立つ説明を入力します。

  18. Save をクリックします。

    このアクションでは、ポリシーを作成し、ポリシーとプロファイルを関連付けることができます。また、ポリシーの実行条件を設定できます。

  19. Conditionsの下にある Add condition をクリックします。

    クライアント・シークレット・ローテーション・ポリシー条件の作成

    Client Rotation Policy Condition

  20. すべてのコンフィデンシャル・クライアントに動作を適用するには、 Condition Type フィールドで client-access-type を選択します。

    特定のクライアントのグループに適用するには、別の方法として、 Condition Type フィールドで client-roles タイプを選択できます。この方法では、特定のロールを作成し、各ロールにカスタム・ローテーションの設定を割り当てることができます。

  21. Client Access Type フィールド に confidential を追加します。

  22. Add をクリックします。

  23. ポリシー設定に戻り、 Client Profiles の下にある Add client profile をクリックし、一覧から Weekly Client Secret Rotation Profile を選択し、Add をクリックします。

    クライアント・シークレット・ローテーション・ポリシー

    Client Rotation Policy

既存のクライアントにシークレット・ローテーションの動作を適用する場合は、以下の手順で行います。

管理コンソールの使用
  1. メニューの Clients をクリックします。

  2. クライアントをクリックします。

  3. 認証情報」タブをクリックします。

  4. クライアント・シークレットの Re-generate をクリックします。


クライアントRESTサービスを使用すると、2つの方法で実行できます。
  • クライアントのアップデート操作を通じて

  • クライアント・シークレットを再生するエンドポイントを介して

サービス・アカウントの使用

OIDCの各クライアントには、 サービス・アカウント が組み込まれています。この サービス・アカウント を使ってアクセストークンを取得します。

手順
  1. メニューの Clients をクリックします。

  2. クライアントを選択してださい。

  3. Settings タブをクリックします。

  4. クライアント認証On に切り替えます。

  5. Service accounts roles を選択します。

  6. Save をクリックします。

  7. クライアント・クレデンシャルの設定を行います。

  8. Scope タブをクリックします。

  9. ロールがあることを確認するか、 Full Scope AllowedON に切り替えてください。

  10. Service Account Roles タブをクリックします。

  11. このサービス・アカウントで利用可能なロールをクライアントに設定します。

アクセストークンからのロールは、以下の論理積となります。

  • クライアントのロール・スコープ・マッピングと、リンクされたクライアントのスコープから継承されたロール・スコープ・マッピングを組み合わせたもの。

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

起動するREST URLは、 /realms/{realm-name}/protocol/openid-connect/token です。このURLはPOSTリクエストとして呼び出す必要があり、クライアントのクレデンシャルをリクエストに添付する必要があります。

デフォルトでは、クライアントのクレデンシャルは、 Authorization.Basic ヘッダー内のクライアントのclientIdおよびclientSecretによって表されます。しかし、署名されたJWTアサーションやその他のカスタム・メカニズムを使ってクライアントを認証することもできます。

また、OAuth 2の仕様に従って、 grant_type パラメーターを "client_credentials" に設定する必要があります。

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

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

    grant_type=client_credentials

このレスポンスは、OAuth 2.0の仕様の Access Token Response に似ています。

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 のセクションで説明されているように、OAuth 2 Revocation Endpointにリクエストを送ることで失効させることができます。

追加のリソース

詳しくはClient Credentials Grantを参照してください。

Audienceのサポート

通常、Keycloakが配置される環境は、Keycloakを認証に使用する confidential クライアント・アプリケーションまたは public クライアント・アプリケーションのセットで構成されています。

クライアント・アプリケーションからのリクエストに対応し、これらのアプリケーションにリソースを提供する サービスOAuth 2 仕様では リソースサーバー ) も用意されています。これらのサービスでは、リクエストを認証するために アクセストークン (ベアラートークン)を送信する必要があります。このトークンは、フロントエンド・アプリケーションがKeycloakにログインした際に取得します。

サービス間の信頼性が低い環境では、このようなシナリオに遭遇することがあります。

  1. フロントエンド・クライアント・アプリケーションがKeycloakに対して認証を要求します。

  2. Keycloakは、ユーザーを認証します。

  3. Keycloakは、アプリケーションにトークンを発行します。

  4. アプリケーションはトークンを使って、信頼できないサービスを呼び出します。

  5. 信頼されないサービスはアプリケーションにレスポンスを返します。ただし、アプリケーションのトークンは保持します。

  6. 信頼されていないサービスは、アプリケーションのトークンを使用して信頼されたサービスを呼び出します。この結果、信頼されていないサービスがトークンを悪用して、クライアント・アプリケーションに代わって他のサービスにアクセスするため、セキュリティーが破られることになります。

このシナリオは、サービス間の信頼度が高い環境ではありえないが、信頼度が低い環境ではありえます。環境によっては、信頼されていないサービスが、元のクライアント・アプリケーションにデータを返すために、信頼されているサービスからデータを取得する必要があるため、このワークフローは正しいかもしれません。

サービス間に高い信頼性が存在する場合、無制限のAudienceが有効です。それ以外の場合は、Audienceを制限する必要があります。Audienceを制限すると同時に、信頼されていないサービスが信頼されているサービスからデータを取得することを許可することができます。この場合、信頼されていないサービスと信頼されたサービスがトークンのAudienceとして追加されていることを確認します。

アクセストークンの悪用を防ぐため、トークンのAudienceを制限し、トークンのAudienceを確認するようにサービスを設定してください。フローは以下のように変更されます。

  1. フロントエンド・アプリケーションはKeycloakに対して認証を行います。

  2. Keycloakは、ユーザーを認証します。

  3. Keycloakはアプリケーションにトークンを発行します。アプリケーションは信頼できないサービスを呼び出す必要があることを知っているので、Keycloakに送信する認証リクエストに scope=<untrusted service> を指定します。 scope パラメーターの詳細については、Client Scopes sectionを参照してください。

    アプリケーションに発行されたトークンは、そのAudience( "audience": [ "<untrusted service>" ] )に信頼されないサービスへの参照を含み、クライアントはこのアクセストークンを使って信頼されないサービスを呼び出すと宣言しています。

  4. 信頼されていないサービスは、トークンを使って信頼されたサービスを呼び出します。信頼されたサービスがトークンのAudienceをチェックし、そのAudienceが信頼されていないサービスのみであることを発見したため、呼び出しは成功しません。この動作は予期されるものであり、セキュリティーが破られることはありません。

クライアントが後で信頼できるサービスを呼び出したい場合、SSOログインを scope=<trusted service> で再発行して別のトークンを取得する必要があります。返されたトークンには、信頼されたサービスがAudienceとして含まれています。

"audience": [ "<trusted service>" ]

この値で <trusted service> を呼び出す。

セットアップ

Audienceチェックを設定する場合は、以下のようにします。

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

  • Keycloakが発行するアクセストークンには、必要なAudienceをすべて含んでいることを確認してください。Audienceは、次のセクションで説明したクライアントロールを使用して追加するか、ハードコードすることができます。ハードコードされたAudienceを参照してください。

Audienceを自動的に追加

Audience Resolve プロトコル・マッパーは、デフォルトのクライアントスコープ roles に定義されています。このマッパーは、現在のトークンに対して少なくとも一つのクライアントロールが利用可能であるクライアントをチェックします。これは、サービス(通常はbearer-only)クライアントがクライアントロールに依存している場合に有用です。

たとえば、bearer-onlyクライアントとコンフィデンシャル・クライアントの場合、コンフィデンシャル・クライアント用に発行されたアクセストークンを使用して、bearer-onlyクライアントのRESTサービスを呼び出すことが可能です。bearer-onlyクライアントは、以下の条件を満たす場合、コンフィデンシャル・クライアント用に発行されたアクセストークンに自動的にAudienceとして追加されます。

  • bearer-onlyクライアントは、自分自身に定義された任意のクライアントロールを持ちます。

  • 対象のユーザーは、これらのクライアントロールのうち少なくとも1つが割り当てられています。

  • コンフィデンシャル・クライアントは、割り当てられたロールのロール・スコープ・マッピングを持ちます。

Audienceが自動的に追加されないようにするには、コンフィデンシャル・クライアントで直接ロール・スコープ・マッピングを設定しないでください。代わりに、専用クライアント・スコープを作成し、その専用クライアント・スコープのクライアントロールのロール・スコープ・マッピングを含むことができます。

コンフィデンシャル・クライアントにオプションのクライアント・スコープが追加されたと仮定すると、scope=<trusted service>パラメーターで明示的に要求された場合、クライアントロールとAudienceがトークンに追加されます。

フロントエンド・クライアント自身はアクセストークンのAudienceに自動的に追加されないため、アクセストークンとIDトークンを容易に区別することができます(アクセストークンには、トークンがAudienceとして発行されるクライアントが含まれないためです)。

クライアント自体をAudienceとして必要とする場合は、ハードコードされたAudienceオプションを参照してください。しかし、同じクライアントをフロントエンドとRESTサービスの両方に使用することは推奨されません。

ハードコードされたAudience

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

プロトコル・マッパーは、フロントエンド・クライアントに直接追加することができます。プロトコル・マッパーを直接追加した場合、Audienceも必ず追加されます。

プロトコル・マッパーをより詳細に制御するには、専用のクライアント・スコープにプロトコル・マッパーを作成し、たとえば good-service と呼ばれるようにします。

Audienceプロトコル・マッパー

audience mapper

  • good-service クライアントのInstallationタブから、アダプターの設定を生成することができ、 verify-token-audience オプションが true に設定されることを確認することができます。これにより、この設定を使用した場合、アダプターは強制的にAudienceを確認することになります。

  • コンフィデンシャル・クライアントが、そのトークンにAudienceとして good-service を要求できるようにする必要があります。

    コンフィデンシャル・クライアントでは以下のようにします。

    1. Client Scopes タブをクリックします。

    2. オプション(またはデフォルト)のクライアント・スコープとして good-service を割り当てます。

      詳しくはClient Scopes Linkingのセクションを参照してください。

  • オプションでクライアント・スコープの評価とアクセストークンの例を生成することができます。オプションのクライアントスコープとして割り当てた場合、 scope パラメーターに good-service が含まれていれば、生成されたアクセストークンのAudienceに good-service が追加されます。

  • コンフィデンシャル・クライアント・アプリケーションでは、 scope パラメーターが使用されていることを確認してください。 good-service にアクセスするためのトークンを発行する場合は、値 good-service を含める必要があります。

    以下を参照してください。

AudienceAudience Resolve の両プロトコル・マッパーは、デフォルトではアクセストークンにのみAudienceを追加します。IDトークンは通常、OpenID Connectの仕様の要件である、トークンが発行されたクライアントIDという単一のAudienceのみを含みます。しかし、アクセストークンには、Audienceマッパーが追加しない限り、トークンが発行されたクライアントIDが含まれているとは限りません。

SAMLクライアントの作成

Keycloakは、登録されたアプリケーションに対してSAML 2.0をサポートし、POSTとRedirectのバインディングに対応しています。クライアント署名の検証を要求するかどうかを選択したり、サーバーに署名や暗号化をさせることもできます。

手順
  1. メニューの Clients をクリックします。

  2. Create client をクリックすると、Create client のページに移動します。

  3. Client type* を SAML に設定します。

    クライアントの作成

    add client saml

  4. クライアントの Client ID を入力します。これは多くの場合URLであり、アプリケーションから送信されるSAMLリクエストで期待される issuer の値です。

  5. 保存 をクリックします。この操作でクライアントが作成され、 Settings タブが表示されます。

次の項では、このタブの各設定について説明します。

Settingsタブ

Settings タブには、このクライアントを設定するための多くのオプションが含まれています。

クライアント設定

client settings saml

一般的な設定
Client ID

OIDCリクエストおよび Keycloakデータベースでクライアントを識別するために使用される英数字のID文字列です。この値は認証リクエストで送信されるissuerの値と一致しなければなりません。Keycloakは認証SAMLリクエストから発行者を取り出し、この値でクライアントとマッチングさせます。

Name

KeycloakのUI画面におけるクライアントの名前です。名前をローカライズするには、置換文字列値を設定します。たとえば、${myapp}のような文字列値です。詳しくは、 Server Developer Guide を参照してください。

説明

クライアントの説明文です。この設定はローカライズすることも可能です。

Always Display in Console

このユーザーがアクティブなセッションを持っていない場合でも、常にこのクライアントをアカウント・コンソールにリストアップします。

アクセス設定
Root URL

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

Home URL

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

Valid Redirect URIs

URLパターンを入力し、+記号をクリックすると追加されます。削除する場合は、-記号をクリックします。 Save をクリックして、これらの変更を保存します。ワイルドカードの値は、URLの末尾にのみ使用できます。たとえば、http://host.com/*$$のようになります。このフィールドは、正確なSAMLエンドポイントが登録されておらず、KeycloakのリクエストからAssertion Consumer URLを導き出す場合に使用されます。

IDP-Initiated SSO URL name

IDP Initiated SSOを行う際に、クライアントを参照するためのURLフラグメント名。空欄にすると、IDP Initiated SSOを無効にします。ブラウザーから参照するURLは、次のようになります。 server-root/realms/{realm}/protocol/saml/clients/{client-url-name}

IDP Initiated SSO Relay State

IDP Initiated SSOを行う場合に、SAMLリクエストで送信したいリレーステート。

Master SAML Processing URL

このURLは、すべてのSAMLリクエストに使用され、レスポンスはSPに向けられます。これは、アサーション・コンシューマー・サービスのURLおよびシングル・ログアウト・サービスのURLとして使用されます。

ログインリクエストにアサーション・コンシューマー・サービスのURLが含まれている場合、そのログインリクエストが優先されます。このURLは、登録された有効なリダイレクトURIパターンによって検証される必要があります。

SAMLの機能
Name ID Format

サブジェクトのName ID Format。この形式は、リクエストでName IDポリシーが指定されていない場合、またはName ID形式の強制属性がONに設定されている場合に使用されます。

Force Name ID Format

リクエストにName IDのポリシーがある場合、それを無視して管理コンソールの Name ID Format で設定された値を使用します。

Force POST Binding

デフォルトでは、Keycloakは元のリクエストの最初のSAMLバインディングを使用して応答します。 Force POST Binding を有効にすると、Keycloakは、元のリクエストがREDIRECTバインディングを使用していたとしても、SAML POSTバインディングを使用して応答します。

Force artifact binding

有効な場合、レスポンス・メッセージは、SAML ARTIFACTバインディング・システムを通じてクライアントに返されます。

Include AuthnStatement

SAMLログイン・レスポンスには、使用された認証方式(パスワードなど)、ログインのタイムスタンプおよびセッションの有効期限を指定することができます。 Include AuthnStatement はデフォルトで有効になっており、ログイン・レスポンスに AuthnStatement 要素が含まれるようになります。これをOFFに設定すると、クライアントが最大セッション長を決定できなくなり、期限切れにならないクライアント・セッションが作成される可能性があります。

Include OneTimeUse Condition

有効な場合、ログイン・レスポンスにOneTimeUse条件が含まれます。

Optimize REDIRECT signing key lookup

ONに設定すると、SAMLプロトコル・メッセージにKeycloakネイティブ拡張が含まれます。この拡張には、署名鍵IDを示すヒントが含まれます。SPは、鍵を用いた署名の検証を試みる代わりに、この拡張機能を署名の検証に用います。

このオプションは、署名がクエリー・パラメーターで転送されるREDIRECTバインディングに適用され、この情報は署名情報には含まれません。これは、鍵IDが常にドキュメント署名に含まれるPOSTバインディング・メッセージとは異なります。

このオプションは、KeycloakサーバーとアダプターがIDPとSPを提供する場合に使用されます。このオプションは、Sign Documents がONに設定されている場合にのみ影響します。

署名と暗号化
Sign Documents

ONに設定すると、Keycloakはレルムの秘密鍵を使ってドキュメントに署名します。

Sign Assertions

アサーションは署名され、SAML XML認証レスポンスに埋め込まれます。

Signature Algorithm

SAML文書に署名する際に使用されるアルゴリズム。

SAML Signature Key Name

POST バインディングを使用して送信される署名付き SAML ドキュメントには、KeyName 要素に署名鍵の識別情報が含まれています。この動作は、SAML Signature Key Name オプションで制御することができます。このオプションは、Keyname の内容を制御します。

  • KEY_ID KeyName にはキーIDが含まれます。このオプションはデフォルトのオプションです。

  • CERT_SUBJECT KeyName は、レルムキーに対応する証明書からのサブジェクトを含みます。このオプションは、Microsoft Active Directoryフェデレーション・サービスによって期待されています。

  • NONE SAMLメッセージから KeyName ヒントが完全に省略されます。

Canonicalization Method

XML署名の正準化手法。

ログイン設定
Login theme

ログイン、ワンタイム・パスワード、グラント登録、パスワード忘れなどのページに使用するテーマです。

Consent required

有効な場合、ユーザーはクライアントのアクセスに同意する必要があります。

ブラウザー・ログインを行うクライアントサイドのクライアント用。クライアントサイドのクライアントでは、シークレットの保持を確実に行うことができないため、正しいリダイレクトURIを設定することでアクセスを制限することが重要です。

Display client on screen

このスイッチは、 Consent RequiredOff の場合に適用されます。

  • Off

    同意画面には、設定されたクライアント・スコープに対応する同意のみが表示されます。

  • On

    また、同意画面には、このクライアント自身についての項目が1つあります。

Client consent screen text

Consent requiredDisplay client on screen が有効な場合に適用されます。このクライアントの許可について、同意画面に表示されるテキストが含まれています。

ログアウト設定
Front channel logout

Front Channel Logout が有効な場合、アプリケーションはログアウトを実行するためにブラウザーのリダイレクトを必要とします。たとえば、アプリケーションはリダイレクトによってのみ実行可能なCookieのリセットを要求するかもしれません。 Front Channel Logout が無効な場合、Keycloakはアプリケーションからログアウトするために、バックグラウンドでSAMLリクエストを呼び出します。

Keysタブ

Encrypt Assertions

SAML文書のアサーションをレルム秘密鍵で暗号化します。AES アルゴリズムは、128ビットのキーサイズを使用します。

Client Signature Required

Client Signature Required が有効な場合、クライアントからのドキュメントは署名されていることが期待されます。Keycloakは、 タブで設定されたクライアントの公開鍵または証明書を使用して、この署名を検証します。

Allow ECP Flow

trueの場合、このアプリケーションは、認証にSAML ECPプロファイルを使用することが許可されます。

Advancedタブ

このタブには、特定の状況に応じた多くのフィールドがあります。 いくつかのフィールドは、他のトピックでカバーされています。他のフィールドの詳細については、クエスチョン・マーク・アイコンをクリックしてください。

ファイングレインSAMLエンドポイントの設定
Logo URL

クライアント・アプリケーション用のロゴを参照するURL。

Policy URL

プロファイル・データがどのように使用されるかについて読むために、Relying Partyがエンドユーザーに提供するURL。

Terms of Service URL

Relying Partyが、エンドユーザーにRelying Partyの利用規約を提供するURL。

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。

Logout Service Artifact Binding URL

ログアウト・サービスの Artifact Binding URLです。 Force Artifact Binding オプションと一緒に設定すると、ログインとログアウトの両方のフローで Artifact バインディングが強制されます。このプロパティーが設定されない限り、ログアウトに Artifact バインディングは使用されません。

Artifact Binding URL

HTTPアーティファクト・メッセージの送信先のURL。

Artifact Resolution Service

ArtifactResolve メッセージの送信先となるクライアントSOAPエンドポイントのURL。

IDP Initiated Login

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

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

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

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

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

クライアントが特別なリレーステートを必要とする場合、 Settings タブの IDP Initiated SSO Relay State フィールドでこれを設定することもできます。また、ブラウザーは RelayState クエリー・パラメーターでリレーステートを指定することもできます(例: root/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 Loginの初期ポイントとして公開される名前が設定されます。

  • Fine Grain SAML Endpoint Configuration のセクションの Assertion Consumer Service POST Binding URL は、次のURLに設定する必要があります。 broker-root/realms/{broker-realm}/broker/{idp-name}/endpoint/clients/{client-id}

    • 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 2.0クライアントを手動で登録する代わりに、標準のSAMLエンティティー記述子XMLファイルを使用してクライアントをインポートすることができます。

Clientページには、 Import client オプションがあります。

Add client

Import SAML client

手順
  1. Browse をクリックします。

  2. XMLエンティティー記述子の情報を含むファイルを読み込みます。

  3. すべての設定が正しく行われているか、情報を確認してください。

mod-auth-melon などの一部のSAMLクライアント・アダプターは、IDPのXMLエンティティー記述子を必要とします。この記述子は、このURLにアクセスして見つけることができます。

root/realms/{realm}/protocol/saml/descriptor

ここで、 realm はクライアントのレルムです。

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

クライアントがこのエンドポイントに HTTP GET リクエストでアクセスすると、Keycloakは、指定されたクライアントとレルムに対して設定されたベースURLを、レスポンスの Location ヘッダーに HTTP 307 (Temporary Redirect)の形式で返します。これにより、クライアントはレルム名とクライアントIDを知っているだけで、それらにリンクすることができます。このインダイレクトにより、クライアントのベースURLをハードコーディングする必要がなくなります。

レルム master とクライアントID account が指定されている例を、以下に示します。

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

このURLは一時的にhttp://host:port/realms/master/account にリダイレクトされます。

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

IDトークン、アクセストークン、またはSAMLアサーションを受け取るアプリケーションは、異なるロールとユーザー・メタデータを必要とする場合があります。

Keycloakを使用して次のこともできます。

  • ロール、クレーム、カスタム属性をハードコードする。

  • ユーザーのメタデータをトークンやアサーションに含める。

  • ロールの名前を変更する。

これらのアクションは、管理コンソールの Mappers タブで実行します。

Mappersタブ

mappers oidc

新規クライアントはビルトイン・マッパーを持ちませんが、クライアント・スコープからいくつかのマッパーを継承することができます。詳しくはクライアント・スコープのセクションを参照してください。

プロトコル・マッパーは、アイテム(たとえば電子メールアドレスなど)をIDトークンおよびアクセストークンの特定のクレームにマッピングします。マッパーの機能は、その名前分かるはずです。事前に設定されたマッパーを追加するには、 Add Builtin をクリックします。

各マッパーには、共通の設定項目があります。マッパータイプによって、その他の設定も可能です。マッパーの横にある Edit をクリックすると、設定画面にアクセスし、これらの設定を調整することができます。

マッパーの設定

mapper config

各オプションの詳細は、ツールチップにカーソルを合わせると表示されます。

ほとんどのOIDCマッパーで、クレームがどこに置かれるかを制御することができます。 Add to ID tokenAdd to access token のスイッチを調整することで、 ID_トークンと _アクセス トークンからクレームを含むかどうかを選択します。

マッパータイプは以下のように追加できます。

手順
  1. Mappers タブに移動します。

  2. Configure a new mapper をクリックします。

    マッパーを追加します。

    add mapper

  3. リストボックスから Mapper Type を選択します。

優先順位

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

マッパーはマッパーの一覧の順番でソートされます。トークンまたはアサーションの変更は、最も低いものが最初に適用されるように、その順序で適用されます。したがって、他の実装に依存している実装は、必要な順序で処理されます。

たとえば、あるトークンに含まれるロールを計算する場合は、次のようになります。

  1. そのロールに基づき、Audienceを解決する。

  2. トークンで既に利用可能なロールとAudienceを使用するJavaScriptのスクリプトを処理します。

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

ユーザー・セッションの詳細は、マッパーを使用して定義され、クライアントで機能を使用または有効にすると、自動的に含まれます。セッションの詳細を含めるには、 Add builtin をクリックします。

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

  • IMPERSONATOR_ID :代理ユーザーのID。

  • IMPERSONATOR_USERNAME :なりすましユーザーのユーザー名。

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

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

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

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

スクリプトマッパー

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

スクリプトがデプロイされると、利用可能なマッパーの一覧からデプロイされたスクリプトを選択できるようになるはずです。

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

Keycloakは、アプリケーションのデプロイメント環境にクライアント・アダプターをインストールするために使用する設定ファイルを生成できます。OIDCおよびSAMLでは、さまざまなアダプタータイプがサポートされています。

  1. Action メニューをクリックし、 Download adapter config オプションを選択します。

    client installation

  2. 設定を生成したい Format Option を選択します。

OIDCおよびSAML用のすべてのKeycloakクライアント・アダプターがサポートされています。SAML用のApache HTTPDアダプターmod-auth-mellonは、標準のSAMLエンティティー記述子ファイルと同様にサポートされています。

クライアント・スコープ

Keycloakを使って、 client scope と呼ばれるエンティティーに共有のクライアント設定を定義します。クライアントスコープ_は、複数のクライアントに対してプロトコル・マッパーロール・スコープ・マッピングを設定します。

クライアント・スコープは、OAuth 2の scope パラメーターもサポートしています。クライアント・アプリケーションは、このパラメーターを使用して、アプリケーションの要件に応じてアクセストークン内のクレームやロールを要求します。

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

  1. メニューの Client Scopes をクリックします。

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

    client scopes list

  2. Create をクリックします。

  3. クライアント・スコープを指定します。

  4. Save をクリックします。

クライアントスコープ_は、通常のクライアントと同様のタブを持ちます。 プロトコル・マッパー と <_role_scope_mappings, ロール・スコープ・マッピング>> を定義することができます。これらのマッピングは他のクライアントに継承させることができ、このクライアント・スコープから継承するように設定されます。

プロトコル

クライアント・スコープを作成する際に、 Protocol を選択します。同じスコープでリンクされたクライアントは、同じプロトコルを持つ必要があります。

各レルムは、メニューにあらかじめ定義されたビルトインのクライアント・スコープのセットを持っています。

  • SAMLプロトコル: role_list 。このスコープには、SAMLアサーションに含まれるロールリストのプロトコル・マッパーが 1 つ含まれます。

  • OpenID Connectプロトコル:いくつかのクライアント・スコープが利用可能です。

    • roles

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

    • web-origins

      このスコープもOpenID Connectの仕様では定義されておらず、アクセストークンの scope に追加されることはありません。このスコープは、アクセストークンの allowed-origins 要求に許可されたウェブオリジンを追加するために使用されます。

    • microprofile-jwt

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

    • offline_access

      このスコープは、クライアントがオフライン・トークンを取得する必要がある場合に使用されます。オフライントークンの詳細はOffline Accessのセクションおよび OpenID Connectの仕様 に記載されています。

    • profile

    • email

    • address

    • phone

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

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

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

client scopes phone

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

内蔵のクライアント・スコープには、仕様で定義されているプロトコル・マッパーが含まれています。クライアントスコープを編集し、プロトコル・マッパーやロール・スコープ・マッピングを自由に作成、更新、削除することができます。

クライアント・スコープには、同意画面に関連するオプションが含まれています。これらのオプションは、リンク先のクライアントで Consent Required が有効になっている場合に有効です。

同意画面での表示

Display On Consent Screen が有効で、スコープが同意を必要とするクライアントに追加されると、 Consent Screen Text で指定されたテキストが同意画面上に表示されます。このテキストは、ユーザーが認証されたとき、およびユーザーがKeycloakからクライアントにリダイレクトされる前に表示されます。 Display On Consent Screen が無効の場合、このクライアント・スコープは同意画面に表示されません。

同意画面テキスト

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

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

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

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

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

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

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

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

scope=openid phone

scopeパラメーターには、scope値をスペースで区切った文字列を指定します。 openid は、すべてのOpenID Connectリクエストで使用されるメタ値です。トークンには、デフォルトのクライアント・スコープである profile および email と、scopeパラメーターで要求されたオプションのクライアント・スコープである phone のマッパーおよびロールス・コープ・マッピングが含まれることになります。

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

マッパー*タブにはプロトコルマッパーが、*スコープ*タブにはこのクライアント用に宣言されたロールスコープマッピングが含まれます。クライアントのスコープから継承されたマッパーとスコープマッピングは含まれません。クライアントのトークンを生成するときに使用される有効なプロトコルマッパー(クライアント自身で定義されたプロトコルマッパーおよびリンクされたクライアントスコープから継承されたプロトコルマッパー)および有効なロールスコープマッピングを確認することは可能です。

手順
  1. クライアントの Client Scopes タブをクリックします。

  2. Evaluate サブタブを開きます。

  3. 適用したいオプションのクライアントスコープを選択します。

これは、 scope パラメーターの値も表示されます。このパラメーターは、アプリケーションからKeycloak OpenID Connect認可エンドポイントに送信される必要があります。

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

client scopes evaluate

アプリケーションから scope パラメーターにカスタム値を送るには、 サーブレット・アダプターについては パラメーター転送のセクションを、JavaScript アダプターについては JavaScriptアダプターのセクション を参照してください。

すべてのサンプルは、特定のユーザーに対して生成され、特定のクライアントに対して、 scope パラメーターの指定値で発行されます。例には、使用されたすべてのクレームとロールマッピングが含まれます。

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

ユーザーにトークンを発行する場合、クライアント・スコープが適用されるのは、そのユーザーが使用を許可されている場合のみです。

クライアント・スコープにロール・スコープ・マッピングが定義されていない場合、各ユーザーはこのクライアント・スコープを使用することができます。しかし、クライアント・スコープにロール・スコープ・マッピングが定義されている場合、ユーザーは少なくとも一つのロールのメンバーである必要があります。ユーザーのロールとクライアント・スコープのロールの間に共通点がなければなりません。複合ロールはこの共通点を評価する際に考慮されます。

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

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

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

手順
  1. クライアントの Client Scopes タブをクリックします。

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

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

client scopes default

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

スコープの説明

クライアント・スコープ

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

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

これは、クライアントまたはクライアント・スコープの Scope タブで使用できます。アクセストークンで使用できるロールを制限するには、 ロール・スコープ・マッピング を使用します。詳細については、ロール・スコープ・マッピングのセクションを参照してください。

認可スコープ

Authorization Scope は、アプリケーションで実行可能なアクションをカバーします。詳細については、 Authorization Services Guide を参照してください。

クライアント・ポリシー

クライアント・アプリケーションのセキュリティー保護を容易にするために、以下の点を統一的に実現することが有益です。

  • クライアントが持つことができる構成に関するポリシーの設定

  • クライアント設定の検証

  • Financial-grade API(FAPI)などの必要なセキュリティー標準およびプロファイルへの準拠

これらの点を統一的に実現するために、 クライアント・ポリシー の概念が導入されています。

ユースケース

クライアント・ポリシーは、以下を実現します。

クライアントが持つことができる構成に関するポリシーの設定

クライアントの構成設定は、クライアントの作成/更新中だけでなく、特定のクライアントに関連するKeycloakサーバーへのOpenID Connectリクエスト中にもクライアント・ポリシーによって適用できます。Keycloakは、 Securing Applications and Services Guide で説明されているクライアント登録ポリシーを通じても同様のことをサポートしています。ただし、クライアント登録ポリシーは、OIDC動的クライアント登録のみを対象としています。クライアント・ポリシーは、クライアント登録ポリシーで実行できることだけでなく、他のクライアント登録および設定方法も対象としています。現在の計画では、クライアント登録はクライアント・ポリシーに置き換えられます。

クライアント設定の検証

Keycloakは、認可エンドポイント、トークン・エンドポイントなどのいくつかのエンドポイントで、Proof Key for Code Exchange、リクエストオブジェクトの署名アルゴリズム、Holder-of-Key Tokenなどの設定にクライアントが従っているかどうかの検証をサポートします。これらは、各設定項目(管理コンソール上、スイッチ、プルダウンメニューなど)で指定できます。クライアント・アプリケーションをセキュアにするためには、管理者が多くの設定を適切に行う必要があり、それは困難です。クライアント・ポリシーは、ちょうど上で述べたクライアント設定のこれらの検証を行うことができ、また、高度なセキュリティー要件を満たすために、いくつかのクライアント設定スイッチを自動設定するために使用することができます。将来的には、個々のクライアント設定に代わって、クライアント・ポリシーが必要な検証を直接行うようになるかもしれません。

FAPIなどの必要なセキュリティー標準やプロファイルへの準拠

Global client profiles は、Keycloakにデフォルトで設定されているクライアント・プロファイルです。FAPI のような標準的なセキュリティー・プロファイルに準拠するようにあらかじめ設定されているので、管理者は簡単にクライアント・アプリケーションを特定のセキュリティー・プロファイルに準拠するように保護することができます。現時点では、Keycloakは FAPI 1 仕様をサポートするためのグローバル・プロファイルを持っています。管理者は、どのクライアントがFAPIに準拠すべきかを指定するために、クライアント・ポリシーを設定する必要があるだけです。管理者はクライアント・プロファイルとクライアント・ポリシーを設定することで、KeycloakのクライアントをSPA、ネイティブアプリ、オープン・バンキングなど、他のさまざまなセキュリティー・プロファイルに簡単に準拠させることができます。

プロトコル

クライアント・ポリシーのコンセプトは、特定のプロトコルに依存しません。しかし、Keycloakは現在、OpenID Connect(OIDC)プロトコルに対してのみ、これをサポートしています。

アーキテクチャー

クライアント・ポリシーは、4つのビルディング・ブロックから構成されています。Condition、Executor、Profile、Policyです。

Condition

Conditionとは、あるポリシーがどのクライアントにいつ採用されるかを決めるものです。あるConditionは、クライアントの作成・更新時にチェックされ、他の条件は、クライアントのリクエスト(OIDC認可リクエスト、トークン・エンドポイント・リクエストなど)時にチェックされます。Conditionは、指定された1つの条件を満たすかどうかをチェックします。たとえば、クライアントのアクセスタイプがconfidentialであるかどうかをチェックするConditionがあります。

このConditionは単独で使用することはできません。後述のpolicyの中で使用することができます。

Conditionは、他の設定可能なプロバイダーと同様に設定することができます。設定可能な内容は、各Conditionの性質によって異なります。

以下のConditionがあります。

クライアントの作成・更新方法
  • 動的クライアント登録(Anonymousまたは初期アクセストークンや登録アクセストークンによる認証)

  • 管理REST API(管理コンソールなど)

そのため、たとえばクライアントを作成する際に、そのクライアントが初期アクセストークンなしのOIDC動的クライアント登録(Anonymousの動的クライアント登録)によって作成された場合、Conditionを真と評価するように設定することが可能です。このConditionを利用することで、たとえば、OIDC動的クライアント登録で登録されたクライアントがすべてFAPIに準拠していることを確認することができます。

クライアントの作成者(特定のロールまたはグループへのプレゼンスでチェックされます)

OpenID Connectの動的クライアント登録において、クライアントの作成者とは、新しいクライアントを生成するためのアクセストークンを取得するために認証されたエンドユーザであり、アクセストークンを使用して登録エンドポイントに実際にアクセスした既存クライアントのサービス・アカウントではありません。管理REST APIによる登録の場合、クライアントのオーサーはKeycloakの管理者のようなエンドユーザーです。

クライアント・アクセス・タイプ(confidential、public、bearer-only)

たとえば、クライアントが認可リクエストを送信したとき、このクライアントがconfidentialであれば、ポリシーが採用されます。

クライアント・スコープ

クライアントが特定のクライアント・スコープ(デフォルトあるいは現在のリクエストで使用されるオプションのスコープ)を持っている場合にtrueと評価されます。これはたとえば、 fapi-example-scope というスコープを持つOIDC認可リクエストが、FAPIに準拠している必要があることを保証するために使うことができます。

クライアントロール

指定された名前のクライアントロールを持つクライアントに適用されます

クライアントのドメイン名、ホストまたはIPアドレス

クライアントの特定のドメイン名に対して適用されます。または、管理者が特定のホストまたはIPアドレスからクライアントを登録・更新する場合に適用されます。

任意のクライアント

このConditionは常にtrueと評価されます。これは、たとえば特定のレルム内のすべてのクライアントがFAPIに準拠していることを確認するために使用します。

Executor

Executorは、ポリシーが採用されたクライアントで実行されるアクションを指定します。Executorは、指定された1つまたは複数のアクションを実します。たとえば、あるExecutorは認可リクエストのパラメータ redirect_uri の値が認可エンドポイントに予め登録されているリダイレクトURIのいずれかと正確に一致するかどうかを調べ、一致しない場合はこのリクエストを拒否します。

Executorは単体では使用できません。後述するprofileの中で使用することができます。

Executorは、他の設定可能なプロバイダーと同様に設定することができます。何が設定できるかは、各Executorの性質に依存します。

Executorは、さまざまなイベントに対して動作します。Executorの実装は、ある種のイベントを無視することができます(たとえば、OIDC request オブジェクトをチェックするExecutorは、OIDC認可リクエストに対してのみ動作します)。以下のイベントがあります。

  • クライアントの作成(動的クライアント登録による作成も含みます)

  • クライアントの更新

  • 認可リクエストの送信

  • トークン・リクエストの送信

  • トークン・リフレッシュ・リクエストの送信

  • トークン無効化リクエストの送信

  • トークン・イントロスペクション・リクエストの送信

  • UserInfoリクエストの送信

  • リフレッシュ・トークン付きのログアウト・リクエストの送信

各イベントにおいて、Executorは複数のフェーズで動作します。たとえば、クライアントを作成・更新する場合、Executorは特定のクライアント設定を自動構成することによって、クライアント設定を変更することができます。その後、Executorは検証フェーズでこの設定を検証します。

このExecutorのいくつかの目的の一つは、FAPIのようなクライアントのコンフォーマンス・プロファイルのセキュリティー要件を実現することです。そのためには、以下のExecutorが必要です。

  • セキュアなクライアント認証メソッドをクライアントに使用することを強制

  • Holder-of-keyとIークンの使用を強制

  • Proof Key for Code Exchange(PKCE)の使用を強制

  • Signed JWTクライアント認証(private-key-jwt)にセキュアな署名アルゴリズムを使用することを強制

  • HTTPSリダイレクトURIを強制し、設定したリダイレクトURIにワイルドカードが含まれないように強制

  • 高いセキュリティー・レベルを満たすOIDC request オブジェクトを強制

  • FAPI 1 仕様にあるように、認可レスポンスで返されるIDトークンにユーザー・プロフィールのデータが含まれず、 detached signature として使用するOIDCハイブリッド・フローのレスポンスタイプを強制

  • CSRFを防止するため、より安全な statenonce パラメーターの処理を強制

  • クライアント登録時に、よりセキュアな署名アルゴリズムを強制

  • CIBAリクエストに binding_message パラメーターを使用するように強制

  • クライアント・シークレット・ローテーションの強制

  • UKオープン・バンキングのように、アクセストークンを取得するための認可コードフローを開始する前に、インテントが発行されたユースケースで、クライアントがインテント発行先であるかどうかをチェックすることを強制します。

Profile

Profileは複数のExecutorで構成され、FAPIのようなセキュリティー・プロファイルを実現することができます。Profileは、管理REST API(管理コンソール)を用いて、Executorとともに設定することができます。3つの global profiles が存在し、これらはデフォルトでKeycloakに設定され、FAPI Baseline、FAPI Advanced、FAPI CIBAの仕様に準拠したExecutorが事前に設定されています。詳細は Securing Applications and Services Guide のFAPIセクションに記載されています。

Policy

Policyは、いくつかのConditionとProfileから構成されます。Policyは、このPolicyのすべてのConditionを満たすクライアントに採用されます。PolicyはいくつかのProfileを参照し,そのProfileのExecutgorはすべて,このPolicyが採用されたクライアントに対してタスクを実行します。

設定

Policy、Profile、Condition、Executorは、管理REST API、つまり管理コンソールでも設定することができます。これを行うには、 RealmRealm SettingsClient Policies というタブがあり、管理者はレルムごとにクライアント・ポリシーを持つことができます。

Global Client Profiles は各レルムで自動的に利用できます。しかし、デフォルトでは、クライアント・ポリシーは設定されていません。これは、たとえば自分のレルムのクライアントをFAPIに準拠させたい場合、管理者が常にクライアント・ポリシーを作成する必要があることを意味します。グローバル・プロファイルは更新できませんが、グローバル・プロファイルの設定を少し変更したい場合、管理者は簡単にテンプレートとして使用し、独自のプロファイルを作成することができます。管理者コンソールにはJSONエディターがあり、グローバル・プロファイルに基づいた新しいプロファイルを簡単に作成することができます。

後方互換性

クライアント・ポリシーは、Securing Applications and Services Guideで説明したクライアント登録ポリシーに置き換えることができます。しかし、クライアント登録ポリシーもまだ共存しています。つまり、たとえばクライアントを作成・更新するための動的クライアント登録要求の際に、クライアント・ポリシーとクライアント登録ポリシーの両方が適用されます。

現在の計画では、クライアント登録ポリシー機能は削除され、既存のクライアント登録ポリシーは自動的に新しいクライアント・ポリシーに移行される予定です。

クライアント・シークレットのローテーションの例

クライアント・シークレット・ローテーションの設定例を参照してください。

ボールトを使用してシークレットを取得する

シークレットを直接入力するのではなく、ボールトからシークレットを取得するには、以下のような特別な細工をした文字列を該当するフィールドに入力します。

**${vault.**_key_**}**

ここで、key はボールトが認識するシークレットの名前です。

レルム間でシークレットが漏れるのを防ぐために、 Keycloakはレルム名とボールトの式から得られる key を組み合わせます。この方法では、 key はデータボールトのエントリーに直接マッピングされませんが、 key とレルム名を組み合わせたアルゴリズムに従って、最終的なエントリー名を作成することになります。

以下のフィールドで、ボールトのシークレットを取得することができます。

SMTPパスワード

レルムのSMTP設定

LDAPバインド・クレデンシャル

LDAPベースのユーザー・フェデレーションのLDAP設定内。

OIDCアイデンティティー・プロバイダー・シークレット

アイデンティティー・プロバイダーOpenID Connect設定内の Client Secret 内。

キーリゾルバー

すべての組み込みプロバイダーはキーリゾルバーの設定をサポートしています。キーリゾルバーは、レルム名と ${vault.key} 式から得られるキーを組み合わせて、データ保管庫から秘密を取得するための最終的なエントリ名にするアルゴリズムや戦略を実装しています。Keycloakは keyResolvers プロパティを使用して、プロバイダーが使用するリゾルバを設定します。この値は、カンマで区切られたリゾルバ名のリストです。 files-plaintext プロバイダーの設定の例を以下に示します。

kc.[sh.bat] start --spi-vault-file-key-resolvers=REALM_UNDERSCORE_KEY,KEY_ONLY

リゾルバは、構成で宣言したのと同じ順序で実行される。各リゾルバに対して、Keycloak はリゾルバが最後に生成したエントリ名を使用し、レルムとデータ保管庫の鍵を組み合わせてデータ保管庫の秘密を検索する。project_name} が秘密を見つけた場合、その秘密を返す。見つからない場合、Keycloak は次のリゾルバを使用する。この探索は Keycloak が空でない秘密を見つけるか、リゾルバを使い果たすまで続けられる。project_name} が秘密を見つけない場合、Keycloak は空の秘密を返す。

先ほどの例では、Keycloak が最初に REALM_UNDERSCORE_KEY リゾルバを使用します。もし Keycloak がそのリゾルバを使ったエントリを金庫の中に見つけたら、 Keycloak はそのエントリを返します。見つからない場合、Keycloak は KEY_ONLY リゾルバを使って再度検索を行います。project_name} が KEY_ONLY リゾルバを使ってエントリーを見つけた場合、 Keycloak はそのエントリーを返します。project_name} が全てのリゾルバを使用した場合、Keycloak は空の秘密を返す。

現在利用可能なリゾルバーのリストは次のとおりです。

名前 説明

KEY_ONLY

Keycloakはrealm名を無視し、vault式のキーを使用します。

REALM_UNDERSCORE_KEY

Keycloak は、レルムとキーをアンダースコア文字で結合したものです。Keycloak は、realm や key に含まれるアンダースコアを別のアンダースコア文字でエスケープします。たとえば、realmが master_realm で key が smtp_key であれば、結合された key は master__realm_smtp__key となります。

REALM_FILESEPARATOR_KEY

Keycloak は、プラットフォームファイルのセパレータ文字を使用して、レルムとキーを結合します。

FACTORY_PROVIDED

Keycloak は、Vaultプロバイダのファクトリーの VaultKeyResolver を使ってレルムとキーを結合します。既存のファクトリーを拡張して getFactoryResolver メソッドを実装すれば、カスタムキーリゾルバーを作成することも可能です。

ビルトインプロバイダのリゾルバを設定していない場合、Keycloak は REALM_UNDERSCORE_KEY を選択します。

イベントを追跡するための監査の設定

Keycloakには、一連の監査機能が含まれています。ログインや管理者の操作をすべて記録し、管理コンソールでその操作を確認することができます。Keycloakには、イベントをリッスンしてアクションを起こすことができるリスナーSPIも含まれています。組み込みのリスナーの例としては、ログファイルやイベント発生時のメール送信などがあります。

ユーザーイベントの監査

ユーザーに影響を与えるすべてのイベントを記録し、表示することができます。Keycloakは、ユーザーのログイン成功、ユーザーの不正なパスワード入力、ユーザー・アカウントの更新などのアクションに対してログインイベントをトリガーします。デフォルトでは、Keycloakは管理コンソールにイベントを保存または表示しません。エラーイベントのみが管理コンソールとサーバーのログファイルに記録されます。

手順

この手順を使用して、ユーザーイベントの監査を開始します。

  1. メニューの Realm settings をクリックします。

  2. Events タブをクリックします。

  3. User events settings タブをクリックします。

  4. Save eventsON に切り替えます。

    ユーザーイベント設定

    User events settings

  5. Expiration フィールドに、イベントを保存する期間を指定します。

  6. Add saved types をクリックすると、保存できる他のイベントが表示されます。

    タイプを追加します

    Add types

  7. Add をクリックします。

保存したイベントをすべて削除したい場合は、 Clear user events をクリックします。

手順

イベントを表示できるようになりました。

  1. メニューの Events タブをクリックします。

    ユーザーイベント

    Login Events

  2. イベントを絞り込むには、 Search user event をクリックします。

    ユーザーイベントを検索します

    Search user event

イベントの種類

ログインイベント:

イベント 説明

Login

ユーザーがログインした。

Register

ユーザーが登録された。

ログアウト

ユーザーがログアウトした。

Code to Token

アプリケーション(クライアント)がコードとトークンを交換した。

Refresh Token

アプリケーション、またはクライアントがトークンをリフレッシュした。

アカウントイベント:

イベント 説明

Social Link

ユーザー・アカウントが、ソーシャル・メディア・プロバイダーとリンクされた。

Remove Social Link

ソーシャル・メディア・アカウントからユーザー・アカウントへのリンクが切れた。

Update Email

アカウントのメールアドレスが変更された。

Update Profile

アカウントのプロファイルが変更された。

Send Password Reset

Keycloakがパスワード・リセット・メールを送信した。

Update Password

アカウントのパスワードが変更された。

Update TOTP

アカウントのTOTP(Time-based One-time Password)の設定が変更された。

Remove TOTP

KeycloakがアカウントからTOTPを削除した。

Send Verify Email

Keycloakが確認メールを送信した。

Verify Email

Keycloakがアカウントのメールアドレスを確認した。

各イベントには、対応するエラーイベントがあります。

イベントリスナー

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

ロギング・イベント・リスナー

Logging Event Listenerが有効な場合、このリスナーはエラーイベントが発生したときにログファイルに書き込みます。

ロギング・イベント・リスナーからのログメッセージの例です。

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

ロギング・イベント・リスナーを使用すると、ハッカーボット攻撃から保護することができます。

  1. LOGIN_ERROR イベントのログファイルを解析します。

  2. ログインに失敗したイベントのIPアドレスを抽出します。

  3. 侵入防止ソフトウェア・フレームワーク・ツールにIPアドレスを送信します。

ロギング・イベント・リスナーはイベントを org.keycloak.events ログカテゴリーに記録します。Keycloakは、デフォルトでは、デバッグ・ログ・イベントをサーバーログに含めません。

サーバーログにデバッグログイベントを含めるには、以下のようにします。

  1. org.keycloak.events カテゴリーのログレベルを変更します。

  2. ロギング・イベント・リスナーが使用するログレベルを変更します。

ロギング・イベントリスナーが使用するログレベルを変更するには、以下を追加します。

bin/kc.[sh|bat] start --spi-events-listener-jboss-logging-success-level=info --spi-events-listener-jboss-logging-error-level=error

ログレベルに有効な値は debuginfowarnerror、および fatal です。

電子メール・イベント・リスナー

電子メール・イベント・リスナーは、イベントが発生するとユーザーのアカウントにメールを送信し、以下のイベントをサポートします。

  • ログインエラー。

  • パスワードの更新。

  • タイムベースワンタイムパスワード(TOTP)の更新。

  • 時間ベースのワンタイムパスワード(TOTP)の削除。

手順

電子メール・イベント・リスナーを有効にするには、次のようにします。

  1. メニューの Realm settings をクリックします。

  2. Events タブをクリックします。

  3. Event listeners フィールドをクリックします。

  4. email を選択します。

    イベントリスナー

    Event listeners

イベントを除外するには --spi-events-listener-email-exclude-events 引数を使用します。以下に例を示します。

kc.[sh|bat] --spi-events-listener-email-exclude-events=UPDATE_TOTP,REMOVE_TOTP

spi-events-store-jpa-max-detail-length 引数を使用すると、データベース内の各イベント詳細の最大長を設定することができます。この設定は、ある詳細(たとえば、redirect_uri)が長い場合に便利です。例えば、以下のようになります。

kc.[sh|bat] --spi-events-store-jpa-max-detail-length=1000

また、 --spi-events-store-jpa-max-field-length 引数を使用することで、すべてのイベントの詳細の最大長を設定することができます。この設定は、基礎となるストレージの制限を遵守したい場合に便利です。たとえば、以下のようになります。

kc.[sh|bat] --spi-events-store-jpa-max-field-length=2500

管理者イベントの監査

管理者が管理コンソールで実行したすべてのアクションを記録することができます。管理コンソールは、KeycloakのRESTインターフェイスを呼び出して管理アクションを実行します。RESTインターフェイスを呼び出し、KeycloakはこれらのREST呼び出しを監査します。結果のイベントは、管理コンソールで確認できます。

手順

この手順を使用して、管理者のアクションの監査を開始します。

  1. メニューの Realm settings をクリックします。

  2. Events タブをクリックします。

  3. Admin events settings タブをクリックします。

  4. Save eventsON に切り替えます。

    Keycloakは Include representation スイッチを表示します。

  5. Include representationON に切り替えます。

    Include Representation スイッチは、管理REST API を通じて送信されたJSONドキュメントを含み、管理者のアクションを表示できるようにします。

    管理イベントの設定

    Admin events settings

  6. Save をクリックします。

  7. 保存されているアクションのデータベースをクリアするには、 Clear admin events をクリックします。

手順

管理者イベントを閲覧できるようになりました。

  1. メニューの Events をクリックします。

  2. Admin events タブをクリックします。

    管理イベント

    Admin events

Include Representation スイッチをONにすると、データベースに多くの情報を保存することになる場合があります。引数 --spi-events-store-jpa-max-field-length を使用すると、表現の最大長を設定することができます。この設定は、基礎となるストレージの制限を遵守したい場合に有効です。たとえば、以下のようになります。

kc.[sh|bat] --spi-events-store-jpa-max-field-length=2500

セキュリティー上の脅威の軽減

セキュリティーの脆弱性は、どのような認証サーバーにも存在します。詳しくはInternet Engineering Task Force (IETF)の OAuth 2.0 Threat ModelOAuth 2.0 Security Best Current Practice を参照してください。

ホスト

Keycloakは、トークン発行者のフィールドやパスワード・リセット・メールのURL内など、いくつかの方法で公開ホスト名を使用しています。

デフォルトでは、ホスト名はリクエスト・ヘッダーから取得できます。ホスト名が有効であることを確認する検証機能はありません。ロードバランサーやプロキシーを使用していない場合は、 Keycloakで無効なホストヘッダーを防ぐために、許容できるホスト名を設定してください。

ホスト名のサービス・プロバイダー・インターフェイス(SPI)は、リクエスト用にホスト名を設定する方法を提供します。この組み込みのプロバイダーを使用すると、フロントエンドのリクエストには固定のURLを設定しつつ、リクエストURIに基づいてバックエンドのリクエストを許可することができます。組み込みのプロバイダーに必要な機能が備わっていない場合は、カスタマイズしたプロバイダーを開発することができます。

管理エンドポイントと管理コンソール

Keycloakは、管理用のREST APIとウェブコンソールを非管理用のポートと同じポートで公開します。外部からのアクセスが必要ない場合は、管理用エンドポイントを外部に公開しないでください。

ブルートフォースアタック

ブルートフォース攻撃とは、何度もログインを試みてユーザーのパスワードを推測しようとする攻撃のことです。Keycloakにはブルートフォース検知機能があり、ログイン失敗回数が指定した閾値を超えた場合、ユーザー・アカウントを一時的に無効にすることができます。

Keycloakはデフォルトで、ブルートフォース検知を無効にします。この機能を有効にすると、ブルートフォース攻撃から保護されます。

手順

この保護機能を有効にするには以下のようにします。

  1. メニューの Realm Settings をクリックします。

  2. Security Defenses タブをクリックします。

  3. Brute Force Detection タブをクリックします。

    ブルートフォース検出

    brute force

Keycloakは、攻撃を検知すると、永久ロックアウトと一時ロックアウトのアクションを配備できます。永久ロックアウトは、管理者が再び有効にするまでユーザー・アカウントを無効にします。一時的ロックアウトは、一定期間、ユーザー・アカウントを無効にします。攻撃が続くと、アカウントが無効になる期間は長くなります。

ユーザーが一時的にロックされている状態でログインしようとすると、Keycloakはデフォルトの Invalid username or password エラーメッセージを表示します。このメッセージは、無効なユーザー名や無効なパスワードの場合に表示されるメッセージと同じもので、攻撃者がアカウントが無効になっていることに気づかないようになっています。

共通パラメーター

名前 説明 デフォルト

Max Login Failures

ログイン失敗の最大回数。

30回失敗

Quick Login Check Milliseconds

ログインを試みるまでの最小時間。

1000ミリ秒

Minimum Quick Login Wait

ログイン試行が Quick Login Check Milliseconds よりも早かった場合に、ユーザーを無効にする最小の時間です。

1分

永続的ロックアウト・フロー

  1. ログインに成功した場合

    1. count のリセット

  2. ログインに失敗した場合

    1. count のインクリメント

    2. countMax Login Failures より大きい場合 …​

      1. ユーザーを永続的に無効にします

    3. 今回の失敗と前回の失敗の間の時間が Quick Login Check Milliseconds よりも短ければ …​

      1. Minimum Quick Login Wait の間、ユーザーを一時的に無効にします

Keycloakがユーザーを無効にすると、管理者がそのユーザーを有効にするまで、そのユーザーはログインできなくなります。アカウントを有効にすると、 count がリセットされます。

一時ロックアウト・パラメーター

名前 説明 デフォルト

Wait Increment

ユーザーのログイン試行回数が Max Login Failures を超えたときに、ユーザーが一時的に無効になる時間を加算した時間。

1分

Max Wait

ユーザーが一時的に無効になる最大時間。

15分

Failure Reset Time

失敗回数がリセットされる時間です。このタイマーは、最後に失敗したログインから実行されます。

12時間

一時的ロックアウト・アルゴリズム

  1. ログインに成功した場合

    1. count のリセット

  2. ログインに失敗した場合

    1. 今回の故障から前回の故障までの時間が Failure Reset Time よりも長い場合 …​

      1. count のリセット

    2. count のインクリメント

    3. Wait Increment * (count / Max Login Failures) を使って wait を計算します。除算は整数に切り捨てられた整数除算です。

    4. wait が0で、今回の失敗と前回の失敗の間の時間が Quick Login Check Milliseconds 以下の場合、 waitMinimum Quick Login Wait に設定します。

      1. waitMax Wait の秒数が小さい間、ユーザーを一時的に無効にします

一時的に無効化されたアカウントがログインに失敗しても、 count は増加しません。

Keycloakのブルートフォース検出の欠点は、サーバーがサービス拒否攻撃に対して脆弱になることです。サービス拒否攻撃を行う場合、攻撃者は知っているアカウントのパスワードを推測してログインを試み、最終的にKeycloakのアカウントを無効にすることができます。

侵入防止ソフトウェア(IPS)の使用を検討します。Keycloakは、ログインの失敗やクライアントのIPアドレスの失敗をすべて記録します。IPSはKeycloakサーバーのログファイルを指定することができ、IPSはこれらのIPアドレスからの接続をブロックするようにファイアウォールを変更することができます。

パスワードポリシー

複雑なパスワード・ポリシーを設定して、ユーザーに複雑なパスワードを選択させるようにしてください。詳しくはPassword Policiesを参照してください。Keycloakサーバーでワンタイムパスワードを使用するように設定することで、パスワードの推測を防ぐことができます。

読み取り専用のユーザー属性

Keycloakに保存されている一般的なユーザーには、ユーザー・プロファイルに関連するさまざまな属性があります。このような属性には、email、firstName、またはlastnameが含まれます。ただし、ユーザーは、一般的なプロファイル・データではなく、メタデータである属性を持っている場合もあります。メタデータ属性は通常、ユーザーに対して読み取り専用である必要があり、通常のユーザーは、Keycloakユーザー・インターフェイスまたはアカウントREST APIからこれらの属性を更新する方法を持ってはなりません。一部の属性は、管理REST APIを使用してユーザーを作成または更新するときに、管理者に対して読み取り専用にする必要があります。

メタデータ属性は通常、これらのグループの属性です。

  • ユーザー・ストレージ・プロバイダーに関連するさまざまなリンクまたはメタデータ。たとえば、LDAP統合の場合、 LDAP_ID 属性にはLDAPサーバー内のユーザーのIDが含まれます。

  • ユーザー・ストレージによってプロビジョニングされたメタデータ。たとえば、LDAPからプロビジョニングされた createdTimestamp は、ユーザーまたは管理者が常に読み取り専用にする必要があります。

  • さまざまなオーセンティケーターに関連するメタデータ。たとえば、 KERBEROS_PRINCIPAL 属性には、特定のユーザーのKerberosプリンシパル名を含めることができます。同様に、 usercertificate 属性には、X.509証明書からのデータを使用してユーザーをバインドすることに関連するメタデータを含めることができます。これは通常、X.509証明書認証が有効になっている場合に使用されます。

  • アプリケーション/クライアントによるユーザーの識別子に関連するメタデータ。たとえば、 saml.persistent.name.id.for.my_app には、クライアント・アプリケーション my_app がユーザーの識別子として使用するSAMLNameIDを含めることができます。

  • 属性ベースのアクセス・コントロール(ABAC)に使用される認可ポリシーに関連するメタデータ。これらの属性の値は、認可の決定に使用できます。したがって、これらの属性をユーザーが更新できないことが重要です。

長期的な観点から、Keycloakには適切なユーザープロファイルSPIがあり、すべてのユーザー属性をきめ細かく設定できます。現在、この機能はまだ完全には利用できません。したがって、Keycloakには、ユーザー属性の内部リストがあります。これは、ユーザーに対しては読み取り専用であり、サーバーレベルで設定された管理者に対しては読み取り専用です。

これは読み取り専用属性のリストです。これらはKeycloakのデフォルトのプロバイダーと機能によって内部的に使用されるため、常に読み取り専用です。

  • ユーザーの場合: KERBEROS_PRINCIPAL, LDAP_ID, LDAP_ENTRY_DN, CREATED_TIMESTAMP, createTimestamp, modifyTimestamp, userCertificate, saml.persistent.name.id.for.*, ENABLED, EMAIL_VERIFIED

  • 管理者の場合: KERBEROS_PRINCIPAL, LDAP_ID, LDAP_ENTRY_DN, CREATED_TIMESTAMP, createTimestamp, modifyTimestamp

システム管理者は、このリストに追加の属性を追加することができます。現在、この設定はサーバーレベルで利用可能です。

この設定は spi-user-profile-legacy-user-profile-read-only-attributesspi-user-profile-legacy-user-profile-admin-read-only-attributes オプションで追加することができます。以下に例を示します。

kc.[sh|bat] start --spi-user-profile-legacy-user-profile-read-only-attributes=foo,bar*

この例では、ユーザーと管理者は属性 foo を更新できません。ユーザーは、 bar で始まる属性を編集することはできません。たとえば、 barbarrier です。設定では大文字と小文字が区別されないため、この例では FOOBarRier などの属性も拒否されます。ワイルドカード文字 * は属性名の末尾でのみサポートされるため、管理者は指定された文字で始まるすべての属性を効果的に拒否できます。属性の中央にある * は通常の文字と見なされます。

クリック・ジャッキング

クリックジャッキングとは、ユーザーが認識しているものとは異なるユーザーインターフェース要素をクリックさせて、ユーザーを騙す手法です。悪意のあるサイトでは、対象サイトの重要なボタンの直下に配置されたダミーのボタン群の上に、透明なiFrameを重ねてロードします。ユーザーが見えるボタンをクリックすると、隠れたページのボタンをクリックしたことになります。攻撃者は、この方法を使ってユーザーの認証情報を盗み、ユーザーのリソースにアクセスすることができます。

デフォルトでは、Keycloakによるすべてのレスポンスは、この現象を防ぐことができるいくつかの特定のHTTPヘッダーを設定します。具体的には、 X-Frame-OptionsContent-Security-Policy が設定されます。この2つのヘッダーの定義を見ると、ブラウザーのアクセスを細かく制御できる部分がたくさんあるので、参考にしてください。

手順

管理コンソールでは、X-Frame-OptionsヘッダーとContent-Security-Policyヘッダーの値を指定することができます。

  1. メニュー項目の Realm Settings をクリックします。

  2. Security Defenses タブをクリックします。

    セキュリティ・ディフェンス

    Security Defenses

デフォルトでは、KeycloakはIFrameの same-origin ポリシーのみを設定します。

SSL/HTTPS要件

OAuth 2.0/OpenID Connectでは、セキュリティーのためにアクセストークンを使用しています。攻撃者は、ネットワークをスキャンしてアクセストークンを探し、それを使って、トークンが許可している悪意のある操作を実行することができます。この攻撃は、中間者攻撃と呼ばれています。中間者攻撃を防ぐために、Keycloak認証サーバーとクライアント間の通信にSSL / HTTPSを使用してください。

Keycloak には SSL/HTTPSの3つのモード があります。SSLは設定が複雑なので、Keycloakではlocalhostや192.168.x.xなどのプライベートIPアドレスでの非HTTPS通信を許可しています。プロダクション環境では、SSLを有効にし、すべての操作でSSLが必須となっていることを確認してください。

アダプター/クライアントサイドでは、SSLトラスト・マネージャーを無効にすることができます。トラスト・マネージャーは、Keycloakが通信するクライアントのアイデンティティーが有効であることを確認し、サーバーの証明書に対するDNSドメイン名を確認します。プロダクション環境では、DNSの中間者攻撃を防ぐために、各クライアント・アダプターがトラストストアを使用していることを確認してください。

CSRF攻撃

クロスサイト・リクエスト・フォージェリ(CSRF)攻撃は、ウェブサイトが既に認証したユーザーからのHTTPリクエストを利用します。Cookieベースの認証を使用しているサイトは、CSRF攻撃に対して脆弱です。このような攻撃は、投稿されたフォームやクエリー・パラメーターに対してstate Cookieを照合することで軽減できます。

OAuth 2.0のログイン仕様では、state Cookieが送信されたstateパラメーターと一致することが要求されています。Keycloakは、この仕様の一部を完全に実装しているため、すべてのログインが保護されます。

Keycloakの管理コンソールは、バックエンドのKeycloak管理REST APIにREST呼び出しを行うJavaScript/HTML5アプリケーションです。これらの呼び出しはすべてベアラートークン認証を必要とし、JavaScriptのAjax呼び出しで構成されているため、CSRFは不可能です。CORSオリジンを検証するように管理REST APIを設定することができます。

Keycloakのユーザー・アカウント管理セクションは、CSRFに対して脆弱な可能性があります。CSRF 攻撃を防ぐために、Keycloakは、state Cookieを設定し、このCookieの値をアクションリンク内の隠しフォーム・フィールドやクエリー・パラメーターに埋め込みます。Keycloak は、クエリー/フォーム・パラメーターをstate Cookieと照合して、ユーザーが呼び出しを行ったことを確認します。

不特定のリダイレクトURI

登録するリダイレクトURIは、できるだけ具体的なものにしてください。 認可コードフロー に曖昧なリダイレクトURIを登録すると、悪意のあるクライアントがより広いアクセス権を持つ別のクライアントになりすますことができます。なりすましは、たとえば、2人のクライアントが同じドメインに住んでいる場合に起こります。

FAPI準拠

Keycloakサーバーがクライアントをより安全でFAPIに準拠していると検証するようにするには、FAPIサポートのためのクライアント・ポリシーを設定することができます。詳細は、 Securing Applications and Services Guide のFAPIセクションに記載されています。とりわけ、これにより、上述のクライアントのSSL必須、安全なリダイレクトURIの使用などのセキュリティー・ベストプラクティスが保証されます。

セキュリティー侵害されたアクセストークンとリフレッシュトークン

Keycloakには、悪意のある行為者がアクセストークンやリフレッシュトークンを盗むのを防ぐためのいくつかのアクションがあります。最も重要なアクションは、Keycloakとそのクライアントやアプリケーションの間でSSL/HTTPS通信を強制することです。KeycloakはデフォルトではSSLを有効にしていません。

アクセストークンの漏洩による被害を軽減するためのもう一つのアクションは、トークンの寿命を短くすることです。トークンの寿命は、timeouts page内で指定できます。アクセストークンの寿命を短くすると、クライアントやアプリケーションは短時間でアクセストークンを更新しなければならなくなります。管理者が漏洩を検知した場合、管理者はすべてのユーザー・セッションをログアウトしてこれらのリフレッシュトークンを無効にしたり、失効ポリシーを設定したりすることができます。

リフレッシュトークンが常にクライアントに非公開で、決して送信されないようにします。

アクセストークンやリフレッシュトークンは、holder-of-keyトークンとして発行することで、漏洩した場合の被害を軽減することができます。詳しくは、OAuth 2.0 Mutual TLS Client Certificate Bound Access Tokenを参照してください。

アクセストークンまたはリフレッシュトークンが侵害された場合、管理コンソールにアクセスし、not-before無効化ポリシーをすべてのアプリケーションにプッシュします。not-beforeポリシーをプッシュすると、それ以前に発行されたトークンが無効になります。 新しいnot-beforeポリシーをプッシュすると、アプリケーションはKeycloakから新しい公開鍵をダウンロードする必要があり、レルムの署名鍵が漏洩した場合の被害を軽減することができます。詳しくは鍵の章を参照してください。

特定のアプリケーション、クライアント、またはユーザーが侵害された場合、それらを無効にすることができます。

侵害された認可コード

OIDC認可コードフローでは、Keycloakが認可コードに暗号的に強い乱数値を生成しています。認可コードはアクセストークンの取得に一度だけ使用されます。

管理コンソールのタイムアウトのページでは、認可コードの有効期間を指定することができます。時間の長さは、クライアントがコードからトークンを要求するのに十分な長さである、10秒以下であることを確認してください。

また、Proof Key for Code Exchange (PKCE)を適用することで、認可コードの漏洩を防ぐことができます。

オープン・リダイレクター

オープン・リダイレクターとは、パラメーターを使用して、検証を行わずにパラメーター値で指定された場所にユーザー・エージェントを自動的にリダイレクトするエンドポイントのことです。攻撃者は、認可エンドポイントとリダイレクトURIパラメーターを使って、認可サーバーをオープン・リダイレクターとして使用し、認可サーバーに対するユーザーの信頼を利用してフィッシング攻撃を仕掛けることができます。

Keycloakは、登録されたすべてのアプリケーションとクライアントが、少なくとも1つのリダイレクトURIパターンを登録することを要求しています。クライアントがKeycloakにリダイレクトの実行を要求すると、KeycloakはリダイレクトURIを有効な登録URIパターンのリストと照合します。クライアントやアプリケーションは、オープンリダイレクター攻撃を軽減するために、できるだけ特定のURIパターンを登録する必要があります。

パスワード・データベースの侵害

Keycloakは、パスワードを平文のテキストではなく、PBKDF2ハッシングアルゴリズムを用いてハッシュ化したテキストとして保存します。Keycloakは、セキュリティー・コミュニティーで推奨されている回数である27,500回のハッシュ反復を行います。PBKDF2ハッシュ化は大量の CPUリソースを使用するため、このハッシュ化の反復回数はパフォーマンスに悪影響を及ぼします。

スコープの制限

デフォルトでは、新しいクライアント・アプリケーションは無制限の role scope mappings を持ちます。そのクライアントのアクセストークンには、そのユーザーが持つすべてのパーミッションが含まれています。攻撃者がクライアントを侵害し、クライアントのアクセストークンを取得した場合、そのユーザーがアクセスできる各システムが危険にさらされます。

アクセストークンのロールを制限するには、クライアントごとにScopeメニュ-を使用します。また、クライアント・スコープ・レベルでロールスコープのマッピングを設定し、Client Scopeメニュ-を使用してクライアント・スコープを割り当てることもできます。

トークンのAudienceの制限

サービス間の信頼度が低い環境では、トークンのオーディエンスを制限してください。詳しくは、 OAuth2 Threat ModelAudienceサポートを参照して覧ください。

Limit Authentication Sessions

Webブラウザーで初めてログインページを開くと、Keycloakは認証中セッションと呼ばれるオブジェクトを作成し、リクエストに関するいくつかの有用な情報を保存します。同じブラウザーの別のタブから新しいログインページを開くたびに、Keycloakは認証中サブセッションと呼ばれる新しいレコードを作成し、認証中セッション内に保存されます。認証リクエストは、管理CLIなどのあらゆるタイプのクライアントから来る可能性があります。その場合、新しい認証中セッションも1つの認証中サブセッションで作成されます。認証中セッションは、ブラウザーフローを使用する以外の方法でも作成されることに注意してください。以下の文章は、ソースフローに関係なく適用されます。

このセクションでは、認証中セッションにInfinispanプロバイダーを使用するデプロイメントについて説明します。

認証中セッションは、内部的には RootAuthenticationSessionEntity として格納されます。各 RootAuthenticationSessionEntity には、複数の認証中サブセッションを AuthenticationSessionEntity オブジェクトの集合として格納することができます。Keycloakは、認証中セッションを専用のInfinispanキャッシュに保存します。 RootAuthenticationSessionEntity に含まれる AuthenticationSessionEntity の数は、各キャッシュ・エントリーのサイズに影響します。認証中セッション・キャッシュの総メモリー使用量は、保存された RootAuthenticationSessionEntity の数と、各 RootAuthenticationSessionEntity 内の AuthenticationSessionEntity の数によって決定されます。

維持される RootAuthenticationSessionEntity オブジェクトの数は、ブラウザーからの未完了のログインフローの数に対応します。 RootAuthenticationSessionEntity の数を制御するために、高度なファイアウォール制御を使用して、入口のネットワーク・トラフィックを制限することが推奨されます。

多くのアクティブな RootAuthenticationSessionEntity と多くの AuthenticationSessionEntity が存在する環境では、より高いメモリ使用量が発生する可能性があります。ロードバランサーがセッション・スティッキネスをサポートしないか、設定されていない場合、クラスター内のネットワーク上の負荷が大幅に増加する可能性があります。この負荷の理由は、適切な認証中セッションを所有していないノードに到着した各リクエストは、所有ノード内の認証中セッション・レコードを検索して更新する必要があり、検索と保存の両方に個別のネットワーク伝送が含まれるからです。

SPI の authenticationSessionsauthSessionsLimit プロパティーを設定することで、 RootAuthenticationSessionEntity あたりの AuthenticationSessionEntity の最大個数を設定することができます。デフォルトでは、1つの RootAuthenticationSessionEntity に対して300の AuthenticationSessionEntity が設定されています。この制限に達すると、新しい認証中セッションの要求があったときに、最も古い認証中サブセッションが削除されます。

次の例では、 RootAuthenticationSessionEntity ごとにアクティブな AuthenticationSessionEntity の数を100に制限する方法を示しています。

bin/kc.[sh|bat] start --spi-authentication-sessions-infinispan-auth-sessions-limit=100

以下は新しいマップストレージにおいて相当するコマンドです。

bin/kc.[sh|bat] start --spi-authentication-sessions-map-auth-sessions-limit=100

SQLインジェクション攻撃

現在、 Keycloak には、既知の SQL インジェクションの脆弱性はありません。

アカウント・コンソール

Keycloakのユーザーは、アカウント・コンソールで自分のアカウントを設定できます。ユーザーは、プロファイルの管理、2要素認証の追加、アイデンティティー・プロバイダー・アカウントの追加、デバイスのアクティビティーの監視を行うことができます。

追加のリソース
  • アカウント・コンソールは、外観や言語設定の面で設定することができます。例として、 Personal info リンクをクリックし、詳細を入力して保存することで、 Personal info ページに属性を追加することができます。詳しくは、参考:Server Developer Guideを参照してください。

アカウント・コンソールへのアクセス

アカウント・コンソールには、どのユーザーもアクセスできます。

手順
  1. アカウントが存在するKeycloakサーバーのレルム名とIPアドレスを控えておきます。

  2. Webブラウザーで、 server-root/realms/{realm-name}/account のような形式のURLを入力します。

  3. ログイン名とパスワードを入力してください。

アカウント・コンソール

Account Console

サインイン方法の設定

このコンソールには、BASIC認証(ログイン名とパスワード)または2要素認証を使用してサインインすることができます。2要素認証の場合は、以下の手順のいずれかを使用します。

OTPによる2要素認証

前提条件
  • OTPは、あなたのレルムにとって有効な認証メカニズムです。

手順
  1. メニューの Account security をクリックします。

  2. Signing in をクリックします。

  3. Set up authenticator application をクリックします。

    サインイン

    Signing in

  4. 画面に表示される案内に従って、 FreeOTP または Google Authenticator をのどちらかをOTPジェネレーターとしてモバイル端末で使用します。

  5. スクリーンショットにあるQRコードをモバイル端末のOTPジェネレーターに読み込ませてください。

  6. 一度ログアウトして、再度ログインしてください。

  7. プロンプトに応答して、モバイルデバイスで提供されるOTPを入力してください。

WebAuthnによる2要素認証

前提条件
  • WebAuthnは、あなたのレルムで有効な二要素認証メカニズムです。詳しくは、 WebAuthn の項を参照してください。

手順
  1. メニューの Account Security をクリックします。

  2. Signing In をクリックします。

  3. Set up Security Key をクリックします。

    サインイン

    Signing In With Security Key

  4. WebAuthnのセキュリティーキーを準備します。このキーの準備方法は、使用するWebAuthnセキュリティーキーの種類によって異なります。たとえば、USBベースのYubikeyの場合、ラップトップのUSBポートにキーを入れる必要があるかもしれません。

  5. セキュリティーキーを登録する場合は、 Register をクリックしてください。

  6. 一度ログアウトして、再度ログインしてください。

  7. 認証フローが正しく設定されている場合、第2要素としてセキュリティーキーで認証するようメッセージが表示されます。

WebAuthnによるパスワードレス認証

前提条件
手順
  1. メニューの Account Security をクリックします。

  2. Signing In をクリックします。

  3. Passwordless のセクションで、 Set up Security Key をクリックします。

    サインイン

    Signing In With Security Key

  4. WebAuthnのセキュリティーキーを準備します。このキーの準備方法は、使用するWebAuthnセキュリティーキーの種類によって異なります。たとえば、USBベースのYubikeyの場合、ラップトップのUSBポートにキーを入れる必要があるかもしれません。

  5. セキュリティーキーを登録する場合は、 Register をクリックしてください。

  6. 一度ログアウトして、再度ログインしてください。

  7. 認証フローが正しく設定されている場合、第2要素であるセキュリティーキーによる認証を促すメッセージが表示されます。これでログイン時にパスワードを入力する必要はありません。

デバイスのアクティビティーの表示

アカウントにログインしているデバイスを表示することができます。

手順
  1. メニューの Account security をクリックします。

  2. Device activity をクリックします。

  3. 不審な点があれば、デバイスをログアウトする。

デバイス

Devices

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

アカウントに<>を付けてリンクすることができます<_identity_broker, identity broker>。このオプションは、ソーシャルプロバイダーのアカウントをリンクするためによく使用されます。</_identity_broker,>

手順
  1. 管理コンソールにログインします。

  2. メニューの Identity providers をクリックします。

  3. プロバイダーを選択し、各項目を入力します。

  4. アカウントコンソールに戻る。

  5. メニューの Account security をクリックします。

  6. Linked accounts をクリックします。

追加したアイデンティティー・プロバイダーはこのページに表示されます。

リンクされたアカウント

Linked Accounts

他のアプリケーションにアクセスする

Applications メニューは、ユーザーがアクセスできるアプリケーションを表示します。この場合、Account Consoleのみ利用可能です。

Applications

Applications

グループ・メンバーシップの表示

メニューの Groups をクリックすると、自分が所属しているグループを表示することができます。 Direct membership のチェックボックスを選択すると、直接関係しているグループだけが表示されます。

前提条件
  • Groups メニューを表示するには、 view-groups アカウントロールが必要です。

グループ・メンバーシップの表示

View group memberships

管理CLI

Keycloakでは、コマンドライン・ツールの管理CLIを使って、コマンドライン・インターフェイス(CLI)から管理タスクを実行することができます。

管理CLIのインストール

Keycloakは、管理CLI サーバーの配布物と実行スクリプトを 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リクエストを行います。管理RESTエンドポイントへのアクセスには認証が必要です。

特定のエンドポイントのJSON属性の詳細については、管理REST APIのドキュメントを参照してください。

  1. ログインして認証されたセッションを開始します。CRUD(Create、Read、Update、Delete)操作ができるようになります。

    例:

    • Linuxの場合:

      $ kcadm.sh config credentials --server http://localhost:8080 --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 --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. プロダクション環境では、トークンの公開を避けるために、https: を使ってKeycloakにアクセスしてください。Javaのデフォルト証明書トラストストアに含まれる信頼できる認証局がサーバーの証明書を発行していない場合は、 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つのメカニズムがあります。一つは、kcadm config credentials を使って、認証されたセッションを開始するものです。

$ kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin

この機構は、取得したアクセストークンとそれに関連するリフレッシュトークンを保存することで、 kcadm コマンドの呼び出しの間に認証済みセッションを維持します。他にも、プライベートな設定ファイルにシークレットを保持することができます。詳細は 次の章 を参照してください。

2つ目のメカニズムは、各コマンドの呼び出しをその間だけ認証するものです。このメカニズムでは、サーバーの負荷が高まり、トークンを取得するためのラウンドトリップにかかる時間が長くなります。この方法の利点は、起動の間にトークンを保存する必要がないため、ディスクに何も保存されないことです。Keycloakでは、--no-config という引数を指定すると、このモードを使用します。

たとえば、操作を行う際には、認証に必要なすべての情報を指定します。

$ kcadm.sh get realms --no-config --server http://localhost:8080 --realm master --user admin --password admin

管理CLIの使い方の詳細については、 kcadm.sh help コマンドを実行してください。

認証済みセッションの開始に関する詳細は、 kcadm.sh config credentials --help コマンドを実行してください。

代替設定の使用

デフォルトでは、管理CLIは kcadm.config という名前の設定ファイルを管理しています。Keycloak は、このファイルをユーザのホーム・ディレクトリーに置きます。 Linuxベースのシステムでは、フルパス名は $HOME/.keycloak/kcadm.config です。 Windowsでは、フルパス名は %HOMEPATH%\.keycloak\kcadm.config となります。

また、 --config オプションを使って別のファイルや場所を指定すれば、複数の認証済みセッションを並行して維持することができます。

1つの設定ファイルに結びついた操作を1つのスレッドから行います。

設定ファイルは、システム上の他のユーザーからは見えないようにしてください。このファイルには、プライベートでなければならないアクセストークンとシークレットが含まれています。Keycloakは、 ~/.keycloak ディレクトリーとそのコンテンツを適切なアクセス制限で自動的に作成します。ディレクトリーがすでに存在する場合、Keycloakはディレクトリーのパーミッションを更新しません。

設定ファイル内にシークレットを保存しないようにすることも可能ですが、そうすると不便で、かつトークンのリクエスト数も増えてしまいます。すべてのコマンドで --no-config オプションを使用し、 config credentials コマンドが要求する認証情報を kcadm の起動時に指定してください。

基本操作とリソースURI

管理CLIは、特定のタスクを簡略化する追加のコマンドを使用して、管理REST APIエンドポイントに対して一般的にCRUD操作を実行できます。

主な使用パターンをご紹介します。

$ kcadm.sh create ENDPOINT [ARGUMENTS]
$ kcadm.sh get ENDPOINT [ARGUMENTS]
$ kcadm.sh update ENDPOINT [ARGUMENTS]
$ kcadm.sh delete ENDPOINT [ARGUMENTS]

creategetupdatedelete コマンドは、それぞれHTTPの POSTGETPUTDELETE に対応しています。ENDPOINTはターゲットとなるリソースのURIで、絶対指定( http: または https: で始まる)または相対指定が可能で、Keycloakでは以下の形式で絶対指定のURLを構成しています。

SERVER_URI/admin/realms/REALM/ENDPOINT

たとえば、サーバーhttp://localhost:8080に対して認証を行い、レルムが master である場合、 users をENDPOINTとして使用すると、http://localhost:8080/admin/realms/master/usersのリソースURLが作成されます。

ENDPOINTを clients に設定した場合、有効なリソースURIはhttp://localhost:8080/admin/realms/master/clientsです。

Keycloakには、 realms というエンドポイントがあり、これはレルムに対するコンテナーです。これは以下のように解決されます。

SERVER_URI/admin/realms

Keycloak は serverinfo というエンドポイントを持っています。このエンドポイントはレルムとは無関係です。

realm-admin権限を持つユーザーとして認証された場合、複数のレルムに対してコマンドを実行する必要があるかもしれません。その場合は、-r オプションを指定して、どのレルムに対してコマンドを実行するのかをCLIに明示的に伝えます。このコマンドは、 kcadm.sh config credentials--realm オプションで指定された REALM を使用する代わりに、 TARGET_REALM を使用します。

SERVER_URI/admin/realms/TARGET_REALM/ENDPOINT

例:

$ kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin
$ kcadm.sh create users -s username=testuser -s enabled=true -r demorealm

この例では、 master レルムの admin ユーザーとして認証されたセッションを開始します。その後、リソースURL http://localhost:8080/admin/realms/demorealm/users に対してPOSTコールを実行します。

createupdate のコマンドは、JSONのボディーをサーバーに送信します。また、 -f FILENAME を使うと、あらかじめ作成しておいたドキュメントをファイルから読み込むことができます。-f - オプションを使用できるとき、Keycloakは標準入力からメッセージ本文を読み込みます。 create users の例のように,個々の属性とその値を指定することができます。Keycloakは属性をJSONボディーにまとめてサーバーに送信します。

Keycloakでは、 update コマンドを使ってリソースを更新する方法がいくつか用意されています。リソースの現在の状態を判断してファイルに保存し、そのファイルを編集して、サーバーに送信して更新することができます。

例:

$ kcadm.sh get realms/demorealm > demorealm.json
$ vi demorealm.json
$ kcadm.sh update realms/demorealm -f demorealm.json

このメソッドは、サーバー上のリソースを、送信されたJSONドキュメントの属性で更新します。

もう一つの方法は、 -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

Keycloakはデフォルトでレルムを無効にします。レルムを有効にすることで、すぐに認証に使用することができます。

新しいオブジェクトの説明は、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

Keycloakサーバー上のレルムのリストをフィルタリングして、ユーザーが見ることのできるレルムのみを返すようにします。

すべてのレルム属性のリストは冗長になる可能性があり、ほとんどのユーザーは、レルム名やレルムの有効化状態などの属性のサブセットに興味を持っています。また、 --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. すべての書き込み可能な属性に新しい値を設定したい場合は、次の通りです。

    1. get コマンドを実行します。

    2. JSONファイルの現在の値を編集します。

    3. 再送信。

      例:

      $ 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. keystorekeystorePasswordkeyPasswordalias の属性値を、使用するキーストアに合わせて変更してください。

  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を使って過去のイベントを照会することができます。Keycloakは、サービスコールのロギング( eventsEnabled )と、管理コンソールや管理REST APIでトリガーされる監査イベント( adminEventsEnabled )を個別に制御します。データベースがいっぱいにならないように、 eventsExpiration イベントの有効期限を設定することができます。Keycloakは eventsExpiration に秒単位で表現されたtime-to-liveを設定します。

すべてのイベントを受信し、JBoss-loggingを介してイベントを記録する組み込みイベントリスナーを設定できます。 org.keycloak.events のロガーを使用して、Keycloakはエラーイベントを 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日間オンにして、管理RESTでイベントを取得できるようにすることができます。

  • 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-cache

    • clear-user-cache

    • clear-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 a limited set of permissions'

クライアントロールの作成

  1. クライアントを特定します。

  2. 利用可能なクライアントの一覧を表示するには、 get コマンドを使用します。

    $ kcadm.sh get clients -r demorealm --fields id,clientId
  3. clients/ID/roles のように、 clientId 属性を使ってエンドポイントURIを構築し、新しいロールを作成します。

    例:

    $ 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

クライアントロールの一覧表示

Keycloakには、専用の get-roles コマンドが用意されており、レルムやクライアントロールのリストアップを簡単に行うことができます。このコマンドは、 get コマンドを拡張したもので、 get コマンドと同じ動作をしますが、ロールのリスト化には追加のセマンティクスが必要です。

get-roles コマンドに clientId--cclientid )オプションまたは id--cid )オプションを渡してクライアントを識別し、クライアントロールをリストアップします。

例:

$ kcadm.sh get-roles -r demorealm --cclientid realm-management

特定のレルムロールを取得する

特定のレルムロールのエンドポイントURIを構築するには、 get コマンドとロール name を使用します。 roles/ROLE_NAMEuser は既存ロールの名前)。

例:

$ kcadm.sh get roles/user -r demorealm

ロール名( --rolename オプション)またはID( --roleid オプション)を渡して、 get-roles コマンドを使用することができます。

例:

$ 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. 複合ロールに対して 割り当てられた レルムロールを一覧表示するには、対象となる複合ロールを名前( --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 オプション)またはID( --rid オプション)で、クライアントをclientId属性( --cclientid オプション)またはID( --cid オプション)で指定します。

    例:

    $ 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

レルムロールを複合ロールに追加する

Keycloakは、レルムロールやクライアントロールを追加するための add-roles コマンドを提供します。

この例では、 testrole という複合ロールに user というロールを追加しています。

$ kcadm.sh add-roles --rname testrole --rolename user -r demorealm

複合ロールからレルムロールを削除する

Keycloakは、レルムロールやクライアントロールを削除するための remove-roles コマンドを提供します。

次の例では、ターゲットの複合ロール testrole から user ロールを削除します。

$ kcadm.sh remove-roles --rname testrole --rolename user -r demorealm

レルムロールへのクライアントロールの追加

Keycloakは、レルムロールやクライアントロールを追加するための add-roles コマンドを提供します。

次の例では、クライアントに定義されたロールと realm-managementcreate-clientview-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-managementcreate-client および view-users ロールを Group グループに追加しています ( --gname オプション)。また、IDでグループを指定することもできます( --gid オプション)。

詳しくは、グループ操作を参照してください。

$ kcadm.sh add-roles -r demorealm --gname Group --cclientid realm-management --rolename create-client --rolename view-users

グループからのクライアントロールの削除

グループからクライアントロールを削除するには、remove-roles コマンドを使います。

次の例では、クライアントの realm management に定義された2つのロール、 creat-clientview-usersGroup グループから削除しています。

詳しくは、グループ操作を参照してください。

$ 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 コマンドを使用します。

この例では、出力をフィルタリングして、 idclientId の属性だけをリストアップしています。

$ kcadm.sh get clients -r demorealm --fields 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/admin/realms/demorealm/clients/8f271c35-44e3-446f-8953-b0893810ebe7/installation/providers/docker-v2-compose-yaml -r demorealm > keycloak-docker-compose-yaml.zip

クライアントの更新

特定のクライアントを取得するのに使ったのと同じエンドポイント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

クライアントの削除

delete コマンドを、特定のクライアントを取得するのに使ったのと同じエンドポイントURIで使います。

例:

$ 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

ユーザーは usernamefirstNamelastName または email でフィルタリングできます。

例:

$ kcadm.sh get users -r demorealm -q email=google.com
$ kcadm.sh get users -r demorealm -q username=testuser

フィルタリングでは、完全一致は使用しません。この例では、 username 属性の値を *testuser* パターンと照合しています。

複数の -q オプションを指定することで、複数の属性でフィルタリングすることができます。Keycloakは、すべての属性で条件に一致するユーザーのみを返します。

特定のユーザーを取得する

users/USER_ID のように、エンドポイントのURIを構成するためにユーザーIDを使用します。

例:

$ kcadm.sh get users/0ba7a3fd-6fd8-48cd-a60b-2e8fd82d56e2 -r demorealm

ユーザーの更新

特定のユーザーを取得するのに使ったのと同じエンドポイント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\"]"

ユーザーの削除

delete コマンドを、特定のユーザーを取得するのに使ったのと同じエンドポイントURIで使います。

例:

$ 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

このコマンドは、対象ユーザーに仮パスワードを設定します。対象となるユーザーは、次回ログイン時にパスワードを変更する必要があります。

また、 --userid を使うと、 id 属性でユーザーを指定することができます。

users/USER_ID/reset-password のように、特定のユーザーを取得するために使用したエンドポイントから構築されたエンドポイントで 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 パラメーターは、Keycloakが PUT コマンドの前に 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 オプション)またはID( --uid オプション)で、クライアントをclientId属性( --cclientid オプション)またはID( --cid オプション)で指定すると、そのユーザーに 割り当てられた クライアントロールの一覧が表示されます。

    例:

    $ 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 コマンドを使用します。

次の例では,ユーザー testuseruser ロールを追加しています。

$ 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を特定する。

  2. IDを使用して、 users/ID/sessions のようなエンドポイントURIを構成することができます。

  3. ユーザーのセッションの一覧を取得するには、 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

すべてのセッションからユーザーをログアウトする

ユーザーのIDを使用して、 users/ID/logout のようなエンドポイントURIを構築します。

そのエンドポイントURIに対して POST を実行するには、 create コマンドを使用します。

例:

$ 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、既存の子グループの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 -s name=SubGroup

特定のユーザーのグループを取得する

ユーザーのIDを使用して、ユーザーのグループへの所属を判断し、 users/USER_ID/groups のようなエンドポイントURIを構成します。

例:

$ kcadm.sh get users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups -r demorealm

グループにユーザーを追加する

ユーザーをグループに追加するには、 users/USER_ID/groups/GROUP_ID のように、ユーザーのIDとグループの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 オプション)、または ID ( --gid オプション) で指定すると、そのグループに 割り当てられた レルムロールを一覧表示します。

    例:

    $ 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 オプション) または ID ( --gid オプション) で指定します。

  2. クライアントをclientId属性 ( --cclientid オプション) またはID ( --id オプション) で指定すると、そのユーザーに 割り当てられた クライアントロールを一覧表示します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management
  3. 有効な レルムロールをリストアップするには、 --effective オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --effective
  4. まだグループに追加できるレルムロールを一覧表示するには、--available オプションを使用します。

    例:

    $ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --available

アイデンティティー・プロバイダーの操作

使用可能なアイデンティティー・プロバイダー の一覧表示

利用可能なアイデンティティー・プロバイダーを一覧表示するには、 serverinfo エンドポイントを使用します。

例:

$ kcadm.sh get serverinfo -r demorealm --fields 'identityProviders(*)'

Keycloak は serverinfo エンドポイントを realms エンドポイントと同様に処理します。Keycloakは、エンドポイントが特定のレルムの外側に存在するため、ターゲットのレルムに対する相対的な解決を行いません。

設定済みアイデンティティー・プロバイダー の一覧表示

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. 新しいアイデンティティー・プロバイダーのインスタンスを作成する際には、 keycloak-oidcproviderId として使用します。

  2. config 属性に authorizationUrltokenUrlclientIdclientSecret を指定します。

    例:

    $ 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/realms/demorealm/protocol/openid-connect/auth -s config.tokenUrl=http://localhost:8180/realms/demorealm/protocol/openid-connect/token -s config.clientId=demo-oidc-provider -s config.clientSecret=secret

OpenID Connect アイデンティティー・プロバイダーの設定

一般的なOpenID Connectプロバイダーを、Keycloak OpenID Connectプロバイダーを設定するのと同じ方法で設定します。ただし、 providerId 属性の値を oidc に設定します。

SAML 2 アイデンティティー・プロバイダーの設定

  1. providerId には、 saml を使用します。

  2. config 属性に singleSignOnServiceUrlnameIDPolicyFormatsignatureAlgorithm を指定します。

例:

$ 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/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. config 属性を指定します。 clientIdclientSecret を指定します。これらの属性は、Facebook Developersのアプリケーション設定ページで確認することができます。詳細はFacebookアイデンティティー・ブローカーのページを参照してください。

    例:

    $ 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. config 属性に clientIdclientSecret を指定します。これらの属性は、Google Developersのアプリケーション設定ページで確認することができます。詳細はGoogleアイデンティティー・ブローカーのページを参照ください。

    例:

    $ 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. config 属性に clientIdclientSecret を指定します。これらの属性は、Twitter Application Managementのアプリケーション設定ページで確認することができます。詳細は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. config 属性の clientIdclientSecret を指定します。これらの属性は、GitHub Developer Application Settingsページで確認することができます。詳しくは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. config 属性の clientIdclientSecret を指定します。これらの属性は、アプリケーションの LinkedIn Developer Console アプリケーションページで見つけることができます。詳細は、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. config 属性の clientIdclientSecret を指定します。これらの属性は、アプリケーションの Microsoft Application Registration Portal ページで確認することができます。詳細は、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. config 属性の clientIdclientSecret 、および key を指定します。これらの属性は、Stack Apps OAuthページで確認することができます。詳細は Stack Overflowアイデンティティー・ブローカーのページを参照してください。

    例:

    $ 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. parentId 属性の値として、レルムIDを指定します。

  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 クエリー・パラメーターを追加します。

  3. 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 のクエリー・パラメーターを追加します。

  3. create コマンドを実行します。

    例:

    $ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerChangedUsersSync

LDAPユーザー・ストレージの接続をテストする

  1. testLDAPConnection のエンドポイントに対して get コマンドを実行します。

  2. クエリー・パラメーター bindCredentialbindDnconnectionUrluseTruststoreSpi を指定します。

  3. クエリー・パラメーター actiontestConnection を設定します。

    例:

    $ 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 を指定します。

  3. クエリー・パラメーター actiontestAuthentication を設定します。

    例:

    $ 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. user-attribute-ldap-mapperproviderId 属性を設定します。

    例:

    $ 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 属性以外のすべての出力をフィルタリングすることで、現在のレルム設定を取得することができます。

たとえば、demorealmpasswordPolicy を表示します。

$ 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. フローのエグゼキューションを取得します。

  2. フローのIDをメモします。

  3. 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. フローのエグゼキューションを取得します。

  2. その authenticationConfig 属性に注目してください。この属性には、設定IDが含まれています。

  3. authentication/config/ID エンドポイントに対して get コマンドを実行します。

例:

$ kcadm get "authentication/config/dd91611a-d25c-421a-87e2-227c18421833" -r examplerealm

エグゼキューションの設定の更新

  1. フローのエグゼキューションを取得します。

  2. フローの authenticationConfig 属性を取得します。

  3. 属性から設定IDをメモします。

  4. 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. フローのエグゼキューションを取得します。

  2. フローの authenticationConfig 属性を取得します。

  3. 属性から設定IDをメモします。

  4. authentication/config/ID エンドポイントで delete コマンドを実行します。

例:

$ kcadm delete "authentication/config/dd91611a-d25c-421a-87e2-227c18421833" -r examplerealm