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、Fuse、Tomcat、Jetty、Springなどのクライアント・アダプター。
-
OpenID Connectのリライング・パーティー・ライブラリー、もしくは、SAML 2.0のサービス・プロバイダー・ライブラリーをもつ、あらゆるプラットフォーム/言語のサポート。
基本的なKeycloakの操作
Keycloakは、あなたのネットワーク上で管理する独立したサーバーです。アプリケーションはこのサーバーを指し示すように設定され、このサーバーによってセキュリティー保護されます。Keycloakはアプリケーションをセキュリティー保護するために、 OpenID Connect や SAML 2.0 といった標準プロトコルを採用しています。ブラウザー・アプリケーションは、ユーザーのブラウザーをアプリケーションから自分のクレデンシャルを入力するKeycloak認証サーバーにリダイレクトします。ユーザーは完全にアプリケーションから分離され、アプリケーションはユーザーのクレデンシャルを見ることも決してないため、このリダイレクトは重要です。代わりに、アプリケーションには、暗号化署名されたIDトークンまたはアサーションが与えられます。これらのトークンはユーザー名、住所、電子メール、および、その他プロファイルデータといったアイデンティティー情報を持つことができます。また、パーミッション・データを保持することも可能でアプリケーションは認可決定を行うことも可能です。これらのトークンはRESTベースのサービスに対して安全な呼び出しを行うためにも使用できます。
コアコンセプトと用語
Keycloakを使用して、WebアプリケーションやRESTサービスをセキュリティー保護しようとする前に、知っておくべきキーコンセプトと用語があります。
- ユーザー
-
システムにログイン可能なエンティティーのことです。電子メール、ユーザー名、住所、電話番号、生年月日など自分自身に関連する属性を持ちます。また、グループ・メンバーシップが割り当てられたり、特定のロールが割り当てられたりします。
- 認証
-
ユーザーを特定し、検証するプロセスのことです。
- 認可
-
ユーザーに対してアクセスを許可するプロセスのことです。
- クレデンシャル
-
クレデンシャルは、Keycloakがユーザーの身元を確認するために使用するデータの一部のことです。例として、パスワード、ワンタイムパスワード、デジタル証明書、さらには指紋などがあります。
- ロール
-
ロールは、ユーザーのタイプまたはカテゴリーを識別します。
Admin
、user
、manager
、employee
はすべて、組織内に存在する典型的なロールです。アプリケーションは、ユーザーの扱いをきめ細く管理することが難しくなる場合があるため、個々のユーザーではなく、特定のロールにパーミッションを割り当てることが多いです。 - ユーザー・ロール・マッピング
-
ユーザー・ロール・マッピングは、ロールとユーザーの間のマッピングを定義します。ユーザーには、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で保護されたアプリケーションを登録したりすることができます。
-
Server Installation and Configuration Guide で定義されているインストールと設定のタスクを、Keycloakサーバーが稼働するまで実行します。
ローカルホストでのアカウント作成
サーバーが localhost
からアクセスできる場合は、以下の手順を実行してください。
-
Webブラウザーで、http://localhost:8080/auth URLにアクセスします。
-
思い出せるユーザー名とパスワードを入力してください。
ウェルカムページ
リモートでのアカウント作成
localhost
アドレスからサーバーにアクセスできない場合や、コマンドラインからKeycloakを起動したい場合は、 …/bin/add-user-keycloak
スクリプトを使用してください。
スタンドアローン動作モードまたはドメイン動作モードを使用している場合、パラメーターは少し異なります。スタンドアローン・モードの場合のスクリプトの使用方法を次に示します。
$ .../bin/add-user-keycloak.sh -r master -u <username> -p <password>
> ...\bin\add-user-keycloak.bat -r master -u <username> -p <password>
ドメインモードでは、 -sc
スイッチを使ってスクリプトをサーバーホストの1つに向ける必要があります。
$ .../bin/add-user-keycloak.sh --sc domain/servers/server-one/configuration -r master -u <username> -p <password>
> ...\bin\add-user-keycloak.bat --sc domain/servers/server-one/configuration -r master -u <username> -p <password>
レルムの設定
管理コンソール用に管理者アカウントを作成すると、レルムを設定することができます。レルムとは、ユーザー、アプリケーション、ロール、グループなどのオブジェクトを管理するための空間です。ユーザーはレルムに所属し、ログインします。1 つのKeycloakのデプロイメントで、データベースの空き容量と同じ数のレルムを定義、保存、管理できます。
管理コンソールの使用
レルムを設定し、ほとんどの管理作業はKeycloakの管理コンソールで行います。
-
管理者アカウントが必要です。 最初の管理者を作成する を参照してください。
-
管理コンソールのURLにアクセスします。
たとえば、ローカルホストの場合、http://localhost:8080/auth/admin/のURLを使用します。
ログインページ -
ウェルカムページで作成したユーザー名とパスワード、またはbinディレクトリーにある
add-user-keycloak
スクリプトを入力します。このアクションは、管理コンソールを表示します。管理コンソール -
使えるメニューや他のオプションをメモします。
-
Master と書かれたメニューをクリックして、管理したいレルムを選択するか、新しいレルムを作成します。
-
右上のリストをクリックすると、自分のアカウントを確認したり、ログアウトしたりできます。
-
クエスチョン・マーク ? のアイコンにカーソルを合わせると、そのフィールドを説明するツールチップ・テキストが表示されます。上の画像は、ツールチップの動作を示しています。
-
masterレルム
管理コンソールには、2種類のレルムが存在します。
-
Master realm
- このレルムはKeycloakを最初に起動したときに作成されたものです。最初のログイン時に作成した管理者アカウントが含まれています。 master レルムは、システム内のレルムの作成と管理にのみ使用してください。 -
Other realms
- これらのレルムは、masterレルムの管理者によって作成されます。これらのレルムでは、管理者は組織内のユーザーと、そのユーザーが必要とするアプリケーションを管理します。アプリケーションはユーザーによって所有されます。
レルムは互いに隔離されており、自分が管理しているユーザーのみを管理、認証することができます。このセキュリティー・モデルに従うことで、誤った変更を防ぐことができます。また、ユーザー・アカウントには、現在のタスクを正常に完了するために必要な特権と権限のみへのアクセスを許可するという伝統に従っています。
-
master レルムを無効にして、新しく作成するレルムに管理者アカウントを定義したい場合は、Dedicated Realm Admin Consolesを参照してください。各レルムには専用の管理コンソールがあり、ローカル・アカウントでログインすることができます。
レルムの作成
レルムを作成することで、ユーザーを作成し、アプリケーションを使用するためのパーミッションを与えることができる管理空間を提供することができます。最初のログインでは、通常 master レルム(他のレルムを作成する際の最上位レルム)に入ります。
どのようなレルムが必要かを決定するには、ユーザーとアプリケーションをどのように分離したいかを検討します。たとえば、会社の従業員用のレルムと、顧客用の別のレルムを作成するとします。 従業員は従業員用のレルムにログインし、社内のアプリケーションにのみアクセスできるようにします。顧客は顧客用レルムにログインし、顧客向けアプリケーションにのみアクセスできるようにします。
-
左ペインの上部をマウスオーバーします。
-
Add Realm をクリックします。
レルムメニューの追加 -
レルムの名前を入力します。
-
Create をクリックします。
レルムを作成する
現在のレルムは、先ほど作成したレルムに設定されています。左上をマウスオーバーして Select Realm をクリックすることで、異なるレルムの管理に切り替えることができます。
-
あるいは、新しいレルムを定義したJSONドキュメントをインポートすることもできます。詳細は エクスポートとインポート の章を参照してください。
レルムにSSLを設定する
各レルムには、そのレルムと通信するためのSSL/HTTPSの要件を定義する、SSLモードが関連付けられています。レルムとやりとりするブラウザーやアプリケーションは、SSLモードによって定義されたSSL/HTTPSの要件を守らなければ、サーバーとやりとりすることができません。
Keycloakは、初回実行時に自己署名証明書を生成します。自己署名証明書は安全ではないため、テスト目的でのみ使用してください。CA署名付き証明書をKeycloakサーバー自体、またはKeycloakサーバーの前にあるリバース・プロキシーにインストールすることを強くお勧めします。 Server Installation and Configuration Guide を参照してください。 |
-
メニューの Realm Settings をクリックします。
-
Login タブをクリックします。
ログインタブ -
Require SSL を以下のSSLモードのいずれかに設定してください。
-
external requests::
localhost
、127.0.0.1
、10.x.x.x
、192.168.x.x
、172.16.x.x
のようなプライベートIPアドレスに固定する限り、ユーザーはSSL無しでKeycloakと対話できます。非プライベートIPアドレスからSSL無しでKeycloakにアクセスしようとすると、エラーが発生します。 -
none:: KeycloakはSSLを必要としません。この選択は、開発時に実験的に使用し、このデプロイメントのサポートを予定していない場合にのみ適用されます。
-
all requests:: KeycloakはすべてのIPアドレスに対してSSLを要求します。
-
サーバー・キャッシュのクリア
Keycloakは、JVMの制限と設定した制限の範囲内で、メモリー内にできる限りのものをキャッシュしています。DBAなどの第三者が、サーバーのREST APIや管理コンソールの範囲外でKeycloakのデータベースを変更した場合、メモリー内キャッシュの一部が古くなっている可能性があります。レルムキャッシュ、ユーザー・キャッシュ、外部公開鍵キャッシュ(外部クライアントやアイデンティティー・プロバイダーの公開鍵など、Keycloakが特定の外部エンティティーの署名を検証するために使用する可能性があるもの)をクリアすることができます。
-
メニューの Realm Settings をクリックします。
-
Cache タブをクリックします。
-
退去させたいキャッシュの Clear ボタンをクリックします。
Cacheタブ
レルムに電子メールを設定する
Keycloakは、ユーザーが電子メールアドレスを確認するとき、パスワードを忘れたとき、あるいは管理者がサーバーイベントに関する通知を受け取る必要があるときに、電子メールを送信します。Keycloakが電子メールを送信できるようにするには、KeycloakにSMTPサーバーの設定を提供します。
-
メニューの Realm Settings をクリックします。
-
Email タブをクリックします。
Emailタブ -
必要に応じてフィールドに入力し、スイッチを切り替えてください。
- ホスト
-
Host は、電子メール送信時に使用するSMTPサーバーのホスト名を示します。
- Port
-
Port はSMTPサーバーのポートを示します。
- From
-
From は、送信されるメールの From SMTPヘッダーに使用されるアドレスです。
- From Display Name
-
From Display Name では、ユーザーフレンドリーなメールアドレスのエイリアスを設定できます(オプション)。設定されていない場合、電子メールクライアントでは通常の From メールアドレスが表示されます。
- Reply To
-
Reply To は、送信されるメールの Reply-To SMTPヘッダーに使用されるアドレスを示します(オプション)。設定されていない場合は、通常の From 電子メールアドレスが使用されます。
- Reply To Display Name
-
Reply To Display Name では、ユーザー・フレンドリーなメールアドレスのエイリアスを設定することができます(オプション)。設定されていない場合は、通常の Reply To のメールアドレスが表示されます。
- Envelope From
-
Envelope From は、送信されるメールの Return-Path SMTPヘッダーに使用される Bounce Address を示します(オプション)。
- SSLの有効化とStartTSLの有効化
-
特にSMTPサーバーが外部ネットワーク上にある場合は、これらのスイッチの1つを ON に切り替えて、ユーザー名とパスワードを回復するための電子メールの送信をサポートします。ほとんどの場合、 Port をSSL/TLSのデフォルトポートである465に変更する必要があります。
- 認証の有効化
-
SMTPサーバーで認証が必要な場合は、このスイッチを ON に設定してください。プロンプトが表示されたら、 Username と Password を入力してください。 Password フィールドの値は、外部のボールトからの値を参照することができます。
テーマと国際化の設定
あるレルムに対して、Keycloakでは、テーマを使うことで、表示される言語も含めて、あらゆるUIの見た目を変更することができます。
-
メニューの Realm Settings をクリックします。
-
Themes タブをクリックします。
Themesタブ -
UIカテゴリーごとに必要なテーマを選び、 Save をクリックします。
- Login Theme
-
ユーザー名・パスワード入力、OTP入力、新規ユーザー登録、その他ログインに関連する画面。
- Account Theme
-
各ユーザーのアカウント管理UI。
- Admin Console Theme
-
Keycloak管理コンソールのスキン。
- Email Theme
-
Keycloakが電子メールを送信する場合に、このテーマで定義されたテンプレートを使用して電子メールを作成します。
-
Server Developer Guideでは、新しいテーマを作成したり、既存のテーマを変更する方法について説明しています。
国際化の有効化
Keycloakでは、すべてのUI画面が国際化されます。デフォルトの言語は英語ですが、どのロケールに対応するか、またどれをデフォルトのロケールにするかを選択できます。
-
メニューの Realm Settings をクリックします。
-
Themes タブをクリックします。
-
Internationalization を ON に設定します。
次回ログイン時に、ログイン画面、アカウントコンソール、管理コンソールで使用する言語を選択できます。
-
Server Developer Guide では、追加の言語を提供する方法について説明しています。テーマによって提供されるすべての国際化テキストは、Localization タブでレルム固有のテキストに上書きすることができます。
ユーザーロケールの選択
ロケール・セレクター・プロバイダーは、入手した情報から最適なロケールを提案します。しかし、ユーザーが誰であるかは不明なことが多いため、以前に認証されたユーザーのロケールを永続化されたCookieに記憶させます。
ロケールを選択するためのロジックは、以下の利用可能な最初のものが使用されます。
-
ユーザーが選択 - ユーザーがドロップダウン・ロケール・セレクターを使用してロケールを選択した場合
-
ユーザー・プロファイル - 認証されたユーザーがいて、そのユーザーが優先ロケールを設定している場合
-
クライアントによる選択 - たとえばui_localesパラメーターを使用してクライアントから渡された場合
-
Cookie - ブラウザーで最後に選択されたロケール
-
Accepted language - Accept-Language ヘッダーから取得したロケール
-
レルムのデフォルト
-
上記のいずれでもない場合、英語にフォールバックします
ユーザーが認証されると、前述の永続化されたCookieのロケールを更新するアクションがトリガーされます。ユーザーがログインページのロケール・セレクターを介してアクティブにロケールを切り替えた場合、ユーザーロケールもこの時点で更新されます。
ロケールを選択するロジックを変更したい場合は、カスタムの LocaleSelectorProvider
を作成するオプションがあります。詳しくは Server Developer Guide を参照してください。ユーザーが認証されると、先ほどの永続化されたCookieのロケールを更新するためのアクションが発生します。ユーザーがログインページのロケール・セレクターでロケールを積極的に切り替えていた場合、この時点でユーザーのロケールも更新されます。
ロケールを選択するロジックを変更したい場合は、カスタムの LocaleSelectorProvider
を作成するオプションがあります。詳しくは Server Developer Guide を参照してください。
ログイン・オプションの制御
Keycloakには、いくつかのログインページ機能が組み込まれています。
パスワード忘れを有効にする
Forgot Password
を有効にすると、ユーザーがパスワードを忘れたり、OTPジェネレーターを紛失した場合に、ログイン・クレデンシャルをリセットすることができます。
-
メニューの Realm Settings をクリックします。
-
Login タブをクリックします。
ログインタブ -
Forgot Password を ON に切り替えてください。
ログインページに
forgot password
というリンクが表示される。パスワード忘れリンク -
このリンクをクリックすると、ユーザーはユーザー名またはメールアドレスを入力し、クレデンシャルをリセットするためのリンクが記載されたメールを受け取ることができます。
パスワード忘れページ
電子メールで送信されるテキストは設定可能です。詳しくはServer Developer Guideを参照してください。
ユーザーがメールのリンクをクリックすると、Keycloakのパスワードを更新するように求められ、OTPジェネレーターを設定している場合は、KeycloakのOTPジェネレーターを再設定するように求められます。 組織のセキュリティー要件によっては、ユーザーに電子メールでOTPジェネレーターをリセットさせたくない場合もあります。
この動作を変更するには、以下の手順を実行します。
-
メニューの Authentication をクリックします。
-
Flows タブをクリックします。
-
Reset Credentials フローを選択します。
リセット・クレデンシャル・フローOTPをリセットしたくない場合は、
Reset OTP
の要件を Disabled に設定してください。 -
Required Actions タブをクリックします。 Update Password が有効になっていることを確認します。
Remember Meの有効化
ログインしたユーザーがブラウザーを閉じると、セッションが破棄され、再度ログインする必要があります。Keycloakを設定すると、ログイン時に Remember Me のチェックボックスをクリックした場合に、ユーザーのログインセッションを維持することができます。このアクションは、ログインCookieをセッションのみのCookieから永続的なCookieに変えます。
-
メニューの Realm Settings をクリックします。
-
Login タブをクリックします。
-
Remember Me スイッチを ON にする。
ログインタブ
この設定を保存すると、レルムのログインページに remember me
のチェックボックスが表示されます。
レルム鍵の設定
Keycloakで使用される認証プロトコルは暗号化署名を必要とし、時には暗号化を必要とします。Keycloakは、これに対応するために秘密鍵と公開鍵の鍵ペアを使用します。
Keycloakは一度に1つのアクティブな鍵ペアを持ちますが、複数のパッシブな鍵も持つこともできます。アクティブな鍵ペアを使用して新しい署名を作成する一方で、パッシブな鍵ペアを使用して以前の署名を検証することができます。これにより、ダウンタイムやユーザーの中断を招くことなく、鍵を定期的にローテーションさせることができます。
レルムが作成されると、鍵ペアと自己署名証明書が自動的に生成されます。
-
管理コンソールでレルムを選択します。
-
Realm settings をクリックします。
-
Keys をクリックします。
-
パッシブ鍵を表示するには、 Passive をクリックします。
-
無効な鍵を表示するには、 Disabled をクリックします。
鍵ペアのステータスが Active
であっても、そのレルムで現在アクティブな鍵ペアとして選択されないことがあります。署名に使用されるアクティブな鍵ペアは、アクティブな鍵ペアを提供できる、 優先順位の高い最初の鍵プロバイダーに基づき選択されます。
鍵のローテーション
定期的に鍵をローテーションすることをお勧めします。そのためには、既存のアクティブな鍵よりも高い優先順位を持つ新しい鍵を作成することから始めます。または、同じ優先順位の新しい鍵を作成し、以前の鍵をパッシブにします。
新しい鍵が利用可能になると、新しいトークンとCookieはすべて新しい鍵で署名されます。ユーザーがアプリケーションを認証すると、SSO Cookieは新しい署名で更新されます。OpenID Connectトークンをリフレッシュすると、新しいトークンが新しい鍵で署名されます。つまり、すべてのトークンとCookieが新しい鍵を使用するようになるため、しばらく経つと古い鍵を削除することができます。
古い鍵を削除する頻度は、セキュリティーとすべてのCookieとトークンの更新を確認することとのトレードオフになります。新しい鍵は3〜6カ月ごとに作成し、古い鍵は新しい鍵を作成してから1〜2カ月後に削除することを検討してください。新しい鍵が追加されてから古い鍵が削除されるまでの間にユーザーが活動していなかった場合、そのユーザーは再認証を行う必要があります。
鍵のローテーションは、オフライントークンにも適用されます。確実に更新されるように、アプリケーションは古い鍵が削除される前にトークンをリフレッシュする必要があります。
鍵ペアの追加
-
管理コンソールでレルムを選択します。
-
Realm settings をクリックします。
-
Keys タブをクリックします。
-
Providers タブをクリックします。
-
Add keystore をクリックし、 rsa-generated を選択します。
-
Priority の欄に数字を入力します。この番号によって、新しい鍵ペアがアクティブな鍵ペアになるかどうかが決まります。
-
keysize の値を選択します。
-
Save をクリックします。
この操作により、自己署名入り証明書を含む新しいキーペアが生成されます。
プロバイダーの優先順位を変更しても鍵は再生成されませんが、鍵のサイズを変更したい場合は、プロバイダーを編集して新しい鍵を生成することができます。
既存の鍵ペアと証明書の追加
他で取得した鍵ペアと証明書を追加するには、 Providers
を選択し、ドロップダウンから rsa
を選択します。優先順位を変更することで、新しい鍵ペアをアクティブな鍵ペアにすることができます。
-
秘密鍵のファイルです。PEM形式のファイルである必要があります。
-
管理コンソールでレルムを選択します。
-
Realm settings をクリックします。
-
Keys タブをクリックします。
-
Providers タブをクリックします。
-
Add keystore をクリックし、 rsa を選択します。
-
Priority の欄に数字を入力します。この番号によって、新しい鍵ペアがアクティブな鍵ペアになるかどうかが決まります。
-
Private RSA Key の横にある Select file をクリックして、秘密鍵ファイルをアップロードします。
-
秘密鍵の署名付き証明書がある場合は、 X509 Certificate の横にある Select file をクリックして、証明書ファイルをアップロードしてください。証明書をアップロードしない場合、Keycloakは自動的に自己署名証明書を生成します。
-
Save をクリックします。
Javaキーストアから鍵をロードする
ホスト上のJavaキーストア・ファイルに格納されている鍵ペアと証明書を追加するには、 Providers
を選択し、ドロップダウンから java-keystore
を選択します。優先順位を変更して、新しい鍵ペアをアクティブにすることができます。
関連する証明書チェーンを読み込むためには、キーペアを読み込むために使用したのと同じ Key Alias
を使って、JavaのKeystoreファイルにインポートする必要があります。
-
管理コンソールでレルムを選択します。
-
Realm settings をクリックします。
-
Keys タブをクリックします。
-
Providers タブをクリックします。
-
Add keystore をクリックし、 java-keystore を選択します。
-
Priority の欄に数字を入力します。この番号によって、新しい鍵ペアがアクティブな鍵ペアになるかどうかが決まります。
-
Keystore に値を入力します。
-
Keystore Password に値を入力します。
-
Key Alias に値を入力します。
-
Key Password に値を入力します。
-
Save をクリックします。
鍵をパッシブにする
-
管理コンソールでレルムを選択します。
-
Realm settingsをクリックします。
-
Keys タブをクリックします。
-
Active タブをクリックします。
-
パッシブ化したい鍵のプロバイダーをクリックします。
-
Active を OFF に切り替えます。
-
Save をクリックします。
鍵の無効化
-
管理コンソールでレルムを選択します。
-
Realm settingsをクリックします。
-
Keys タブをクリックします。
-
Active タブをクリックします。
-
パッシブ化したい鍵のプロバイダーをクリックします。
-
Enabled を OFF に切り替えます。
-
Save をクリックします。
鍵の漏洩
Keycloakは、署名鍵をローカルにのみ保存し、クライアント・アプリケーションやユーザーまたは他のエンティティーと共有することはありません。しかし、レルムの署名鍵が漏洩したと思われる場合は、まず上記のように新しい鍵ペアを生成し、漏洩した鍵ペアを直ちに削除する必要があります。
また、 Providers
テーブルからプロバイダーを削除することもできます。
-
メニューの Clients をクリックします。
-
security-admin-console をクリックします。
-
Revocation タブをクリックします。
-
Set to now をクリックします。
-
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で処理し、保存することができます。
プロバイダーの追加
ストレージ・プロバイダーを追加するには、次の手順を実行します。
-
メニューの User Federation をクリックします。
ユーザー・フェデレーション -
プロバイダーの種類を Add Provider のリストから選択します。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ストレージの設定
-
メニューの User Federation をクリックします。
ユーザー・フェデレーション -
Add Provider の一覧から ldap を選択します。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にマッピングされていないユーザーデータを変更しようとすると、ユーザーの更新ができなくなります。たとえば、ユーザーの |
編集モード
ユーザのメタデータは、ユーザーはアカウント・コンソールから、管理者は管理コンソールから修正することができます。LDAP設定ページの Edit Mode
の設定は、ユーザーのLDAP更新権限を定義します。
- READONLY
-
ユーザー名、電子メール、姓、名、その他のマッピングされた属性は変更できません。ユーザーがこれらのフィールドを更新しようとすると、いつでも Keycloak エラーが表示されます。パスワードの更新はサポートされていません。
- WRITABLE
-
ユーザー名、電子メール、姓、名などのマッピングされた属性やパスワードを変更し、LDAPストアと自動的に同期させることはできません。
- UNSYNCED
-
Keycloakは、ユーザー名、電子メール、名、姓、パスワードの変更を Keycloakのローカル・ストレージに保存するため、管理者はこのデータをLDAPに同期して戻さなければなりません。このモードでは、Keycloakが読み取り専用のLDAPサーバー上のユーザー・メタデータを更新することができます。このオプションは、LDAPからローカルのKeycloakのユーザー・データベースにユーザーをインポートする場合にも適用されます。
KeycloakがLDAPプロバイダーを作成するとき、Keycloakは初期LDAPマッパーのセットも作成します。Keycloak は、 Vendor 、 Edit 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のグローバル・トラストストアを設定します。グローバル・トラストストアの設定の詳細については、 Server Installation and Configuration Guide を参照してください。これは、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のデータベース内のfirstName
とlastname
属性にマップします。ユーザーのフルネームをcn
に格納することは、LDAP の配備では一般的なことです。
Keycloakで新規ユーザーを登録する際、LDAPプロバイダーの |
- Hardcoded Attribute Mapper
-
このマッパーはLDAPとリンクしている各Keycloakユーザーにハードコードされた属性値を追加します。このマッパーは
enabled
やemailVerified
というユーザー・プロパティーに値を強制することもできます。 - ロールマッパー
-
このマッパーは、LDAPから取得したロールマッピングをKeycloakのロールマッピングに設定します。1つのロールマッパーで、LDAPロール(通常はLDAPツリーの特定のブランチのグループ)を、指定されたクライアントのレルムロールまたはクライアントロールに対応するロールにマッピングすることができます。同じLDAPプロバイダーに対して、より多くのロールマッパーを設定することができます。たとえば、
ou=main,dc=example,dc=org
のグループからのロールマッピングはレルムロールマッピングにマッピングし、ou=finance,dc=example,dc=org
のグループからのロールマッピングはクライアントfinance
のクライアント・ロールマッピングにマッピングすると指定することができます。 - ハードコードされたロールマッパー
-
このマッパーは、LDAPプロバイダーからの各Keycloakユーザーに対して、指定されたKeycloakロールを付与します。
- グループマッパー
-
このマッパーは、LDAPツリーのブランチからKeycloak内のグループにLDAPグループをマッピングします。このマッパーはまた、LDAP からのユーザー・グループ・マッピングを Keycloak 内のユーザー・グループ・マッピングに伝搬させます。
- MSADユーザー・アカウント・マッパー
-
このマッパーは Microsoft Active Directory (MSAD)に特化したものです。MSADのユーザー・アカウントの状態を、有効なアカウントや期限切れのパスワードのようなKeycloakのアカウントの状態に統合することができます。このマッパーは
userAccountControl
とpwdLastSet
という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に上げると便利です。ロギングでこのレベルを上げます。
カテゴリー org.keycloak.storage.ldap
のログレベルをTRACEに上げると便利です。 standalone(-ha).xml
ファイルのロギング・サブシステムでこのレベルを上げます。この設定では、LDAPサーバーへのすべてのクエリーのログと、クエリーの送信に使用されたパラメーターを含む、多くのログメッセージが TRACE
レベルで server.log
ファイルに送信されます。ユーザー・フォーラムまたはJIRAでLDAPの質問を作成する場合は、TRACEログを有効にしてサーバーログを添付することを検討してください。大きすぎる場合は、問題が発生する操作の際にログに追加されたメッセージとサーバーログのスニペットだけを含めることをお勧めします。
-
LDAPプロバイダーを作成すると、サーバーログに次のINFOレベルでメッセージが表示されます。
LDAPプロバイダーを作成すると、サーバーログに次のINFOレベルでメッセージが表示されます。
Creating new LDAP Store for the LDAP storage provider: ...
LDAPプロバイダーの設定が表示されます。質問したりバグを報告したりする前に、このメッセージを含めてLDAPの設定を表示するとよいでしょう。最終的には、含めたくない設定の変更をいくつかのプレースホルダー値で自由に置き換えてください。 一例は bindDn=some-placeholder
です。 connectionUrl
についても、同様に自由に置き換えることができますが、少なくとも使用されたプロトコル ( ldap
と ldaps
) を含めることは一般的に役立ちます。同様に、DEBUGレベルで次のようなメッセージとともに表示されるLDAPマッパーの設定の詳細を含めると便利です。
Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ...
これらのメッセージは、DEBUGロギングが有効になっている場合にのみ表示されることに注意してください。
-
パフォーマンスやコネクション・プーリングの問題を追跡するために、
Connection Pool Debug Level
というプロパティーを設定することを検討してください。
パフォーマンスまたは接続プーリングの問題を追跡するには、LDAPプロバイダーのプロパティー Connection Pool Debug Level
の値を all
に設定することを検討してください。これにより、サーバーログにLDAP接続プーリングのログが含む多くのメッセージが追加されます。これは、接続プーリングまたはパフォーマンスに関連する問題を追跡するために使用できます。
接続プーリングの設定を変更した後、LDAPプロバイダー接続の再初期化を強制するために、Keycloakサーバーを再起動する必要がある場合があります。 |
サーバーを再起動しても接続プールに関するメッセージが表示されない場合は、接続プールがLDAPサーバーで機能していないことを示している可能性があります。
-
LDAPの問題を報告する場合、あなたの環境で問題を起こす可能性がある対象のデータとLDAPツリーの一部を添付することを検討してください。たとえば、あるユーザーのログインに時間がかかる場合、様々な"group"エントリーの
member
属性の数を示すLDAPエントリーを添付することを検討できます。この場合、これらのグループ・エントリーがKeycloakのグループLDAPマッパー (またはロール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は、読み取り専用のD-Busインターフェイスで通信します。このため、ユーザーの設定や更新はFreeIPA/IdMの管理インターフェイスで行うことになります。デフォルトでは、このインターフェイスはユーザー名、電子メール、名、姓をインポートします。
Keycloakはグループとロールを自動的に登録しますが、同期を取りません。Keycloakの管理者がKeycloakで行った変更は、SSSDと同期されません。 |
FreeIPA/IdMサーバー
FreeIPA Dockerイメージは、Docker Hubで公開されています。FreeIPAサーバーのセットアップは、 FreeIPAのドキュメント を参照してください。
-
このコマンドを使用して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
withserver.freeipa.local
represents the FreeIPA/IdM server hostname. ChangeYOUR_PASSWORD
to a password of your own. -
コンテナーの起動後、
/etc/hosts
を次のように変更します。x.x.x.x server.freeipa.local
この変更を行わない場合は、DNSサーバーを設定する必要があります。
-
以下のコマンドでLinuxサーバーをIPAドメインに登録し、SSSDフェデレーション・プロバイダーがKeycloak上で起動・実行されるようにします。
ipa-client-install --mkhomedir -p admin -w password
-
クライアントで以下のコマンドを実行し、インストールが正常に行われることを確認します。
kinit admin
-
パスワードを入力してください。
-
このコマンドを使用して、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
-
kinitを使用してユーザーのパスワードを強制的に設定します。
kinit <username>
-
以下を入力すると、IPAの正常な動作に戻ります。
kdestroy -A kinit admin
SSSDとD-Bus
フェデレーション・プロバイダーはD-BUSを用いてSSSDからデータを取得し、PAMを用いてデータを認証します。
-
sssd-dbusのRPMをインストールします。
$ sudo yum install sssd-dbus
-
Keycloakの配布ファイルから入手可能なプロビジョニング・スクリプトを実行します。
$ bin/federation-sssd-setup.sh
このプロビジョニング・スクリプトは
/etc/sssd/sssd.conf
に以下の変更を加えます。[domain/your-hostname.local] ... ldap_user_extra_attrs = mail:mail, sn:sn, givenname:givenname, telephoneNumber:telephoneNumber ... [sssd] services = nss, sudo, pam, ssh, ifp ... [ifp] allowed_uids = root, yourOSUsername user_attributes = +mail, +telephoneNumber, +givenname, +sn
-
セットアップが成功したことを確認するために、
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ストアを設定します。
-
メニューの User Federation をクリックします。
-
Add Provider の一覧から sssd を選択します。Keycloakで、sssdの設定ページに移動します。
-
Save をクリックします。
これで、FreeIPA/IdMのクレデンシャルを使って Keycloakに対する認証ができるようになりました。
カスタム・プロバイダー
Keycloakには、ユーザー・ストレージ・フェデレーション用のカスタム・プロバイダーを開発するためのService Provider Interface (SPI)があります。カスタム・プロバイダーの開発に関するドキュメントは、 Server Developer Guide にあります。
ユーザーの管理
管理コンソールから、ユーザーを管理するために実行できるアクションは多岐にわたります。
ユーザーの検索
ユーザーを検索すると、そのユーザーのグループやロールなどの詳細情報が表示されます。
-
ユーザーが存在するレルムにいます。
-
メインメニューの Users をクリックします。この Users ページが表示されます。
-
検索ボックスに、検索したいユーザーの氏名、姓、名、Eメールアドレスのいずれかを入力します。検索では、条件に一致するすべてのユーザーが返されます。
-
また、 View all users をクリックすると、システム内の全ユーザーを一覧表示することもできます。
このアクションは、ローカルKeycloakのデータベースのみを検索し、LDAPなどの連携データベースは検索しません。連携データベースのバックエンドには、ユーザーを検索するためのページネーション機構がありません。 -
連携バックエンドからユーザーを検索するには、ユーザーリストをKeycloakのデータベースに同期させる必要があります。検索条件を調整して、バックエンドのユーザーをKeycloakのデータベースに同期させます。
-
または、左メニューの User Federation をクリックします。
-
選択したユーザーに変更を適用するには、フェデレーション・プロバイダーと のページで Sync changed users をクリックします。
-
データベース内のすべてのユーザーに変更を適用するには、フェデレーション・プロバイダーのページで Sync all users をクリックします。
-
-
-
ユーザー・フェデレーションについては、ユーザー・フェデレーションを参照してください。
ユーザーの作成
ユーザーは、そのユーザーが必要とするアプリケーションを持つ予定のレルムに作成します。他のレルムを作成するためだけのmasterレルムにユーザーを作成することは避けてください。
-
masterレルム以外のレルムを選択します。
-
メニューの Users をクリックします。
-
Add User をクリックします。
-
新しいユーザーの詳細を入力します。
Username は唯一の必須項目です。 -
Save をクリックします。詳細を保存すると、新しいユーザーの Management ページが表示されます。
ユーザーの削除
アプリケーションへのアクセスが不要になったユーザーを削除することができます。ユーザーを削除すると、ユーザー・プロフィールやデータも削除されます。
-
メニューの Users をクリックします。 Users ページが表示されます。
-
View all users をクリックして、削除するユーザーを探します。
または、検索バーを使ってユーザーを探すこともできます。 -
削除したいユーザーの横にある Delete をクリックし、削除を確認します。
ユーザーによるアカウント削除の有効化
管理コンソールでこの機能を有効にすると、エンドユーザーやアプリケーションはアカウント・コンソールでアカウントを削除することができます。この機能を有効にすると、その機能を特定のユーザーに与えることができます。
アカウント削除機能の有効化
この機能を有効にするには、 Required Actions タブで設定します。
-
メニューの Authentication をクリックします。
-
Required Actions タブをクリックします。
-
Delete Account の行で Enabled を選択します。
必須アクションタブでのアカウント削除
ユーザー属性の設定
ユーザー属性は、各ユーザーにカスタマイズされた体験を提供します。ユーザー属性を設定することで、コンソールで各ユーザーにパーソナライズされたアイデンティティーを作成することができます。
-
ユーザーが存在するレルムにいます。
-
メニューの Users をクリックします。
-
管理するユーザーを選択します。
-
Attributes タブをクリックします。
-
Key フィールドに属性名を入力します。
-
Value フィールドに属性値を入力します。
-
Add をクリックします。
-
Save をクリックします。
読み取り専用の属性の中には、管理者が更新してはいけないものがあります。これには、たとえば、 LDAP_ID のように、LDAPプロバイダーが自動的に入力するような、設計上読み取り専用になっている属性が含まれます。他のいくつかの属性は、セキュリティー上の理由から、典型的なユーザー管理者のために読み取り専用にする必要があります。詳細は セキュリティー上の脅威の軽減 の章を参照してください。
|
ユーザー・クレデンシャル
ユーザーのクレデンシャルは、 Credentials タブで管理できます。
このタブには以下のフィールドがあります。
- Position
-
Position 列の矢印ボタンで、ユーザーに対するクレデンシャルの優先順位を変更することができます。一番上のクレデンシャルが最も高い優先度になります。この優先順位によって、ユーザーがログインした後にどのクレデンシャルが最初に表示されるかが決まります。
- Type
-
この欄には、"password"や"OTP"など、クレデンシャルの種類が表示されます。
- User Label
-
これは、ログイン時の選択オプションとして提示されたときにクレデンシャルを認識するための割り当てることができるラベルです。クレデンシャルを説明するために任意の値を設定することができます。
- Data
-
これは、クレデンシャルに関する非機密の技術情報です。デフォルトでは非表示になっています。 Show data… をクリックすると、クレデンシャルのデータを表示することができます。
- Actions
-
この列には2つのアクションがあります。 Save をクリックすると、ユーザー・フィールドの値が記録されます。クレデンシャルを削除するには、 Delete をクリックします。
特定のユーザーに対して、他のタイプのクレデンシャルを管理コンソールで設定することはできません。
ユーザーがOTPデバイスを紛失した場合や、クレデンシャルが漏洩した場合に、ユーザーのクレデンシャルを削除することができます。ユーザーのクレデンシャルの削除は、 Credentials タブでのみ可能です。
ユーザーのパスワードの設定
ユーザーがパスワードを持っていない場合、またはパスワードを削除した場合は、 Set Password のセクションが表示されます。
すでにパスワードが設定されている場合は、 Reset Password の項目で再設定することができます。
-
メニューの Users をクリックします。 Users ページが表示されます。
-
ユーザーを選択します。
-
認証情報」タブをクリックします。
-
Set Password のセクションに新しいパスワードを入力します。
-
Set Password をクリックします。
Temporary が ON の場合、ユーザーは初回ログイン時にパスワードを変更する必要があります。ユーザーがパスワードを保持できるようにするには、 Temporary を OFF に設定し、ユーザーが Set Password をクリックしてパスワードを変更する必要があります。 -
または、ユーザーにパスワードの再設定を依頼する電子メールを送信することもできます。
-
Credential Reset の下にある Reset Actions リストに移動します。
-
リストから Update Password を選択します。
-
Send Email をクリックします。送信された電子メールには、ユーザーを Update Password ウィンドウに誘導するリンクが含まれています。
-
オプションで、メールリンクの有効期限を設定することができます。これは、 Realm Settings の Tokens タブにあるデフォルトのプリセットに設定されています。
-
OTPの作成
OTPが条件付きである場合、ユーザーはKeycloakに移動する必要があります。アカウントコンソールで新しいOTPジェネレーターを再設定してください。OTPが必要な場合、ユーザーはログイン時に新しいOTPジェネレーターを再設定する必要があります。
または、ユーザーにOTPジェネレーターのリセットを要求するメールを送信することもできます。次の手順は、ユーザーがすでに OTP クレデンシャルを持っている場合にも適用されます。
-
適切なレルムにログインしている。
-
メインメニューの Users をクリックします。 Users ページが表示されます。
-
ユーザーを選択します。
-
認証情報」タブをクリックします。
-
Reset Actions のリストに移動します。
-
OTPを設定する]をクリックします。
-
Send Email をクリックします。送信されたメールには、ユーザーを OTP設定ページ に誘導するリンクが含まれています。
必須アクション
初回ログイン時にユーザーが実行しなければならないアクションを設定することができます。これらのアクションは、ユーザーがクレデンシャルを提供した後に必要となります。最初のログイン後、これらのアクションは必要なくなります。必須アクションは、そのユーザーの Details タブで追加します。
以下は、必須アクションの種類の例です。
- Update Password
-
ユーザーはパスワードを変更する必要があります。
- Configure OTP
-
ユーザーはFree OTPまたはGoogleオーセンティケーター・アプリケーションを使用して、モバイルデバイスにワンタイム・パスワード・ジェネレーターを設定する必要があります。
- Verify Email
-
ユーザーは、自分のEメールアカウントを確認する必要があります。検証用リンクが記載された電子メールがユーザーに送信されますので、クリックしてください。このワークフローが正常に完了すると、ユーザーはログインできるようになります。
- Update Profile
-
ユーザーは、名前、住所、電子メール、電話番号などのプロフィール情報を更新する必要があります。
一人のユーザーに対する必須アクションの設定
どのユーザーに対しても必須アクションを設定できます。
-
メニューの Users をクリックします。
-
一覧からユーザーを選択します。
-
Required User Actions の一覧に移動します。
-
アカウントに追加したいアクションをすべて選択します。
-
アクション名の横にある X をクリックすると、削除されます。
-
追加するアクションを選択したら、 Save をクリックします。
全ユーザーへの必須アクションの設定
すべての新規ユーザーの初回ログイン前に必要なアクションを指定することができます。この条件は、 Users ページの Add User ボタン、またはログインページの Register リンクで作成されたユーザーに適用されます。
-
メニューの Authentication をクリックします。
-
Required Actions タブをクリックします。
-
1つ以上の必須アクションの Default Action 列のチェックボックスをクリックします。新規ユーザーの初回ログイン時には、選択したアクションを実行する必要があります。
必須アクションとしての利用規約の有効化
新規ユーザーがKeycloakに初めてログインする前に、利用規約に同意しなければならないという必須アクションを有効にすることができます。
-
メニューの Authentication をクリックします。
-
Required Actions タブをクリックします。
-
Terms and Conditions のアクションを有効にします。
-
ベースとなるログインテーマ内の
terms.ftl
ファイルを編集します。
-
テーマの拡張と作成の詳細については、 Server Developer Guide を参照してください。
ユーザーの成り代わり
適切なパーミッションを持つ管理者は、ユーザーに成りすますことができます。たとえば、あるユーザーがアプリケーションのバグに遭遇した場合、管理者はそのユーザーに成りすまして問題を調査したり、再現したりすることができます。
レルム内で impersonation
ロールを持つすべてのユーザーが、あるユーザーになりすますことができます。
-
管理者とユーザーが同じレルムにいる場合は、管理者がログアウトし、成りすましをされるユーザーとして自動的にログインします。
-
管理者とユーザーが異なるレルムにいる場合、管理者はログインしたままで、さらにそのユーザーのレルムのユーザーとしてログインします。
いずれの場合も、なりすましたユーザーの User Account Management ページが表示されます。
Impersonate ボタンは、 Users ページの Details タブからアクセスできます。
-
管理パーミッションの割り当てについては、管理コンソールのアクセス制御の章を参照してください。
ユーザー登録
Keycloak をサードパーティー認可サーバーとして使用して、自己登録したユーザーを含むアプリケーションのユーザーを管理することができます。自己登録を有効にすると、ログインページに登録リンクが表示され、ユーザーがアカウントを作成できるようになります。
ユーザーが登録を完了するには、登録フォームにプロファイルル情報を追加する必要があります。登録フォームは、ユーザーが入力しなければならないフィールドを削除または追加することでカスタマイズできます。
-
ユーザー登録のカスタマイズについては、 Server Developer Guide を参照してください。
reCAPTCHAの有効化
ボットからの登録を保護するために、KeycloakはGoogle reCAPTCHA と統合しています。
reCAPTCHAを有効にすると、ログインテーマ内の register.ftl
を編集して、登録ページでのreCAPTCHAボタンの配置とスタイルを設定することができます。
-
ブラウザーで次のURLを入力します。
https://developers.google.com/recaptcha/
-
APIキーを作成し、reCAPTCHAサイトのキーとシークレットを取得します。この手順で使用するため、reCAPTCHAサイトのキーとシークレットをメモしておいてください。
localhostはデフォルトで動作します。ドメインは指定する必要はありません。 -
Keycloakの管理コンソールに移動します。
-
メニューの Authentication をクリックします。
-
Flows タブをクリックします。
-
ドロップダウンメニューから Registration を選択します。
-
reCAPTCHA の要件を Required に設定します。これにより、reCAPTCHAが有効になります。
-
reCAPTCHAフローの項目の右側にある Actions をクリックします。
-
Config のリンクをクリックします。
Recaptchaの設定ページ-
Google reCAPTCHAのウェブサイトから生成された Recaptcha Site Key を入力してください。
-
Google reCAPTCHAのウェブサイトから生成された Recaptcha Secret を入力してください。
-
-
Googleが登録ページをiframeとして使用することを認可します。
Keycloakでは、Webサイトがiframe内にログインページのダイアログを含めることができません。この制限は、クリックジャッキング攻撃を防止するためのものです。Keycloakで設定されているデフォルトのHTTPレスポンス・ヘッダーを変更する必要があります。 -
メニューの Realm Settings をクリックします。
-
Security Defenses タブをクリックします。
-
X-Frame-Options ヘッダーのフィールドに
https://www.google.com
と入力します。 -
Content-Security-Policy ヘッダーのフィールドに
https://www.google.com
と入力します。
-
-
テーマの拡張と作成の詳細については、 Server Developer Guide を参照してください。
Keycloakによって収集された個人データ
デフォルトでは、Keycloakは次のデータを収集します。
-
ユーザーの電子メール、姓、名前などの基本的なユーザー・プロフィール・データ
-
ソーシャル・ログインに使用するときにソーシャル・アカウントとソーシャル・アカウントへの参照に使用される基本的なユーザー・プロフィール・データ
-
IPアドレス、オペレーティング・システム名、ブラウザー名など、監査とセキュリティーの目的で収集されたデバイス情報
Keycloakで収集された情報は高度にカスタマイズできます。カスタマイズを行う場合は、次のガイドラインが適用されます。
-
登録およびアカウント・フォームには、誕生日、性別、国籍などのカスタム・フィールドを含めることができます。管理者は、Keycloakを設定して、ソーシャル・プロバイダーまたはLDAPなどのユーザー・ストレージ・プロバイダーからそのデータを取得できます。
-
Keycloakは、パスワード、OTPコード、WebAuthn公開鍵などのユーザー・クレデンシャルを収集します。この情報は暗号化されてデータベースに保存されるため、Keycloak管理者には表示されません。クレデンシャルの各タイプには、パスワードのハッシュに使用されるアルゴリズムやパスワードのハッシュに使用されるハッシュ反復回数など、管理者に表示される非機密メタデータを含めることができます。
-
認可サービスとUMAサポートを有効にすると、Keycloakは、特定のユーザーがオーナーであるいくつかのオブジェクトに関する情報を保持することができます。
ユーザー・プロフィール
Keycloakでは、ユーザーは一連の属性と関連付けられています。これらの属性は、Keycloak内のユーザーをより適切に説明、識別するため、また、アプリケーションにユーザーに関する追加情報を渡すために使用されます。
ユーザー・プロフィールは、ユーザー属性を表現するための明確なスキーマを定義し、それらがレルム内でどのように管理されるかを定義するものです。ユーザー情報を一貫して表示することで、管理者は属性の管理方法を様々な角度から制御することができます。また、Keycloakを拡張して追加の属性をサポートすることも容易になります。
他の機能の中でも、ユーザー・プロフィールを使用すると、管理者は次のことができます。
-
ユーザー属性のスキーマを定義します
-
コンテキスト情報に基づいて、属性が必要かどうかを定義します(例:ユーザーだけ必要か、管理者だけか、両方か、要求されるスコープに依存するか。)
-
第三者(管理者を含む)がユーザー属性を参照・変更できないような強いプライバシー要件に対応することができるように、ユーザー属性の参照・編集用のパーミッションを定義します
-
ユーザー情報が常に更新され、属性に関連するメタデータやルールに準拠するように、ユーザー・プロフィールのコンプライアンスを動的に強化します
-
組み込みのバリデーターを活用したり、カスタムのバリデーターを作成することで、属性ごとに検証ルールを定義します
-
アカウント・コンソールの登録、プロフィールの更新、ブローカリング、個人情報など、ユーザーが操作するフォームを、属性定義に従って動的にレンダリングし、テーマを手動で変更する必要がありません。
ユーザー・プロフィールの機能は、ユーザー・プロフィールSPIによってバックアップされています。デフォルトでは、これらの機能は無効化されており、レルムはレガシー動作との後方互換性を保つためにデフォルトの構成を使用するように設定されています。
レガシーな動作は、ユーザー名、電子メール、姓名などのユーザーのルート属性を管理する際にKeycloakで使用されるデフォルトの制約を維持することであり、カスタム属性を管理する方法については何の制約もありません。登録、プロフィール更新、ブローカリング、アカウント・コンソールによるアカウント管理などのユーザーフローについては、ユーザーは前述の属性を使用するように制限され、テーマ・テンプレートを変更して追加の属性をサポートすることが可能です。 すでにKeycloakを使用している場合は、これまで使用していたレガシーな動作となります。 |
レガシーな動作とは異なり、Declarativeプロバイダーでは、管理コンソールと明確に定義されたJSONスキーマを通じて、レルムに対するユーザー・プロフィールの構成をより柔軟に定義することができます。
次のセクションでは、Declarativeプロバイダを使用して独自のユーザー・プロフィール構成を定義する方法について見ていきます。
将来的には、Keycloakではレガシーな動作はサポートされなくなります。理想的には、ユーザー・プロフィールによって提供される新しい機能に目を向け始め、それに従ってレルムを移行すべきです。 |
ユーザー・プロフィールを有効にする
Declarative User Profileは、 テクノロジー・プレビュー であり、完全にはサポートされていません。この機能はデフォルトで無効になっています。 有効にするには、 |
declarative_user_profile
機能を有効にすることに加えて、レルムに対してユーザー・プロフィールを有効にする必要があります。これを行うには、左サイドメニューの Realm Settings
リンクをクリックし、 User Profile Enabled
スイッチをオンにします。
この機能を有効にし、 Save
ボタンをクリックすると、 User Profile
タブにアクセスすることができ、ここからユーザー属性の設定を管理できるようになります。
レルムのユーザー・プロフィールを有効にすることで、Keycloakはユーザー・プロフィールの構成に基づいて、属性を管理する方法について追加の制約を課そうとします。まとめると、この機能が有効になった際に期待されることは以下の通りです。
-
管理者視点では、ユーザー詳細ページの
Attributes
タブには、ユーザー・プロフィールの構成で定義された属性のみが表示されます。また、属性ごとに定義された条件も、属性を管理する際に考慮されます。 -
登録、プロフィールの更新、ブローカリング、アカウント・コンソールの個人情報などのユーザー向けフォームは、ユーザー・プロフィールの構成に基づいて動的にレンダリングされる予定です。そのため、Keycloak はこれらのフォームを動的にレンダリングするために、異なるテンプレートに依存する予定です。
次のトピックでは、ユーザー・プロフィールの構成を管理する方法と、それがレルムにどのような影響を与えるかを探ります。
ユーザー・プロフィールの管理
ユーザー・プロフィールの設定は、レルム単位で管理されます。そのためには、左サイドメニューの Realm Settings
リンクをクリックし、User Profile
タブをクリックします。
Attributes
サブタブには、ユーザー・プロフィールに現在関連付けられている属性のリストが表示されます。デフォルトでは、ユーザーのルート属性に基づいて作成され、各属性はバリデーションとパーミッションの観点からいくつかのデフォルト設定がされています。
Attribute Groups
のサブタブでは、属性グループを管理することができます。属性グループは、ユーザー向けフォームをレンダリングする際に、属性を関連付けて表示することができます。
今のところ、属性グループはレンダリングの目的にのみ使用されていますが、将来的には、リンク先の属性にトップレベルの設定を定義することも可能になる予定です。 |
JSON Editor
サブタブでは、明確に定義されたJSONスキーマを使用して設定を表示および編集することができます。他のタブで行った変更は、このタブで表示されるJSON設定に反映されます。
次のセクションでは、 Attributes
サブタブで設定を管理する方法を学びます。
属性の管理
Attributes
サブタブでは、ユーザー・プロフィールに関連する属性の作成、編集、削除を行うことができます。
新しい属性を定義してユーザー・プロフィールと関連付けるには、属性一覧の右上にある Create
ボタンをクリックします。
属性を設定する際に、以下の設定を定義することができます。
- 名前
-
属性の名前です。
- Display name
-
主にユーザー向けのフォームをレンダリングする際に使用される、属性のユーザー・フレンドリーな名前です。国際化をサポートしており、メッセージ・バンドルから値を読み込むことができます。
- Attribute Group
-
属性が属する属性グループがある場合、そのグループを設定します。
- Enabled when scope
-
属性を動的に有効にするためのスコープのリストを定義できるようにします。設定されていない場合、属性は常に有効であり、ユーザー・プロフィールの管理およびユーザー向けフォームのレンダリング時にその制約が常に適用されます。そうでない場合は、リスト内のスコープのいずれかがクライアントから要求されたときにのみ、同じ制約が適用されます。
- Required
-
属性を必須として設定します。有効ではない場合、その属性はオプションです。それ以外の場合、属性はユーザーと管理者によって提供されなければなりません。また、クライアントが要求するスコープに基づいて、ユーザーまたは管理者のみに属性を必須とすることも可能です。
- Permission
-
このセクションでは、ユーザーと管理者の参照と書き込みのパーミッションを定義することができます。
- Validation
-
このセクションでは、属性値を管理する際に実行されるバリデーションを定義することができます。Keycloakは組み込みのバリデータのセットを提供し、そこから選んで独自のバリデータを追加することができます。
- Annotation
-
このセクションでは、属性にアノテーションを関連付けることができます。アノテーションは主に、レンダリング目的でフロントエンドに追加のメタデータを渡すのに便利です。
パーミッションの管理
Permission
セクションでは、ユーザーと管理者が属性に対して読み書きできるアクセスレベルを定義することができます。
そのために、以下のような設定を行います。
- Can user view?
-
有効にすると、ユーザーはその属性を参照することができます。そうでなければ、ユーザーはその属性にアクセスできません。
- Can user edit?
-
有効にすると、ユーザーはその属性を表示および編集することができます。そうでない場合、ユーザーはその属性に書き込むアクセス権を持ちません。
- Can admin view?
-
有効にすると、管理者はその属性を参照することができます。そうでなければ、管理者はその属性にアクセスできません。
- Can admin edit?
-
有効にすると、管理者はその属性を表示および編集することができます。そうでない場合、管理者はその属性に書き込むアクセス権を持ちません。
属性を作成すると、その属性には何のパーミッションも設定されません。事実上、ユーザーも管理者もその属性にアクセスすることはできません。属性を作成したら、その属性が対象者のみに表示されるように、適宜パーミッションを設定するようにしてください。 |
パーミッションは、属性の管理方法と管理者、およびユーザー向けフォームでの属性の表示方法に直接的な影響を及ぼします。
たとえば、ある属性をユーザーしか参照できないように設定すると、管理者は管理コンソールからユーザーを管理する際に、その属性にアクセスできなくなります(User APIからもアクセスできなくなります)。また、ユーザーは自分のプロフィールを更新する際に、その属性を変更することができなくなります。ユーザー属性が既存のアイデンティティー・ストア(フェデレーション)から取得され、ソース・アイデンティティー・ストアを介する以外に属性を更新する可能性がなく、ユーザーに属性を単に表示したい場合、興味深い構成となります。
同様に、ある属性を管理者のみ書き込み可能で、ユーザーは読み取り専用にすることもできます。この場合、管理者だけがその属性を管理できるようになります。
プライバシーに関する要件によっては、管理者はアクセスできないが、ユーザーには読み書き権限がある属性が必要な場合もあります。
ユーザー・プロフィールの設定に新しい属性を追加する場合は、必ず正しいパーミッションを設定してください。
バリデーションの管理
Validation
セクションでは、属性値が特定のルールに適合していることを確認するために、さまざまな形式のバリデーションを選択することができます。
Keycloakはすぐに利用できる異なるバリデーターを提供します。
名前 | 説明 | 設定 |
---|---|---|
length |
文字列値の長さを最小値と最大値で確認します。 |
min :許容される最小の長さを定義する整数です。 max :許容される最大の長さを指定する整数です。 trim-disabled :バリデーション前に値をトリミングするかどうかを定義するBoolean値です。 |
integer |
値が整数であり、下限および/または上限の範囲内にあるかどうかを確認します。範囲が定義されていない場合は、値が有効な数値であるかどうかだけをチェックします。 |
min :下限の範囲を指定する整数です。 max :上限の範囲を指定する整数です。 |
double |
値がdoubleであり、下限および/または上限の範囲内であるかどうかを確認します。範囲を指定しなかった場合、バリデータは値が有効な数値であるかどうかだけをチェックします。 |
min :下限の範囲を指定する整数です。 max :上限の範囲を指定する整数です。 |
uri |
値が有効なURIであるかどうかを確認します。 |
なし |
pattern |
値が特定の正規表現パターンにマッチするかどうかを確認します。 |
pattern :値を検証する際に使用する正規表現パターン。 error-message :国際化バンドルでのエラーメッセージのキーを設定します。設定されていない場合、汎用メッセージが使用されます。 |
値が有効な電子メール形式であるかどうかを確認します。 |
なし |
|
local-date |
値がレルムおよび/あるいはユーザーのロケールに基づいた有効な形式であるかどうかを確認します。 |
なし |
person-name-prohibited-characters |
スクリプト・インジェクションなどの攻撃に対する追加の防壁として、値が有効な人名であるかどうかをチェックします。この検証は、人名に一般的でない文字をブロックするデフォルトの正規表現パターンに基づいています。 |
error-message :国際化バンドルでのエラーメッセージのキーを設定します。設定されていない場合、汎用メッセージが使用されます。 |
username-prohibited-characters |
スクリプト・インジェクションなどの攻撃に対する追加の防壁として、値が有効なユーザー名であるかどうかをチェックします。この検証は、ユーザー名に一般的でない文字をブロックするデフォルトの正規表現パターンに基づいています。 |
error-message :国際化バンドルでのエラーメッセージのキーを設定します。設定されていない場合、汎用メッセージが使用されます。 |
オプション |
値が定義された許容値のセットから外れていないかどうかをチェックします。セレクト・フィールドやマルチセレクト・フィールドで入力された値を検証するのに便利です。 |
options: 許可された値を含む文字列の配列。 |
アノテーションの管理
フロントエンドに追加情報を渡すために、属性にアノテーションを付与し、属性のレンダリング方法を指定することができます。この機能は主にKeycloakのテーマを拡張して、属性に関連付けられたアノテーションに基づいてページを動的にレンダリングする際に役立ちます。この仕組みは、たとえば 属性のForm入力フィールドを設定する に使われています。
属性グループの管理
Attribute Groups
サブタブでは、属性グループの作成、編集、削除を行うことができます。属性グループは、関連する属性のコンテナーを定義することができ、ユーザー向けフォームに表示される際に一緒に表示されます。
属性にバインドされている属性グループを削除することはできません。そのためには、まず属性を更新してバインディングを削除する必要があります。 |
新しいグループを作成するには、属性グループ一覧の右上にある Create
ボタンをクリックします。
グループを構成する際に、以下の設定を定義することができます。
- 名前
-
グループ名です。
- Display name
-
主にユーザー向けのフォームをレンダリングする際に使用される、グループのユーザー・フレンドリーな名前です。国際化をサポートしており、メッセージ・バンドルから値を読み込むことができます。
- Display description
-
ユーザー向けフォームをレンダリングする際に、ツールチップとして表示されるユーザー・フレンドリーなテキストです。
- Annotation
-
このセクションでは、属性にアノテーションを関連付けることができます。アノテーションは主に、レンダリング目的でフロントエンドに追加のメタデータを渡すのに便利です。
JSON設定の使用
ユーザー・プロフィールの設定は、明確に定義されたJSONスキーマを使用して保存されます。 JSON Editor
サブタブをクリックすることで、ユーザー・プロフィールの設定を直接編集することができます。
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
と、オプションで required
、 permission
、 annotations
の設定を定義する必要があります。
必須プロパティー
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"]
}
]
}
view
と edit
の両プロパティーは、その値が user
または admin
である配列を期待します。これは、その属性がユーザーまたは管理者のどちらによって参照または編集可能であるかによります。
edit
パーミッションが付与されると、view
パーミッションも暗黙のうちに付与されます。
動的フォームの使用
ユーザー・プロフィールの主な機能の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つのページテンプレートすべてから使用されます。新しい入力タイプをここに実装することができます。 |
デフォルトのレンダリング機構は、以下の機能を提供します。
-
属性に設定されたパーミッションに基づき、フィールドを動的に表示します。
-
属性に設定された制約に基づき、必須フィールドのマーカーを動的にレンダリングします。
-
属性に設定されたフィールド入力タイプ(テキスト、日付、数字、セレクト、マルチセレクト)を動的にレンダリングします。
-
属性に設定されたパーミッションに応じて、読み取り専用のフィールドを動的にレンダリングします。
-
属性に設定された順序に応じて、フィールドを動的に順序付けします。
-
同じ属性グループに属するフィールドを動的にグループ化することができます。
属性のグループ化
動的なフォームがレンダリングされる際、同じ属性グループに属する属性をグループ化しようとします。
属性が属性グループにリンクされている場合、同じグループ内の属性が同じグループヘッダー内で近接していることを確認するために、属性の順序も重要です。そうしないと、グループ内の属性に順序がない場合、同じグループヘッダーがダイナミックフォームに複数回レンダリングされる可能性があります。 |
属性のためのフォーム入力ファイルの設定
Keycloakは、動的なフォームで属性に使用される入力タイプを設定するためのアノテーションを内蔵しており、属性の視覚化の他の側面を提供しています。
利用可能なアノテーションは以下です。
名前 | 説明 |
---|---|
inputType |
フォームの入力フィールドのタイプ。利用可能なタイプを以下の表に示します。 |
inputHelperTextBefore |
入力フィールドの前(上)に表示されるヘルパーテキストです。ここでは直接テキストや国際化パターン( |
inputHelperTextAfter |
入力フィールドの後(下)に表示されるヘルパーテキストです。ここでは直接テキストや国際化パターン( |
inputOptionsFromValidation |
selectおよびmultiselectタイプのためのアノテーション。入力オプションを取得するカスタム属性検証の名前(オプション)。以下の 詳細な説明 を参照してください。 |
inputOptionLabelsI18nPrefix |
selectおよびmultiselectタイプのアノテーション。UIでオプションを表示するための国際化キーのプレフィックス。以下の detailed description を参照してください。 |
inputOptionLabels |
selectおよびmultiselectタイプのためのアノテーション。オプションマップで、オプションのUIラベルを定義します(直接または国際化を使用して)。以下の 詳細な説明 を参照してください。 |
inputTypePlaceholder |
HTMLの入力 |
inputTypeSize |
フィールドに適用されるHTMLのinputの |
inputTypeCols |
フィールドに適用されるHTMLのinputの |
inputTypeRows |
HTMLのinputの |
inputTypePattern |
HTMLのinputの |
inputTypeMaxLength |
HTMLのinputの |
inputTypeMinLength |
HTMLのinputの |
inputTypeMax |
HTMLのinputの |
inputTypeMin |
HTMLのinputの |
inputTypeStep |
HTMLのinputの |
フィールドタイプは、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仕様に基づく数値( |
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に適さないIDのような場合、 inputOptionLabelsI18nPrefix
アノテーションが提供する簡単な国際化サポートを使用することができます。これは国際化キーのプレフィックスを定義し、オプションの値はこのプレフィックスにドットで追加されます。
オプション値のためのローカライズされたUIラベルテキストは、共通のローカライゼーション機構を使用して、 userprofile.jobtitle.sweng
と userprofile.jobtitle.swarch
キーで提供されなければなりません。
また、inputOptionLabels
アノテーションを使用して、個々のオプションのラベルを提供することができます。マップのキーはオプションの値 (バリデーションで定義) で、マップの値はそのオプションのUIラベルテキストそのもの、またはその国際化パターン ( ${i18n.key}
のような) です。
ユーザー・プロフィールの |
国際化を行わず、個々のオプションにラベルを直接入力した例。
"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.swengineer
と jobtitle.swarchitect
のキーで提供される必要があります。
カスタム・バリデーターは inputOptionsFromValidation
属性アノテーションのおかげで、オプションを提供するために使用することができます。このバリデーションでは、オプションの配列を提供する options
の設定が必要です。国際化は、組み込みの options
のバリデーションで提供されるオプションと同じように動作します。
ユーザー・プロフィールの強制遵守
ユーザーのプロフィールが設定に準拠していることを確認するために、管理者は VerifyProfile
必須アクションを使用して、最終的にKeycloakで認証する際にユーザーのプロフィールを強制的に更新させることができます。
|
VerifyProfile
アクションを有効にすると、ユーザー認証の際に次のような処理を行います。
-
ユーザー・プロフィールがレルムに設定されたユーザー・プロフィールの構成に完全に準拠しているかどうかを確認します。
-
そうでない場合は、認証時に追加のステップを実行し、ユーザーが不足または無効な属性を更新できるようにします。
-
ユーザー・プロフィールが設定に適合している場合、追加のステップは実行されず、ユーザーは認証プロセスを続行します。
デフォルトでは、 VerifyProfile
アクションは無効になっています。有効にするには、左サイドメニューの Authentication
リンクをクリックし、Required Actions
タブをクリックします。このタブで Register
ボタンをクリックし、 VerifyProfile
アクションを選択します。
ユーザー・プロフィールへの移行
レルムに対してユーザー・プロフィール機能を有効にする前に、注意すべき重要な点がいくつかあります。属性メタデータを管理するための単一の場所を提供することで、この機能はユーザーに設定できる属性とその管理方法について非常に厳格なものとなっています。
ユーザー管理に関しては、管理者はユーザー・プロフィールの構成で定義された属性のみを管理することができます。ユーザーに設定された他の属性で、まだユーザー・プロフィール構成で定義されていないものは、アクセスできません。ユーザーまたは管理者のいずれかに公開したい、すべてのユーザー属性を定義したユーザー・プロフィール構成に更新することをお勧めします。
ユーザー情報を照会するためにUser REST APIにアクセスする場合にも、同様の推奨事項が適用されます。
LDAP_ID
、 LDAP_ENTRY_DN
、 KERBEROS_PRINCIPAL
などのKeycloak内部ユーザー属性に関して、これらの属性にアクセスしたい場合は、ユーザー・プロフィール構成に属性として設定する必要があります。推奨は、これらの属性を管理者のみ参照可能とし、管理コンソールでユーザー属性を管理する際や、User APIでユーザーを照会する際に参照できるようにすることです。
テーマに関して、従来のテンプレート(ユーザーのルート属性でハードコードされたもの)をカスタマイズしている場合、ユーザー向けのフォームをレンダリングする際に、そのカスタム・テンプレートは使われず、これらのフォームを動的にレンダリングする新しいテンプレートが使用されます。理想的には、テンプレートのカスタマイズを避け、新しいテンプレートが提供する動的にフォームをレンダリングする動作を維持するようにします。それでも不十分な場合は、テンプレートをカスタマイズするか、新しいテンプレートを強化するかどうかを検討しますので、ご意見をお聞かせください。
ユーザー・セッションの管理
ユーザーがレルムにログインすると、Keycloakは各ユーザーのユーザー・セッションを維持し、セッション内でユーザーがアクセスした各クライアントを記憶します。レルム管理者は、各ユーザー・セッションに対して以下のような複数のアクションを実行することができます。
-
レルムのログイン統計情報を表示する。
-
アクティブなユーザーとログインした場所を表示する。
-
ユーザーをセッションからログアウトさせる。
-
トークンを失効させる。
-
トークンのタイムアウトを設定する。
-
セッションのタイムアウトを設定する。
セッションの管理
Keycloakでアクティブなクライアントとセッションのトップレベルのビューを表示するには、メニューから Sessions をクリックします。
Logout all の操作
Logout all ボタンをクリックすると、レルム内のすべてのユーザーをログアウトすることができます。
Logout all ボタンをクリックすると、すべてのSSOクッキーが無効になり、アクティブなブラウザー・セッション内で認証を要求しているクライアントは再度ログインする必要があります。Keycloakは、OIDCクライアント・アダプターを使用して、ログアウト・イベントをクライアントに通知します。SAMLなどのクライアント・タイプは、バックチャネルのログアウト・リクエストを受信しません。
Logout all をクリックしても、未使用のアクセストークンは無効化されません。未使用のトークンは自然に失効する必要があります。OIDCクライアント・アダプターを使用しているクライアントの場合、無効化ポリシーをプッシュしてトークンを無効化させることができますが、他のアダプターの場合はうまくいきません。 |
失効ポリシー
システムが侵害された場合、 Sessions
画面の Revocation タブをクリックすることで、すべてのアクティブなセッションとアクセストークンを取り消すことができます。
このコンソールを使って、その日時以前に発行されたセッションやトークンが無効になる日時を指定することができます。 Set to now をクリックすると、ポリシーが現在の日時に設定されます。 Push をクリックすると、Keycloak OIDCクライアント・アダプターで登録されたOIDCクライアントにこの失効ポリシーがプッシュされます。
セッションとトークンのタイムアウト
Keycloakには、 Realm Settings メニューの Tokens タブによる、セッション、Cookie、トークンのタイムアウトの制御が含まれています。
設定 | 説明 |
---|---|
デフォルトの署名アルゴリズム |
レルムにトークンを割り当てるために使用するデフォルトのアルゴリズム。 |
Revoke Refresh Token |
ON の場合、Keycloakはリフレッシュトークンを取り消し、クライアントが使用しなければならない別のトークンを発行します。このアクションは、リフレッシュトークン・フローを実行するOIDCクライアントに適用されます。 |
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の設定と同じセッション寿命が使用されます。 |
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が対応するオフライントークンを取り消すまでの最大時間です。このオプションは、ユーザーの活動に関係なく、オフライントークンが有効であり続ける最大時間を制御します。 |
Offline Session Idle |
この設定はオフライン・アクセスのためのものです。ユーザーがこのタイムアウトより長く非アクティブの場合、オフライントークン・リクエストはアイドル・タイムアウトになります。この設定は、オフライントークンのアイドル・タイムアウトをオフライン・セッションのアイドルよりも短くするものです。ユーザーは、個々のクライアントに対してこの設定をオーバーライドできます。この設定はオプションで、0に設定すると、オフライン・セッション・アイドルの設定と同じアイドル・タイムアウトが使用されます。 |
Offline Session Idle |
この設定はオフライン・アクセスのためのものです。オフライントークンの有効期限が切れて無効になるまでの最大時間です。この設定は、オフラインセッション・タイムアウトよりも短いトークン・タイムアウトを指定しますが、ユーザーが個々のクライアントに対してオーバーライドすることができます。この設定はオプションで、0に設定すると、Offline Session Maxの設定と同じアイドル・タイムアウトが使用されます。 |
Client Session Idle |
ユーザーがこのタイムアウトより長く非アクティブの場合、リフレッシュトークン・リクエストはアイドル・タイムアウトになります。この設定では、リフレッシュトークンのアイドル・タイムアウトをセッション・アイドル・タイムアウトよりも短く指定しますが、ユーザーが個々のクライアントに対してオーバーライドすることができます。この設定はオプションで、0に設定すると、SSO Session Idleの設定と同じアイドル・タイムアウトが使用されます。 |
Client Session Max |
リフレッシュトークンが期限切れで無効になるまでの最大時間。この設定は、セッション・タイムアウトよりも短いリフレッシュトークンのタイムアウトを指定しますが、ユーザーが個々のクライアントに対してオーバーライドすることができます。この設定はオプションで、0に設定すると、SSO Session Maxの設定のアイドル・タイムアウトと同じものが使用されます。 |
Access Token Lifespan |
KeycloakがOIDCのアクセストークンを作成する際に、この値でトークンの有効期間を制御します。 |
Access Token Lifespan For Implicit Flow |
インプリシット・フローでは、Keycloakはリフレッシュトークンを提供しません。インプリシット・フローで作成されたアクセストークンには、別途タイムアウトが存在します。 |
Client login timeout |
クライアントがOIDCの認可コードフローを終了するまでの最大時間。 |
Login timeout |
ログインにかかる合計時間です。認証にこの時間以上かかる場合は、再度認証を開始する必要があります。 |
Login action timeout |
認証プロセスにおいて、ユーザーが1つのページに滞在できる最大時間。 |
User-Initiated Action Lifespan |
ユーザーのアクション・パーミッションが失効するまでの最大時間です。一般的に、ユーザーは自分で作成したアクションにすぐに反応するため、この値は短くしてください。 |
Default Admin-Initiated Action Lifespan |
管理者がユーザーに送信したアクション・パーミッションが期限切れになるまでの最大時間です。オフラインのユーザーに管理者がメールを送信できるように、この値は長くしてください。管理者はトークンを発行する前に、デフォルトのタイムアウトをオーバーライドすることができます。 |
Override User-Initiated Action Lifespan |
個々の操作ごとに独立したタイムアウトを指定します(たとえば、電子メール検証、パスワード忘れ、ユーザーアクション、アイデンティティー・プロバイダーの電子メール検証など)。この値のデフォルトは、 User-Initiated Action Lifespan で設定された値です。 |
アイドル・タイムアウトの場合、セッションがアクティブである2分間のウィンドウが存在します。たとえば、タイムアウトを30分に設定した場合、セッションが終了するのは32分後となります。 このアクションは、クラスターおよびクロス・データセンター環境において、あるクラスターノードで有効期限より少し前にトークンがリフレッシュされ、他のクラスターノードがリフレッシュノードからリフレッシュ成功のメッセージをまだ受け取っていないため、誤ってセッションを期限切れと見なす場合に必要です。 |
オフライン・アクセス
オフライン・アクセス ログイン時、クライアント・アプリケーションはリフレッシュトークンの代わりにオフライントークンを要求します。クライアント・アプリケーションはこのオフライントークンを保存し、ユーザーがログアウトした場合、次回以降のログインに使用できます。このアクションは、ユーザーがオンラインでないときでも、アプリケーションでユーザーに代わってオフライン・アクションを実行する必要がある場合に便利です。たとえば、定期的なデータのバックアップなどです。
クライアント・アプリケーションは、オフライントークンをストレージに永続化し、それを使用して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
プロパティーを false
に設定することで実現できます。
次の例は、遅延オフライン・セッション・ローディングを設定する方法を示しています。
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
...
<spi name="userSessions">
<default-provider>infinispan</default-provider>
<provider name="infinispan" enabled="true">
<properties>
<property name="preloadOfflineSessionsFromDatabase" value="false"/>
</properties>
</provider>
</spi>
...
</subsystem>
CLIコマンドを使用した同等の設定は以下になります。
/subsystem=keycloak-server/spi=userSessions:add(default-provider=infinispan)
/subsystem=keycloak-server/spi=userSessions/provider=infinispan:add(properties={preloadOfflineSessionsFromDatabase => "false"},enabled=true)
トランジェント・セッション
Keycloakでは、トランジェント・セッションを使用することができます。トランジェント・セッションを使用する場合、Keycloakは認証に成功した後にユーザー・セッションを作成しません。Keycloakは、ユーザー認証に成功した現在のリクエストのスコープに一時的なトランジェント・セッションを作成します。Keycloakは、認証後にトランジェント・セッションを使用してプロトコル・マッパーを実行することができます。
トランジェント・セッションの間、クライアント・アプリケーションはトークンのリフレッシュ、トークンのイントロスペクト、または特定のセッションの検証を行うことができません。これらのアクションが不要な場合もあるため、ユーザー・セッションを永続化することによるリソースの追加使用を避けることができます。このセッションは、パフォーマンス、メモリー、およびネットワーク通信(クラスターおよびクロス・データセンター環境)のリソースを節約します。
ロールやグループを使用したパーミッションやアクセスの割り当て
ロールとグループは、アプリケーションを使用するためのアクセスやパーミッションをユーザーに与えるという、似たような目的を持っています。グループは、ロールや属性を適用するユーザーの集合体です。ロールは、特定のアプリケーションのパーミッションとアクセス・コントロールを定義します。
ロールは通常、1種類のユーザーに適用されます。たとえば、ある組織では admin
、 user
、 manager
、 そして employee
というロールがあります。アプリケーションはロールにアクセスやパーミッションを割り当て、複数のユーザーをそのロールに割り当てて、ユーザーが同じアクセスやパーミッションを持てるようにすることができます。たとえば、管理コンソールには、管理コンソールのさまざまな部分にアクセスするためのパーミッションをユーザーに与えるロールがあります。
ロールのためのグローバルな名前空間があり、各クライアントもロールを定義できる専用の名前空間を持っています。
レルムロールの作成
レルムレベルのロールは、ロールを定義するための名前空間です。ロールの一覧を表示するには、メニューの Roles をクリックします。
-
Add Role をクリックします。
-
Role Name を入力します。
-
Description を入力します。
-
Save をクリックします。
description フィールドは、置換変数に $${var-name}}
という文字列を指定することでローカライズすることができます。ローカライズされた値は、テーマのプロパティー・ファイルの中で、あなたのテーマに設定されます。詳しくは Server Developer Guide を参照してください。
クライアントロール
クライアントロールは、クライアント専用の名前空間です。各クライアントは独自の名前空間を取得します。クライアントロールは、個々のクライアントの Roles タブで管理されます。レルムレベルのロールと同じ方法で、このUIとやりとりします。
ロールを複合ロールに変換する
レルムレベルまたはクライアントレベルのロールはすべて、 複合ロール にすることができます。複合ロールとは、1つ以上のロールを関連付けたロールのことです。複合ロールがユーザーにマップされると、そのユーザーは複合ロールに関連付けられたロールを継承します。この継承は再帰的であるため、ユーザーは複合ロールの複合ロールをも継承します。ただし、複合ロールは使いすぎないようにすることをお勧めします。
-
メニューの Roles をクリックします。
-
変換するロールをクリックします。
-
Composite Roles を ON にします。
ロールを選択するUIが表示され、作成中の複合ロールにレルムレベルとクライアントレベルのロールを関連付けることができます。
この例では、 employee レルムレベルロールは developer 複合ロールと関連付けられています。 developer ロールを持つユーザーは、 employee ロールも継承します。
トークンおよびSAMLアサーションを作成する場合、どの複合ロールでも、関連するロールがクライアントに返される認証レスポンスのクレームおよびアサーションに追加されます。 |
ロールマッピングの割り当て
ロールマッピングは、そのユーザーの Role Mappings タブで割り当てることができます。
-
メニューの Users をクリックします。
-
ロールマッピングを行いたいユーザーをクリックします。ユーザーが表示されていない場合は、 View all users をクリックします。
-
Role Mappings タブをクリックします。
-
Available Roles のボックスで、ユーザーに割り当てるロールをクリックします。
-
Add selected をクリックします。
この例では、あるユーザーに対して複合ロール developer を割り当てています。このロールは複合ロールのトピックで作成されました。
developer ロールが割り当てられると、 developer コンポジットに関連付けられた employee ロールが Effective Roles ボックスに表示されます。 Effective Roles とは、ユーザーに明示的に割り当てられたロールと、複合ロールから継承されたロールのことです。
デフォルトロールの使用
デフォルトロールを使用すると、アイデンティティー・ブローカリングでユーザーを作成またはインポートしたときに、ユーザー・ロール・マッピングを自動的に割り当てることができます。
-
メニューの Roles をクリックします。
-
Default Roles タブをクリックします。
このスクリーン・ショットは、いくつかの default roles が既に存在していることを示しています。
ロール・スコープ・マッピング
OIDCのアクセストークンまたはSAMLのアサーションの作成時に、ユーザー・ロール・マッピングはトークンまたはアサーション内のクレームとなります。アプリケーションはこれらのクレームを使用して、アプリケーションによって制御されるリソースへのアクセスを決定します。Keycloakはアクセストークンにデジタル署名を行い、アプリケーションはそれを再利用してリモートでセキュリティー保護されたRESTサービスを呼び出します。しかし、これらのトークンにはリスクが伴います。攻撃者はこれらのトークンを入手し、そのパーミッションを使用してネットワークを侵害することができます。このような状況を防ぐには、ロール・スコープ・マッピング を使用します。
ロール・スコープ・マッピング は、アクセストークン内で宣言されるロールを制限します。クライアントがユーザーに認証を要求すると、 受け取ったアクセストークンには、クライアントのスコープに対して 明示的に指定されたロールマッピングのみが含まれます。その結果、クライアントにすべてのユーザー・パーミッションへのアクセスを与える代わりに、個々のアクセストークンのパーミッションを制限することになります。
デフォルトでは、各クライアントはユーザーのすべてのロールマッピングを取得します。ロールマッピングは各クライアントの Scope タブで確認できます。
デフォルトでは、スコープの有効なロールはレルム内で宣言されたすべてのロールになります。このデフォルトの動作を変更するには、Full Scope Allowed を ON に切り替えて、各クライアントで必要な特定のロールを宣言します。また、クライアント・スコープ を使用して、一連のクライアントに対して同じロール・スコープ・マッピングを定義できます。
グループ
Keycloakのグループは、各ユーザーの属性とロールマッピングの共通セットを管理します。ユーザーは任意の数のグループのメンバーになることができ、各グループに割り当てられた属性とロールマッピングを継承します。
グループを管理するには、メニューの Groups をクリックします。
グループは階層構造になっています。グループは複数のサブグループを持つことができますが、1つのグループは1つの親を持つことができるだけです。サブグループは、親グループの属性とロールマッピングを継承します。ユーザーは、その親から属性とロールマッピングを継承します。
親グループと子グループがあり、子グループにのみ所属するユーザーがいる場合、子グループのユーザーは、親グループと子グループの両方の属性とロールマッピングを継承します。
次の例では、トップレベルの Sales グループと子グループの North America サブグループが含まれています。
グループを追加するには、以下のようにします。
-
グループをクリックします。
-
New をクリックします。
-
ツリーの Groups アイコンを選択し、トップレベルのグループを作成します。
-
Create Group 画面で、グループ名を入力する。
-
Save をクリックします。
グループ管理ページが表示されます。
グループ
定義した属性とロールマッピングは、グループのメンバーであるグループとユーザーに継承されます。
ユーザーをグループに追加するには、以下のようにします。
-
メニューの Users をクリックします。
-
ロールマッピングを行いたいユーザーをクリックします。ユーザーが表示されていない場合は、 View all users をクリックします。
-
Groups をクリックします。
ユーザーグループ -
Available Groups ツリーからグループを選択します。
-
Join をクリックします。
ユーザーからグループを削除するには、以下のようにします。
-
Group Membership ツリーからグループを選択します。
-
Leave をクリックします。
この例では、ユーザー_jimlincoln_ は North America グループに所属しています。グループの Members タブに jimlincoln が表示されているのが確認できます。
グループとロールの比較
グループとロールには、いくつかの類似点と相違点があります。Keycloakでは、グループはユーザーの集まりで、これにロールと属性を適用します。ロールはユーザーの種類を定義し、アプリケーションはロールにパーミッションとアクセス・コントロールを割り当てます。
複合ロールは、同じ機能を提供するため、グループと似ています。両者の違いは概念的なものです。複合ロールは、一連のサービスおよびアプリケーションにパーミッション・モデルを適用します。アプリケーションとサービスを管理するには、複合ロールを使用します。
グループは、組織内のユーザーとそのロールの集合体にフォーカスします。ユーザーを管理するには、グループを使用します。
デフォルト・グループの使用
作成されたユーザーやアイデンティティー・ブローカリングでインポートされたユーザーに自動的にグループメンバーを割り当てるには、デフォルト・グループを使用します。
-
メニューの Groups をクリックします。
-
Default Groups タブをクリックします。
このスクリーン・ショットは、いくつかの default groups が既に存在していることを示しています。
認証の設定
この章では、いくつかの認証に関するトピックを取り上げます。これらのトピックは以下のとおりです。
-
厳格なパスワードとワンタイム・パスワード(OTP)ポリシーの実施
-
異なるクレデンシャル・タイプの管理
-
Kerberosによるログイン
-
組み込みのクレデンシャル・タイプの無効化および有効化
パスワードポリシー
Keycloakがレルムを作成するとき、パスワード・ポリシーをレルムに関連付けません。長さ、セキュリティー、複雑さに制限のない単純なパスワードを設定できます。単純なパスワードは、プロダクション環境では受け入れられません。Keycloakには、管理コンソールで利用可能なパスワード・ポリシーのセットがあります。
-
メニューの Authentication をクリックします。
-
Password Policy タブをクリックします。
-
追加するポリシーを Add policy ドロップダウン・ボックスで選択します。
-
選択したポリシーに対応する Policy Value に値を入力します。
-
Save をクリックします。
Password policy
ポリシーを保存した後、Keycloakは新しいユーザーに対してポリシーを適用し、既存のユーザーに対しては、次回ログイン時にパスワードが変更されるようにパスワードの更新アクションを設定します。たとえば、次のようになります。
Password policy types
HashAlgorithm
パスワードは平文で保存されません。保存や検証の前に、Keycloakは標準的なハッシュ・アルゴリズムでパスワードをハッシュします。PBKDF2 は、組み込みで利用可能な唯一のデフォルトのアルゴリズムです。独自のハッシュアルゴリズムを追加する方法については、 Server Developer Guide を参照してください。
ハッシュ・アルゴリズムを変更した場合、ユーザーがログインするまで、ストレージ内のパスワード・ハッシュは変更されません。 |
Hashing iterations
保存または検証前にKeycloakがパスワードをハッシュ化する回数を指定します。初期値は27,500回です。
Keycloakは、パスワード・データベースにアクセスできる敵対的な行為者がリバース・エンジニアリングによってパスワードを読み取れないようにするためにパスワードをハッシュ化します。
ハッシュ化の繰り返し値が大きいと、より高いCPUパワーを必要とするため、パフォーマンスに影響を与える可能性があります。 |
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 タブをクリックします。
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の設定オプション
認証フロー
認証フローとは、ログインや登録などのKeycloakのワークフローにおける、認証、画面、アクションのコンテナーのことです。すべてのフロー、アクション、およびチェックを表示するには、各フローに以下が必要です。
-
メニューの Authentication をクリックします。
-
Flows タブをクリックします。
組み込みフロー
Keycloakには、いくつかの組み込みフローがあります。これらのフローを変更することはできませんが、フローの要件を自分のニーズに合わせて変更することは可能です。
ドロップ・ダウンリストで、 browser を選択すると、Browser Flow画面が表示されます。
ドロップダウンリストのクエスチョン・マークのツールチップにカーソルを合わせると、フローの説明が表示されます。2つのセクションが存在します。
Auth type
認証または実行するアクションの名前。認証がインデントされている場合は、サブフローに含まれます。これは、親の動作によって実行される場合とされない場合があります。
-
Cookie
ユーザーが初めてログインに成功すると、KeycloakはセッションCookieを設定します。Cookieがすでに設定されている場合、この認証タイプは成功となります。Cookieプロバイダーは成功を返し、このレベルのフローの各エグゼキューションは alternative であるため、Keycloakは他のエグゼキューションを実行しません。この結果、ログインに成功します。
-
Kerberos
このオーセンティケーターはデフォルトで無効になっており、ブラウザーフローではスキップされます。
-
Identity Provider Redirector
このアクションは Actions > Config のリンクから設定します。アイデンティティー・ブローカリングの別のIdPにリダイレクトします。
-
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
アクションのエグゼキューションを制御する一連のラジオボタンが実行されます。
Alternative
フローが成功したと評価されるには、1つの要素だけが正常に実行される必要があります。フローが成功したと評価されるには、 Required フロー要素があれば十分なので、 Required フロー要素を含むフロー内の Alternative フロー要素は、実行されません。
Conditional
この要件タイプは、サブフローにのみ設定されます。
-
Conditional サブフローはエグゼキューションを含みます。これらのエグゼキューションは、論理文として評価されなければなりません。
-
すべてのエグゼキューションが true と評価された場合、 Conditional サブフローは Required として動作します。
-
すべてのエグゼキューションが false と評価された場合、 Conditional サブフローは Disabled として動作します。
-
エグゼキューションを設定しない場合、 Conditional サブフローは Disabled として動作します。
-
フローがエグゼキューションを含み、フローが Conditional に設定されていない場合、Keycloakはエグゼキューションを評価せず、エグゼキューションは機能的に Disabled とみなされます。
フローの作成
フローを設計する際には、重要な機能性とセキュリティーに関する考慮事項が適用されます。
フローを作成するには、以下を実行します。
-
メニューの Authentication をクリックします。
-
New をクリックします。
既存のフローをコピーして、修正することができます。フローを選択し、 Copy をクリックし、新しいフローの名前を入力します。 |
新しいフローを作成する場合、まず次のオプションでトップレベルのフローを作成する必要があります。
- Alias
-
フローの名前。
- 説明
-
フローに設定できる説明。
- トップレベル・フロー・タイプ
-
フローのタイプです。タイプ client は、クライアント(アプリケーション)の認証にのみ使用されます。それ以外の場合は、 generic を選択します。
Keycloakがフローを作成すると、Keycloakは Delete 、 Add execution 、 Add flow ボタンを表示します。
フローとサブフローの挙動は3つの要因で決まります。
-
フローとサブフローの構造。
-
フロー内のエグゼキューション
-
要求はサブフローとエグゼキューションの中で設定されます。
リセットメールの送信からワンタイムパスワードの認証まで、さまざまなアクションを実行できます。実行を追加するには、 Add execution ボタンをクリックします。 Provider の横にあるクエスチョン・マークにカーソルを合わせると、実行の説明が表示されます。
自動エグゼキューション と 対話型エグゼキューション の2種類が存在します。 自動エグゼキューション は Cookie エグゼキューションと同様で、フロー内で自動的にアクションを実行します。 対話型エグゼキューション は、入力を得るためにフローを停止させます。実行が成功すると、ステータスが success に設定されます。フローが完了するには、ステータスが success である実行が少なくとも1つ必要です。
トップレベルのフローにサブフローを追加するには、 Add flow ボタンを使用します。 Add flow ボタンを押すと、 Create Execution Flow ページが表示されます。このページは、 Create Top Level Form ページと似ています。違いは、 Flow Type に generic (デフォルト)または form を指定できることです。 form 型は、組み込みの Registration フローと同様に、ユーザー用のフォームを生成するサブフローを構築します。サブフローの成功は、含まれるサブフローを含め、そのエグゼキューションのRequirementがどのように評価されるかに依存します。サブフローがどのように機能するかについての詳細な説明は、エグゼキューションのRequirementのセクションを参照してください。
エグゼキューションを追加した後、要件が正しい値であることを確認します。 |
フロー内のすべての要素には、 Actions メニューに Delete オプションがあります。このアクションは、フローからエレメントを削除します。実行には、実行を設定するための Config メニューオプションがあります。また、Add execution および Add flow メニューオプションを使用して、実行とサブフローを追加することも可能です。
エグゼキューションの順序は重要です。エグゼキューションやサブフローは、その名前の横にある上下のボタンで、フロー内で上下に移動させることができます。
認証フローを設定する際には、設定にセキュリティー・ホールが存在しないことを確認するために、適切にテストを行うようにしてください。様々なコーナーケースをテストすることをお勧めします。たとえば、認証前にユーザーのアカウントからさまざまなクレデンシャルを削除した場合の、そのユーザーの認証動作をテストすることを検討します。 たとえば、OTPフォームやWebAuthn認証などの2要素認証がフローでREQUIREDに設定されており、ユーザーが特定のタイプのクレデンシャルを持っていない場合、ユーザーは認証中に特定のクレデンシャルを設定することができるようになります。この場合、ユーザーは認証時にこのクレデンシャルを正しくセットアップしているため、このクレデンシャルでは認証されないことを意味します。したがって、ブラウザー認証では、パスワードやWebAuthn Passwordless Authenticatorなどの1要素クレデンシャルを使用して認証フローを設定するようにしてください。 |
パスワードレスのブラウザー・ログイン・フローの作成
フローの作成を説明するために、ここでは高度なブラウザー・ログイン・フローの作成について説明します。このフローの目的は、WebAuthnを使ったパスワードレスでのログインと、パスワードとOTPによる二要素認証のどちらかをユーザーが選択できるようにすることです。
-
メニューの Authentication をクリックします。
-
Flows タブをクリックします。
-
New をクリックします。
-
エイリアスとして
Browser Password-less
を入力します。 -
Save をクリックします。
-
Add execution をクリックします。
-
ドロップダウン・リストから Cookie を選択します。
-
Save をクリックします。
-
認証タイプ Cookie の Alternative をクリックし、その要件を代替に設定します。
-
Add execution をクリックします。
-
ドロップダウン・リストから Kerberos を選択します。
-
Add execution をクリックします。
-
ドロップダウン・リストから Identity Provider Redirector を選択します。
-
Save をクリックします。
-
Identity Provider Redirector 認証タイプの Alternative をクリックして、その要件を代替に設定します。
-
Add flow をクリックします。
-
エイリアスとして Forms を入力します。
-
Save をクリックします。
-
Forms 認証タイプの Alternative をクリックして、その要件を代替に設定します。
ブラウザーフローとの共通部分 -
Forms を実行するための Actions をクリックします。
-
Add execution を選択します。
-
ドロップダウンリストから、 Username Form を選択します。
-
Save をクリックします。
-
Username Form 認証タイプの Required 認証をクリックして、その要件を必須に設定します。
この段階では、フォームにはユーザー名は必要ですが、パスワードは必要ありません。セキュリティー・リスクを回避するために、パスワード認証を有効にする必要があります。
-
Forms サブフローの Actions をクリックします。
-
Add flow をクリックします。
-
エイリアスとして
Authentication
を入力します。 -
Save をクリックします。
-
Authentication 認証タイプの Required をクリックして、その要件を必須に設定します。
-
Authentication サブフローの Actions をクリックします。
-
Add execution をクリックします。
-
ドロップダウン・リストから Webauthn Passwordless Authenticator を選択します。
-
Save をクリックします。
-
Webauthn Passwordless Authenticator の認証タイプの Alternative をクリックして、その要件を代替に設定します。
-
Authentication サブフローの Actions をクリックします。
-
Add flow をクリックします。
-
エイリアスとして
Password with OTP
を入力します。 -
Save をクリックします。
-
Password with OTP の認証タイプは、 Alternative をクリックすると代替になります。
-
Password with OTP サブフローの Actions をクリックします。
-
Add execution をクリックします。
-
ドロップダウン・リストから Password Form を選択します。
-
Save をクリックします。
-
Password Form の認証タイプの Required をクリックして、その要件を必須に設定します。
-
Password with OTP サブフローの Actions をクリックします。
-
Add execution をクリックします。
-
ドロップダウン・リストから OTP Form を選択します。
-
Save をクリックします。
-
OTP Form 認証タイプの Required をクリックして、その要件を必須に設定します。
最後に、バインディングを変更します。
-
Bindings をクリックします。
-
Browser Flow のドロップダウン・リストをクリックします。
-
ドロップダウン・リストから、 Browser Password-less を選択します。
-
Save をクリックします。
ユーザー名を入力すると、次のような流れで動作します。
ユーザーがWebAuthnのパスワードレス・クレデンシャルを記録している場合、このクレデンシャルを使って直接ログインすることができます。これがパスワードレス・ログインです。 WebAuthn Passwordless
のエグゼキューションと Password with OTP
フローが Alternative に設定されているため、ユーザーは Password with OTP を選択することもできます。これらが Required に設定されている場合、ユーザーはWebAuthn、パスワード、OTPを入力する必要があります。
WebAuthnパスワードレス認証で Try another way リンクを選択した場合、ユーザーは Password
と Security Key
(WebAuthnパスワードレス)のどちらかを選択することができます。パスワードを選択した場合、ユーザーは割り当てられたワンタイムパスワードでログインを続ける必要があります。WebAuthnのクレデンシャルを持っていない場合、ユーザーはパスワードを入力し、次にOTPを入力する必要があります。ユーザーが OTP クレデンシャルを持っていない場合は、OTP を記録するように求められます。
WebAuthn Passwordlessのエグゼキューションが Required ではなく Alternative に設定されているため、このフローはユーザーにWebAuthnクレデンシャルの登録を要求することはありません。ユーザーにWebauthnクレデンシャルを持たせるためには、管理者がそのユーザーに必須アクションを追加する必要があります。これを行うには、以下のようにします。
このような高度なフローを作成すると、副作用が発生することがあります。たとえば、ユーザーのパスワードをリセットする機能を有効にした場合、パスワードフォームからアクセスできるようになります。デフォルトの
|
スクリプト・オーセンティケーター
スクリプトを管理コンソールやRESTエンドポイントからアップロードする機能は廃止予定です。
詳しくは、 JavaScript Providers を参照してください。
Kerberos
Keycloakは、Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) プロトコルによるKerberosチケットを使ったログインをサポートしています。SPNEGOは、ユーザーがセッションを認証した後、Webブラウザーを通じて透過的に認証します。Web以外の場合、またはログイン時にチケットが利用できない場合、KeycloakはKerberosのユーザー名とパスワードによるログインをサポートします。
Web認証の一般的なユースケースは次のとおりです。
-
ユーザーはデスクトップにログインする。
-
ユーザーはブラウザーを使ってKeycloakで保護されたWebアプリケーションにアクセスします。
-
アプリケーションはKeycloakのログイン画面にリダイレクトされます。
-
Keycloakは、ステータス401、HTTPヘッダー
WWW-Authenticate.Negotiate: Negotiate
のHTMLログイン画面をレンダリングします。 -
ブラウザーがデスクトップ・ログイン時のKerberosチケットを持っている場合、ブラウザーはデスクトップのサインオン情報を
Authorization: Negotiate 'spnego-token'
ヘッダーでKeycloakへ転送します。そうでなければ、標準的なログイン画面が表示され、ユーザーはログインクレデンシャルを入力します。 -
Keycloakは、ブラウザーから送信されたトークンを検証し、ユーザーを認証します。
-
Kerberos認証をサポートするLDAPFederationProviderを使用する場合、KeycloakはLDAPからユーザーデータをプロビジョニングします。KerberosFederationProviderを使用する場合、Keycloakは、ユーザーにプロフィールの更新とログインデータの事前入力をさせます。
-
Keycloakはアプリケーションに戻ります。KeycloakとアプリケーションはOpenID ConnectまたはSAMLメッセージで通信します。Keycloakは、Kerberos/SPNEGOログインのブローカーとして動作します。そのため、KeycloakがKerberosで認証していることは、アプリケーションからは見えません。
以下の手順で、Kerberos認証を設定します。
-
Kerberosサーバー(KDC)のセットアップと設定です。
-
Keycloakサーバーのセットアップと設定です。
-
クライアント・マシンのセットアップと設定です。
Kerberosサーバーのセットアップ
Kerberosサーバーをセットアップする手順は、オペレーティング・システム(OS)とKerberosベンダーに依存します。Windows Active Directory、MIT Kerberos、およびお使いのOSのマニュアルを参照して、Kerberosサーバーのセットアップと設定を確認してください。
セットアップ時には、以下の手順で行ってください。
-
Kerberosデータベースにユーザー・プリンシパルを追加します。また、KerberosをLDAPと統合し、LDAPサーバーからユーザー・アカウントをプロビジョニングすることも可能です。
-
"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クライアントをインストールします。
-
Kerberosクライアントをインストールします。Fedora、Ubuntu、または RHELを使用している場合は、Kerberosクライアントとその他のユーティリティーを含む freeipa-client パッケージをインストールします。
-
Kerberosクライアントの設定(Linuxでは、 /etc/krb5.conf ファイルに設定されています)。
Kerberosレルムを設定に追加し、サーバーが実行されるHTTPドメインを設定します。
たとえば、MYDOMAIN.ORGレルムでは、
domain_realm
のセクションを次のように設定します。[domain_realm] .mydomain.org = MYDOMAIN.ORG mydomain.org = MYDOMAIN.ORG
-
HTTPプリンシパルでkeytabファイルをエクスポートし、そのファイルがKeycloakサーバーを実行しているプロセスからアクセス可能であることを確認します。実稼働環境では、このファイルがこのプロセスによってのみ読み取り可能であることを確認します。
上記のMIT Kerberosの例では、keytabを
/tmp/http.keytab
ファイルにエクスポートしています。もし、Key Distribution Centre (KDC) とKeycloakが同じホストで動いていれば、このファイルはすでに利用可能です。
SPNEGO処理の有効化
デフォルトでは、KeycloakはSPNEGOプロトコルのサポートを無効にします。有効にするには、ブラウザーフローで Kerberos を有効にしてください。
Kerberos requirementを disabled から alternative (Kerberos はオプション) または required (ブラウザーでKerberosを有効にする必要がある) に設定します。SPNEGOまたはKerberosで動作するようにブラウザーを設定していない場合、Keycloakは通常のログイン画面に戻ります。
Kerberosユーザー・ストレージ・フェデレーション・プロバイダーの設定
ここでユーザー・ストレージ・フェデレーションを使用して、KeycloakがKerberosチケットを解釈する方法を設定する必要があります。Kerberos認証をサポートする2つの異なるフェデレーション・プロバイダーが存在します。
LDAPサーバーにバックアップされたKerberosで認証するには、LDAPフェデレーション・プロバイダーを設定します。
-
LDAPプロバイダーの設定ページに移動します。
LDAPとKerberosの統合 -
Allow Kerberos authentication を ON にします。
Kerberos認証 を許可すると、KeycloakはKerberosプリンシパル・アクセス・ユーザー情報を使用し、Keycloak 環境に情報をインポートできるようになります。
LDAPサーバーがKerberosソリューションをバックアップしていない場合、 Kerberos ユーザー・ストレージ・フェデレーション・プロバイダーを使用します。
-
メニューの User Federation をクリックします。
-
Add provider セレクトボックスから Kerberos を選択します。
Kerberosユーザー・ストレージ・プロバイダー
Kerberos プロバイダーは、Kerberosチケットを解析して単純なプリンシパル情報を取得し、その情報をローカルKeycloakデータベースにインポートします。姓、名、電子メールなどのユーザー・プロフィール情報はプロビジョニングされません。
クライアントマシンのセットアップと設定
クライアントマシンはKerberosクライアントを持ち、上で説明したように krb5.conf
を設定する必要があります。また、クライアント・マシンは、ブラウザーでSPNEGOログインサポートを有効にしなければなりません。Firefoxを使用している場合は、Kerberos用にFirefoxを設定するを参照してください。
.mydomain.org
のURI は network.negotiate-auth.trusted-uris
設定オプションに含まれていなければなりません。
Windowsドメインでは、クライアント側で設定を調整する必要はありません。Internet ExplorerとEdgeは、すでにSPNEGO認証に参加することができます。
クレデンシャルの委譲
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
に存在します。また、サンプルのソースを ここで 直接確認することもできます。
|
クレデンシャルの委譲はセキュリティー上の問題があるため、必要な場合のみ使用し、HTTPSでのみ使用してください。詳細と例については、 この記事 を参照してください。 |
クロスレルム・トラスト
Kerberosプロトコルにおいて、 realm
はKerberosプリンシパルの集合です。これらのプリンシパルの定義はKerberosデータベースに存在し、それは通常LDAPサーバーです。
Kerberosプロトコルは、レルム間の信頼を可能にします。たとえば、2つのKerberosレルム、AとBが存在する場合、レルム間信頼はレルムAからのユーザがレルムBのリソースにアクセスすることを可能にします。レルムBはレルムAを信頼します。
Keycloakサーバーは、クロス・レルム・トラストをサポートしています。これを実装するには、以下を実行します。
-
クロス・レルム・トラストのためにKerberosサーバを設定します。このステップの実装は、Kerberosサーバーの実装に依存します。このステップは、Kerberosプリンシパル
krbtgt/B@A
をレルムAとレルムBのKerberosデータベースに追加するために必要です。プリンシパルは両方のレルムで同じパスワード、鍵のバージョン番号、暗号を持たなければなりません。詳細については、Kerberos サーバーのドキュメントを参照してください。
クロス・レルム・トラストは、デフォルトでは一方向的です。レルムAとレルムBの間で双方向の信頼を行うには、両方の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
フラグを有効にします。 -
standalone/configuration/standalone.xml
のlogging
のセクションでorg.keycloak
というカテゴリーのTRACEロギングを有効にすると、standalone/log/server.log
でさらに情報を受け取れるようになります。 -
システム・プロパティー
-Dsun.security.krb5.debug=true
と-Dsun.security.spnego.debug=true
を追加します
X.509クライアント証明書によるユーザー認証
Keycloakは、サーバーがMutual SSL認証を使用するように設定されている場合、X.509クライアント証明書によるログインをサポートします。
以下は、典型的なワークフローです。
-
クライアントは、SSL/TLSチャネル上で認証要求を送信します。
-
SSL/TLSハンドシェイクでは、サーバーとクライアントはx.509/v3証明書を交換します。
-
コンテナー(WildFly)は、証明書のPKIXパスと証明書の有効期限を検証します。
-
x.509クライアント証明書オーセンティケーターは、以下の方法でクライアント証明書を検証します。
-
CRLおよび(または)CRL配布ポイントを使用して証明書失効ステータスをチェックします。
-
OCSP(オンライン証明書ステータス・プロトコル)を使用して証明書失効ステータスをチェックします。
-
証明書内のキー使用が予想されるキー使用と一致するかどうかを検証します。
-
証明書内の拡張キーが予想される拡張キーと一致するかどうかを検証します。
-
-
これらのチェックのいずれかが失敗した場合、x.509認証は失敗します。それ以外の場合、オーセンティケーターは証明書のアイデンティティーを抽出し、既存のユーザーにマッピングします。
証明書が既存のユーザーにマッピングされる場合、認証フローによって動作が分岐する。
-
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 Source
が Match SubjectDN using regular expression
か、 Match IssuerDN using regular expression
のどちらかにセットされている場合に適用されます。
既存のユーザーに証明書のアイデンティティーをマッピングする
証明書アイデンティティー・マッピングは、抽出されたユーザー・アイデンティティーを既存のユーザーのユーザー名、電子メール、または証明書アイデンティティーと一致する値を持つカスタム属性にマップできます。たとえば、 Identity source
を Subject’s email に、または User mapping method
を Username or email に設定すると、X.509クライアント証明書オーセンティケーターはユーザー名または電子メールで既存のユーザーをルックアップする際の、検索基準として証明書のSubjectDNのemail属性を使用します。
|
X.509クライアント証明書のユーザー認証を有効にする
以下のセクションでは、X.509クライアント証明書認証を有効にするためにWildFly/UndertowとKeycloakサーバーを設定する方法について説明します。
WildFlyで相互SSLを有効にする
WildFlyでSSLを有効にする方法については、 Enable SSL を参照してください。
-
KEYCLOAK_HOME/standalone/configuration/standalone.xmlを開き、新しいレルムを追加します。
<security-realms>
<security-realm name="ssl-realm">
<server-identities>
<ssl>
<keystore path="servercert.jks"
relative-to="jboss.server.config.dir"
keystore-password="servercert password"/>
</ssl>
</server-identities>
<authentication>
<truststore path="truststore.jks"
relative-to="jboss.server.config.dir"
keystore-password="truststore password"/>
</authentication>
</security-realm>
</security-realms>
ssl/keystore
-
ssl
要素には、JKS 鍵ストアからサーバーの公開鍵ペアを読み込むための詳細を記述したkeystore
要素が含まれます。 ssl/keystore/path
-
JKSキーストアへのパス。
ssl/keystore/relative-to
-
キーストアパスが相対的なパス。
ssl/keystore/keystore-password
-
キーストアを開くためのパスワード。
ssl/keystore/alias
(オプション)-
キーストア内のエントリーのエイリアス。キーストアに複数のエントリーが含まれている場合に設定します。
ssl/keystore/key-password
(オプション)-
秘密鍵のパスワード(キーストアのパスワードと異なる場合)。
authentication/truststore
-
インバウンド/アウトゴーイング接続のリモート側が提示する証明書を検証するためにトラストストアをロードする方法を定義します。通常、トラストストアには、信頼できる認証局の証明書のコレクションが含まれています。
authentication/truststore/path
-
信頼できる認証局の証明書を含むJKSキーストアへのパス。
authentication/truststore/relative-to
-
トラストストアのパスが相対的であることを示すパス。
authentication/truststore/keystore-password
-
トラストストアを開くためのパスワード。
HTTPSリスナーを有効にする
WildFlyでHTTPSを有効にする方法については、 HTTPSリスナー を参照してください。
-
<https-listener>要素を追加します。
<subsystem xmlns="urn:jboss:domain:undertow:12.0">
....
<server name="default-server">
<https-listener name="default"
socket-binding="https"
security-realm="ssl-realm"
verify-client="REQUESTED"/>
</server>
</subsystem>
https-listener/security-realm
-
この値は、前のセクションのレルムの名前と一致する必要があります。
https-listener/verify-client
-
REQUESTED に設定すると、サーバーはオプションでクライアント証明書の提出を求めます。 REQUIRED に設定すると、サーバーは、クライアント証明書が提供されていない場合、受信接続を拒否します。
ブラウザーフローへのX.509クライアント証明書認証の追加
-
メニューの Authentication をクリックします。
-
"Browser" フローをクリックします。
-
Copy をクリックすると、内蔵の "Browser" フローのコピーが作成されます。
-
コピーの名前を入力します。
-
Ok をクリックします。
-
Add policy ドロップダウン・ボックスでコピーをクリックします。
-
Add execution をクリックします。
-
"X509/Validate Username Form"をクリックします。
-
Save をクリックします。
X509エグゼキューション -
上下の矢印ボタンをクリックして、 "X509/Validate Username Form" を "Browser Forms" エグゼキューションの上に移動させることができます。
-
条件を "ALTERNATIVE" に設定します。
X509ブラウザーフロー -
Bindings をクリックします。
-
Browser Flow のドロップダウン・リストをクリックします。
-
ドロップダウン・リストから、ブラウザーフローのコピーをクリックします。
-
Save をクリックします。
X509ブラウザーフロー・バインディング
X.509クライアント証明書認証の設定
- 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クライアント証明書認証の追加
-
メニューの Authentication をクリックします。
-
"Direct Grant"フローをクリックします。
-
Copy をクリックすると、"Direct Grant"フローのコピーが作成されます。
-
コピーの名前を入力します。
-
Ok をクリックします。
-
"Username Validation"の Actions リンクをクリックし、 Delete をクリックします。
-
Delete をクリックします。
-
"Password"の Actions リンクをクリックし、 Delete をクリックします。
-
Delete をクリックします。
-
Add execution をクリックします。
-
"X509/Validate Username"をクリックします。
-
Save をクリックします。
X509ダイレクト・グラント・エグゼキューション -
x509 Browser Flowに記載されている手順で、x509認証の設定を行います。
-
Bindings をクリックします。
-
Direct Grant Flow のドロップダウン・リストをクリックします。
-
新しく作成した"x509 Direct Grant"フローをクリックします。
-
Save をクリックします。
X509ダイレクト・グラント・バインディング
クライアント証明書検索
project_name} サーバーが直接 HTTP リクエストを受け取ると、WildFly サーブレットサブシステムは SSL ハンドシェイクを確立し、クライアント証明書を抽出します。appserver_name} は、サーブレット仕様で規定されているように、HTTPリクエストの javax.servlet.request.X509Certificate
属性にクライアント証明書を保存します。project_name} X509認証ツールは、この属性から証明書を検索することができます。
しかし、Keycloakサーバーがロードバランサーやリバース・プロキシーの背後でHTTPリクエストをリッスンしている場合、プロキシー・サーバーはクライアント証明書を抽出し、相互のSSL接続を確立することがあります。リバース・プロキシーは一般に、認証されたクライアント証明書を基礎となるリクエストのHTTPヘッダーにセットします。プロキシーはリクエストをバックエンドKeycloakサーバーに転送します。この場合、KeycloakはHTTPリクエストの属性ではなくHTTPヘッダーからX.509証明書チェーンを調べなければなりません。
Keycloakがリバース・プロキシーの背後にある場合、一般的には KEYCLOAK_HOME/standalone/configuration/standalone.xml で x509cert-lookup
SPI の代替プロバイダーを設定する必要があります。HTTPヘッダー証明書を検索する default
プロバイダーには、さらに2つの組み込みプロバイダー haproxy
と apache
が存在します。
HAProxy証明書検索プロバイダー
このプロバイダーは、KeycloakサーバーがHAProxyのリバース・プロキシーの背後にある場合に使用します。サーバーには、次の設定を使用します。
<spi name="x509cert-lookup">
<default-provider>haproxy</default-provider>
<provider name="haproxy" enabled="true">
<properties>
<property name="sslClientCert" value="SSL_CLIENT_CERT"/>
<property name="sslCertChainPrefix" value="CERT_CHAIN"/>
<property name="certificateChainLength" value="10"/>
</properties>
</provider>
</spi>
この設定例では、クライアント証明書はHTTPヘッダーの SSL_CLIENT_CERT
から検索され、そのチェーンの他の証明書はHTTPヘッダーの CERT_CHAIN_0
を介して CERT_CHAIN_9
などから検索されるようになっています。 certificateChainLength
属性はチェーンの最大長なので、最後の属性は CERT_CHAIN_9
となります。
クライアント証明書およびクライアント証明書チェーンのHTTPヘッダーの設定の詳細については、HAProxyのドキュメントを参照してください。
Apache証明書検索プロバイダー
このプロバイダーは、KeycloakサーバーがApacheのリバース・プロキシーの後ろにある場合に使用できます。サーバーには、次の設定を使用してください。
<spi name="x509cert-lookup">
<default-provider>apache</default-provider>
<provider name="apache" enabled="true">
<properties>
<property name="sslClientCert" value="SSL_CLIENT_CERT"/>
<property name="sslCertChainPrefix" value="CERT_CHAIN"/>
<property name="certificateChainLength" value="10"/>
</properties>
</provider>
</spi>
この設定は haproxy
プロバイダーと同じです。クライアント証明書とクライアント証明書チェーンのHTTPヘッダーの設定方法については、 mod_ssl と mod_headers にあるApacheのドキュメントを参照してください。
Nginx証明書検索プロバイダー
このプロバイダーは、KeycloakサーバーがNGINXのリバース・プロキシーの後ろにある場合に使用できます。サーバーには、次の設定を使用してください。
<spi name="x509cert-lookup">
<default-provider>nginx</default-provider>
<provider name="nginx" enabled="true">
<properties>
<property name="sslClientCert" value="ssl-client-cert"/>
<property name="sslCertChainPrefix" value="USELESS"/>
<property name="certificateChainLength" value="2"/>
</properties>
</provider>
</spi>
NGINXの SSL/TLSモジュール はクライアント証明書チェーンを公開しません。KeycloakのNGINX証明書検索プロバイダーは、 Keycloak truststore を使用してそれを再構築します。クライアント証明書チェーンを再構築するために、keytool CLIを使用してすべてのルートおよび中間CAでKeycloakトラストストアを入力します。 |
クライアント証明書のHTTPヘッダーの設定の詳細については、NGINXのドキュメントを参照してください。
NGINXの設定ファイルの例を以下に示します。
...
server {
...
ssl_client_certificate trusted-ca-list-for-client-auth.pem;
ssl_verify_client optional_no_ca;
ssl_verify_depth 2;
...
location / {
...
proxy_set_header ssl-client-cert $ssl_client_escaped_cert;
...
}
...
}
Keycloak truststore に、trusted-ca-list-for-client-auth.pemのすべての証明書を追加する必要があります。 |
その他のリバース・プロキシーの実装
Keycloakは、他のリバース・プロキシーの実装をビルトインでサポートしていません。しかし、他のリバース・プロキシーでも apache
や haproxy
と同じような動作をさせることができます。もし、どれもうまくいかない場合は、 org.keycloak.services.x509.X509ClientCertificateLookupFactory
と org.keycloak.services.x509.X509ClientCertificateLookup
プロバイダーを自分で実装して作成してください。プロバイダーの追加方法については、 Server Developer Guide を参照してください。
トラブルシューティング
- HTTPヘッダーのダンプ
-
リバース・プロキシーがKeycloakに送信するものを見るには、
RequestDumpingHandler
Undertowフィルターを有効にして、server.log
ファイルを参照してください。 - ロギング・サブシステムでTRACEロギングを有効にします。
...
<profile>
<subsystem xmlns="urn:jboss:domain:logging:8.0">
...
<logger category="org.keycloak.authentication.authenticators.x509">
<level name="TRACE"/>
</logger>
<logger category="org.keycloak.services.x509">
<level name="TRACE"/>
</logger>
RequestDumpingHandlerやTRACEロギングをプロダクション環境で使用しないでください。 |
- X.509によるダイレクト・グラント認証
-
リソース・オーナー・パスワード・クレデンシャル・グラントを利用してトークンを要求する場合、以下のテンプレートを使用することができます。
$ curl https://[host][:port]/auth/realms/master/protocol/openid-connect/token \
--insecure \
--data "grant_type=password&scope=openid profile&username=&password=&client_id=CLIENT_ID&client_secret=CLIENT_SECRET" \
-E /path/to/client_cert.crt \
--key /path/to/client_cert.key
[host][:port]
-
リモートKeycloakサーバーのホストとポート番号です。
CLIENT_ID
-
クライアントID。
CLIENT_SECRET
-
コンフィデンシャル・クライアントに対するクライアント・シークレット。
client_cert.crt
-
Mutual SSL認証において、クライアントの身元を確認するための公開鍵証明書です。証明書はPEM形式である必要があります。
client_cert.key
-
公開鍵ペアの秘密鍵。この鍵はPEM形式である必要があります。
W3C Web Authentication(WebAuthn)
Keycloakは、 W3C Web Authentication(WebAuthn) の限定的なサポートを提供します。KeycloakはWebAuthnの Relying Party(RP) として機能します。
WebAuthnのサポートは開発中であることに注意してください。この機能は実験的に使用してください。 |
WebAuthnの運用がうまくいくかどうかは、ユーザーのWebAuthn対応オーセンティケーター、ブラウザー、プラットフォームに依存します。お使いのオーセンティケーター、ブブラウザー、プラットフォームが WebAuthn 仕様をサポートしていることを確認してください。 |
セットアップ
2FAのWebAuthnサポートのセットアップ手順は次のとおりです。
WebAuthnオーセンティケーターの登録の有効化
-
メニューの Authentication をクリックします。
-
Required Actions タブをクリックします。
-
Register をクリックします。
-
Required Action のドロップダウン・リストをクリックします。
-
Webauthn Register をクリックします。
-
Ok をクリックします。
すべての新規ユーザーにWebAuthnのクレデンシャルの登録を要求する場合は、 Default Action のチェックボックスをONにします。
ブラウザーフローへのWebAuthn認証の追加
-
メニューの Authentication をクリックします。
-
Browser フローをクリックします。
-
Copy をクリックすると、内蔵の Browser フローのコピーが作成されます。
-
コピーの名前を入力します。
-
Ok をクリックします。
-
WebAuthn Browser Browser - Conditional OTP の Actions リンクをクリックし、 Delete をクリックします。
-
Delete をクリックします。
すべてのユーザーにWebAuthnが必要な場合は、以下のようにします。
-
WebAuthn Browser Forms の Actions のリンクをクリックします。
-
Add execution をクリックします。
-
Provider のドロップダウン・リストをクリックします。
-
Webauthn Authenticator をクリックします。
-
Save をクリックします。
-
WebAuthn Authenticator の REQUIRED をクリックします。
-
Bindings をクリックします。
-
Browser Flow のドロップダウン・リストをクリックします。
-
Webauthn Browser をクリックします。
-
Save をクリックします。
ユーザーがWebAuthnのクレデンシャルを持っていない場合、ユーザーはWebAuthnのクレデンシャルを登録する必要があります。 |
ユーザーは、WebAuthnのクレデンシャルが登録されている場合のみ、WebAuthnでログインすることができます。そのため、 WebAuthn Authenticator のエグゼキューションを追加する代わりに、以下ができます。
-
WebAuthn Browser Forms の Actions のリンクをクリックします。
-
Add flow をクリックします。
-
Alias の項目には "Conditional 2FA" と入力します。
-
Save をクリックします。
-
Conditional 2FA の CONDITIONAL をクリックします。
-
Conditional 2FA の_Actions_のリンクをクリックします。
-
Add execution をクリックします。
-
Provider のドロップダウン・リストをクリックします。
-
Condition - User Configured をクリックします。
-
Save をクリックします。
-
Conditional 2FA の REQUIRED をクリックします。
-
Conditional 2FA の_Actions_のリンクをクリックします。
-
Add execution をクリックします。
-
Provider のドロップダウン・リストをクリックします。
-
Webauthn Authenticator をクリックします。
-
Save をクリックします。
-
Conditional 2FA の ALTERNATIVE をクリックします。
2つ目の要素については、WebAuthnを使用するかOTPを使用するかをユーザーが選択できます。
-
Conditional 2FA の Actions のリンクをクリックします。
-
Add execution をクリックします。
-
Provider のドロップダウン・リストをクリックします。
-
ITP Form をクリックします。
-
Save をクリックします。
-
Conditional 2FA の ALTERNATIVE をクリックします。
WebAuthnオーセンティケーターを使用した認証
WebAuthnオーセンティケーターを登録した後、ユーザーは以下の操作を行います。
-
ログインフォームを開きます。ユーザーはユーザー名とパスワードで認証する必要があります。
-
ユーザーのブラウザーは、ユーザーにWebAuthnオーセンティケーターを使用した認証を要求します。
管理者としてWebAuthnを管理する
クレデンシャルの管理
Keycloakは、 ユーザークレデンシャル管理 の他のクレデンシャルと同様にWebAuthnのクレデンシャルを管理します。
-
Keycloakは、 Reset Actions の一覧からWebAuthnクレデンシャルを作成し、 Webauthn Register を選択するという必須アクションをユーザーに割り当てます。
-
管理者は、 Delete をクリックして、WebAuthnのクレデンシャルを削除することができます。
-
管理者は、 Show data… を選択して、AAGUIDなどのクレデンシャルのデータを表示できます。
-
管理者は、User Label フィールドに値を設定し、データを保存することで、クレデンシャルにラベルを設定することができます。
ポリシーの管理
管理者は、WebAuthn関連の操作をレルムごとに WebAuthn Policy として設定できます。
-
メニューの Authentication をクリックします。
-
WebAuthn Policy タブをクリックします。
-
ポリシー内の項目を設定します(以下の説明を参照)。
-
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オーセンティケーターが生成するAttestation文の信頼性を検証します。Keycloakは、このためにトラストアンカーの証明書を必要とします。Keycloakは Keycloak truststore を利用しているので、事前にこれらの証明書をインポートしておく必要があります。
この検証を省略するには、このトラストストアを無効にするか、WebAuthnポリシーの設定項目 "Attestation Conveyance Preference" を "none" に設定してください。
ユーザーとしてのWebAuthnクレデンシャルの管理
パスワードレスWebAuthnと二要素認証の併用
Keycloakは二要素認証にWebAuthnを使っていますが、一要素認証にWebAuthnを使うこともできます。この場合、 passwordless
のWebAuthn のクレデンシャルを持つユーザーは、パスワードなしでKeycloakを認証することができます。Keycloakは、ひとつのレルムとひとつの認証フローで、WebAuthnをパスワードなし認証と二要素認証の両方の仕組みとして使うことができます。
管理者は通常、WebAuthnパスワードレス認証のためにユーザーが登録したセキュリティー鍵が、異なる要件を満たすことを要求します。たとえば、セキュリティー鍵は、ユーザーがPINを使用してセキュリティー鍵に認証することを要求したり、セキュリティー鍵がより強力な認証局で認証することを要求したりすることがあります。
このため、Keycloakは管理者に個別の WebAuthn Passwordless Policy
を設定することを許可しています。 WebAuthn Register Passwordless
のアクションが必要で、 WebAuthn Passwordless Authenticator
タイプのオーセンティケーターが別途必要です。
セットアップ
WebAuthnのパスワードレス対応については、以下のように設定してください。
-
WebAuthnのパスワードレス対応に必須アクションを新規に登録します。WebAuthnオーセンティケーターの登録の有効化で説明した手順を使用してください。
Webauthn Register Passwordless
アクションを登録します。 -
ポリシーを設定します。ポリシーの管理で説明した手順と設定オプションが使用できます。管理コンソールのタブ WebAuthn Passwordless Policy で設定を実行します。通常、セキュリティー鍵の要件は、2要素ポリシーの要件よりも強くなります。たとえば、パスワードレスポリシーを設定する際に、User Verification Requirement を Required に設定します。
-
認証フローを設定します。ブラウザフローへの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 Form と WebAuthn Authenticator が含まれます。
-
最終的なフローの設定はこのような感じになります。
すでにKeycloakに認識されているユーザーに、必須アクションとして WebAuthn Register Passwordless を追加し、これをテストすることができます。最初の認証では、ユーザーはパスワードと第2要素のWebAuthnクレデンシャルを使用する必要があります。WebAuthn Passwordlessクレデンシャルを使用する場合、ユーザーはパスワードと第2要素の 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 Access
と Allow 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
の設定はとても簡単です。次のように、任意のエイリアスと必要なメッセージを指定できます。
最後に、ログインテーマの 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がサポートするすべてのアイデンティティー・プロバイダーは、以下のフローを使用します。 |
-
認証されていないユーザーが、クライアント・アプリケーションで保護されたリソースを要求します。
-
クライアント・アプリケーションは、ユーザーをKeycloak にリダイレクトし、認証を行います。
-
Keycloakは、レルムに設定されているアイデンティティー・プロバイダーの一覧を含むログインページを表示します。
-
ユーザーは、ボタンやリンクをクリックして、いずれかのアイデンティティー・プロバイダーを選択します。
-
Keycloakは、対象のアイデンティティー・プロバイダーに認証を要求する認証リクエストを発行し、ユーザーをアイデンティティー・プロバイダーのログインページにリダイレクトします。管理者は、管理コンソールのアイデンティティー・プロバイダーの接続プロパティーやその他の設定オプションをすでに設定しています。
-
ユーザーはアイデンティティー・プロバイダーを認証するためのクレデンシャルまたは同意を提供します。
-
アイデンティティー・プロバイダーによる認証が成功すると、ユーザーは認証レスポンスとともにKeycloakにリダイレクトして戻ります。通常、このレスポンスにはKeycloakがアイデンティティー・プロバイダーの認証を信頼してユーザー情報を取得するために使用するセキュリティー・トークンが含まれています。
-
Keycloakは、アイデンティティー・プロバイダーからのレスポンスが有効かどうかをチェックします。有効であれば、Keycloakは、ユーザーがまだ存在していない場合、ユーザーをインポートして作成します。Keycloakは、トークンにユーザー情報が含まれていない場合、アイデンティティー・プロバイダーにさらなるユーザー情報を求めることがあります。この動作が アイデンティティー・フェデレーション です。 ユーザーがすでに存在している場合、Keycloakは、アイデンティティー・プロバイダーから返されたアイデンティティーを既存のアカウントとリンクさせるようユーザーに求めることがあります。この動作は アカウント・リンキング です。Keycloakでは、_アカウント・リンキング_を設定し、First Login Flowで指定します。この段階で、Keycloakはユーザーを認証し、サービス・プロバイダーで要求されたリソースにアクセスするためのトークンを発行します。
-
ユーザーが認証されると、Keycloakは、ローカル認証時に以前に発行されたトークンを送信して、ユーザーをサービス・プロバイダーにリダイレクトします。
-
サービス・プロバイダーは Keycloakからトークンを受け取り、保護されたリソースへのアクセスを許可します。
このフローのバリエーションは可能です。たとえば、クライアント・アプリケーションは、特定のアイデンティティー・プロバイダーのリストを表示するのではなく、特定のアイデンティティー・プロバイダーを要求することができます。また、Keycloakを設定して、アイデンティティーを連携させる前にユーザーに追加情報の提供を強制することもできます。
認証プロセスの最後に、Keycloakはそのトークンをクライアント・アプリケーションに発行します。クライアント・アプリケーションは外部の アイデンティティー・プロバイダーとは別のものなので、クライアント・アプリケーショ ンのプロトコルや、ユーザーのアイデンティティーをどのように検証するかを見ることはできません。プロバイダーは Keycloakのことだけを知っていればよいのです。
デフォルトのアイデンティティー・プロバイダー
Keycloakは、ログイン画面を表示するのではなく、アイデンティティー・プロバイダーにリダイレクトすることができます。このリダイレクトを有効にするには以下を行います。
-
メニューの Authentication をクリックします。
-
Browser フローをクリックします。
-
ドロップダウン・リストから Identity Provider Redirector を選択します。
-
Default Identity Provider に、ユーザーをリダイレクトしたいアイデンティティー・プロバイダーを設定します。
Keycloakが設定されたデフォルトのアイデンティティー・プロバイダーを見つけられない場合は、ログイン画面が表示されます。
このオーセンティケーターは、 kc_idp_hint
のクエリー・パラメーターの処理を担当します。詳細はクライアント提案のアイデンティティー・プロバイダーのセクションを参照してください。
一般的な構成
アイデンティティー・ブローカーの設定の基礎となるのは、アイデンティティー・プロバイダー(IDP)です。Keycloakは、各レルムに対して アイデンティティー・プロバイダーを作成し、デフォルトですべてのアプリケーションに対して有効にします。レルムのユーザーは、アプリケーションにサインインする際に、登録されたアイデンティティー・プロバイダーのいずれかを使用できます。
-
メニューの Identity Providers をクリックします。
アイデンティティー・プロバイダー -
Add provider
のリストから、追加したいアイデンティティー・プロバイダーを選択します。Keycloakは、選択したアイデンティティー・プロバイダーの設定ページを表示します。facebookアイデンティティー・プロバイダーの追加アイデンティティー・プロバイダーを設定すると、Keycloakのログイン画面にアイデンティティー・プロバイダーがオプションとして表示されます。ログイン画面には、アイデンティティー・プロバイダーごとにカスタムアイコンを配置できます。詳しくは カスタムアイコン を参照してください。
IDPログイン・ページ- ソーシャル
-
ソーシャル・プロバイダーは、あなたのレルムでソーシャル認証を可能にします。Keycloakを使用すると、ユーザーはソーシャル・ネットワーク・アカウントを使用してアプリケーションにログインできます。サポートされているプロバイダーは、Twitter、Facebook、Google、LinkedIn、Instagram、Microsoft、PayPal、Openshift v3、GitHub、GitLab、Bitbucket、Stack Overflowです。
- プロトコル・ ベース
-
プロトコルベースのプロバイダーは、特定のプロトコルに依存してユーザーの認証と認可を行います。これらのプロバイダーを使用することで、特定のプロトコルに準拠した任意のアイデンティティー・プロバイダーに接続することができます。Keycloakは、SAML v2.0およびOpenID Connect v1.0プロトコルに対応しています。これらのオープンスタンダードに基づいて、任意のアイデンティティー・プロバイダーを設定し、仲介することができます。
アイデンティティー・プロバイダーの種類ごとに設定オプションがありますが、すべてのタイプに共通する設定があります。以下の設定オプションが利用可能です。
設定 | 説明 |
---|---|
Alias |
エイリアスは、アイデンティティー・プロバイダーの一意の識別子であり、内部のアイデンティティー・プロバイダーを参照します。Keycloakは、エイリアスを使用して、アイデンティティー・プロバイダーとの通信にリダイレクトURIまたはコールバックURLを必要とするOpenID ConnectプロトコルのリダイレクトURIを構築します。すべてのアイデンティティー・プロバイダーにはエイリアスが必要です。エイリアスの例としては、 |
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でログインするには、以下の手順で行います。
-
メニューの Identity Providers をクリックします。
-
Add provider
の一覧からBitbucket
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
ブラウザーの別のタブで、 OAuth on Bitbucket Cloud の処理を行います。 Add Consumer をクリックすると
-
Callback URL フィールドに Redirect URI の値を貼り付けてください。
-
アプリケーションがメールを読むことを許可するために、Account セクションで Email と Read を選択していることを確認してください。
-
-
コンシューマーを作成する際に Bitbucket が表示する
Key
とSecret
の値に注意してください。 -
Keycloakでは、
Key
の値を Client ID フィールドに貼り付けます。 -
Keycloakでは、
Secret
の値を Client Secret フィールドに貼り付けます。 -
Save をクリックします。
-
メニューの Identity Providers をクリックします。
-
Add provider
の一覧からFacebook
を選択します。KeycloakはFacebookのアイデンティティー・プロバイダーの設定ページを表示します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
別のブラウザータブで、 Facebook Developer Guide の指示に従って、Facebookでプロジェクトとクライアントを作成します。
-
アプリがWebサイトタイプのアプリであることを確認します。
-
Facebookの
Website
設定ブロックのSite URL
に、 Redirect URI の値を入力します。 -
アプリが公開されていることを確認します。
-
-
Client ID
andClient Secret
の値をFacebookアプリからKeycloakのClient ID
とClient Secret
のフィールドに入力します。 -
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でログインするには、以下の手順で行います。
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからGithub
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
別のブラウザータブで、 create an OAUTH app を実行します。
-
アプリの作成時に、
Authorization callback URL
フィールドに Redirect URI の値を入力してください。 -
OAUTHアプリの管理画面で、Client IDとClient secretをメモします。
-
-
Keycloakでは、
Client ID
の値を Client ID フィールドに貼り付けます。 -
Keycloakでは、
Client Secret
の値を Client Secret フィールドに貼り付けます。 -
Save をクリックします。
GitLab
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからGitLab
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
別のブラウザータブで、 add a new GitLab application を実行します。
-
クリップボードにある Redirect URI を Redirect URI として使用します。
-
アプリケーションを保存する際には、
Client ID
とClient Secret
をメモしてください。
-
-
Keycloakでは、
Client ID
の値を Client ID フィールドに貼り付けます。 -
Keycloakでは、
Client Secret
の値を Client Secret フィールドに貼り付けます。 -
Save をクリックします。
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからGoogle
を選択します。アイデンティティー・プロバイダーの追加 -
ブラウザーの別のタブで、 Google Cloud Platformのコンソール を開きます。
-
GoogleアプリのGoogleダッシュボードで、 OAuth consent screen メニューをクリックします。同意画面を作成し、同意画面のユーザータイプが外部であることを確認します。
-
Googleのダッシュボードで以下を行います。
-
Credentials メニューをクリックします。
-
CREATE CREDENTIALS - OAuth Client ID をクリックします。
-
Application type の一覧から Web application を選択します。
-
Create をクリックします。
-
Your Client ID と Your Client Secret に注意してください。
-
-
Keycloakでは、Your Client ID の値を Client ID フィールドに貼り付けます。
-
Keycloakでは、Your Client Secret の値を Client Secret フィールドに貼り付けます。
-
Default Scopes の欄に必要なスコープを入力してください。デフォルトでは、Keycloakは
openid
、profile
、email
のスコープを使用します。Googleのスコープの一覧は、 OAuth Playground を参照してください。 -
GSuite組織のメンバーのみにアクセスを制限するには、
Hosted Domain
フィールドにG Suiteドメインを入力します。 -
Save をクリックします。
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからLinkedIn
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
別のブラウザータブで、 create an app を実行します。
-
アプリを作成した後、 Auth タブをクリックします。
-
Authorized redirect URLs for your app フィールドに、 Redirect URI の値を入力してください。
-
Your Client ID と Your Client Secret に注意してください。
-
-
Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。
-
Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。
-
Save をクリックします。
Microsoft
-
メニューの Identity Providers をクリックします。
-
Add provider
の一覧からMicrosoft
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
別のブラウザータブで、 create a Microsoft app を実行します。
-
Add URL をクリックして、MicrosoftアプリにリダイレクトURLを追加します。
-
Application ID と Application Secret に注意してください。
-
-
Keycloakでは、Application ID の値を Client ID フィールドに貼り付けます。
-
Keycloakでは、Application Secret の値を Client Secret フィールドに貼り付けます。
-
Save をクリックします。
OpenShift 3
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからOpenshift
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
コマンドライン・ツール
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が使用します 。
|
OpenShift 4
-
jq のインストール。
-
コンテナーに設定された
X509_CA_BUNDLE
には、/var/run/secrets/kubernetes.io/serviceaccount/ca.crt
が設定されています。
-
コマンドラインで以下のコマンドを実行し、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"
-
Keycloakのメニューの Identity Providers をクリックします。
-
Add provider
のリストからOpenshift
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
コマンドライン・ツール
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が使用します 。
|
詳しくは、 OpenShiftの公式ドキュメント を参照してください。
PayPal
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからPayPal
を選択します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
別のブラウザータブで、 PayPal Developer applications area を開きます。
-
Create App をクリックして、PayPalアプリを作成します。
-
クライアントIDとクライアント・シークレットを確認します。 Show のリンクをクリックするとシークレットが表示されます。
-
Connect with PayPal がチェックされていることを確認してください。
-
Keycloakから取得した Redirect URI の値を*Return URL* フィールドに設定します。
-
-
Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。
-
Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。
-
Save をクリックします。
スタックオーバーフロー
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからStack Overflow
を選択します。アイデンティティー・プロバイダーの追加 -
別のブラウザータブで、 Stack Appsにアプリケーションを登録 にログインします。
アプリケーションの登録-
Application Name フィールドにアプリケーション名を入力してください。
-
OAuth Domain フィールドにOAuthドメインを入力してください。
-
Register Your Application をクリックします。
設定
-
-
Client ID と Client Secret に注意してください。
-
Keycloakでは、Client ID の値を Client ID フィールドに貼り付けます。
-
Keycloakでは、Client Secret の値を Client Secret フィールドに貼り付けます。
-
Save をクリックします。
-
Twitterの開発者アカウントです。
-
メニューの Identity Providers をクリックします。
-
Add provider "のリストから "Twitter "を選択します。
アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
ブラウザーの別のタブで Twitter Application Management を開き、アプリを作成します。
-
nameとdescriptionには任意の値を入力してください。
-
Website の値には、
localhost
を除く任意の有効なURLを指定します。 -
Redirect URL の値を Callback URL フィールドに貼り付けてください。
-
Twitterアプリを作成する際は、 Keys and Access Tokens のセクションの Consumer Secret と Keys and Access Tokens の値に注意してください。
-
-
Keycloakでは、 Client ID フィールドに Consumer Key の値を貼り付けます。
-
Keycloakでは、 Client Secret フィールドに Consumer Secret の値を貼り付けます。
-
Save をクリックします。
-
メニューの Identity Providers をクリックします。
-
Add provider
の一覧からInstagram
を選択します。KeycloakはInstagramのアイデンティティー・プロバイダーの設定ページを表示します。アイデンティティー・プロバイダーの追加 -
Redirect URI* の値をクリップボードにコピーしてください。
-
別のブラウザータブで、 Facebook Developer Console を開きます。
-
My Apps をクリックします。
-
Add a New App を選択します。
Add a new app -
For Everything Else
を選択します。新規アプリIDの作成 -
必須項目をすべて入力してください。
-
Create App をクリックすると、Facebookはダッシュボードを表示します。
-
ナビゲーション・パネルで、 Settings - Basic を選択します。
プラットフォームの追加 -
*+ Add Platform*を選択します。
-
[Website] をクリックします。
-
あなたのサイトのURLを入力してください。
製品の追加 -
メニューから
Dashboard
を選択します。 -
Instagramのボックスにある Set Up をクリックします。
-
メニューから Instagram - Basic Display を選択します。
-
Create New App をクリックします。
インスタグラムのアプリIDを新規に作成します。 -
Display Name に値を入力してください。
アプリの設定 -
Keycloakの Redirect URL を Valid OAuth Redirect URIs フィールドに貼り付けてください。
-
Keycloakの Redirect URL を Deauthorize Callback URL フィールドに貼り付けてください。
-
Keycloakの Redirect URL を Data Deletion Request URL フィールドに貼り付けてください。
-
Instagram App Secret フィールドの Show をクリックします。
-
Instagram App ID と Instagram App Secret に注意してください。
-
App Review - Requests をクリックします。
-
画面の指示に従ってください。
-
-
Keycloakでは、Instagram App ID の値を Client ID フィールドに貼り付けます。
-
Keycloakでは、 Instagram App Secret の値を Client Secret フィールドに貼り付けます。
-
Save をクリックします。
OpenID Connect v1.0アイデンティティー・プロバイダー
Keycloakは、OpenID Connectプロトコルに基づくアイデンティティー・プロバイダーを仲介します。これらのアイデンティティー・プロバイダー(IDP)は、ユーザーを認証してアクセスを許可するために、仕様で定義されている 認可コードフロー をサポートする必要があります。
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからOpenID Connect v1.0
を選択します。アイデンティティー・プロバイダーの追加 -
初期設定のオプションを入力します。設定オプションの詳細は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 IDPの公開鍵を知っている必要があります。パフォーマンスのために、Keycloakは外部のOIDCアイデンティティー・プロバイダーの公開鍵をキャッシュします。アイデンティティー・プロバイダーの秘密鍵が漏洩した場合は、鍵を更新し、鍵キャッシュをクリアします。詳細については、キャッシュのクリアのセクションを参照してください。
Use JWKS URL
このスイッチは、
Validate Signatures
が ON の場合に適用されます。 Use JWKS URL が ON の場合、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/auth/realms/test/protocol/openid-connect/certs のような URL を使用することができます。Validating Public Key
Keycloakが外部IDPの署名を検証するために使用するPEM形式の公開鍵です。この鍵は、
Use JWKS URL
が OFF の場合に適用されます。Validating Public Key Id
この設定は、 Use JWKS URL が OFF の場合に適用されます。この設定では、公開鍵のIDをPEM形式で指定します。鍵から鍵IDを計算する標準的な方法がないため、外部のアイデンティティー・プロバイダーはKeycloakが使用するものとは異なるアルゴリズムを使用できます。このフィールドの値が指定されていない場合、Keycloakは、外部のIDPから送信された鍵IDに関係なく、すべてのリクエストに検証用の公開鍵を使用します。 ON の場合、このフィールドの値はKeycloakがプロバイダーからの署名を検証するために使用する鍵IDであり、IDPが指定する鍵IDと一致しなければなりません。
OpenID Provider Metadataを指し示すURLやファイルを提供することで、これらの設定データをすべてインポートすることができます。Keycloakの外部IDPに接続する場合は、 <root>/auth/realms/{realm-name}/.well-known/openid-configuration
からIDPの設定をインポートできます。このリンクは、IDPに関するメタデータを記述したJSONドキュメントです。
SAML v2.0アイデンティティー・プロバイダー
Keycloakは、SAML v2.0プロトコルに基づいて、アイデンティティー・プロバイダーを仲介できます。
-
メニューの Identity Providers をクリックします。
-
Add provider
のリストからSAML v2.0
を選択します。アイデンティティー・プロバイダーの追加 -
初期設定のオプションを入力します。設定オプションの詳細はGeneral IDP Configurationを参照してください。 .SAML Config
設定 | 説明 |
---|---|
Service Provider Entity ID |
リモートのアイデンティティー・プロバイダーが、このサービス・プロバイダーからのリクエストを識別するために使用するSAMLエンティティーID。デフォルトでは、この設定はレルムベースのURL |
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 が |
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 Signed が ON の場合、使用する署名アルゴリズムを指定します。 |
SAML Signature Key Name |
POST バインディングで送信される署名付き 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} が |
Attribute Consuming Service Index |
リモートIdPに要求する属性セットを特定します。Keycloakは、アイデンティティー・プロバイダー構成にマッピングされた属性を、自動生成されたSPメタデータ・ドキュメントに自動的に追加します。 |
Attribute Consuming Service Name |
自動生成されるSPメタデータ・ドキュメントで提示される一連の属性の説明的な名前です。 |
外部 IDP の SAML IDP エンティティ記述子を指す URL またはファイルを指定することで、すべての構成データをインポートすることができる。プロジェクト名}の外部IDPに接続している場合、URL /auth/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 プロバイダは追加の制約を適用しません。
設定 | 説明 |
---|---|
Comparison |
アイデンティティー・プロバイダーがコンテキストの要件を評価するために使用する方法です。使用可能な値は |
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}/auth/realms/{realm-name}/broker/{broker-alias}/endpoint/descriptor
ディスクリプターにアクセスする前に、設定変更を保存していることを確認してください。
SAMLリクエストでサブジェクトを送信する
デフォルトでは、SAML ID プロバイダを指すソーシャルボタンは、ユーザを以下のログイン URL にリダイレクトする。
http[s]://{host:port}/auth/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
アダプターを使用している場合は、以下のようにして同じ動作を実現できます。
var 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データベースにエントリーを持ちます。
-
メニューの Identity Providers をクリックします。
-
リストの中からいずれかのアイデンティティー・プロバイダーを選択します。
-
Mappers タブをクリックします。
アイデンティティー・プロバイダー・マッパー -
Create をクリックします。
アイデンティティー・プロバイダー・マッパー -
Sync Mode Override の値を選択します。マッパーは、ユーザーが繰り返しログインする際に、この設定に従ってユーザー情報を更新します。
-
前のバージョンのKeycloakの動作を使用するには、 legacy を選択してください。
-
特定のアイデンティティー・プロバイダーを使用してKeycloakに初めてログインした際に、Keycloakにユーザーが初めて作成された時のデータをインポートする場合は、 import を選択します。
-
ユーザーがログインするたびにユーザーデータを更新する場合は、 force を選択します。
-
アイデンティティー・プロバイダーで設定された同期モードを使用するには、 inherit を選択します。他のすべてのオプションは、この同期モードを上書きします。
-
-
Mapper Type のリストからマッパーを選択します。 Mapper Type にカーソルを合わせると、マッパーの説明とマッパーに入力する設定が表示されます。
-
Save をクリックします。
JSONベースのクレームの場合、入れ子にはドット記法、配列のフィールドにインデックスでアクセスするには角括弧を使います。たとえば、 contact.address[0].country
のようになります。
ソーシャル・プロバイダーが提供するユーザー・プロフィールのJSONデータの構造を調査するには、サーバーのapp-server設定ファイル(domain.xmlまたはstandalone.xml)で、 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がユニークなユーザーを扱うことを保証します。オーセンティケーターの要件を Alternative に設定します。
- Automatically Set Existing User
-
このオーセンティケーターは、既存のユーザーを検証なしで認証コンテキストに設定します。オーセンティケーターの要件を "Alternative" に設定します。
この設定は最もシンプルなものですが、他のオーセンティケーターを使用することも可能です。例: * エンドユーザーに自分のプロフィール情報を確認させたい場合は、フローの最初にReview Profileオーセンティケーターを追加することができます。 * このフローに認証メカニズムを追加して、ユーザーにクレデンシャルの確認を強制することもできます。認証メカニズムを追加するには、複雑なフローが必要です。たとえば、"Alternative"サブフローで"Automatically Set Existing User"と"Password Form"を"Required"に設定します。 |
ユーザーの自動作成を無効にする
デフォルトの初回ログインフローは、外部のアイデンティティーに一致するKeycloakアカウントを検索し、それらのリンクを提案します。一致するKeycloakアカウントが存在しない場合、フローは自動的にアカウントを作成します。
このデフォルトの動作は、いくつかのセットアップには適していないかもしれません。たとえば、読み取り専用のLDAPユーザーストアを使用していて、すべてのユーザーがあらかじめ作成されている場合です。このような場合には、ユーザーの自動作成をオフにする必要があります。
ユーザーの作成を無効にするには、以下を行います。
-
メニューの Authentication をクリックします。
-
リストから First Broker Login を選択します。
-
Create User If Unique を DISABLED に設定してください。
-
Confirm Link Existing Account を DISABLED に設定してください。
この設定は、Keycloak自体が、外部アイデンティティーに対応する内部アカウントを判別できないことも意味します。したがって、 Verify Existing Account By Re-authentication
オーセンティケーターは、ユーザーにユーザー名とパスワードの両方を提供するように要求します。
既存ユーザーの初回ログインフローの検出
次のような最初のログインフローを設定するには、
-
このレルムにすでに登録されているユーザーのみがログインできる
-
ユーザーはプロンプトなしで自動的にリンクされる
次の2つのオーセンティケーターを使用して新しいフローを作成します。
- 既存のブローカー・ユーザーを検出する
-
このオーセンティケーターは、一意にユーザーが処理されることを保障します。オーセンティケーターの要件は
Mandatory
に設定します。 - Automatically Set Existing User
-
検証なしで、既存のユーザーを認証コンテキストに自動的に設定します。オーセンティケーターの要求は
Mandatory
に設定します。
アイデンティティー・プロバイダーの設定の First Login Flow
にそのフローを設定する必要があります。アイデンティティー・プロバイダーの属性を使用してユーザー・プロファイル(姓、名など)を更新する場合は、 Sync Mode
を force
に設定することもできます。
このフローは、IDを他のアイデンティティー・プロバイダー(github、facebookなど)に委任したいが、ログインできるユーザーを管理したい場合に使用できます。 |
この設定では、Keycloakは、どの内部アカウントが外部アイデンティティーに対応するかを判断できません。 Verify Existing Account By Re-authentication オーセンティケーターは、プロバイダーにユーザー名とパスワードを要求します。
外部IDPトークンの取得
Keycloakでは、IDPの設定ページにある Store Token
という設定オプションを使って、外部IDPでの認証プロセスから得たトークンとレスポンスを保存することができます。
アプリケーション・コードは、これらのトークンとレスポンスを取得して、追加のユーザー情報をインポートしたり、外部のIDPを安全に要求したりすることができます。たとえば、アプリケーションはGoogleトークンを使用して、他のGoogleサービスやREST APIを使用することができます。特定のアイデンティティー・プロバイダーのトークンを取得するには、次のようなリクエストを送信します。
GET /auth/realms/{realm}/broker/{provider_alias}/token HTTP/1.1
Host: localhost:8080
Authorization: Bearer <KEYCLOAK ACCESS TOKEN>
アプリケーションはKeycloakで認証を行い、アクセストークンを受け取る必要があります。このアクセストークンには、 broker
クライアントレベル・ロールの read-token
が設定されていなければなりません。したがって、ユーザーはこのロールに対応するロールマッピングを持っている必要があり、クライアント・アプリケーションはそのスコープ内にそのロールを持っている必要があります。この場合、Keycloakの保護されたサービスにアクセスしているので、ユーザー認証の際にKeycloakが発行したアクセストークンを送信します。ブローカー設定ページで、 Stored Tokens Readable スイッチを 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トークン および アクセストークン を取得します。
-
ユーザーがブラウザーを使ってアプリケーションにアクセスします。アプリケーションは、ユーザーがアプリケーションにログインしていないことを検出します。
-
アプリケーションは、認証のためにブラウザーをKeycloakにリダイレクトします。
-
アプリケーションは、ブラウザーのリダイレクトのクエリー・パラメーターとしてコールバックURLを渡します。Keycloakは、認証に成功するとそのパラメーターを使用します。
-
Keycloakは、ユーザーを認証し、1回限りの短命の一時的なコードを作成します。
-
Keycloakは、コールバックURLを用いてアプリケーションにリダイレクトし、コールバックURLのクエリー・パラメーターとして一時コードを追加します。
-
アプリケーションは一時的なコードを抽出し、バックグラウンドで Keycloak に REST 呼び出しを行い、コードを identity および access と refresh トークンに交換します。 リプレイ攻撃を防ぐため、一時的なコードを複数回使用することはできません。
システムは、盗まれたトークンの有効期間中、そのトークンに対して脆弱です。セキュリティーとスケーラビリティーの観点から、アクセストークンは一般にすぐに期限切れになるように設定されており、それ以降のトークンリクエストには失敗します。トークンの有効期限が切れた場合、アプリケーションはログイン・プロトコルによって送信される追加の リフレッシュ トークンを使用して新しいアクセストークンを取得することができます。 |
コンフィデンシャル ・クライアントは、一時的なコードをトークンに交換する際にクライアント・シークレットを提供します。パブリック・クライアントは、クライアント・シークレットの提供は必要ありません。パブリック・クライアントは、HTTPSを厳密に実施し、クライアントに登録されるリダイレクトURIを厳密に管理することで安全性を確保します。HTML5/JavaScriptクライアントは、クライアント・シークレットを安全に送信する方法がないため、 パブリック クライアントである必要があります。詳しくは クライアントの管理 の章を参照してください。
Keycloakは、 Proof Key for Code Exchange の仕様にも対応しています。
インプリシット・フロー
インプリシット・フローは、ブラウザーベースのプロトコルです。認可コードフローと似ているが、リクエスト数が少なく、リフレッシュ・トークンもありません。
トークンをリダイレクトURIで送信する場合、 アクセス トークンがブラウザーの履歴に漏れる可能性があります(下記参照)。 また、このフローでは、クライアントにリフレッシュトークンを提供しません。したがって、アクセストークンは長寿命でなければならず、また、アクセストークンの有効期限が切れると、ユーザーは再認証をしなければならない。 このフローを使用することはお勧めしません。このフローがサポートされているのは、OIDCとOAuth 2.0の仕様に含まれているからです。 |
プロトコルは次のように動作します。
-
ユーザーがブラウザーを使ってアプリケーションにアクセスします。アプリケーションは、ユーザーがアプリケーションにログインしていないことを検出します。
-
アプリケーションは、認証のためにブラウザーをKeycloakにリダイレクトします。
-
アプリケーションは、ブラウザーのリダイレクトにコールバックURLをクエリー・パラメーターとして渡します。Keycloakは、認証に成功すとクエリー・パラメーターを使用します。
-
Keycloakは、ユーザーを認証し、 ID トークンと アクセス トークンを作成します。KeycloakはコールバックURLを使用してアプリケーションにリダイレクトし、さらに ID トークンと アクセス トークンをコールバックURLのクエリー・パラメーターとして追加します。
-
アプリケーションは、コールバックURLから ID トークンと アクセス トークンを抽出します。
リソース・オーナー・パスワード・クレデンシャル・グラント(Direct Access Grants)
Direct Access Grants は、RESTクライアントがユーザーの代わりにトークンを取得するために使用されます。これは、HTTP POSTリクエストで、以下を含みます。
-
ユーザーのクレデンシャル。クレデンシャルはフォームのパラメーターで送信されます。
-
クライアントのID。
-
クライアントのシークレット(コンフィデンシャル・クライアントの場合)。
HTTP レスポンスには、 ID トークン、 アクセス トークン、 リフレッシュ トークンが含まれます。
クライアント・クレデンシャル・グラント
クライアント・クレデンシャル・グラント は、外部ユーザーの代わりに動作するトークンを取得するのではなく、クライアントに関連付けられたサービス・アカウントのメタデータとパーミッションに基づいてトークンを作成します。 クライアント・クレデンシャル・グラント は REST クライアントによって使用されます。
詳しくはサービス・アカウントの章を参照してください。
デバイス認可グラント
これは、入力機能が制限されているか、適切なブラウザーがない、インターネットに接続されたデバイスで実行されているクライアントによって使用されます。プロトコルの簡単な概要は次のとおりです。
-
アプリケーションはKeycloakにデバイスコードとユーザーコードを要求します。Keycloakは、デバイスコードとユーザーコードを作成します。Keycloakは、デバイス コードとユーザーコードを含むレスポンスをアプリケーションに返します。
-
アプリケーションは、ユーザーコードと検証URIをユーザーに提供します。ユーザーは、別のブラウザーを使用して、認証を受けるための検証URIにアクセスします。
-
アプリケーションはKeycloakを繰り返しポーリングして、ユーザーがユーザー認証を完了したかどうかを調べます。ユーザー認証が完了すると、アプリケーションはデバイス コードを ID トークン、 access トークン、 および refresh トークンと交換します。
クライアント起点バックチャネル認証グラント
この機能は、OAuth 2.0の認可コードグラントのようにユーザーのブラウザーを通してリダイレクトすることなく、OpenIDプロバイダーと直接通信して認証フローを開始させたいクライアントが使用します。以下はプロトコルの概要です。
-
クライアントは、クライアントによって行われた認証リクエストを識別するauth_req_idをKeycloakに要求します。Keycloakはauth_req_idを作成します。
-
この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つのプロバイダーを使用します。
-
認証チャネル・プロバイダー:Keycloakと、AD(Authentication Device)を介してユーザーを実際に認証するエンティティーとの間の通信を提供します。
-
User Resolver Provider:クライアントから提供された情報からKeycloakの
UserModel
を取得して、ユーザーを識別します。
Keycloakには両方のデフォルト・プロバイダーがあります。ただし、管理者は次のように認証チャネル・プロバイダーを設定する必要があります。
<spi name="ciba-auth-channel">
<default-provider>ciba-http-auth-channel</default-provider>
<provider name="ciba-http-auth-channel" enabled="true">
<properties>
<property name="httpAuthenticationChannelUri" value="https://backend.internal.example.com/auth"/>
</properties>
</provider>
</spi>
設定可能な項目とその説明は次のとおりです。
設定 | 説明 |
---|---|
httpAuthenticationChannelUri |
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によって認証された認証エンティティーに通知します。 |
scope |
認証エンティティーが認証されたユーザーから同意を得るスコープを示します。 |
is_consent_required |
認証エンティティーがスコープについて認証されたユーザーから同意を得る必要があるかどうかを示します。 |
binding_message |
その値は、CDとADのUIの両方に表示され、ADによる認証がCDによってトリガーされたことをユーザーに認識させることを目的としています。 |
acr_values |
CDから要求している認証コンテキストクラス参照を通知します。 |
- Authentication Delegation Response
-
認証エンティティーからKeycloakにレスポンスが返され、認証エンティティーがKeycloakから認証リクエストを受信したことが通知されます。
-
Responses
-
HTTPステータスコード | 説明 |
---|---|
201 |
認証委任リクエストを受信したことをKeycloakに通知します。 |
認証結果通知/ACKは以下のメッセージで構成されています。
- 認証結果通知
-
認証エンティティーは、認証リクエストの結果をKeycloakに送信します。
POST /auth/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によるユーザー認証の結果を示します。 |
- 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には、ログアウト機構に関連する3つの異なる仕様があり、これらはすべて現在ドラフトの状態です。
繰り返しになりますが、これはすべてOIDCの仕様で説明されているため、ここでは簡単な概要のみを示します。
Session Management
これはブラウザーベースのログアウトです。アプリケーションは、定期的にKeycloakからセッション・ステータス情報を取得します。セッションがKeycloakで終了すると、アプリケーションはそれに気づき、自身のログアウトをトリガーします。
Frontchannel Logout
これもブラウザー・ベースのログアウトで、ログアウトが始まると、ユーザーはKeycloakの特定のエンドポイントにリダイレクトされます。
ユーザーがログアウト・エンドポイントにリダイレクトされると、Keycloakはクライアントにログアウト・リクエストを送信して、ローカル・ユーザー・セッションを無効にし、ログアウト・プロセスが終了したらユーザーを何らかのURLにリダイレクトするようにします。
クライアントの設定により、ログアウト・リクエストは、フロントチャネルを介してクライアントに送信される場合と、バックチャネルを介して送信される場合があります。
フロントチャネルでログアウト・リクエストを受信するようにクライアントを設定するには、Front-Channel Logoutのクライアントの設定を見てください。この方法を使用する場合、以下の点を考慮してください。
-
Keycloakがクライアントに送信するログアウト・リクエストは、ブラウザーと、ログアウトページでレンダリングされる埋め込みの
iframe
に依存しています。 -
フロントチャネルのログアウトは、
iframe
に基づいているため、コンテンツ・セキュリティー・ポリシー(CSP)の影響を受け、ログアウト・リクエストがブロックされる可能性があります。 -
ログアウトページを表示する前、またはログアウト・リクエストが実際にクライアントに送信される前にユーザーがブラウザーを閉じた場合、クライアントでのセッションが無効にならない可能性があります。
ユーザーをログアウトさせ、クライアント上のセッションを終了させるには、より信頼性が高く安全な方法であるバックチャネル・ログアウトの使用を検討してください。 |
クライアントがフロントチャネル・ログアウトを有効にしていない場合、KeycloakはまずBack-Channel Logout URLを使ってバックチャネルでログアウト・リクエストを送ろうとします。<_back-channel-logout-url, Back-Channel Logout URL>定義されていない場合、サーバーはAdmin URLの使用に戻ります。
KeycloakサーバーのOIDC URIエンドポイント
Keycloakが公開しているOIDCエンドポイントの一覧を以下に示します。これらのエンドポイントは、Keycloak以外のクライアント・アダプターがOIDCを用いて認証サーバーと通信する際に利用することができます。これらはすべて相対URLです。URLのルートは、HTTP(S)プロトコル、ホスト名、パスからなり、通常 /auth が先頭に付きます。たとえば、以下です。
https://localhost:8080/auth
- /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
-
デバイス認可グラントで、デバイスコードとユーザーコードを取得するために使用します。
いずれも{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を使用して情報を交換します。
-
あるユーザーがブラウザーを使ってアプリケーションに接続します。アプリケーションは、ユーザーが認証されていないことを検出します。
-
アプリケーションはXML認証要求文書を生成し、URIのクエリー・パラメーターとしてエンコードします。このURIは、Keycloakサーバーへのリダイレクトに使用されます。設定によっては、アプリケーションはXMLドキュメントにデジタル署名し、その署名をKeycloakへのリダイレクトURIのクエリー・パラメーターとして含めることもできます。この署名は、リクエストを送信したクライアントを検証するために使用されます。
-
ブラウザーはKeycloakにリダイレクトされます。
-
サーバーはXML認証要求文書を抽出し、必要であれば電子署名を検証します。
-
ユーザーは認証クレデンシャルを入力します。
-
認証後、サーバーはXML認証応答文書を生成します。この文書には、名前、住所、電子メール、およびユーザーが持つすべてのロールマッピングなど、ユーザーに関するメタデータを保持するSAMLアサーションが含まれます。この文書は、通常、XML署名を使用してデジタル署名され、暗号化されることもあります。
-
XML認証応答文書は、リダイレクトURIのクエリー・パラメーターとしてエンコードされます。このURIにより、ブラウザーはアプリケーションに戻ります。デジタル署名もクエリー・パラメーターとして含まれます。
-
アプリケーションはリダイレクトURIを受け取り、XMLドキュメントを抽出します。
-
アプリケーションはレルムの署名を検証し、有効な認証応答を受け取っていることを確認します。SAMLアサーション内の情報は、アクセスの判断やユーザーデータの表示に使用されます。
POSTバインディング
POST バインディングは Redirect バインディングと似ていますが、 POST バインディングはGETリクエストの代わりにPOSTリクエストを使ってXMLドキュメントを交換します。 POST バインディングは、ドキュメントを交換する際にJavaScriptを使用して、ブラウザーがKeycloakサーバーやアプリケーションにPOSTリクエストを送信するようにします。HTTPは、JavaScriptが埋め込まれたHTMLフォームを含むHTMLドキュメントで応答します。ページがロードされると、JavaScriptは自動的にフォームを呼び出します。
2つの制約があるため、 POST バインディングを推奨します。
-
セキュリティー — Redirect バインディングにおいて、SAMLレスポンスはURLの一部となります。これは、ログにレスポンスを記録する可能性があるため、安全性が低いです。
-
サイズ — HTTPペイロードでドキュメントを送信することで、限られたURLで送信するよりも大量のデータに対してより広い範囲を提供します。
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 認証を有効にするには、Profiles を参照してください。 |
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で作成された各レルムには、そのレルムを管理できる専用の管理コンソールがあります。 master
レルムは、管理者がシステム上で複数のレルムを管理できる特別なレルムです。また、異なるレルム内のユーザーに対するきめ細かいアクセスを定義して、サーバーを管理することもできます。この章では、このシナリオのすべてについて説明します。
Masterレルムのアクセス・コントロール
Keycloakの master
レルムは特別なレルムであり、他のレルムとは異なる扱い方をされます。Keycloakの master
レルムのユーザーには、Keycloakサーバーにデプロイされている0個以上のレルムを管理するパーミッションを与えることができます。レルムが作成されると、Keycloakは新しいレルムにアクセスするためのきめ細かいパーミッションを与えるさまざまなロールを自動的に作成します。これらのロールを master
レルムのユーザーにマッピングすることで、管理コンソールおよび管理RESTエンドポイントへのアクセスを制御できます。特定のレルムだけを管理できるユーザーだけでなく、複数のスーパーユーザーを作成することも可能です。
グローバルロール
master
レルムには次の2つのレルムレベルのロールがあります。
-
admin
-
create-realm
admin
ロールを持つユーザーはスーパーユーザーであり、サーバー上のあらゆるレルムを管理する完全なアクセス権を持っています。 create-realm
ロールを持つユーザーは、新しいレルムを作成することができます。このユーザーは、自身が作成した全ての新しいレルムに対して、完全にアクセスできるようになります。
レルム特有のロール
master
レルム内の管理ユーザーは、システム内の1つ以上の他のレルムに対して管理権限を与えることができます。Keycloakの各レルムは、 master
レルムのクライアントによって表されます。クライアントの名前は <realm name>-realm
です。これらのクライアントには、個々のレルムを管理するためのさまざまなアクセスのレベルを定義したクライアントレベルのロールが定義されています。
利用可能なロールは次のとおりです。
-
view-realm
-
view-users
-
view-clients
-
view-events
-
manage-realm
-
manage-users
-
create-client
-
manage-clients
-
manage-events
-
view-identity-providers
-
manage-identity-providers
-
impersonation
ユーザーに必要なロールを割り当てると、管理コンソールの特定の部分のみを使用できます。
manage-users ロールを持つ管理者は、自分自身が管理するユーザーにのみ管理ロールを割り当てることができます。したがって、 manage-users ロールを持っていても、 manage-realm ロールを持っていない管理者は、このロールを割り当てることはできません。
|
レルム専用の管理コンソール
各レルムには専用の管理コンソールがあり、 /auth/admin/{realm-name}/console
のURLでアクセスできます。特定のユーザー・ロール・マッピングを割り当てることによって、そのレルム内のユーザーにレルム管理パーミッションを与えることができます。
各レルムには、 realm-management
という名前のビルトイン・クライアントがあります。レルムの左メニュー項目の Clients
をクリックすることでこのクライアントを見ることができます。このクライアントは、レルムを管理するパーミッションを指定するクライアントレベルのロールを定義します。
-
view-realm
-
view-users
-
view-clients
-
view-events
-
manage-realm
-
manage-users
-
create-client
-
manage-clients
-
manage-events
-
view-identity-providers
-
manage-identity-providers
-
impersonation
ユーザーに必要なロールを割り当てると、管理コンソールの特定の部分のみを使用できます。
きめ細かい管理パーミッション
Fine Grain Admin Permissionsは、 テクノロジー・プレビュー であり、完全にはサポートされていません。この機能はデフォルトで無効になっています。 有効にするには、 |
時には manage-realm
や manage-users
のようなロールより、きめ細かいパーミッションを持つ制限付き管理者アカウントを作成したいことがあります。Keycloakでは、レルムを管理するための制限付きアクセスポリシーを定義して割り当てることができます。アクセスポリシーには次のようなものがあります。
-
特定のクライアントの管理
-
特定のグループに属するユーザーの管理
-
グループのメンバーシップの管理
-
制限付きのユーザー管理
-
きめ細かい代理ログイン制御
-
特定の制約付きロールセットをユーザーに割り当てる
-
特定の制約付きロールセットを複合ロールに割り当てる
-
特定の制約付きロールセットをクライアントのスコープに割り当てる
-
ユーザー、グループ、ロール、およびクライアントの表示と管理のための新しい一般ポリシー
きめ細かい管理パーミッションについて、いくつか注意すべき点があります。
-
きめ細かい管理パーミッションは、認可サービス上に実装されています。きめ細かいパーミッションを設定する前に、それらの機能を読んでおくことを強くお勧めします。
-
きめ細かいパーミッションは、専用の管理コンソールおよびレルム管理者のみ使用できます。レルム間のきめ細かいパーミッションは、定義することはできません。
-
きめ細かいパーミッションは、追加のパーミッションを付与するために使用されます。組み込みの管理者ロールのデフォルトの動作を上書きすることはできません。
特定のクライアントの管理
最初に、管理者が1つのクライアントだけを管理できるようにしましょう。この例では、 test
というレルムと sales-application
というクライアントがあります。レルム test
では、レルムのユーザーに、そのアプリケーションだけを管理するパーミッションを与えます。
きめ細かいパーミッションはレルム間で使用することはできません。 master レルムの管理者は、前の章で定義されている組み込みの管理者ロールに限定されています。
|
パーミッションの設定
最初に、管理コンソールにログインして、クライアントのパーミッションを設定する必要があります。きめ細かいパーミッションを定義するクライアントの管理画面に移動します。
Permissions
というタブメニュー項目が表示されるので、そのタブをクリックします。
デフォルトでは、各クライアントはきめ細かいパーミッションが有効になっていません。 Permissions Enabled
スイッチをONにしてパーミッションを初期化してください。
Permissions Enabled スイッチをOFFにすると、このクライアントに対して定義したすべてのパーミッションが削除されます。
|
Permissions Enabled
をONにすると、認可サービスを使用してさまざまなパーミッション・オブジェクトを初期化します。ここでは、クライアントの manage
パーミッションを例にします。 manage
パーミッションのリンクをクリックすると、クライアントのパーミッション設定画面にリダイレクトされます。すべての認可オブジェクトは、 realm-management
クライアントの Authorization
タブに含まれています。
最初に初期化されたとき、 manage
パーミッションは関連付けられたポリシーを持ちません。ポリシータブに移動して作成する必要があります。ポリシータブにアクセスするには、上記の画像に表示されている Authorization
リンクをクリックしてください。次に、Policiesタブをクリックします。
このページには、 Create policy
というプルダウン・メニューがあります。このメニューには、定義することができる多くのポリシーがあります。ロールまたはグループに関連付けられたポリシーを定義したり、JavaScriptでルールを定義することもできます。この例では、 User Policy
を作成します。
このポリシーは、ユーザー・データベース内のハードコードされたユーザーと一致させます。この例では、 sales-admin
ユーザーです。次に、 sales-application
クライアントの manage
パーミッション・ページに戻り、ポリシーをパーミッション・オブジェクトに割り当てる必要があります。
sales-admin
ユーザーは、 sales-application
クライアントを管理するパーミッションを持つことができます。
また、Role Mappings
タブから、 sales-admin
に query-clients
ロールを割り当てる必要があります。
query-clients
ロールを割り当てる理由として、このロールは、 sales-admin
が管理コンソールを訪れたときに表示するメニュー項目を管理コンソールに伝えるためです。 query-clients
ロールは、管理コンソールに sales-admin
ユーザー用の表示すべきクライアント・メニューを伝えます。
重要な点として、 query-clients
ロールを設定しないと、 sales-admin
のような制限付きの管理者は、管理コンソールにログインするときにメニューオプションが表示されません。
テストする
次に、masterレルムからログアウトし、 sales-admin
ユーザーで test
レルムの専用の管理コンソールに再ログインします。専用の管理コンソールは /auth/admin/test/console
にあります。
この管理者はこの1つのクライアントを管理できるようになりました。
ユーザー・ロール・マッピングの制限
もう一つは、管理者がユーザーへの割り当てを許可したロールを制限することです。最後の例に続けて、 sales-admin
ユーザーのパーミッション・セットを拡張して、このアプリケーションにアクセスできるユーザーを制御できるようにしましょう。きめ細かいパーミッションを使用して、 sales-admin
が sales-application
に特定のアクセスを許可するロールのみを割り当てることができます。また、管理者だけがロールを割り当てることができ、その他のユーザー管理は実行できないように制限することもできます。
sales-application
には3つの異なるクライアント・ロールを定義しています。
sales-admin
ユーザーが、これらのロールをシステム内のどのユーザーにも割り当てられるようにしたいです。これを行うための最初のステップは、管理者によってロールを割り当て可能とすることです。 viewLeads
ロールをクリックすると、このロールの Permissions
タブがあります。
そのタブをクリックし、 Permissions Enabled
をONにすると、ポリシーを適用できるアクションが表示されます。
ここで知りたいのは map-role
です。このパーミッションをクリックし、前の例で作成したユーザーポリシーを追加します。
これまでに行ったことは、 sales-admin
が viewLeads
ロールを割り当て可能とすることです。これから行うことは、管理者がこのロールをどのように割り当てることができるかを指定することです。これを行うには、このレルムの管理コンソールの Users
セクションに移動する必要があります。左のメニュー項目の Users
をクリックすると、レルムのユーザー・インターフェイスが表示されます。 Permissions
タブから、 Permissions Enabled
をクリックして有効にします。
ここで知りたいパーミッションは map-roles
です。これは、管理者がロールをユーザーに割り当てる機能のみを許可するという点で、制限的なポリシーです。 map-roles
パーミッションをクリックし、これに対して作成したユーザーポリシーを再度追加すると、 sales-admin
はロールを任意のユーザーに割り当てることができます。
最後に、 view-users
ロールを sales-admin
に追加します。これにより、管理者は sales-application
ロールを追加したいレルムのユーザーを表示することができます。
テストする
次に、masterレルムからログアウトし、 sales-admin
ユーザーで test
レルムの専用の管理コンソールに再ログインします。専用の管理コンソールは /auth/admin/test/console
にあります。
sales-admin
がシステム内のユーザーを表示することができるようになりました。いずれかのユーザーを選択すると、 Role Mappings
タブを除き、各ユーザーの詳細ページは読み取り専用になります。このタブでは、管理者が sales-application
ロールを表示する場合を除いて、ユーザーに割り当てるための Available
ロールがないことがわかります。
sales-admin
が viewLeads
ロールの割り当てができることを指定しました。
クライアントごとのmap-rolesへのショートカット
sales-application
が公開したすべてのクライアント・ロールに対して、これを実行しなければならないのは面倒です。作業を簡単にするために、管理者がクライアントによって定義された任意のロールを割り当てられるように指定する方法があります。管理コンソールにログインしてmasterレルムの管理者でログインし、 sales-application
パーミッションページに戻ると、 map-roles
パーミッションが表示されます。
この特定のパーミッションへのアクセスを管理者に許可すると、その管理者はクライアントによって定義されたすべてのロールを割り当てることができます。
パーミッションの一覧
特定のクライアントやクライアントの特定のロールを管理する以外にも、きめ細かいパーミッションを使用すると、さらに多くのことを行うことができます。この章では、レルムで記述できるパーミッション種別の一覧を示します。
ロール
特定のロールの 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つのタイプのクライアントは、認証されたユーザーに代わって他のサービスを呼び出すために、アクセストークンを要求します。このセクションでは、クライアントの設定に関するさまざまな側面とそれを実行するさまざまな方法について説明します。
OIDCクライアント
OpenID Connect は、アプリケーションをセキュリティー保護するのに推奨されるプロトコルです。ウェブ・フレンドリーで、HTML5/JavaScriptアプリケーションで最もうまく動作するように、一から設計されました。
OpenID Connectクライアントの作成
OpenID Connectプロトコルを使用するアプリケーションを保護するために、クライアントを作成します。
-
メニューの Clients をクリックします。
-
Create をクリックすると、 Add Client のページに移動します。
Add client -
Client ID に任意の名前を入力します。
-
Client Protocol のドロップダウンボックスで、 openid-connect を選択します。
-
Root URL フィールドにアプリケーションのベースURLを入力します。
-
Save をクリックします。
この操作により、クライアントが作成され、 Settings タブが表示されます。
-
OIDCプロトコルの詳細については、 OpenID Connect を参照してください。
基本設定
OIDCクライアントを作成すると、 Settings タブに以下のフィールドが表示されます。
- Client ID
-
OIDCリクエストおよびKeycloakデータベースでクライアントを識別するために使用される英数字のID文字列です。
- Name
-
Keycloakにおけるクライアントの名前。UI画面での名称。名前をローカライズするには、置換文字列値を設定します。たとえば、${myapp}のような文字列値です。詳しくは、 Server Developer Guide を参照してください。
- 説明
-
クライアントの説明文です。この設定はローカライズすることも可能です。
- Enabled
-
オフにすると、クライアントは認証を要求できなくなります。
- Consent Required
-
オンにすると、ユーザーはそのアプリケーションへのアクセスを許可するために使用できる同意ページを見ることができます。また、クライアントがアクセスできる正確な情報をユーザーが知ることができるように、メタデータが表示されます。
- Access Type
-
OIDCクライアントの種類を表します。
- Confidential
-
ブラウザー・ログインを行い、アクセストークン・リクエストの際にクライアント・シークレットを要求するサーバーサイド・クライアント用。この設定は、サーバーサイドのアプリケーションで使用する必要があります。
- Public
-
ブラウザー・ログインを行うクライアントサイドのクライアント用。クライアントサイドのクライアントでは、シークレットの保持を確実に行うことができないため、正しいリダイレクトURIを設定することでアクセスを制限することが重要です。
- Bearer-only
-
このアプリケーションは、ベアラートークンの要求のみを許可します。オンにすると、このアプリケーションはブラウザーのログインに参加できなくなります。
- Standard Flow Enabled
-
有効にすると、クライアントはOIDC 認可コードフローを使用できるようになります。
- Implicit Flow Enabled
-
有効にすると、クライアントはOIDC インプリシット・フローを使用できるようになります。
- Direct Access Grants Enabled
-
有効にすると、クライアントはOIDC Direct Access Grants を使用することができます。
- OAuth 2.0 Device Authorization Grant Enabled
-
オンの場合、クライアントはOIDC Device認可グラント の利用が許可されます。
- OpenID Connect Client Initiated Backchannel Authentication Grant Enabled
-
これがオンの場合、クライアントは OIDC Client Initiated Backchannel Authentication Grantの使用を許可されます。
- Root URL
-
Keycloakが設定された相対URLを使用する場合、この値が先頭に追加されます。
- Valid Redirect URIs
-
必須項目です。URLパターンを入力し、 + で追加、 - で既存のURLを削除して Save をクリックします。URLパターンの末尾にワイルドカードを使用することができます。例) http://host.com/*
排他的リダイレクトURLパターンは、通常、より安全です。詳しくは Unspecific Redirect URIs を参照してください。
- Base URL
-
このURLは、 Keycloak がクライアントにリンクする必要がある場合に使用されます。
- Admin URL
-
クライアントのコールバック・エンドポイント。 サーバーはこのURLを使用して、取り消しポリシーのプッシュ、バックチャネル・ログアウトの実行、およびその他の管理操作などのコールバックを実行します。{project_name }サーブレット・アダプターの場合、このURLはサーブレット・アプリケーションのルートURLにすることができます。詳しくは、 Securing Applications and Services Guide を参照してください。
Logo URL
クライアント・アプリケーション用のロゴを参照するURL。
Policy URL
プロファイル・データがどのように使用されるかについて読むために、Relying Partyがエンドユーザーに提供するURL。
Terms of Service URL
Relying Partyが、エンドユーザーにRelying Partyの利用規約を提供するURL。
- 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 を参照してください。
- 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。省略された場合、ログアウト・リクエストはクライアントに送信されません。
詳細設定
詳細設定_をクリックすると、追加項目が表示されます。
OAuth 2.0 Mutual TLS Certificate Bound Access Tokens Enabled
KeycloakでMutual TLSを有効にするには、WildFlyでMutual SSLを有効にするを参照してください。 |
Mutual TLSは、アクセストークンとリフレッシュトークンを、TLSハンドシェイク中に交換されるクライアント証明書とともにバインドする。この結合により、攻撃者が盗んだトークンを使用することを防ぐことができます。
このタイプのトークンは、Holder-of-Keyトークンです。ベアラ・トークンと異なり、Holder-of-Key トークンの受信者は、トークンの送信者が正当であるかどうかを検証することができます。
この設定がオンの場合、ワークフローは次のようになります。
-
トークン・リクエストは、認可コード・フローまたはハイブリッド・フローでトークン・エンドポイントに送信されます。
-
Keycloak は、クライアント証明書を要求する。
-
Keycloak は、クライアント証明書を受信する。
-
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に適用される。
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は以下のようになります。
-
クライアントは、非対称暗号鍵ペアを生成する。
-
公開鍵は、CEK を暗号化するために使用される。
-
Keycloak IDトークンごとにCEKを生成する。
-
Keycloak この生成されたCEKを用いてIDトークンを暗号化する。
-
Keycloakは、クライアントの公開鍵を用いてCEKを暗号化する。
-
クライアントは、この暗号化されたCEKを自分の秘密鍵で復号化する。
-
クライアントは復号化されたCEKを使用してIDトークンを復号化する。
クライアント以外の第三者は、IDトークンを復号化することはできません。
クライアントは、CEKを暗号化するための公開鍵をKeycloakに渡す必要があります。Keycloakは、クライアントが提供するURLからの公開鍵のダウンロードに対応しています。クライアントは、 Json Web Keys (JWK) の仕様に従った公開鍵を提供する必要があります。
手順を以下に示します。
-
クライアントの Keys タブを開きます。
-
JWKS URL をONに切り替えます。
-
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)
アルゴリズムを選択する手順としては
-
クライアントの Settings タブを開きます。
-
Fine Grain OpenID Connect Configuration*を開きます。
-
IDトークン暗号化コンテンツ暗号化アルゴリズム*のプルダウンメニューから、アルゴリズムを選択します。
コンフィデンシャル・クライアントのクレデンシャル
クライアントのaccess typeが confidential に設定されている場合、クライアントのクレデンシャルを Credentials タブで設定する必要があります。
Client Authenticator ドロップダウン・リストでは、クライアントに使用するクレデンシャルの種類を指定します。
クライアントIDとシークレット
この選択肢はデフォルトの設定です。シークレットは自動的に生成され、必要に応じて Regenerate Secret をクリックすると、シークレットが再作成されます。
Signed JWT は "Signed Json Web Token"
このクレデンシャル・タイプを選択した場合、 Keys
タブでクライアントの秘密鍵と証明書も生成する必要があります。秘密鍵はJWTに署名するために使われ、一方、証明書はサーバーが署名を検証するために使われます。
この手順を開始するには、 Generate new keys and certificate
ボタンをクリックしてください。
-
使用するアーカイブ形式を選択します。
-
Key Password を入力します。
-
store password を入力します。
-
Generate and Download をクリックします.
鍵を生成すると、Keycloakが証明書を保存するので、クライアント用に秘密鍵と証明書をダウンロードします。
また、外部ツールを使って鍵を生成し、 Import Certificate をクリックしてクライアントの証明書をインポートすることも可能です。
-
証明書のアーカイブ形式を選択します。
-
ストアパスワードを入力します。
-
Import File をクリックして、証明書ファイルを選択します。
-
Import をクリックします。
Use JWKS URL をクリックすると、証明書のインポートは不要になります。この場合、公開鍵が公開されているURLを JWK 形式で指定します。このオプションを使用すると、鍵が変更されることがあっても、Keycloakは鍵を再インポートできます。
Keycloakアダプターでセキュリティー保護されたクライアントを使用している場合、https://myhost.com/myapp をクライアント・アプリケーションのルートURLと仮定して、この形式でJWKS URLを設定することが可能です。
https://myhost.com/myapp/k_jwks
詳しくは Server Developer Guide を参照してください。
Keycloakは、OIDCクライアントの公開鍵をキャッシュしています。クライアントの秘密鍵が漏洩した場合、鍵を更新して鍵キャッシュをクリアしてください。詳しくはキャッシュのクリアのセクションを参照してください。 |
クライアントシークレットで署名されたJWT
このオプションを選択すると、秘密鍵の代わりにクライアント・シークレットで署名されたJWTを使用できます。
クライアント・シークレットは、クライアントがJWTに署名するために使用されます。
X509 Certificate
Keycloakは、TLSハンドシェイク時にクライアントが適切なX509証明書を使用しているかどうかを検証します。
このオプションはKeycloakでMutual TLSを必要とします。WildFlyでMutual SSLを有効にするを参照してください。 |
バリデーターは、証明書のSubject DNフィールドを、設定された正規表現でチェックします。いくつかのユースケースでは、すべての証明書を受け入れることで十分です。そのような場合は、(.*?)(?:$)
式を使用することができます。
KeycloakがリクエストからクライアントIDを取得する方法は2つ存在します。
-
クエリーの
client_id
パラメーターです( OAuth 2.0仕様 のセクション 2.2 で説明されています)。 -
フォームのパラメーターとして
client_id
を指定します。
サービス・アカウントの使用
OIDCの各クライアントには、 サービス・アカウント が組み込まれています。この サービス・アカウント を使ってアクセストークンを取得します。
-
メニューの Clients をクリックします。
-
クライアントを選択してださい。
-
Settings タブをクリックします。
-
クライアントのAccess Typeを confidential に設定してください。
-
Service Accounts Enabled を ON に切り替えてください。
-
Save をクリックします。
-
クライアント・クレデンシャルの設定を行います。
-
Scope タブをクリックします。
-
ロールがあることを確認するか、 Full Scope Allowed を ON に切り替えてください。
-
Service Account Roles タブをクリックします。
-
このサービス・アカウントで利用可能なロールをクライアントに設定します。
アクセストークンからのロールは、以下の論理積となります。
-
クライアントのロール・スコープ・マッピングと、リンクされたクライアントのスコープから継承されたロール・スコープ・マッピングを組み合わせたもの。
-
サービス・アカウント・ロール
起動するREST URLは、 /auth/realms/{realm-name}/protocol/openid-connect/token
です。このURLはPOSTリクエストとして呼び出す必要があり、クライアントのクレデンシャルをリクエストに添付する必要があります。
デフォルトでは、クライアントのクレデンシャルは、 Authorization.Basic ヘッダー内のクライアントのclientIdおよびclientSecretによって表されます。しかし、署名されたJWTアサーションやその他のカスタム・メカニズムを使ってクライアントを認証することもできます。
また、OAuth 2の仕様に従って、 grant_type パラメーターを "client_credentials" に設定する必要があります。
たとえば、サービス・アカウントを取得するためのPOST呼び出しは次のようになります。
POST /auth/realms/demo/protocol/openid-connect/token
Authorization: Basic cHJvZHVjdC1zYS1jbGllbnQ6cGFzc3dvcmQ=
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
このレスポンスは、OAuth 2.0の仕様の 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にログインした際に取得します。
サービス間の信頼性が低い環境では、このようなシナリオに遭遇することがあります。
-
フロントエンド・クライアント・アプリケーションがKeycloakに対して認証を要求します。
-
Keycloakは、ユーザーを認証します。
-
Keycloakは、アプリケーションにトークンを発行します。
-
アプリケーションはトークンを使って、信頼できないサービスを呼び出します。
-
信頼されないサービスはアプリケーションにレスポンスを返します。ただし、アプリケーションのトークンは保持します。
-
信頼されていないサービスは、アプリケーションのトークンを使用して信頼されたサービスを呼び出します。この結果、信頼されていないサービスがトークンを悪用して、クライアント・アプリケーションに代わって他のサービスにアクセスするため、セキュリティーが破られることになります。
このシナリオは、サービス間の信頼度が高い環境ではありえないが、信頼度が低い環境ではありえます。環境によっては、信頼されていないサービスが、元のクライアント・アプリケーションにデータを返すために、信頼されているサービスからデータを取得する必要があるため、このワークフローは正しいかもしれません。
サービス間に高い信頼性が存在する場合、無制限のAudienceが有効です。それ以外の場合は、Audienceを制限する必要があります。Audienceを制限すると同時に、信頼されていないサービスが信頼されているサービスからデータを取得することを許可することができます。この場合、信頼されていないサービスと信頼されたサービスがトークンのAudienceとして追加されていることを確認します。
アクセストークンの悪用を防ぐため、トークンのAudienceを制限し、トークンのAudienceを確認するようにサービスを設定してください。フローは以下のように変更されます。
-
フロントエンド・アプリケーションはKeycloakに対して認証を行います。
-
Keycloakは、ユーザーを認証します。
-
Keycloakはアプリケーションにトークンを発行します。アプリケーションは信頼できないサービスを呼び出す必要があることを知っているので、Keycloakに送信する認証リクエストに scope=<untrusted service> を指定します。 scope パラメーターの詳細については、Client Scopes sectionを参照してください。
アプリケーションに発行されたトークンは、そのAudience( "audience": [ "<untrusted service>" ] )に信頼されないサービスへの参照を含み、クライアントはこのアクセストークンを使って信頼されないサービスを呼び出すと宣言しています。
-
信頼されていないサービスは、トークンを使って信頼されたサービスを呼び出します。信頼されたサービスがトークンの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 と呼ばれるようにします。
-
good-service クライアントのInstallationタブから、アダプターの設定を生成することができ、 verify-token-audience オプションが true に設定されることを確認することができます。これにより、この設定を使用した場合、アダプターは強制的にAudienceを確認することになります。
-
コンフィデンシャル・クライアントが、そのトークンにAudienceとして good-service を要求できるようにする必要があります。
コンフィデンシャル・クライアントでは以下のようにします。
-
Client Scopes タブをクリックします。
-
オプション(またはデフォルト)のクライアント・スコープとして good-service を割り当てます。
詳しくはClient Scopes Linkingのセクションを参照してください。
-
-
オプションでクライアント・スコープの評価とアクセストークンの例を生成することができます。オプションのクライアントスコープとして割り当てた場合、 scope パラメーターに good-service が含まれていれば、生成されたアクセストークンのAudienceに good-service が追加されます。
-
コンフィデンシャル・クライアント・アプリケーションでは、 scope パラメーターが使用されていることを確認してください。 good-service にアクセスするためのトークンを発行する場合は、値 good-service を含める必要があります。
以下を参照してください。
-
parameters forwarding section (サーブレットアダプタを使用する場合)
-
javascript adapter section (アプリケーションがJavaScriptアダプターを使用する場合)
-
Audience と Audience Resolve の両プロトコル・マッパーは、デフォルトではアクセストークンにのみAudienceを追加します。IDトークンは通常、OpenID Connectの仕様の要件である、トークンが発行されたクライアントIDという単一のAudienceのみを含みます。しかし、アクセストークンには、Audienceマッパーが追加しない限り、トークンが発行されたクライアントIDが含まれているとは限りません。 |
SAMLクライアントの作成
Keycloakは、登録されたアプリケーションに対してSAML 2.0をサポートし、POSTとRedirectのバインディングに対応しています。クライアント署名の検証を要求するかどうかを選択したり、サーバーに署名や暗号化をさせることもできます。
-
メニューの Clients をクリックします。
-
Create をクリックすると、 Add Client のページに移動します。
Add client -
クライアントの Client ID を入力します。これは多くの場合URLであり、アプリケーションから送信されるSAMLリクエストで期待される issuer の値です。
-
Client Protocol ドロップダウン・ボックスで saml を選択します。
-
Client SAML Endpoint URLを入力します。このURLは、KeycloakサーバーにSAMLリクエストとレスポンスを送信させる場所です。一般的に、アプリケーションには、SAMLリクエストを処理するための1つのURLがあります。複数のURLを、クライアントの Settings タブで設定することができます。
-
保存 をクリックします。この操作でクライアントが作成され、 Settings タブが表示されます。
クライアント設定各設定について、次の一覧で説明します。
- Client ID
-
OIDCリクエストおよび Keycloak データベースでクライアントを識別するために使用される英数字の ID 文字列です。この値はAuthNRequestsで送信されるissuerの値と一致しなければならない。Keycloak は Authn SAML リクエストから発行者を取り出し、この値でクライアントとマッチングさせる。
- Name
-
KeycloakのUI画面におけるクライアントの名前です。名前をローカライズするには、置換文字列値を設定します。たとえば、${myapp}のような文字列値です。詳しくは、 Server Developer Guide を参照してください。
- 説明
-
クライアントの説明文です。この設定はローカライズすることも可能です。
- Enabled
-
OFFに設定すると、クライアントは認証を要求できなくなります。
- Consent Required
-
ONに設定すると、ユーザーはそのアプリケーションへのアクセスを許可する同意ページを見ることができます。また、このページには、クライアントがアクセスできる情報のメタデータが表示されます。Facebookへのソーシャル・ログインをしたことがある人は、よく似たページを見ることができます。Red Hat Single Sign-On は同じ機能を提供します。
- Include AuthnStatement
-
SAMLログイン・レスポンスには、使用された認証方式(パスワードなど)、ログインのタイムスタンプおよびセッションの有効期限を指定することができます。 Include AuthnStatement はデフォルトで有効になっており、ログイン・レスポンスに AuthnStatement 要素が含まれるようになります。これをOFFに設定すると、クライアントが最大セッション長を決定できなくなり、期限切れにならないクライアント・セッションが作成される可能性があります。
- Sign Documents
-
ONに設定すると、Keycloakはレルムの秘密鍵を使ってドキュメントに署名します。
- Optimize REDIRECT signing key lookup
-
ONに設定すると、SAMLプロトコル・メッセージにKeycloakネイティブ拡張が含まれます。この拡張には、署名鍵IDを示すヒントが含まれます。SPは、鍵を用いた署名の検証を試みる代わりに、この拡張機能を署名の検証に用います。
このオプションは、署名がクエリー・パラメーターで転送されるREDIRECTバインディングに適用され、この情報は署名情報には含まれません。これは、鍵IDが常にドキュメント署名に含まれるPOSTバインディング・メッセージとは異なります。
このオプションは、KeycloakサーバーとアダプターがIDPとSPを提供する場合に使用されます。このオプションは、Sign Documents がONに設定されている場合にのみ影響します。
- 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署名の正準化手法。
- Encrypt Assertions
-
SAML文書のアサーションをレルム秘密鍵で暗号化します。AES アルゴリズムは、128ビットのキーサイズを使用します。
- Client Signature Required
-
Client Signature Required が有効な場合、クライアントからのドキュメントは署名されていることが期待されます。Keycloakは、
鍵
タブで設定されたクライアントの公開鍵または証明書を使用して、この署名を検証します。 - Force POST Binding
-
デフォルトでは、Keycloakは元のリクエストの最初のSAMLバインディングを使用して応答します。 Force POST Binding を有効にすると、Keycloakは、元のリクエストがREDIRECTバインディングを使用していたとしても、SAML POSTバインディングを使用して応答します。
- Front Channel Logout
-
Front Channel Logout が有効な場合、アプリケーションはログアウトを実行するためにブラウザーのリダイレクトを必要とします。たとえば、アプリケーションはリダイレクトによってのみ実行可能なCookieのリセットを要求するかもしれません。 Front Channel Logout が無効な場合、Keycloakはアプリケーションからログアウトするために、バックグラウンドでSAMLリクエストを呼び出します。
- Force Name ID Format
-
リクエストにName IDのポリシーがある場合、それを無視して管理コンソールの Name ID Format で設定された値を使用します。
- Name ID Format
-
サブジェクトのName ID Format。この形式は、リクエストでName IDポリシーが指定されていない場合、またはName ID形式の強制属性がONに設定されている場合に使用されます。
- Root URL
-
Keycloakが設定された相対URLを使用する場合、この値がURLの前に付加されます。
- Valid Redirect URIs
-
URLパターンを入力し、+記号をクリックすると追加されます。削除する場合は、-記号をクリックします。 Save をクリックして、これらの変更を保存します。ワイルドカードの値は、URLの末尾にのみ使用できます。たとえば、http://host.com/*$$のようになります。このフィールドは、正確なSAMLエンドポイントが登録されておらず、KeycloakのリクエストからAssertion Consumer URLを導き出す場合に使用されます。
- Base URL
-
Keycloakがクライアントにリンクする必要がある場合、このURLが使用されます。
Logo URL
クライアント・アプリケーション用のロゴを参照するURL。
Policy URL
プロファイル・データがどのように使用されるかについて読むために、Relying Partyがエンドユーザーに提供するURL。
Terms of Service URL
Relying Partyが、エンドユーザーにRelying Partyの利用規約を提供するURL。
- Master SAML Processing URL
-
このURLは、すべてのSAMLリクエストに使用され、レスポンスはSPに向けられます。これは、アサーション・コンシューマー・サービスのURLおよびシングル・ログアウト・サービスのURLとして使用されます。
ログインリクエストにアサーション・コンシューマー・サービスのURLが含まれている場合、そのログインリクエストが優先されます。このURLは、登録された有効なリダイレクトURIパターンによって検証される必要があります。
- Assertion Consumer Service POST Binding URL
-
アサーション・コンシューマー・サービスのPOSTバインディングURL。
- Assertion Consumer Service Redirect Binding URL
-
アサーション・コンシューマー・サービスのREDIRECTバインディングURL。
- Logout Service POST Binding URL
-
ログアウト・サービスのPOSTバインディングURL。
- Logout Service Redirect Binding URL
-
ログアウト・サービスのREDIRECTバインディングURL。
- 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/auth/realms/{realm}/protocol/saml/clients/{url-name}
IdP initiated loginの実装は、REDIRECT バインディングよりも POST バインディングを優先します(詳細についてはSAMLバインディングをチェックしてください)。したがって、最終的なバインディングとSPのURLは次のように選択されます。
-
特定の Assertion Consumer Service POST Binding URL が定義されている場合 (クライアント設定の Fine Grain SAML Endpoint Configuration セクション内に)、そのURLを介して POST バインディングが使用されます。
-
一般的な Master SAML Processing URL が指定されている場合、POST バインディングは、この一般的なURLを介して再度使用されます。
-
最後の手段として、Assertion Consumer Service Redirect Binding URL が設定されている場合(Fine Grain SAML Endpoint Configuration 内)、このURLで REDIRECT バインディングが使用されます。
クライアントが特別なリレーステートを必要とする場合、 Settings タブの IDP Initiated SSO Relay State フィールドでこれを設定することもできます。また、ブラウザーは RelayState クエリー・パラメーターでリレーステートを指定することもできます(例: root/auth/realms/{realm}/protocol/saml/clients/{url-name}?RelayState=thestate
アイデンティティー・ブローカリングを使用する場合、クライアントに対して外部IDPからのIDP Initiated ログインを設定することができます。実際のクライアントは、上記のようにブローカーIDPでIDP Initiated ログインするように設定されます。外部IDPはクライアントを、特別なURLを指し示す、アプリケーションIDP Initiated ログインのためにセットアップする必要があります。URLはブローカーを指し、ブローカリングIDPで選択されたクライアントのために、IDP Initiated ログイン・エンドポイントを代理します。つまり、外部IDPのクライアント設定では次のようになります。
-
IDP Initiated SSO URL Name には、IDP Initiated Loginの初期ポイントとして公開される名前が設定されます。
-
Fine Grain SAML Endpoint Configuration のセクションの Assertion Consumer Service POST Binding URL は、以下のURLに設定する必要があります。
broker-root/auth/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ファイルを使用してクライアントをインポートすることができます。
Add Clientページには、 Import オプションがあります。
-
Select File をクリックします。
-
XMLエンティティー記述子の情報を含むファイルを読み込みます。
-
すべての設定が正しく行われているか、情報を確認してください。
mod-auth-melon などの一部のSAMLクライアント・アダプターは、IDPのXMLエンティティー記述子を必要とします。この記述子は、このURLにアクセスして見つけることができます。
root/auth/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/auth/realms/master/clients/account/redirect
このURLは一時的にhttp://host:port/auth/realms/master/account にリダイレクトされます。
OIDCトークンとSAMLアサーションのマッピング
IDトークン、アクセストークン、またはSAMLアサーションを受け取るアプリケーションは、異なるロールとユーザー・メタデータを必要とする場合があります。
Keycloakを使用して次のこともできます。
-
ロール、クレーム、カスタム属性をハードコードする。
-
ユーザーのメタデータをトークンやアサーションに含める。
-
ロールの名前を変更する。
これらのアクションは、管理コンソールの Mappers タブで実行します。
新規クライアントはビルトイン・マッパーを持ちませんが、クライアント・スコープからいくつかのマッパーを継承することができます。詳しくはクライアント・スコープのセクションを参照してください。
プロトコル・マッパーは、アイテム(たとえば電子メールアドレスなど)をIDトークンおよびアクセストークンの特定のクレームにマッピングします。マッパーの機能は、その名前分かるはずです。事前に設定されたマッパーを追加するには、 Add Builtin をクリックします。
各マッパーには、共通の設定項目があります。マッパータイプによって、その他の設定も可能です。マッパーの横にある Edit をクリックすると、設定画面にアクセスし、これらの設定を調整することができます。
各オプションの詳細は、ツールチップにカーソルを合わせると表示されます。
ほとんどのOIDCマッパーで、クレームがどこに置かれるかを制御することができます。 Add to ID token と Add to access token のスイッチを調整することで、 ID_トークンと _アクセス トークンからクレームを含むかどうかを選択します。
マッパータイプは以下のように追加できます。
-
Mappers タブに移動します。
-
Create をクリックします。
マッパーを追加します。 -
リストボックスから Mapper Type を選択します。
優先順位
マッパーの実装には 優先順位 があります。 優先順位 はマッパーの設定プロパティーではなく、マッパーの具体的な実装のプロパティーです。
マッパーはマッパーの一覧の順番でソートされます。トークンまたはアサーションの変更は、最も低いものが最初に適用されるように、その順序で適用されます。したがって、他の実装に依存している実装は、必要な順序で処理されます。
たとえば、あるトークンに含まれるロールを計算する場合は、次のようになります。
-
そのロールに基づき、Audienceを解決する。
-
トークンで既に利用可能なロールとAudienceを使用するJavaScriptのスクリプトを処理します。
OIDCユーザー・セッション・ノート・マッパー
ユーザー・セッションの詳細は、マッパーを使用して定義され、クライアントで機能を使用または有効にすると、自動的に含まれます。セッションの詳細を含めるには、 Add builtin をクリックします。
代理ユーザー・セッションは、次の詳細を提供します。
-
IMPERSONATOR_ID :代理ユーザーのID。
-
IMPERSONATOR_USERNAME :なりすましユーザーのユーザー名。
サービス・アカウント・セッションは、次の詳細を提供します。
-
clientId :サービス・アカウントのクライアントID。
-
clientAddress :サービス・アカウントの認証済みデバイスのリモートホストIP。
-
clientHost :サービス・アカウントの認証済みデバイスのリモートホスト名。
スクリプトマッパー
ユーザー定義のJavaScriptコードを実行して、クレームをトークンにマッピングするには、 Script Mapper を使用します。サーバーへのスクリプトのデプロイの詳細については、 JavaScript Providers を参照してください。
スクリプトがデプロイされると、利用可能なマッパーの一覧からデプロイされたスクリプトを選択できるようになるはずです。
クライアント・アダプターの設定の生成
Keycloakは、アプリケーションのデプロイメント環境にクライアント・アダプターをインストールするために使用する設定ファイルを生成できます。OIDCおよびSAMLでは、さまざまなアダプタータイプがサポートされています。
-
設定を生成したいクライアントの Installation タブに移動します。
-
設定を生成したい Format Option を選択します。
OIDCおよびSAML用のすべてのKeycloakクライアント・アダプターがサポートされています。SAML用のApache HTTPDアダプターmod-auth-mellonは、標準のSAMLエンティティー記述子ファイルと同様にサポートされています。
クライアント・スコープ
Keycloakを使って、 client scope と呼ばれるエンティティーに共有のクライアント設定を定義します。クライアントスコープ_は、複数のクライアントに対してプロトコル・マッパー と ロール・スコープ・マッピングを設定します。
クライアント・スコープは、OAuth 2の scope パラメーターもサポートしています。クライアント・アプリケーションは、このパラメーターを使用して、アプリケーションの要件に応じてアクセストークン内のクレームやロールを要求します。
クライアント・スコープを作成するには、次の手順を実行します。
-
メニューの Client Scopes をクリックします。
クライアント・スコープの一覧 -
Create をクリックします。
-
クライアント・スコープを指定します。
-
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
-
クライアント・スコープである profile 、email 、address および phone は OpenID Connectの仕様 で定義されています。これらのスコープにはロール・スコープ・マッピングは定義されていませんが、 プロトコル・マッパーは定義されています。これらのマッパーは、OpenID Connectの仕様で定義されているクレームに対応しています。
たとえば、phone クライアント・スコープを開き、 Mappers タブを開くと、スコープ 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 パラメーターによって要求された場合に限られます。
例
この例では、クライアントにはデフォルトのクライアント・スコープとして profile と email がリンクされており、オプションのクライアント・スコープとして profile と email がリンクされていると仮定します。クライアントは、OpenID Connect認可エンドポイントにリクエストを送信するときに、scopeパラメーターの値を使用します。
scope=openid phone
scopeパラメーターには、scope値をスペースで区切った文字列を指定します。 openid は、すべてのOpenID Connectリクエストで使用されるメタ値です。トークンには、デフォルトのクライアント・スコープである profile および email と、scopeパラメーターで要求されたオプションのクライアント・スコープである phone のマッパーおよびロールス・コープ・マッピングが含まれることになります。
クライアント・スコープの評価
マッパー*タブにはプロトコルマッパーが、*スコープ*タブにはこのクライアント用に宣言されたロールスコープマッピングが含まれます。クライアントのスコープから継承されたマッパーとスコープマッピングは含まれません。クライアントのトークンを生成するときに使用される有効なプロトコルマッパー(クライアント自身で定義されたプロトコルマッパーおよびリンクされたクライアントスコープから継承されたプロトコルマッパー)および有効なロールスコープマッピングを確認することは可能です。
-
クライアントの Client Scopes タブをクリックします。
-
Evaluate サブタブを開きます。
-
適用したいオプションのクライアントスコープを選択します。
これは、 scope パラメーターの値も表示されます。このパラメーターは、アプリケーションからKeycloak OpenID Connect認可エンドポイントに送信される必要があります。
アプリケーションから scope パラメーターにカスタム値を送るには、 サーブレット・アダプターについては パラメーター転送のセクションを、JavaScript アダプターについては JavaScriptアダプターのセクション を参照してください。 |
すべてのサンプルは、特定のユーザーに対して生成され、特定のクライアントに対して、 scope パラメーターの指定値で発行されます。例には、使用されたすべてのクレームとロールマッピングが含まれます。
クライアント・スコープ・パーミッション
ユーザーにトークンを発行する場合、クライアント・スコープが適用されるのは、そのユーザーが使用を許可されている場合のみです。
クライアント・スコープにロール・スコープ・マッピングが定義されていない場合、各ユーザーはこのクライアント・スコープを使用することができます。しかし、クライアント・スコープにロール・スコープ・マッピングが定義されている場合、ユーザーは少なくとも一つのロールのメンバーである必要があります。ユーザーのロールとクライアント・スコープのロールの間に共通点がなければなりません。複合ロールはこの共通点を評価する際に考慮されます。
ユーザーがクライアント・スコープを使用することを許可されていない場合、トークン生成時にプロトコル・マッパーやロール・スコープ・マッピングが使用されることはありません。トークンの scope の値には、クライアント・スコープが表示されなくなります。
レルムのデフォルトのクライアント・スコープ
Realm Default Client Scopes を使用すると、新しく作成されたクライアントに自動的にリンクされるクライアント・スコープのセットを定義することができます。
-
クライアントの Client Scopes タブをクリックします。
-
Default Client Scopes をクリックします。
ここから、新しく作成するクライアントに Default Client Scopes として追加したいクライアントスコープと Optional Client Scopes を選択します。
クライアントを作成する際、必要に応じてデフォルトのクライアントスコープをアンリンクすることができます。これは、デフォルトロールを削除するのと似ています。
スコープの説明
- クライアント・スコープ
-
クライアント・スコープとは、レルムレベルで設定される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ークンの使用を強制
-
Signed JWTクライアント認証(private-key-jwt)にセキュアな署名アルゴリズムを使用することを強制
-
HTTPSリダイレクトURIを強制し、設定したリダイレクトURIにワイルドカードが含まれないように強制
-
高いセキュリティー・レベルを満たすOIDC
request
オブジェクトを強制 -
FAPI 1 仕様にあるように、認可レスポンスで返されるIDトークンにユーザー・プロフィールのデータが含まれず、 detached signature として使用するOIDCハイブリッド・フローのレスポンスタイプを強制
-
CSRFを防止するため、より安全な
state
とnonce
パラメーターの処理を強制 -
クライアント登録時に、よりセキュアな署名アルゴリズムを強制
-
CIBAリクエストに
binding_message
パラメーターを使用するように強制
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、Profile、Condition、Executorは、管理REST API、つまり管理コンソールでも設定することができます。これを行うには、 Realm → Realm Settings → Client 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 内。
ボールトを使用するには、Keycloakにボールト・プロバイダーを登録します。プロバイダーはここで説明されているものを使用するか、自分で実装することができます。詳しくは Server Developer Guide を参照してください。
Keycloakでは、Keycloakインスタンスごとに、一度に最大1つのアクティブなデータ・ボールト・プロバイダーが許可され ます。クラスター内の各インスタンスでデータ・ボールト・プロバイダーを一貫して設定します。 |
Kubernetes / OpenShift files plain-text ボールト・プロバイダー
Keycloakは、 Kubernetes secrets のVault実装をサポートしています。Kubernetes secretsはデータボリュームとしてマウントでき、フラットファイル構造を持つディレクトリとして表示されます。Keycloak は、各シークレットをファイルとして表現し、ファイル名をシークレット名、ファイルの内容をシークレット値として表現します。
このディレクトリー内のファイル名は、シークレット名の前にレルム名とアンダースコアを付けた名前にする必要があります。ファイル名中のシークレット名またはレルム名のアンダースコアをすべてダブルにします。たとえば、 sso_realm
というレルム内のフィールドで、 secret-name
という名前のシークレットを参照する場合、 ${vault.secret-name}
と書き、検索するファイル名は sso__+realm_+++secret-name
となります。レルム名のアンダースコアが2つであることに注意してください。
このタイプの秘密結社を使用するには、standalone.xml ファイルで files-plaintext
プロバイダを宣言し、マウントされたボリュームを含むディレクトリをそのパラメータに設定する必要があります。この例では、files-plaintext
プロバイダーが、Keycloak ベースディレクトリからの相対パスで、データ保管庫ファイルが検索されるディレクトリを standalone/configuration/vault
に設定したものを示しています。
<spi name="vault">
<default-provider>files-plaintext</default-provider>
<provider name="files-plaintext" enabled="true">
<properties>
<property name="dir" value="${jboss.home.dir}/standalone/configuration/vault/" />
</properties>
</provider>
</spi>
CLIコマンドを使用した同等の設定は以下になります。
/subsystem=keycloak-server/spi=vault/:add
/subsystem=keycloak-server/spi=vault/provider=files-plaintext/:add(enabled=true,properties={dir => "${jboss.home.dir}/standalone/configuration/vault"})
/subsystem=keycloak-server/spi=vault:write-attribute(name=default-provider,value=files-plaintext)
Elytron Credential Storeボールト・プロバイダー
KeycloakはElytronのクレデンシャル・ストアに保存されているシークレットの読み込みもサポートしています。 elytron-cs-keystore
ボールト・プロバイダーは、Elytronが提供するデフォルトの実装である、キーストアに基づく実装からシークレットを取得することが可能です。
このクレデンシャル・ストアはキーストアを使用します。 JCEKS
がデフォルトのフォーマットですが、PKCS12
などの他のフォーマットも使用できます。ユーザーは WildFly/JBoss EAP の elytron
サブシステム、または elytron-tool.sh
スクリプトを使用してストアのコンテンツを作成および管理することができます。
このプロバイダーを使用するには、 keycloak-server
サブシステムで elytron-cs-keystore
を宣言し、Elytronによって作成されたキーストアの場所とマスター・シークレットを設定する必要があります。プロバイダーの最小設定の例を以下に示します。
<spi name="vault">
<default-provider>elytron-cs-keystore</default-provider>
<provider name="elytron-cs-keystore" enabled="true">
<properties>
<property name="location" value="${jboss.home.dir}/standalone/configuration/vault/credential-store.jceks" />
<property name="secret" value="secretpw1!"/>
</properties>
</provider>
</spi>
もし、基盤となるキーストアが JCEKS
と異なるフォーマットである場合、 keyStoreType
を使ってそのフォーマットを指定する必要があります。
<spi name="vault">
<default-provider>elytron-cs-keystore</default-provider>
<provider name="elytron-cs-keystore" enabled="true">
<properties>
<property name="location" value="${jboss.home.dir}/standalone/configuration/vault/credential-store.p12" />
<property name="secret" value="secretpw1!"/>
<property name="keyStoreType" value="PKCS12"/>
</properties>
</provider>
</spi>
secretについては、elytron-cs-keystore
プロバイダが elytron-tool.sh
スクリプトを用いてクリアテキストの値とマスクされた値をサポートしています。
<spi name="vault">
...
<property name="secret" value="MASK-3u2HNQaMogJJ8VP7J6gRIl;12345678;321"/>
...
</spi>
elytronのクレデンシャルストアの作成と管理、およびキーストアの秘密のマスキングに関する詳細については、Elytronのドキュメントを参照してください。
Keycloak は |
キーリゾルバー
すべての組み込みプロバイダーはキーリゾルバーの設定をサポートしています。キーリゾルバーは、レルム名と ${vault.key}
式から得られるキーを組み合わせて、データ保管庫から秘密を取得するための最終的なエントリ名にするアルゴリズムや戦略を実装しています。Keycloakは keyResolvers
プロパティを使用して、プロバイダーが使用するリゾルバを設定します。この値は、カンマで区切られたリゾルバ名のリストです。 files-plaintext
プロバイダーの設定の例を以下に示します。
<spi name="vault">
<default-provider>files-plaintext</default-provider>
<provider name="files-plaintext" enabled="true">
<properties>
<property name="dir" value="${jboss.home.dir}/standalone/configuration/vault/" />
<property name="keyResolvers" value="REALM_UNDERSCORE_KEY, KEY_ONLY"/>
</properties>
</provider>
</spi>
リゾルバは、構成で宣言したのと同じ順序で実行される。各リゾルバに対して、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が |
REALM_FILESEPARATOR_KEY |
Keycloak は、プラットフォームファイルのセパレータ文字を使用して、レルムとキーを結合します。 |
FACTORY_PROVIDED |
Keycloak は、Vaultプロバイダのファクトリーの |
ビルトインプロバイダのリゾルバを設定していない場合、Keycloak は REALM_UNDERSCORE_KEY
を選択します。
FACTORY_PROVIDED
リゾルバーは、任意のプロバイダーファクトリーを拡張して getFactoryResolver
メソッドをオーバーライドすることで、カスタムリゾルバーを実装するために使用するフックを提供します。たとえば、 elytron-cs-keystore
プロバイダーを使用したいが、組み込みのリゾルバーはキーストアで使用するフォーマットにマッチしない場合、 ElytronCSKeystoreProvider
を拡張して getFactoryResolver
メソッドを実装すればよいでしょう。
public class CustomElytronProviderFactory extends ElytronCSKeyStoreProviderFactory {
...
@Override
protected VaultKeyResolver getFactoryResolver() {
return (realm, key) -> realm + "###" + key;
}
@Override
public String getId() {
return "custom-elytron-cs-keystore;
}
...
}
カスタムファクトリは、realmとkeyをトリプル#文字で結合したキーリゾルバを返します。たとえば、master_realm##smtp_key
のようなエントリーがあります。このファクトリーは、他のカスタムプロバイダと同様にインストールします。
カスタムファクトリは |
以前のカスタムプロバイダをインストールして使用するには、次のような構成になります。
<spi name="vault">
<default-provider>custom-elytron-cs-keystore</default-provider>
<provider name="custom-elytron-cs-keystore" enabled="true">
<properties>
<property name="location" value="${jboss.home.dir}/standalone/configuration/vault/credential-store.p12" />
<property name="secret" value="MASK-3u2HNQaMogJJ8VP7J6gRIl;12345678;321"/>
<property name="keyStoreType" value="PKCS12"/>
<property name="keyResolvers" value="FACTORY_PROVIDED"/>
</properties>
</provider>
</spi>
この設定により、Keycloak はカスタムElytronプロバイダを設定し、カスタムファクトリが作成するキーリゾルバを使用するようになります。
サンプル設定
以下は、ボールトとクレデンシャル・ストアを構成する例です。この手順には次の2つの部分があります。
-
クレデンシャル・ストアとボールトを作成します。クレデンシャル・ストアとボールトのパスワードは平文です。
-
パスワードに
elytron-tool.sh
で提供されたマスクを使用するように、クレデンシャル・ストアとボールトを更新します。
この例では、 BIND DN credential: secret12
を設定したLDAPインスタンスをテスト対象として使用します。このテスト対象は、レルム ldaptest
のユーザー・フェデレーションを使用してマッピングされています。
マスクを使用しないクレデンシャル・ストアおよびボールトの設定
クレデンシャル・ストアとボールトを作成し、クレデンシャル・ストアとボールトのパスワードをプレーンテキストにします。
-
稼働中のLDAPインスタンスは、
BIND DN credential: secret12
を持っています。 -
デフォルトのキーリゾルバーを使用する場合、エイリアスは<realm-name>_<key-value>という形式を使用します。この例では、インスタンスはレルム
ldaptest
で動作しており、ldaptest_ldap_secret
はそのレルムのldap_secret
の値に対応するエイリアスです。
リゾルバーは、レルム名とキー名のアンダースコア文字をダブル・アンダースコア文字に置き換えます。たとえば、キーが ldaptest_ldap_secret の場合、最終的なキーは ldaptest_ldap__secret となります。
|
-
Elytronのクレデンシャル・ストアを作成します。
[standalone@localhost:9990 /] /subsystem=elytron/credential-store=test-store:add(create=true, location=/home/test/test-store.p12, credential-reference={clear-text=testpwd1!},implementation-properties={keyStoreType=PKCS12})
-
クレデンシャル・ストアにエイリアスを追加します。
/subsystem=elytron/credential-store=test-store:add-alias(alias=ldaptest_ldap__secret,secret-value=secret12)
リゾルバーでは、キー
ldaptest_ldap__secret
にダブル・アンダースコアが使われていることに注目してください。 -
クレデンシャル・ストアからエイリアスをリストアップして、Elytronが生成するキーストアのコンテンツを検査します。
keytool -list -keystore /home/test/test-store.p12 -storetype PKCS12 -storepass testpwd1! Keystore type: PKCS12 Keystore provider: SUN Your keystore contains 1 entries ldaptest_ldap__secret/passwordcredential/clear/, Oct 12, 2020, SecretKeyEntry,
-
KeycloakでボールトSPIを設定します。
/subsystem=keycloak-server/spi=vault:add(default-provider=elytron-cs-keystore) /subsystem=keycloak-server/spi=vault/provider=elytron-cs-keystore:add(enabled=true, properties={location=>/home/test/test-store.p12, secret=>testpwd1!, keyStoreType=>PKCS12})
この時点では、ボールトとクレデンシャル・ストアのパスワードはマスクされていません。
<spi name="vault"> <default-provider>elytron-cs-keystore</default-provider> <provider name="elytron-cs-keystore" enabled="true"> <properties> <property name="location" value="/home/test/test-store.p12"/> <property name="secret" value="testpwd1!"/> <property name="keyStoreType" value="PKCS12"/> </properties> </provider> </spi> <credential-stores> <credential-store name="test-store" location="/home/test/test-store.p12" create="true"> <implementation-properties> <property name="keyStoreType" value="PKCS12"/> </implementation-properties> <credential-reference clear-text="testpwd1!"/> </credential-store> </credential-stores>
-
LDAPプロバイダーで、
binDN credential
を${vault.ldap_secret}
に置き換えてください。 -
LDAP接続をテストしてください。
LDAPボールト
クレデンシャル・ストアとボールトでのパスワードのマスキング
elytron-tool.sh
が提供するマスクを使用したパスワードを設定するように、クレデンシャル・ストアとボールトを更新することができます。
-
salt
とiteration
パラメーターの値を使用して、マスクされたパスワードを作成します。$ EAP_HOME/bin/elytron-tool.sh mask --salt SALT --iteration ITERATION_COUNT --secret PASSWORD
例:
elytron-tool.sh mask --salt 12345678 --iteration 123 --secret testpwd1! MASK-3BUbFEyWu0lRAu8.fCqyUk;12345678;123
-
マスクされたパスワードを使用するように、Elytronのクレデンシャル・ストアの設定を更新します。
/subsystem=elytron/credential-store=cs-store:write-attribute(name=credential-reference.clear-text,value="MASK-3BUbFEyWu0lRAu8.fCqyUk;12345678;123")
-
マスクされたパスワードを使用するようにKeycloakボールトの設定を更新します。
/subsystem=keycloak-server/spi=vault/provider=elytron-cs-keystore:remove() /subsystem=keycloak-server/spi=vault/provider=elytron-cs-keystore:add(enabled=true, properties={location=>/home/test/test-store.p12, secret=>”MASK-3BUbFEyWu0lRAu8.fCqyUk;12345678;123”, keyStoreType=>PKCS12})
ボールトとクレデンシャル・ストアが次のようにマスクされます。
<spi name="vault"> <default-provider>elytron-cs-keystore</default-provider> <provider name="elytron-cs-keystore" enabled="true"> <properties> <property name="location" value="/home/test/test-store.p12"/> <property name="secret" value="MASK-3BUbFEyWu0lRAu8.fCqyUk;12345678;123"/> <property name="keyStoreType" value="PKCS12"/> </properties> </provider> </spi> .... ..... <credential-stores> <credential-store name="test-store" location="/home/test/test-store.p12" create="true"> <implementation-properties> <property name="keyStoreType" value="PKCS12"/> </implementation-properties> <credential-reference clear-text="MASK-3BUbFEyWu0lRAu8.fCqyUk;12345678;123"/> </credential-store> </credential-stores>
-
これで、
${vault.ldap_secret}
を使用してLDAPへの接続をテストすることができます。
Elytronツールの詳細については、 Using Credential Stores with Elytron Client を参照してください。
イベントを追跡するための監査の設定
Keycloakには、一連の監査機能が含まれています。ログインや管理者の操作をすべて記録し、管理コンソールでその操作を確認することができます。Keycloakには、イベントをリッスンしてアクションを起こすことができるリスナーSPIも含まれています。組み込みのリスナーの例としては、ログファイルやイベント発生時のメール送信などがあります。
ログインイベント
ユーザーに影響を与えるすべてのイベントを記録し、表示することができます。Keycloakは、ユーザーのログイン成功、ユーザーの不正なパスワード入力、ユーザー・アカウントの更新などのアクションに対してログインイベントをトリガーします。デフォルトでは、Keycloakは管理コンソールにイベントを保存または表示しません。エラーイベントのみが管理コンソールとサーバーのログファイルに記録されます。
イベントの保存を開始するには、ストレージを有効にします。
-
メニューの Events をクリックします。
-
Config タブをクリックします。
イベントの設定 -
Save Events を ON に切り替えます。
イベントの保存 -
保存するイベントを Saved Types フィールドに指定します。
Clear events ボタンをクリックすると、すべてのイベントを消去できます。
Expiration 欄に、イベントを保存する期間を指定します。ログインイベントの保存を有効にし、設定を有効にしたら、 Save ボタンをクリックします。
ログインイベント*タブをクリックすると、イベントが表示されます。
Filter ボタンを使って、イベントをフィルターできます。
この例では、 Login
イベントのみをフィルタリングします。フィルターを実行するには、 Update をクリックします。
イベントの種類
ログインイベント:
イベント | 説明 |
---|---|
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
ロギング・イベント・リスナーを使用すると、ハッカーボット攻撃から保護することができます。
-
LOGIN_ERROR
イベントのログファイルを解析します。 -
ログインに失敗したイベントのIPアドレスを抽出します。
-
侵入防止ソフトウェア・フレームワーク・ツールにIPアドレスを送信します。
ロギング・イベント・リスナーはイベントを org.keycloak.events
ログカテゴリーに記録します。Keycloakは、デフォルトでは、デバッグ・ログ・イベントをサーバーログに含めません。
サーバーログにデバッグログイベントを含めるには、以下のようにします。
-
standalone.xml
ファイルを編集します。 -
ロギング・イベント・リスナーが使用するログレベルを変更します。
代わりに、 org.keycloak.events
のログレベルを設定できます。
たとえば、ログレベルを変更するには、以下を追加します。
<subsystem xmlns="urn:jboss:domain:logging:...">
...
<logger category="org.keycloak.events">
<level name="DEBUG"/>
</logger>
</subsystem>
ロギング・イベントリスナーが使用するログレベルを変更するには、以下を追加します。
<subsystem xmlns="urn:jboss:domain:keycloak-server:...">
...
<spi name="eventsListener">
<provider name="jboss-logging" enabled="true">
<properties>
<property name="success-level" value="info"/>
<property name="error-level" value="error"/>
</properties>
</provider>
</spi>
</subsystem>
ログレベルに有効な値は debug
、info
、warn
、error
、および fatal
です。
電子メール・イベント・リスナー
電子メール・イベント・リスナーは、イベントが発生するとユーザーのアカウントにメールを送信し、以下のイベントをサポートします。
-
ログインエラー。
-
パスワードの更新。
-
タイムベースワンタイムパスワード(TOTP)の更新。
-
時間ベースのワンタイムパスワード(TOTP)の削除。
電子メール・イベント・リスナーを有効にするには、次のようにします。
-
メニューから Events をクリックします。
-
Config タブをクリックします。
-
Event Listeners フィールドをクリックします。
-
email
を選択します。
イベントを除外するには、配布物に含まれる standalone.xml
、 standalone-ha.xml
、 domain.xml
の設定ファイルを編集してください。たとえば、以下のようにします。
<spi name="eventsListener">
<provider name="email" enabled="true">
<properties>
<property name="exclude-events" value="["UPDATE_TOTP","REMOVE_TOTP"]"/>
</properties>
</provider>
</spi>
standalone.xml
、 standalone-ha.xml
または domain.xml
設定ファイルを編集することで、データベース内のイベント詳細の最大長を設定することができます。この設定は、あるフィールド(たとえば、redirect_uri)が長い場合に便利です。たとえば、以下のようにします。
<spi name="eventsStore">
<provider name="jpa" enabled="true">
<properties>
<property name="max-detail-length" value="1000"/>
</properties>
</provider>
</spi>
standalone.xml
、 standalone-ha.xml
、 domain.xml
ファイルの場所については Server Installation and Configuration Guide を参照してください。
管理イベント
管理者が管理コンソールで実行したすべてのアクションを記録することができます。管理コンソールは、KeycloakのRESTインターフェイスを呼び出して管理アクションを実行します。RESTインターフェイスを呼び出し、KeycloakはこれらのREST呼び出しを監査します。結果のイベントは、管理コンソールで確認できます。
管理アクションの監査を有効にするには以下を行います。
-
メニューの Events をクリックします。
-
Config タブをクリックします。
イベントの設定 -
Admin Events Settings のセクションで、 Save Events を ON に切り替えます。Keycloakは、 Include Representation スイッチを表示します。
管理イベントの設定 -
Include Representation を ON に切り替えます。
Include Representation
スイッチは、管理者のアクションを表示できるように、管理REST APIを通して送られたJSONドキュメントを含みます。データベースに保存されているアクションをクリアするには、 Clear admin events をクリックします。
管理イベントを表示するには、 Admin Events タブをクリックします。
Details
列に Representation ボタンがある場合、 Representation ボタンをクリックして、Keycloakが操作で送信したJSONを表示します。
特定のイベントを表示するには、 Filter
をクリックします。
データベースのインポートとエクスポート
Keycloakには、データベース全体をエクスポート、インポートする機能があります。
Keycloakのデータベース全体をある環境から別の環境に移行したり、別のデータベースに移行することができます。エクスポート/インポートはサーバーの起動時にトリガーされ、そのパラメーターはJavaプロパティーを介して渡されます。
インポートとエクスポートはサーバーの起動時に行われるため、エクスポート/インポート中はサーバーやデータベースに対して何もしないでください。 |
データベースをエクスポート/インポートすることができます。
-
ファイルシステム上のディレクトリーです。
-
ファイルシステム上の単一のJSONファイル
ディレクトリーからインポートする場合、ファイル名はこの命名規則に従わなければなりません。
-
<REALM_NAME>-realm.json. For example, "acme-roadrunner-affairs-realm.json" for the realm named "acme-roadrunner-affairs".
-
<REALM_NAME>-users-<INDEX>.json. For example, "acme-roadrunner-affairs-users-0.json" for the first user’s file of the realm named "acme-roadrunner-affairs"
ディレクトリーにエクスポートする場合は、各JSONファイルに保存されるユーザー数を指定できます。
1つのファイルにエクスポートするとファイルサイズが大きくなるため、データベースに500人以上のユーザーが含まれる場合は、1つのファイルではなくディレクトリーにエクスポートしてください。多数のユーザーをディレクトリーにエクスポートすると、ディレクトリー・プロバイダーが各"ページ"(ユーザーのファイル)に対して個別のトランザクションを使用するため、最適なパフォーマンスが得られます。 1ファイル、1トランザクションあたりのユーザー数のデフォルトは50人ですが、この数を上書きすることができます。詳しくは keycloak.migration.usersPerFile を参照してください。 1つのファイルへのエクスポート、または1つのファイルからのインポートは1つのトランザクションを使用するため、データベースに多くのユーザーが含まれている場合、パフォーマンスが低下する可能性があります。 |
暗号化されていないディレクトリーにエクスポートするには以下のようにします。
bin/standalone.sh -Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=dir -Dkeycloak.migration.dir=<DIR TO EXPORT TO>
単一のJSONファイルにエクスポートするには、以下のようにします。
bin/standalone.sh -Dkeycloak.migration.action=export
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO EXPORT TO>
同様に、インポートする場合は、 export
ではなく、 -Dkeycloak.migration.action=import
としてください。たとえば、以下のようになります。
bin/standalone.sh -Dkeycloak.migration.action=import
-Dkeycloak.migration.provider=singleFile -Dkeycloak.migration.file=<FILE TO IMPORT>
-Dkeycloak.migration.strategy=OVERWRITE_EXISTING
その他のコマンドラインオプションは以下の通りです。
- -Dkeycloak.migration.realmName
-
このプロパティーを使用して、指定された 1 つのレルムをエクスポートします。このパラメーターが指定されていない場合は、すべてのレルムがエクスポートされます。
- -Dkeycloak.migration.usersExportStrategy
-
このプロパティーは、ユーザーがどこにエクスポートするかを指定します。可能な値は次のとおりです。
-
DIFFERENT_FILES - ユーザーは、最大のファイルあたりのユーザー数を条件として、異なるファイルにエクスポートします。DIFFERENT_FILESは、このプロパティーのデフォルト値です。
-
SKIP - Keycloakユーザーのエクスポートをスキップします。
-
REALM_FILE - ユーザーは、レルム設定のある同じファイルにエクスポートします。このファイルは"foo-realm.json"と同様に、レルムデータとユーザーが含まれています。
-
SAME_FILE - ユーザーは同じファイルにエクスポートされますが、レルムファイルとは異なります。レルムのデータは"foo-realm.json"、ユーザーは"foo-users.json"のような結果になります。
-
- -Dkeycloak.migration.usersPerFile
-
このプロパティーは、ファイルおよびデータベース・トランザクションごとのユーザー数を指定します。デフォルト値は 50 です。Keycloakは、keycloak.migration.usersExportStrategyがDIFFERENT_FILESの場合に、このプロパティーを使用します。
- -Dkeycloak.migration.strategy
-
Keycloakはインポート時にこのプロパティーを使用します。同じ名前のレルムがすでにデータベースに存在する場合の処理方法を指定します。
設定可能な値は以下の通りです。
-
IGNORE_EXISTING - 同じ名前のレルムがすでに存在する場合、そのレルムをインポートしません。
-
OVERWRITE_EXISTING - 既存のレルムを削除し、JSONファイルからの新しいデータで再びレルムをインポートします。ある環境から別の環境に完全に移行するために、この値を使用します。
Keycloakのエクスポートからではないファイルをインポートする場合は、 keycloak.import
オプションを使用してください。複数のレルムファイルをインポートする場合は、カンマで区切ったファイル名のリストを指定します。これはKeycloakがmasterレルムを初期化した後に行われるので、ファイル名のリストはこれまでのケースよりも適しています。
例
-
-Dkeycloak.import=/tmp/realm1.json
-
-Dkeycloak.import=/tmp/realm1.json,/tmp/realm2.json
|
管理コンソールでのエクスポート/インポート
Keycloak管理コンソールからほとんどのリソースをインポートし、またほとんどのリソースをエクスポートしています。Keycloakは、ユーザーのエクスポートをサポートしていません。
Keycloakのエクスポートファイルに含まれるシークレットやプライベートな情報を含む属性をマスクします。管理コンソールからのエクスポートしたファイルは、バックアップやサーバー間のデータ転送には適していません。バックアップやサーバー間のデータ転送に適しているのは、起動時のエクスポートのみです。 |
エクスポート時に作成されたファイルを使用して、管理コンソールからインポートすることができます。あるレルムからエクスポートして別のレルムにインポートしたり、あるサーバーからエクスポートして別のサーバーにインポートしたりすることができます。
管理コンソールのエクスポート/インポートでは、1ファイルにつき1つのレルムのみが許可されます。 |
管理コンソールのインポートでは、リソースを上書きすることができます。この機能は、特に運用サーバーでは注意して使用してください。管理コンソールのエクスポート操作によるJSONファイルには、シークレットの無効な値が含まれているため、データのインポートには適していません。 |
管理コンソールを使用して、クライアント、グループ、およびロールをエクスポートすることができます。レルムのデータベースに多数のクライアント、グループ、およびロールが含まれている場合、エクスポートの完了までに時間がかかり、Keycloakサーバーがユーザーのリクエストに応答しないことがあります。この機能は、特に本番サーバーでは注意して使用してください。 |
セキュリティー上の脅威の軽減
セキュリティーの脆弱性は、どのような認証サーバーにも存在します。詳しくはInternet Engineering Task Force (IETF)の OAuth 2.0 Threat Model と OAuth 2.0 Security Best Current Practice を参照してください。
ホスト
Keycloakは、トークン発行者のフィールドやパスワード・リセット・メールのURL内など、いくつかの方法で公開ホスト名を使用しています。
デフォルトでは、ホスト名はリクエスト・ヘッダーから取得できます。ホスト名が有効であることを確認する検証機能はありません。ロードバランサーやプロキシーを使用していない場合は、 Keycloakで無効なホストヘッダーを防ぐために、許容できるホスト名を設定してください。
ホスト名のサービス・プロバイダー・インターフェイス(SPI)は、リクエスト用にホスト名を設定する方法を提供します。この組み込みのプロバイダーを使用すると、フロントエンドのリクエストには固定のURLを設定しつつ、リクエストURIに基づいてバックエンドのリクエストを許可することができます。組み込みのプロバイダーに必要な機能が備わっていない場合は、カスタマイズしたプロバイダーを開発することができます。
管理エンドポイントと管理コンソール
デフォルトでKeycloakは、管理用REST APIとWebコンソールを、非管理用と同じポートで公開します。外部からのアクセスが必要でない場合は、管理用エンドポイントを外部に公開しないでください。管理用エンドポイントを外部に公開する必要がある場合は、Keycloakで直接公開するか、プロキシーを使用します。
プロキシーを使ってエンドポイントを公開するには、そのプロキシーのドキュメントを参照してください。 /auth/admin
エンドポイントへのリクエストへのアクセスを制御する必要があります。
Keycloakでは、エンドポイントを直接公開するために、IP制限とセパレートポートの2つのオプションが用意されています。
KeycloakのフロントエンドのURLで管理コンソールにアクセスできなくなった場合は、デフォルトのホストネーム・プロバイダーに固定の管理URLを設定してください。
IP制限
特定のIPアドレスのみに /auth/admin
へのアクセスを制限することができます。たとえば、 /auth/admin
へのアクセスを、 10.0.0.1
から 10.0.0.255
の範囲のIPアドレスに制限することができます。
<subsystem xmlns="urn:jboss:domain:undertow:12.0">
...
<server name="default-server">
...
<host name="default-host" alias="localhost">
...
<filter-ref name="ipAccess"/>
</host>
</server>
<filters>
<expression-filter name="ipAccess" expression="path-prefix('/auth/admin') -> ip-access-control(acl={'10.0.0.0/24 allow'})"/>
</filters>
...
</subsystem>
また、これらのCLIコマンドを使って、特定のIPアドレスへのアクセスを制限することもできます。
/subsystem=undertow/configuration=filter/expression-filter=ipAccess:add(,expression="path-prefix[/auth/admin] -> ip-access-control(acl={'10.0.0.0/24 allow'})")
/subsystem=undertow/server=default-server/host=default-host/filter-ref=ipAccess:add()
プロキシーを使用してIP制限を行う場合は、KeycloakがプロキシーのIPアドレスではなく、クライアントのIPアドレスを受信するようにプロキシーを設定してください。 |
ポート制限
/auth/admin
を別の未公開ポートに公開することができます。たとえば、/auth/admin
をポート 8444
で公開し、デフォルトポート 8443
へのアクセスを防ぐことができます。
<subsystem xmlns="urn:jboss:domain:undertow:12.0">
...
<server name="default-server">
...
<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
<https-listener name="https-admin" socket-binding="https-admin" security-realm="ApplicationRealm" enable-http2="true"/>
<host name="default-host" alias="localhost">
...
<filter-ref name="portAccess"/>
</host>
</server>
<filters>
<expression-filter name="portAccess" expression="path-prefix('/auth/admin') and not equals(%p, 8444) -> response-code(403)"/>
</filters>
...
</subsystem>
...
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
...
<socket-binding name="https" port="${jboss.https.port:8443}"/>
<socket-binding name="https-admin" port="${jboss.https.port:8444}"/>
...
</socket-binding-group>
CLIコマンドを使って、 /auth/admin
をポート 8444
に公開し、デフォルトのポート 8443
にはアクセスできないようにすることができます。
/socket-binding-group=standard-sockets/socket-binding=https-admin/:add(port=8444)
/subsystem=undertow/server=default-server/https-listener=https-admin:add(socket-binding=https-admin, security-realm=ApplicationRealm, enable-http2=true)
/subsystem=undertow/configuration=filter/expression-filter=portAccess:add(,expression="path-prefix('/auth/admin') and not equals(%p, 8444) -> response-code(403)")
/subsystem=undertow/server=default-server/host=default-host/filter-ref=portAccess:add()
ブルートフォースアタック
ブルートフォース攻撃とは、何度もログインを試みてユーザーのパスワードを推測しようとする攻撃のことです。Keycloakにはブルートフォース検知機能があり、ログイン失敗回数が指定した閾値を超えた場合、ユーザー・アカウントを一時的に無効にすることができます。
Keycloakはデフォルトで、ブルートフォース検知を無効にします。この機能を有効にすると、ブルートフォース攻撃から保護されます。 |
この保護機能を有効にするには以下のようにします。
-
メニューの Realm Settings をクリックします。
-
Security Defenses タブをクリックします。
-
Brute Force Detection タブをクリックします。
ブルートフォース検出
Keycloakは、攻撃を検知すると、永久ロックアウトと一時ロックアウトのアクションを配備できます。永久ロックアウトは、管理者が再び有効にするまでユーザー・アカウントを無効にします。一時的ロックアウトは、一定期間、ユーザー・アカウントを無効にします。攻撃が続くと、アカウントが無効になる期間は長くなります。
ユーザーが一時的にロックされている状態でログインしようとすると、Keycloakはデフォルトの |
共通パラメーター
名前 | 説明 | デフォルト |
---|---|---|
Max Login Failures |
ログイン失敗の最大回数。 |
30回失敗 |
Quick Login Check Milliseconds |
ログインを試みるまでの最小時間。 |
1000ミリ秒 |
Minimum Quick Login Wait |
ログイン試行が Quick Login Check Milliseconds よりも早かった場合に、ユーザーを無効にする最小の時間です。 |
1分 |
永続的ロックアウト・フロー
-
ログインに成功した場合
-
count
のリセット
-
-
ログインに失敗した場合
-
count
のインクリメント -
count
が Max Login Failures より大きい場合 …-
ユーザーを永続的に無効にします
-
-
今回の失敗と前回の失敗の間の時間が Quick Login Check Milliseconds よりも短ければ …
-
Minimum Quick Login Wait の間、ユーザーを一時的に無効にします
-
-
Keycloakがユーザーを無効にすると、管理者がそのユーザーを有効にするまで、そのユーザーはログインできなくなります。アカウントを有効にすると、 count
がリセットされます。
一時ロックアウト・パラメーター
名前 | 説明 | デフォルト |
---|---|---|
Wait Increment |
ユーザーのログイン試行回数が Max Login Failures を超えたときに、ユーザーが一時的に無効になる時間を加算した時間。 |
1分 |
Max Wait |
ユーザーが一時的に無効になる最大時間。 |
15分 |
Failure Reset Time |
失敗回数がリセットされる時間です。このタイマーは、最後に失敗したログインから実行されます。 |
12時間 |
一時的ロックアウト・アルゴリズム
-
ログインに成功した場合
-
count
のリセット
-
-
ログインに失敗した場合
-
今回の故障から前回の故障までの時間が Failure Reset Time よりも長い場合 …
-
count
のリセット
-
-
count
のインクリメント -
Wait Increment * (
count
/ Max Login Failures) を使ってwait
を計算します。除算は整数に切り捨てられた整数除算です。 -
wait
が0で、今回の失敗と前回の失敗の間の時間が Quick Login Check Milliseconds 以下の場合、wait
を Minimum Quick Login Wait に設定します。-
wait
と Max 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
システム管理者は、このリストに属性を追加する方法があります。設定は現在、サーバーレベルで利用できます。この設定を standalone(-*).xml
ファイルのKeycloakサーバー・サブシステムの設定に追加できます。
<spi name="userProfile"> <provider name="legacy-user-profile" enabled="true"> <properties> <property name="read-only-attributes" value="["foo","bar*"]"/> <property name="admin-read-only-attributes" value="["foo"]"/> </properties> </provider> </spi>
次のコマンドでJBoss CLIを使用して、同じ設定を行うことができます。
/subsystem=keycloak-server/spi=userProfile/:add /subsystem=keycloak-server/spi=userProfile/provider=legacy-user-profile/:add(properties={},enabled=true) /subsystem=keycloak-server/spi=userProfile/provider=legacy-user-profile/:map-put(name=properties,key=read-only-attributes,value=[foo,bar*]) /subsystem=keycloak-server/spi=userProfile/provider=legacy-user-profile/:map-put(name=properties,key=admin-read-only-attributes,value=[foo])
この例では、ユーザーと管理者は属性 foo
を更新できません。ユーザーは、 bar
で始まる属性を編集することはできません。たとえば、 bar
や barrier
です。設定では大文字と小文字が区別されないため、この例では FOO
や BarRier
などの属性も拒否されます。ワイルドカード文字 *
は属性名の末尾でのみサポートされるため、管理者は指定された文字で始まるすべての属性を効果的に拒否できます。属性の中央にある *
は通常の文字と見なされます。
クリック・ジャッキング
クリックジャッキングとは、ユーザーが認識しているものとは異なるユーザーインターフェース要素をクリックさせて、ユーザーを騙す手法です。悪意のあるサイトでは、対象サイトの重要なボタンの直下に配置されたダミーのボタン群の上に、透明なiFrameを重ねてロードします。ユーザーが見えるボタンをクリックすると、隠れたページのボタンをクリックしたことになります。攻撃者は、この方法を使ってユーザーの認証情報を盗み、ユーザーのリソースにアクセスすることができます。
デフォルトでは、Keycloakによるすべてのレスポンスは、この現象を防ぐことができるいくつかの特定のHTTPヘッダーを設定します。具体的には、 X-Frame-Options と Content-Security-Policy が設定されます。この2つのヘッダーの定義を見ると、ブラウザーのアクセスを細かく制御できる部分がたくさんあるので、参考にしてください。
管理コンソールでは、X-Frame-OptionsヘッダーとContent-Security-Policyヘッダーの値を指定することができます。
-
メニュー項目の Realm Settings をクリックします。
-
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 Model とAudienceサポートを参照して覧ください。
Limit Authentication Sessions
Webブラウザーで初めてログインページを開くと、Keycloakは認証中セッションと呼ばれるオブジェクトを作成し、リクエストに関するいくつかの有用な情報を保存します。同じブラウザーの別のタブから新しいログインページを開くたびに、Keycloakは認証中サブセッションと呼ばれる新しいレコードを作成し、認証中セッション内に保存されます。認証リクエストは、管理CLIなどのあらゆるタイプのクライアントから来る可能性があります。その場合、新しい認証中セッションも1つの認証中サブセッションで作成されます。認証中セッションは、ブラウザーフローを使用する以外の方法でも作成されることに注意してください。以下の文章は、ソースフローに関係なく適用されます。
このセクションでは、認証中セッションにInfinispanプロバイダーを使用するデプロイメントについて説明します。 |
認証中セッションは、内部的には RootAuthenticationSessionEntity
として格納されます。各 RootAuthenticationSessionEntity
には、複数の認証中サブセッションを AuthenticationSessionEntity
オブジェクトの集合として格納することができます。Keycloakは、認証中セッションを専用のInfinispanキャッシュに保存します。 RootAuthenticationSessionEntity
に含まれる AuthenticationSessionEntity
の数は、各キャッシュ・エントリーのサイズに影響します。認証中セッション・キャッシュの総メモリー使用量は、保存された RootAuthenticationSessionEntity
の数と、各 RootAuthenticationSessionEntity
内の AuthenticationSessionEntity
の数によって決定されます。
維持される RootAuthenticationSessionEntity
オブジェクトの数は、ブラウザーからの未完了のログインフローの数に対応します。 RootAuthenticationSessionEntity
の数を制御するために、高度なファイアウォール制御を使用して、入口のネットワーク・トラフィックを制限することが推奨されます。
多くのアクティブな RootAuthenticationSessionEntity
と多くの AuthenticationSessionEntity
が存在する環境では、より高いメモリ使用量が発生する可能性があります。ロードバランサーが セッション・スティッキネス をサポートしないか、設定されていない場合、クラスター内のネットワーク上の負荷が大幅に増加する可能性があります。この負荷の理由は、適切な認証中セッションを所有していないノードに到着した各リクエストは、所有ノード内の認証中セッション・レコードを検索して更新する必要があり、検索と保存の両方に個別のネットワーク伝送が含まれるからです。
SPI の authenticationSessions
で authSessionsLimit
プロパティーを設定することで、 RootAuthenticationSessionEntity
あたりの AuthenticationSessionEntity
の最大個数を設定することができます。デフォルトでは、1つの RootAuthenticationSessionEntity
に対して300の AuthenticationSessionEntity
が設定されています。この制限に達すると、新しい認証中セッションの要求があったときに、最も古い認証中サブセッションが削除されます。
次の例では、 RootAuthenticationSessionEntity
ごとにアクティブな AuthenticationSessionEntity
の数を100に制限する方法を示しています。
<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
...
<spi name="authenticationSessions">
<default-provider>infinispan</default-provider>
<provider name="infinispan" enabled="true">
<properties>
<property name="authSessionsLimit" value="100"/>
</properties>
</provider>
</spi>
...
</subsystem>
CLIコマンドを使用した同等の設定は以下になります。
/subsystem=keycloak-server/spi=authenticationSessions:add(default-provider=infinispan)
/subsystem=keycloak-server/spi=authenticationSessions/provider=infinispan:add(properties={authSessionsLimit => "100"},enabled=true)
アカウント・コンソール
Keycloakのユーザーは、アカウント・コンソールで自分のアカウントを管理できます。ユーザーは、プロファイルの管理、2要素認証の追加、アイデンティティー・プロバイダー・アカウントの追加、デバイスのアクティビティー管理を行うことができます。
-
アカウント・コンソールは、すべてのKeycloakユーザー・インターフェイスと同様に、完全にテーマ化および国際化可能です。たとえば、Personal Info ページに属性を追加することができます。詳しくは、 Server Developer Guide を参照してください。
アカウント・コンソールへのアクセス
アカウント・コンソールには、どのユーザーもアクセスできます。
-
アカウントが存在するKeycloakサーバーのレルム名とIPアドレスを控えておきます。
-
Webブラウザーで、
<server-root>/auth/realms/{realm-name}/account
のような形式のURLを入力します。 -
ログイン名とパスワードを入力してください。
サインイン方法の設定
このコンソールには、BASIC認証(ログイン名とパスワード)または2要素認証を使用してサインインすることができます。2要素認証の場合は、以下の手順のいずれかを使用します。
OTPによる2要素認証
-
OTPは、あなたのレルムにとって有効な認証メカニズムです。
-
メニューの Account Security をクリックします。
-
Signing In をクリックします。
-
Set Up Authenticator Application をクリックします。
サインイン -
画面に表示される案内に従って、 FreeOTP または Google Authenticator をのどちらかをOTPジェネレーターとしてモバイル端末で使用します。
-
スクリーンショットにあるQRコードをモバイル端末のOTPジェネレーターに読み込ませてください。
-
一度ログアウトして、再度ログインしてください。
-
プロンプトに応答して、モバイルデバイスで提供されるOTPを入力してください。
WebAuthnによる2要素認証
-
WebAuthnは、あなたのレルムで有効な二要素認証のメカニズムです。詳しくはWebAuthnのセクションを参照してください。
-
メニューの Account Security をクリックします。
-
Signing In をクリックします。
-
Set up Security Key をクリックします。
サインイン -
WebAuthnのセキュリティーキーを準備します。このキーの準備方法は、使用するWebAuthnセキュリティーキーの種類によって異なります。たとえば、USBベースのYubikeyの場合、ラップトップのUSBポートにキーを入れる必要があるかもしれません。
-
セキュリティーキーを登録する場合は、 Register をクリックしてください。
-
一度ログアウトして、再度ログインしてください。
-
認証フローが正しく設定されている場合、第2要素としてセキュリティーキーで認証するようメッセージが表示されます。
WebAuthnによるパスワードレス認証
-
WebAuthnは、あなたのレルムで有効なパスワードレス認証メカニズムです。詳しくはPasswordless WebAuthn のセクションを参照してください。
-
メニューの Account Security をクリックします。
-
Signing In をクリックします。
-
Passwordless のセクションで、 Set up Security Key をクリックします。
サインイン -
WebAuthnのセキュリティーキーを準備します。このキーの準備方法は、使用するWebAuthnセキュリティーキーの種類によって異なります。たとえば、USBベースのYubikeyの場合、ラップトップのUSBポートにキーを入れる必要があるかもしれません。
-
セキュリティーキーを登録する場合は、 Register をクリックしてください。
-
一度ログアウトして、再度ログインしてください。
-
認証フローが正しく設定されている場合、第2要素であるセキュリティーキーによる認証を促すメッセージが表示されます。これでログイン時にパスワードを入力する必要はありません。
デバイスのアクティビティーの表示
アカウントにログインしているデバイスを表示することができます。
-
メニューの Account Security をクリックします。
-
Device Activity をクリックします。
-
不審な点があれば、デバイスをログアウトする。
アイデンティティー・プロバイダー・アカウントの追加
アカウントに<>を付けてリンクすることができます<_identity_broker, identity broker>。このオプションは、ソーシャルプロバイダーのアカウントをリンクするためによく使用されます。</_identity_broker,>
-
管理コンソールにログインします。
-
メニューの Identity Providers をクリックします。
-
プロバイダーを追加する」をクリックします。
-
プロバイダーを選択し、各項目を入力します。
-
アカウントコンソールに戻る。
-
メニューの Account Security をクリックします。
-
Linked Accounts をクリックします。
追加したアイデンティティー・プロバイダーはこのページに表示されます。
管理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
環境変数 繰り返しを避けるために、このドキュメントの残りの部分では、CLIの違いが |
管理CLIの利用
管理CLIは、管理RESTエンドポイントにHTTPリクエストを行います。管理RESTエンドポイントへのアクセスには認証が必要です。
特定のエンドポイントのJSON属性の詳細については、管理REST APIのドキュメントを参照してください。 |
-
ログインして認証されたセッションを開始します。CRUD(Create、Read、Update、Delete)操作ができるようになります。
例:
-
Linuxの場合:
$ kcadm.sh config credentials --server http://localhost:8080/auth --realm demo --user admin --client admin $ kcadm.sh create realms -s realm=demorealm -s enabled=true -o $ CID=$(kcadm.sh create clients -r demorealm -s clientId=my_client -s 'redirectUris=["http://localhost:8980/myapp/*"]' -i) $ kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json
-
Windowsの場合:
c:\> kcadm config credentials --server http://localhost:8080/auth --realm demo --user admin --client admin c:\> kcadm create realms -s realm=demorealm -s enabled=true -o c:\> kcadm create clients -r demorealm -s clientId=my_client -s "redirectUris=[\"http://localhost:8980/myapp/*\"]" -i > clientid.txt c:\> set /p CID=<clientid.txt c:\> kcadm get clients/%CID%/installation/providers/keycloak-oidc-keycloak-json
-
-
プロダクション環境では、トークンの公開を避けるために、
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/auth --realm master --user admin --password admin
この機構は、取得したアクセストークンとそれに関連するリフレッシュトークンを保存することで、 kcadm
コマンドの呼び出しの間に認証済みセッションを維持します。他にも、プライベートな設定ファイルにシークレットを保持することができます。詳細は 次の章 を参照してください。
2つ目のメカニズムは、各コマンドの呼び出しをその間だけ認証するものです。このメカニズムでは、サーバーの負荷が高まり、トークンを取得するためのラウンドトリップにかかる時間が長くなります。この方法の利点は、起動の間にトークンを保存する必要がないため、ディスクに何も保存されないことです。Keycloakでは、--no-config
という引数を指定すると、このモードを使用します。
たとえば、操作を行う際には、認証に必要なすべての情報を指定します。
$ kcadm.sh get realms --no-config --server http://localhost:8080/auth --realm master --user admin --password admin
管理CLIの使い方の詳細については、 kcadm.sh help
コマンドを実行してください。
認証済みセッションの開始に関する詳細は、 kcadm.sh config credentials --help
コマンドを実行してください。
代替設定の使用
デフォルトでは、管理CLIは kcadm.config
という名前の設定ファイルを管理しています。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]
create
、 get
、 update
、 delete
コマンドは、それぞれHTTPの POST
、 GET
、 PUT
、 DELETE
に対応しています。ENDPOINTはターゲットとなるリソースのURIで、絶対指定( http:
または https:
で始まる)または相対指定が可能で、Keycloakでは以下の形式で絶対指定のURLを構成しています。
SERVER_URI/admin/realms/REALM/ENDPOINT
たとえば、サーバーhttp://localhost:8080/authに対して認証を行い、レルムが master
である場合、 users
をENDPOINTとして使用すると、http://localhost:8080/auth/admin/realms/master/usersのリソースURLが作成されます。
ENDPOINTを clients
に設定した場合、有効なリソースURIはhttp://localhost:8080/auth/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/auth --realm master --user admin --password admin $ kcadm.sh create users -s username=testuser -s enabled=true -r demorealm
この例では、 master
レルムの admin
ユーザーとして認証されたセッションを開始します。その後、リソースURL http://localhost:8080/auth/admin/realms/demorealm/users
に対してPOSTコールを実行します。
create
と update
のコマンドは、JSONのボディーをサーバーに送信します。また、 -f FILENAME
を使うと、あらかじめ作成しておいたドキュメントをファイルから読み込むことができます。-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
コマンドを使用して、新しい有効なレルムを作成します。属性を realm
と enabled
に設定します。
$ 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
レルムの更新
-
レルムのすべての属性を変更したくない場合は、
-s
オプションを使って属性に新しい値を設定します。例:
$ kcadm.sh update realms/demorealm -s enabled=false
-
すべての書き込み可能な属性に新しい値を設定したい場合は、次の通りです。
-
get
コマンドを実行します。 -
JSONファイルの現在の値を編集します。
-
再送信。
例:
$ kcadm.sh get realms/demorealm > demorealm.json $ vi demorealm.json $ kcadm.sh update realms/demorealm -f demorealm.json
-
レルムの削除
以下のコマンドを実行して、レルムを削除してください。
$ kcadm.sh delete realms/demorealm
レルムのすべてのログイン・ページ・オプションを有効にする
特定の機能を制御する属性を true
に設定します。
例:
$ kcadm.sh update realms/demorealm -s registrationAllowed=true -s registrationEmailAsUsername=true -s rememberMe=true -s verifyEmail=true -s resetPasswordAllowed=true -s editUsernameAllowed=true
レルム鍵の一覧表示
ターゲットレルムの keys
エンドポイントに対して get
オペレーションを使用します。
$ kcadm.sh get keys -r demorealm
新しいレルム鍵の生成
-
新しいRSA生成キーペアを追加する前に、対象レルムのIDを取得します。
例:
$ kcadm.sh get realms/demorealm --fields id --format csv --noquotes
-
kcadm.sh get keys -r demorealm
で明らかになった既存のプロバイダーよりも高い優先度で、新しい鍵プロバイダーを追加します。例:
-
Linuxの場合:
$ kcadm.sh create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keySize=["2048"]'
-
Windowsの場合:
c:\> kcadm create components -r demorealm -s name=rsa-generated -s providerId=rsa-generated -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s "config.priority=[\"101\"]" -s "config.enabled=[\"true\"]" -s "config.active=[\"true\"]" -s "config.keySize=[\"2048\"]"
-
-
parentId
属性を対象レルムのIDの値に設定します。新たに追加された鍵は、
kcadm.sh get keys -r demorealm
で明らかにされるように、アクティブな鍵になっています。
Javaキーストア・ファイルから新しいレルム鍵を追加する
-
新しい鍵プロバイダーを追加すると、JKSファイルとしてあらかじめ用意された新しいキーペアを追加することができます。
以下に例を示します。
-
Linuxの場合:
$ kcadm.sh create components -r demorealm -s name=java-keystore -s providerId=java-keystore -s providerType=org.keycloak.keys.KeyProvider -s parentId=959844c1-d149-41d7-8359-6aa527fca0b0 -s 'config.priority=["101"]' -s 'config.enabled=["true"]' -s 'config.active=["true"]' -s 'config.keystore=["/opt/keycloak/keystore.jks"]' -s 'config.keystorePassword=["secret"]' -s 'config.keyPassword=["secret"]' -s 'config.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\"]"
-
-
keystore
、keystorePassword
、keyPassword
、alias
の属性値を、使用するキーストアに合わせて変更してください。 -
parentId
属性を対象レルムのIDの値に設定します。
鍵をパッシブにする、または無効にする
-
パッシブにする鍵を特定します。
$ kcadm.sh get keys -r demorealm
-
鍵の
providerId
属性を使って、components/PROVIDER_ID
のようなエンドポイントURIを構築します。 -
update
を行う。例:
-
Linuxの場合:
$ kcadm.sh update components/PROVIDER_ID -r demorealm -s 'config.active=["false"]'
-
Windowsの場合:
c:\> kcadm update components/PROVIDER_ID -r demorealm -s "config.active=[\"false\"]"
以下のように、他の主要な属性を更新することができます。
-
-
たとえば、
config.enabled=["false"]
のように、鍵を無効にするためにenabled
の値を設定してください。 -
鍵の優先度を変更するために新しい
priority
値を設定します。たとえば、config.priority=["110"]
です。
古い鍵を削除する
-
削除する鍵が非アクティブであり、無効化されていることを確認してください。このアクションは、アプリケーションやユーザーが保持する既存のトークンが失敗するのを防ぐためのものです。
-
削除する鍵を特定します。
$ kcadm.sh get keys -r demorealm
-
削除を実行するには、鍵の
providerId
を使用します。$ kcadm.sh delete components/PROVIDER_ID -r demorealm
レルムのイベントログの設定
events/config
エンドポイントで update
コマンドを使用してください。
eventsListeners
属性には、イベントを受信するすべてのイベントリスナーを指定するEventListenerProviderFactoryのIDのリストが含まれています。ビルトインのイベント・ストレージを制御する属性が用意されているので、管理REST APIを使って過去のイベントを照会することができます。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
キャッシュのフラッシュ
-
キャッシュをクリアするには、これらのエンドポイントのいずれかで
create
コマンドを使用します。-
clear-realm-cache
-
clear-user-cache
-
clear-keys-cache
-
-
realm
を対象のレルムと同じ値に設定します。例:
$ kcadm.sh create clear-realm-cache -r demorealm -s realm=demorealm $ kcadm.sh create clear-user-cache -r demorealm -s realm=demorealm $ kcadm.sh create clear-keys-cache -r demorealm -s realm=demorealm
エクスポートされた.jsonファイルからのレルムのインポート
-
partialImport
エンドポイントでcreate
コマンドを使用します。 -
ifResourceExists
をFAIL
、SKIP
、OVERWRITE
のいずれかに設定します。 -
エクスポートされたレルム
.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'
クライアントロールの作成
-
クライアントを特定します。
-
利用可能なクライアントの一覧を表示するには、
get
コマンドを使用します。$ kcadm.sh get clients -r demorealm --fields id,clientId
-
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_NAME
( user
は既存ロールの名前)。
例:
$ 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
コマンドを使用します。
-
複合ロールに対して 割り当てられた レルムロールを一覧表示するには、対象となる複合ロールを名前(
--rname
オプション)またはID(--rid
オプション)で指定します。例:
$ kcadm.sh get-roles -r demorealm --rname testrole
-
有効な レルムロールをリストアップするには、
--effective
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --rname testrole --effective
-
複合ロールに追加できるレルムロールの一覧を表示するには、
--available
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --rname testrole --available
複合ロールに割り当てられた、利用可能な、有効なクライアントロールの一覧表示
複合ロールが割り当てられ、利用可能かつ有効なクライアントロールを一覧表示するには、 get-roles
コマンドを使用します。
-
複合ロールに対して 割り当てられた クライアントロールを一覧表示するには、対象となる複合ロールを名前(
--rname
オプション)またはID(--rid
オプション)で、クライアントをclientId属性(--cclientid
オプション)またはID(--cid
オプション)で指定します。例:
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management
-
有効な レルムロールをリストアップするには、
--effective
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --effective
-
対象となる複合ロールに追加できるレルムロールの一覧を表示するには、
--available
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --rname testrole --cclientid realm-management --available
レルムロールを複合ロールに追加する
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-management
、 create-client
、 view-users
ロールを testrole
複合ロールに追加します。
$ kcadm.sh add-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users
クライアントロールへのクライアントロールの追加
-
get-roles
コマンドを使用して複合クライアントロールのIDを特定します。例:
$ kcadm.sh get-roles -r demorealm --cclientid test-client --rolename operations
-
test-client
というclientId属性、support
というクライアントロール、operations
というクライアントロールを持つクライアントが存在し、IDが "fc400897-ef6a-4e8c-872b-1581b7fa8a71" である複合ロールになっているとします。 -
次の例を使用して、複合ロールに別のロールを追加します。
$ kcadm.sh add-roles -r demorealm --cclientid test-client --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --rolename support
-
get-roles --all
コマンドを使用して、複合ロールのロールを一覧表示します。例:
$ kcadm.sh get-roles --rid fc400897-ef6a-4e8c-872b-1581b7fa8a71 --all
複合ロールからのクライアントロールの削除
複合ロールからクライアントロールを削除するには、remove-roles
コマンドを使用します。
次の例を使用して、 realm-management
クライアントに定義された create-client
と view-users
の2つのロールを複合ロール testrole
から削除します。
$ kcadm.sh remove-roles -r demorealm --rname testrole --cclientid realm-management --rolename create-client --rolename view-users
グループへのクライアント・ロールの追加
レルムロールとクライアントロールを追加するには、 add-roles
コマンドを使用します。
次の例では、クライアントに定義された realm-management
、create-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-client
と view-users
を Group
グループから削除しています。
詳しくは、グループ操作を参照してください。
$ kcadm.sh remove-roles -r demorealm --gname Group --cclientid realm-management --rolename create-client --rolename view-users
クライアント操作
クライアントの作成
-
clients
のエンドポイントでcreate
コマンドを実行して、新しいクライアントを作成します。例:
$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true
-
アダプターに認証用のシークレットを設定する場合は、シークレットを指定します。
例:
$ kcadm.sh create clients -r demorealm -s clientId=myapp -s enabled=true -s clientAuthenticatorType=client-secret -s secret=d0b8122f-8dfb-46b7-b68a-f5cc4e25d000
クライアントの一覧表示
クライアントの一覧を表示するには、 clients
エンドポイントで get
コマンドを使用します。
この例では、出力をフィルタリングして、 id
と clientId
の属性だけをリストアップしています。
$ 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/auth/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
ユーザーは username
、 firstName
、 lastName
または email
でフィルタリングできます。
例:
$ kcadm.sh get users -r demorealm -q email=google.com $ kcadm.sh get users -r demorealm -q 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
コマンドを使うと、ユーザーに割り当てられた、利用可能かつ有効なレルムロールをリストアップできます。
-
対象となるユーザーをユーザー名またはIDで指定すると、そのユーザーに 割り当てられた レルムロールが一覧表示されます。
例:
$ kcadm.sh get-roles -r demorealm --uusername testuser
-
有効な レルムロールをリストアップするには、
--effective
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --uusername testuser --effective
-
ユーザーに追加できるレルムロールの一覧を表示するには、
--available
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --uusername testuser --available
ユーザーに割り当てられた、利用可能な、有効なクライアントロールの一覧表示
ユーザーに割り当てられた、利用可能かつ有効なクライアントロールの一覧を表示するには、 get-roles
コマンドを使用します。
-
対象となるユーザーをユーザー名(
--uusername
オプション)またはID(--uid
オプション)で、クライアントをclientId属性(--cclientid
オプション)またはID(--cid
オプション)で指定すると、そのユーザーに 割り当てられた クライアントロールの一覧が表示されます。例:
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management
-
有効な レルムロールをリストアップするには、
--effective
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --effective
-
ユーザーに追加できるレルムロールの一覧を表示するには、
--available
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --uusername testuser --cclientid realm-management --available
ユーザーにレルムロールを追加する
ユーザーにレルムロールを追加するには、 add-roles
コマンドを使用します。
次の例では,ユーザー testuser
に user
ロールを追加しています。
$ 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
ユーザー・セッションの一覧表示
-
ユーザーのIDを特定する。
-
IDを使用して、
users/ID/sessions
のようなエンドポイントURIを構成することができます。 -
ユーザーのセッションの一覧を取得するには、
get
コマンドを使用します。例:
$kcadm get users/6da5ab89-3397-4205-afaa-e201ff638f9e/sessions
特定のセッションからユーザーをログアウトする
-
上記のセッションのIDを決定します。
-
セッションのIDを使用して、
sessions/ID
のようなエンドポイントURIを構成します。 -
セッションを無効にするには、
delete
コマンドを使用します。例:
$ kcadm.sh delete sessions/d0eaa7cc-8c5d-489d-811a-69d3c4ec84d1
すべてのセッションからユーザーをログアウトする
ユーザーの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
グループを別のグループの下に移動する
-
既存の親グループのID、既存の子グループのIDを検索します。
-
親グループのIDを使って、
groups/PARENT_GROUP_ID/children
のようなエンドポイントURIを作成します。 -
このエンドポイントで
create
コマンドを実行し、子グループのIDをJSONのボディーとして渡します。
例:
$ kcadm.sh create groups/51204821-0580-46db-8f2d-27106c6b5ded/children -r demorealm -s id=08d410c6-d585-4059-bb07-54dcb92c5094
特定のユーザーのグループを取得する
ユーザーのIDを使用して、ユーザーのグループへの所属を判断し、 users/USER_ID/groups
のようなエンドポイントURIを構成します。
例:
$ kcadm.sh get users/b544f379-5fc4-49e5-8a8d-5cfb71f46f53/groups -r demorealm
グループにユーザーを追加する
ユーザーをグループに追加するには、 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
コマンドを使用します。
-
ターゲットグループを名前 (
--gname
オプション)、パス (--gpath
オプション)、または ID (--gid
オプション) で指定すると、そのグループに 割り当てられた レルムロールを一覧表示します。例:
$ kcadm.sh get-roles -r demorealm --gname Group
-
有効な レルムロールをリストアップするには、
--effective
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --gname Group --effective
-
グループに追加できるレルムロールを一覧表示するには、
--available
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --gname Group --available
グループに割り当てられた、利用可能で、有効なクライアントロールの一覧表示
グループに割り当てられた、利用可能かつ有効なクライアントロールを一覧するには get-roles
コマンドを使用します。
-
ターゲットグループを名前 (
--gname
オプション) または ID (--gid
オプション) で指定します。 -
クライアントをclientId属性 (
--cclientid
オプション) またはID (--id
オプション) で指定すると、そのユーザーに 割り当てられた クライアントロールを一覧表示します。例:
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management
-
有効な レルムロールをリストアップするには、
--effective
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --effective
-
まだグループに追加できるレルムロールを一覧表示するには、
--available
オプションを使用します。例:
$ kcadm.sh get-roles -r demorealm --gname Group --cclientid realm-management --available
アイデンティティー・プロバイダーの操作
使用可能なアイデンティティー・プロバイダー の一覧表示
利用可能なアイデンティティー・プロバイダーを一覧表示するには、 serverinfo
エンドポイントを使用します。
例:
$ kcadm.sh get serverinfo -r demorealm --fields 'identityProviders(*)'
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 アイデンティティー・プロバイダーの設定
-
新しいアイデンティティー・プロバイダーのインスタンスを作成する際には、
keycloak-oidc
をproviderId
として使用します。 -
config
属性にauthorizationUrl
、tokenUrl
、clientId
、clientSecret
を指定します。例:
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=keycloak-oidc -s providerId=keycloak-oidc -s enabled=true -s 'config.useJwksUrl="true"' -s config.authorizationUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/auth -s config.tokenUrl=http://localhost:8180/auth/realms/demorealm/protocol/openid-connect/token -s config.clientId=demo-oidc-provider -s config.clientSecret=secret
OpenID Connect アイデンティティー・プロバイダーの設定
一般的なOpenID Connectプロバイダーを、Keycloak OpenID Connectプロバイダーを設定するのと同じ方法で設定します。ただし、 providerId
属性の値を oidc
に設定します。
SAML 2 アイデンティティー・プロバイダーの設定
-
providerId
には、saml
を使用します。 -
config
属性にsingleSignOnServiceUrl
、nameIDPolicyFormat
、signatureAlgorithm
を指定します。
例:
$ kcadm.sh create identity-provider/instances -r demorealm -s alias=saml -s providerId=saml -s enabled=true -s 'config.useJwksUrl="true"' -s config.singleSignOnServiceUrl=http://localhost:8180/auth/realms/saml-broker-realm/protocol/saml -s config.nameIDPolicyFormat=urn:oasis:names:tc:SAML:2.0:nameid-format:persistent -s config.signatureAlgorithm=RSA_SHA256
Facebookアイデンティティー・プロバイダーの設定
-
ProviderId
にはfacebook
を使用します。 -
config
属性を指定します。clientId
とclientSecret
を指定します。これらの属性は、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アイデンティティー・プロバイダーの設定
-
ProviderId
にはgoogle
を使用します。 -
config
属性にclientId
とclientSecret
を指定します。これらの属性は、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アイデンティティー・プロバイダーの設定
-
providerId
には、twitter
を使用します。 -
config
属性にclientId
とclientSecret
を指定します。これらの属性は、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アイデンティティー・プロバイダーの設定
-
providerId
には、github
を使用します。 -
config
属性のclientId
とclientSecret
を指定します。これらの属性は、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アイデンティティー・プロバイダーの設定
-
providerId
には、linkedin
を使用します。 -
config
属性のclientId
とclientSecret
を指定します。これらの属性は、アプリケーションの 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 アイデンティティー・プロバイダーの設定
-
ProviderId
にはmicrosoft
を使用します。 -
config
属性のclientId
とclientSecret
を指定します。これらの属性は、アプリケーションの 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アイデンティティー・プロバイダーの設定
-
providerId
にとして、stackoverflow
コマンドを使用します。 -
config
属性のclientId
、clientSecret
、および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ストレージ・プロバイダーの設定
-
components
エンドポイントに対してcreate
コマンドを使用します。 -
parentId
属性の値として、レルムIDを指定します。 -
providerId
属性の値としてkerberos
を指定し、providerType
属性の値としてorg.keycloak.storage.UserStorageProvider
を指定します。 -
例:
$ 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ユーザー・ストレージ・プロバイダーの設定
-
components
エンドポイントに対してcreate
コマンドを使用します。 -
providerId
属性の値としてldap
を指定し、providerType
属性の値としてorg.keycloak.storage.UserStorageProvider
を指定します。 -
parentId
属性の値として、レルムIDを指定します。 -
次の例を使用して、Kerberos統合LDAPプロバイダーを作成します。
$ kcadm.sh create components -r demorealm -s name=kerberos-ldap-provider -s providerId=ldap -s providerType=org.keycloak.storage.UserStorageProvider -s parentId=3d9c572b-8f33-483f-98a6-8bb421667867 -s 'config.priority=["1"]' -s 'config.fullSyncPeriod=["-1"]' -s 'config.changedSyncPeriod=["-1"]' -s 'config.cachePolicy=["DEFAULT"]' -s config.evictionDay=[] -s config.evictionHour=[] -s config.evictionMinute=[] -s config.maxLifespan=[] -s 'config.batchSizeForSync=["1000"]' -s 'config.editMode=["WRITABLE"]' -s 'config.syncRegistrations=["false"]' -s 'config.vendor=["other"]' -s 'config.usernameLDAPAttribute=["uid"]' -s 'config.rdnLDAPAttribute=["uid"]' -s 'config.uuidLDAPAttribute=["entryUUID"]' -s 'config.userObjectClasses=["inetOrgPerson, organizationalPerson"]' -s 'config.connectionUrl=["ldap://localhost:10389"]' -s 'config.usersDn=["ou=People,dc=keycloak,dc=org"]' -s 'config.authType=["simple"]' -s 'config.bindDn=["uid=admin,ou=system"]' -s 'config.bindCredential=["secret"]' -s 'config.searchScope=["1"]' -s 'config.useTruststoreSpi=["ldapsOnly"]' -s 'config.connectionPooling=["true"]' -s 'config.pagination=["true"]' -s 'config.allowKerberosAuthentication=["true"]' -s 'config.serverPrincipal=["HTTP/localhost@KEYCLOAK.ORG"]' -s 'config.keyTab=["http.keytab"]' -s 'config.kerberosRealm=["KEYCLOAK.ORG"]' -s 'config.debug=["true"]' -s 'config.useKerberosForPasswordAuthentication=["true"]'
ユーザー・ストレージ・プロバイダー・インスタンスの削除
-
ストレージ・プロバイダー・インスタンスの
id
属性を使用して、components/ID
のようなエンドポイントURIを構成します。 -
このエンドポイントに対して
delete
コマンドを実行します。例:
$ kcadm.sh delete components/3d9c572b-8f33-483f-98a6-8bb421667867 -r demorealm
特定のユーザー・ストレージ・プロバイダーのすべてのユーザーの同期をトリガーする
-
ストレージ・プロバイダーの
id
属性を用いて、user-storage/ID_OF_USER_STORAGE_INSTANCE/sync
のようなエンドポイントURIを構成します。 -
action=triggerFullSync
クエリー・パラメーターを追加します。 -
create
コマンドを実行します。例:
$ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerFullSync
特定のユーザー・ストレージ・プロバイダーに対して、変更されたユーザーの同期をトリガーする
-
ストレージ・プロバイダーの
id
属性を用いて、user-storage/ID_OF_USER_STORAGE_INSTANCE/sync
のようなエンドポイントURIを構成します。 -
action=triggerChangedUsersSync
のクエリー・パラメーターを追加します。 -
create
コマンドを実行します。例:
$ kcadm.sh create user-storage/b7c63d02-b62a-4fc1-977c-947d6a09e1ea/sync?action=triggerChangedUsersSync
LDAPユーザー・ストレージの接続をテストする
-
testLDAPConnection
のエンドポイントに対してget
コマンドを実行します。 -
クエリー・パラメーター
bindCredential
、bindDn
、connectionUrl
、useTruststoreSpi
を指定します。 -
クエリー・パラメーター
action
にtestConnection
を設定します。例:
$ kcadm.sh create testLDAPConnection -s action=testConnection -s bindCredential=secret -s bindDn=uid=admin,ou=system -s connectionUrl=ldap://localhost:10389 -s useTruststoreSpi=ldapsOnly
LDAPユーザー・ストレージ認証をテストする
-
testLDAPConnection
のエンドポイントに対してget
コマンドを実行します。 -
クエリー・パラメーターとして、
bindCredential
、bindDn
、connectionUrl
、useTruststoreSpi
を指定します。 -
クエリー・パラメーター
action
にtestAuthentication
を設定します。例:
$ kcadm.sh create testLDAPConnection -s action=testAuthentication -s bindCredential=secret -s bindDn=uid=admin,ou=system -s connectionUrl=ldap://localhost:10389 -s useTruststoreSpi=ldapsOnly
マッパーの追加
ハードコードされたロールLDAPマッパーの追加
-
components
エンドポイントに対してcreate
コマンドを実行します。 -
ProviderType
属性をorg.keycloak.storage.ldap.mappers.LDAPStorageMapper
に設定します。 -
parentId
属性にLDAPプロバイダー・インスタンスのIDを設定します。 -
providerId
属性にhardcoded-ldap-role-mapper
を設定します。設定パラメーターにrole
の値を指定することを確認してください。例:
$ kcadm.sh create components -r demorealm -s name=hardcoded-ldap-role-mapper -s providerId=hardcoded-ldap-role-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config.role=["realm-management.create-client"]'
MS Active Directoryマッパーの追加
-
components
エンドポイントに対してcreate
コマンドを実行します。 -
ProviderType
属性をorg.keycloak.storage.ldap.mappers.LDAPStorageMapper
に設定します。 -
parentId
属性にLDAPプロバイダー・インスタンスのIDを設定します。 -
providerId
属性をmsad-user-account-control-mapper
に設定します。例:
$ kcadm.sh create components -r demorealm -s name=msad-user-account-control-mapper -s providerId=msad-user-account-control-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea
ユーザー属性LDAPマッパーの追加
-
components
エンドポイントに対してcreate
コマンドを実行します。 -
ProviderType
属性をorg.keycloak.storage.ldap.mappers.LDAPStorageMapper
に設定します。 -
parentId
属性にLDAPプロバイダー・インスタンスのIDを設定します。 -
user-attribute-ldap-mapper
にproviderId
属性を設定します。例:
$ kcadm.sh create components -r demorealm -s name=user-attribute-ldap-mapper -s providerId=user-attribute-ldap-mapper -s providerType=org.keycloak.storage.ldap.mappers.LDAPStorageMapper -s parentId=b7c63d02-b62a-4fc1-977c-947d6a09e1ea -s 'config."user.model.attribute"=["email"]' -s 'config."ldap.attribute"=["mail"]' -s 'config."read.only"=["false"]' -s 'config."always.read.value.from.ldap"=["false"]' -s 'config."is.mandatory.in.ldap"=["false"]'
グループLDAPマッパーの追加
-
components
エンドポイントに対してcreate
コマンドを実行します。 -
ProviderType
属性をorg.keycloak.storage.ldap.mappers.LDAPStorageMapper
に設定します。 -
parentId
属性にLDAPプロバイダー・インスタンスのIDを設定します。 -
providerId
属性にgroup-ldap-mapper
を設定します。例: