Server Administration Guide

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ユーザー属性マッパー。ユーザー名、名、姓、電子メールなどの基本的な 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サーバーのドキュメントを参照してください。

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

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

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

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

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

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

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

このライブラリーのRPMは、 Keycloakのリポジトリーで見つけることができます。このRPMをインストールする前に、このコマンドでRPMの署名を確認してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

OTPジェネレーターに使用できるKeycloakのアルゴリズムは、タイムベースとカウンターベースがあります。

タイムベースのワンタイムパスワード（TOTP）では、トークン生成器が現在の時刻と共有のシークレットをハッシュ化します。サーバーは、時間枠内のハッシュと提出された値を比較することで、OTPを検証します。TOTPは、短い時間枠の中で有効です。

カウンターベースのワンタイムパスワード（HOTP）では、Keycloak は現在時刻ではなく、共有カウンターを使用します。project_name}サーバーは、OTPログインが成功するたびにカウンターを増加させる。有効なOTPはログインに成功すると変化します。

TOTPは、HOTPのOTPが不定期に有効なのに対し、マッチング可能なOTPが短時間で有効なため、HOTPよりも安全性が高い。HOTPは、OTPの入力に時間制限がないため、TOTPよりもユーザーフレンドリーである。

HOTPは、サーバーがカウンターをインクリメントするたびに、データベースの更新を必要とします。この更新は、高負荷時に認証サーバーのパフォーマンスを低下させる。効率を上げるため、TOTPは使用したパスワードを記憶しないので、データベースの更新を行う必要はありません。欠点は、有効時間内にTOTPを再利用することが可能なことである。

Keycloakには、いくつかの組み込みフローがあります。これらのフローを変更することはできませんが、フローのRequirementを自分のニーズに合わせて変更することは可能です。

フローを設計する際には、重要な機能性とセキュリティーに関する考慮事項が適用されます。

フローを作成するには、以下を実行します。

新しいフローを作成する場合、まず次のオプションでトップレベルのフローを作成する必要があります。

Keycloakがフローを作成すると、Keycloakは Add step 、 Add flow ボタンを表示します。

フローとサブフローの挙動は3つの要因で決まります。

エグゼキューションには、リセットメールの送信からワンタイムパスワードの認証まで、さまざまなアクションがあります。エグゼキューションを追加するには、 Add step ボタンをクリックします。 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 オプションがあります。このアクションは、フローから要素を削除するものです。エクゼキューションには、 ⚙️ メニュー項目（歯車アイコン）があり、エクゼキューションを設定することができます。また、 Add step と Add flow のリンクを使用して、エクゼキューションとサブフローをサブフローに追加することが可能です。

エグゼキューションの順序が重要なです。エグゼキューションやサブフローは名前をドラッグすることで上下に移動させることができます。

フローの作成を説明するために、ここでは高度なブラウザー・ログイン・フローの作成について説明します。このフローの目的は、 WebAuthn を使ったパスワードレスでのログインと、パスワードとOTPによる二要素認証のどちらかをユーザーが選択できるようにすることです。

この段階では、フォームにはユーザー名は必要ですが、パスワードは必要ありません。セキュリティー・リスクを回避するために、パスワード認証を有効にする必要があります。

最後に、バインディングを変更します。

ユーザー名を入力すると、次のような流れで動作します。

ユーザーが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 を記録するように求められます。

このセクションでは、ステップアップ・メカニズムを利用して、高度なブラウザー・ログインフローを作成する方法について説明します。ステップアップ認証の目的は、ユーザーの特定の認証レベルに基づいて、クライアントやリソースへのアクセスを許可することです。

ここで、最初の認証レベルのフローを設定します。

次に、2つ目の認証レベルのフローを設定します。

最後に、バインディングを変更します。

ステップアップ・メカニズムを利用するためには、認証リクエストで要求された認証レベル（LoA）を指定します。このために、 claims パラメーターが使用されます。

claims パラメーターは、JSON形式で指定されます。

KeycloakのJavaScriptアダプターは、このJSONを簡単に構築し、ログイン・リクエストに送信するためのサポートを備えています。詳しくは、 JavaScriptアダプターのドキュメントを参照してください。

また、 claims パラメーターの代わりに、よりシンプルなパラメーター acr_values を使用することで、特定のレベルを非必須として要求することができます。これはOIDCの仕様に記載されています。

また、特定のクライアントのデフォルトレベルを設定することもできます。このレベルは、パラメーター acr_values または acr クレームを持つパラメーター claims が存在しない場合に使用されます。詳しくは、Client ACR設定を参照してください）。

詳細については、 オフィシャルのOIDC仕様 を参照してください。

フローロジック

前回設定した認証フローのロジックは以下の通りです。
クライアントが高い認証レベル、つまり認証レベル2（LoA 2）を要求した場合、ユーザーは完全な2要素認証を実行する必要があります。ユーザー名/パスワード + OTPの2要素認証が必要です。しかし、ユーザーが既にKeycloakのセッションを持っていて、もしユーザー名とパスワードでログインしていた場合（LoA 1）、ユーザーは2つ目の認証要素（OTP）だけを要求されます。

条件のオプション Max Age は、後続の認証レベルが有効な時間（何秒）を決定します。この設定は、後続の認証時にユーザーが再び認証要素の提示を求められるかどうかを決定するのに役立ちます。もし claims または acr_values パラメーターによって特定のレベルXが要求され、ユーザーがすでにレベルXで認証しているにもかかわらず、その有効期限が切れている場合（たとえば、最大年齢が300に設定されていて、ユーザーが310秒以前に認証された場合）、ユーザーはそのレベルで再認証を要求されることになります。しかし、そのレベルがまだ有効期限切れでない場合、そのユーザーは自動的にそのレベルで認証されたとみなされます。

値0の Max Age を使用すると、その特定のレベルがこの 1 回の認証に対してのみ有効であることを意味します。したがって、そのレベルを要求する再認証のたびに、そのレベルで再度認証する必要があります。これは、アプリケーションでより高いセキュリティーを必要とし（例：支払いの送信）、常に特定のレベルでの認証を必要とする操作に便利です。

パラメーターで明示的なレベルが要求されていない場合、Keycloakは、認証フローで最初に見つかったLoA条件（前述の例のUsername/Passwordなど）で認証を要求します。既にそのレベルで認証されているユーザーが、そのレベルの有効期限が切れた場合、ユーザーは再認証を要求されないが、トークンの acr は値0となります。この結果は、OIDC Core 1.0の仕様のセクション2にある long-lived browser cookie のみに基づく認証とみなされます。

サンプルのシナリオ

トークン内のACRクレーム

ACRクレームは acr クライアント・スコープで定義された acr loa level プロトコル・マッパーによってトークンに追加されます。このクライアント・スコープはレルムのデフォルトのクライアント・スコープであるため、レルムで新しく作成されたすべてのクライアントに追加されます。

トークンの中に acr というクレームを入れたくない場合や、それを追加するためのカスタムロジックが必要な場合は、クライアントからクライアント・スコープを削除することができます。

ログイン・リクエストが claims パラメーターで acr を essential クレームとして要求するリクエストを開始した場合、Keycloakは常に指定されたレベルのいずれかを返すことに注意してください。指定されたレベルのいずれかを返すことができない場合（たとえば、要求されたレベルが不明であったり、認証フローで設定された条件よりも大きい場合）、Keycloakはエラーをスローします。

Kerberosサーバーをセットアップする手順は、オペレーティング・システム（OS）とKerberosベンダーに依存します。Windows Active Directory、MIT Kerberos、およびお使いのOSのマニュアルを参照して、Kerberosサーバーのセットアップと設定を確認してください。

セットアップ時には、以下の手順で行ってください。

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

Keycloakが動作しているホストで、keytabファイル /tmp/http.keytab にアクセスできることを確認します。

マシンにKerberosクライアントをインストールします。

クライアントマシンは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 を作成する。たとえば、以下のようになります。

このコードの例は、Keycloakのサンプル配布ファイルまたはデモ配布ファイルのダウンロードの examples/kerberos に存在します。また、サンプルのソースを ここで 直接確認することもできます。

Kerberosプロトコルにおいて、 realm はKerberosプリンシパルの集合です。これらのプリンシパルの定義はKerberosデータベースに存在し、それは通常LDAPサーバーです。

Kerberosプロトコルは、レルム間の信頼を可能にします。たとえば、2つのKerberosレルム、AとBが存在する場合、レルム間信頼はレルムAからのユーザがレルムBのリソースにアクセスすることを可能にします。レルムBはレルムAを信頼します。

Keycloakサーバーは、クロス・レルム・トラストをサポートしています。これを実装するには、以下を実行します。

たとえば、Kerberosのプリンシパル・ユーザーである john@A は、LDAPにおいて uid=john,ou=People,dc=example,dc=com といったLDAP DNで利用可能でなければなりません。レルムAとレルムBのユーザーを認証したい場合は、LDAPがレルムAとレルムBの両方のユーザーを見つけることができることを確認してください。

問題が発生した場合は、追加のログを有効にしてデバッグしてください。

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

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

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

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

2つ目の要素については、WebAuthnを使用するかOTPを使用するかをユーザーが選択できます。

WebAuthnオーセンティケーターを登録した後、ユーザーは以下の操作を行います。

WebAuthnオーセンティケーターを登録する際、KeycloakはWebAuthnオーセンティケーターが生成する証明書の信頼性を検証します。Keycloakは、 トラストストア にインポートされたトラストアンカーの証明書を必要とします。

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

Keycloakは二要素認証にWebAuthnを使っていますが、一要素認証にWebAuthnを使うこともできます。この場合、 passwordless のWebAuthn のクレデンシャルを持つユーザーは、パスワードなしでKeycloakを認証することができます。Keycloakは、ひとつのレルムとひとつの認証フローで、WebAuthnをパスワードなし認証と二要素認証の両方の仕組みとして使うことができます。

管理者は通常、WebAuthnパスワードレス認証のためにユーザーが登録したセキュリティー鍵が、異なる要件を満たすことを要求します。たとえば、セキュリティー鍵は、ユーザーがPINを使用してセキュリティー鍵に認証することを要求したり、セキュリティー鍵がより強力な認証局で認証することを要求したりすることがあります。

このため、Keycloakは管理者に個別の WebAuthn Passwordless Policy を設定することを許可しています。 WebAuthn Register Passwordless のアクションが必要で、 WebAuthn Passwordless Authenticator タイプのオーセンティケーターが別途必要です。

Keycloakは二要素認証にWebAuthnを使用していますが、一要素認証にWebAuthnを使用することができます。この場合、WebAuthnの passwordless クレデンシャルを持つユーザーは、ログインやパスワードを送信することなくKeycloakに認証することができます。Keycloakは、WebAuthnをログインレス/パスワードレスと二要素認証の両方のメカニズムとして、レルムのコンテキストで使用することができます。

管理者は通常、WebAuthnのログインレス認証のためにユーザーによって登録されたセキュリティー・キーが、異なる要件を満たすことを要求します。ログインレス認証では、ユーザーがセキュリティー・キーに対して認証を行い（たとえば、PINコードや指紋を使用する）、ログインレス・クレデンシャルに関連する暗号鍵がセキュリティー・キー上に物理的に保存されることが必要です。すべてのセキュリティー・キーがそのような要件を満たすわけではありません。デバイスが 'user verification' と 'resident key' をサポートしているかどうかは、セキュリティ・キーのベンダーに確認してください。サポートされているセキュリティー・キーを参照してください。

Keycloakは、管理者が WebAuthn Passwordless Policy をログインレス認証を可能にするように設定することを許可します。ログインレス認証は WebAuthn Passwordless Policy と WebAuthn Passwordless クレデンシャルでのみ設定できることに注意してください。WebAuthn ログインレス認証と WebAuthn パスワードレス認証は同じレルムに設定できますが、同じポリシー WebAuthn Passwordless Policy を共有することになります。

条件付きフローでリソースへのアクセスを許可または拒否できます。2つのオーセンティケーター Deny Access と Allow Access は、条件によってリソースへのアクセスを制御します。

これは、ロール role1 を持たないすべてのユーザーへのアクセスを拒否し、プロパティー deny-role1 で定義されたエラーメッセージを表示する方法の例です。この例には、 Condition - User Role および Deny Access のエグゼキューションが含まれます。

最後に、ログインテーマの messages_en.properties（英語の場合）でエラーメッセージを含むプロパティーを定義します。

Bitbucketでログインするには、以下の手順で行います。

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でログインするには、以下の手順で行います。