8.7. W3C Web Authentication (WebAuthn)
Red Hat build of Keycloak は、W3C Web Authentication (WebAuthn) をサポートします。Red Hat build of Keycloak は、WebAuthn の Relying Party (RP) として機能します。
WebAuthn 操作が成功するかどうかは、オーセンティケーター、ブラウザー、およびプラットフォームをサポートするユーザーの WebAuthn によります。オーセンティケーター、ブラウザー、およびプラットフォームが WebAuthn 仕様をサポートしていることを確認してください。
8.7.1. 設定
2FA の WebAuthn サポートの設定手順は、以下のようになります。
8.7.1.1. WebAuthn オーセンティケーター登録の有効化
- メニューで Authentication をクリックします。
- Required Actions タブをクリックします。
- Webauthn Register スイッチを ON に切り替えます。
すべての新規ユーザーに WebAuthn 認証情報の登録を要求する場合は、Default Action スイッチを ON に切り替えます。
8.7.2. WebAuthn 認証の Browser Flow への追加
- メニューで Authentication をクリックします。
- Browser フローをクリックします。
- "アクションリスト" から Duplicate を選択して、ビルトインの Browser フローのコピーを作成します。
- コピーの名前として "WebAuthn Browser" と入力します。
- 複製 をクリックします。
- 名前をクリックすると詳細へ移動します
- "WebAuthn Browser Browser - Conditional OTP" のゴミ箱アイコン 🗑️ をクリックし、Delete をクリックします。
全ユーザーの WebAuthn が必要な場合は、以下を実行します。
- WebAuthn Browser Forms の + メニューをクリックします。
- Add step をクリックします。
- WebAuthn Authenticator をクリックします。
- Add をクリックします。
WebAuthn Authenticator 認証タイプで Required を選択し、その要件を必須に設定します。
- 画面上部の Action メニューをクリックします。
- ドロップダウンリストから Bind flow を選択します。
- ドロップダウンリストから Browser を選択します。
- Save をクリックします。
ユーザーに WebAuthn 認証情報がない場合、ユーザーは WebAuthn 認証情報を登録する必要があります。
WebAuthn 認証情報が登録されている場合に限り、ユーザーは WebAuthn でログインできます。そのため、WebAuthn Authenticator 実行を追加する代わりに、以下を実行できます。
手順
- WebAuthn Browser Forms 行の + メニューをクリックします。
- Add sub-flow をクリックします。
- name フィールドに "Conditional 2FA" を入力します。
- Conditional 2FA の Conditional を選択して、その要件を条件付きに設定します。
- Conditional 2FA 行で、プラス記号 + をクリックし、Add condition を選択します。
- Add condition をクリックします。
- Condition - User Configured をクリックします。
- Add をクリックします。
- Condition - User Configured で Required を選択し、その要件を必須に設定します。
- WebAuthn Authenticator を Conditional 2FA フローにドラッグアンドドロップします。
WebAuthn Authenticator の Alternative を選択して、その要件を代替に設定します。
ユーザーは、2 つ目の要素に WebAuthn または OTP のいずれかを使用することを選択できます。
手順
- Conditional 2FA 行でプラス記号 + をクリックし、Add step を選択します。
- リストから OTP Form を選択します。
- Add をクリックします。
OTP Form の Alternative を選択して、その要件を代替に設定します。
8.7.3. WebAuthn オーセンティケーターを使用した認証
WebAuthn オーセンティケーターを登録した後に、ユーザーは以下の操作を実行します。
- ログインフォームを開きます。ユーザーは、ユーザー名とパスワードで認証する必要があります。
- ユーザーのブラウザーは、WebAuthn オーセンティケーターを使用して認証することをユーザーに要求します。
8.7.4. 管理者として WebAuthn の管理
8.7.4.1. 認証情報の管理
Red Hat build of Keycloak は、ユーザー認証情報の管理 からの他の認証情報と同様に、WebAuthn 認証情報を管理します。
- Red Hat build of Keycloak は、Reset Actions の一覧から WebAuthn 認証情報を作成するために必要なアクションをユーザーに割り当て、Webauthn Register を選択します。
- 管理者は Delete をクリックして WebAuthn 認証情報を削除できます。
- 管理者は、Show data… を選択して、AAGUID などの認証情報のデータを表示することができます。
- 管理者は、User Label フィールドに値を設定し、データを保存することで、認証情報のラベルを設定できます。
8.7.4.2. ポリシーの管理
管理者は、WebAuthn 関連の操作をレルムごとに WebAuthn Policy として設定できます。
手順
- メニューで Authentication をクリックします。
- Policy タブをクリックします。
- WebAuthn Policy タブをクリックします。
- ポリシー内で項目を設定します (以下の説明を参照してください)。
- Save をクリックします。
設定可能な項目とその説明は以下のとおりです。
設定 | 説明 |
---|---|
Relying Party エンティティー名 | WebAuthn Relying Party として読み取り可能なサーバー名。この項目は必須であり、WebAuthn オーセンティケーターの登録に適用されます。デフォルト設定は "keycloak" です。詳細は、WebAuthn Specification を参照してください。 |
署名アルゴリズム | アルゴリズム。公開鍵認証情報 に使用する署名アルゴリズムを WebAuthn オーセンティケーターに指示します。Red Hat build of Keycloak は、公開鍵認証情報を使用して Authentication Assertions に署名し、検証します。アルゴリズムが存在しない場合は、デフォルトの ES256 が適合されます。ES256 は、WebAuthn オーセンティケーターの登録に適用されるオプションの設定項目です。詳細は、WebAuthn Specification を参照してください。 |
Relying Party ID | 公開鍵認証情報 のスコープを決定する WebAuthn Relying Party の ID。ID は、オリジンの有効なドメインでなければなりません。この ID は、WebAuthn オーセンティケーターの登録に適用されるオプションの設定項目です。このエントリーが空白の場合、Red Hat build of Keycloak は Red Hat build of Keycloak のベース URL のホスト部分を適応させます。詳細は、WebAuthn の仕様 を参照してください。 |
証明の伝達設定 | ブラウザーでの WebAuthn API 実装 (WebAuthn Client) は、Attestation ステートメントを生成するのに推奨される方法です。この設定は、WebAuthn オーセンティケーターの登録に適用されるオプションの設定項目です。オプションが存在しない場合、その動作は "none" の選択と同じになります。詳細は、WebAuthn の仕様 を参照してください。 |
オーセンティケーター添付 | WebAuthn Client に対する WebAuthn オーセンティケーターの許容割り当てパターン。このパターンは、WebAuthn オーセンティケーターの登録に適用されるオプションの設定項目です。詳細は、WebAuthn Specification を参照してください。 |
Require Discoverable Credential | WebAuthn 認証システムが公開鍵認証情報を クライアント側で検出可能な認証情報 として生成することを要求するオプション。このオプションは、WebAuthn オーセンティケーターの登録に適用されます。空欄のままにすると、その動作は "No" の選択と同じになります。詳細は、WebAuthn の仕様 を参照してください。 |
ユーザー検証要件 | WebAuthn オーセンティケーターがユーザーの検証を確認することを要求するオプション。これは、WebAuthn オーセンティケーターの登録と、WebAuthn オーセンティケーターによるユーザーの認証に適用される任意の設定項目です。オプションが存在しない場合、その動作は "preferred" の選択と同じになります。詳細は、WebAuthn Specification for registering a WebAuthn authenticator および WebAuthn Specification for authenticating the user by a WebAuthn authenticator を参照してください。 |
タイムアウト | WebAuthn オーセンティケーターを登録し、WebAuthn オーセンティケーターを使用してユーザーを認証する際のタイムアウト値 (秒単位)。ゼロに設定すると、その動作は WebAuthn オーセンティケーターの実装により異なります。デフォルト値は 0 です。詳細は、WebAuthn Specification for registering a WebAuthn authenticator および WebAuthn Specification for authenticating the user by a WebAuthn authenticator を参照してください。 |
同じオーセンティケーター登録の回避 | 有効にすると、Red Hat build of Keycloak は、すでに登録されている WebAuthn オーセンティケーターを再登録できません。 |
許可される AAGUID | WebAuthn オーセンティケーターが登録する必要のある AAGUID のホワイトリスト。 |
8.7.5. 証明ステートメントの検証
WebAuthn オーセンティケーターを登録すると、Red Hat build of Keycloak は、WebAuthn オーセンティケーターが生成した証明ステートメントの信頼性を検証します。Red Hat build of Keycloak では、トラストストア にトラストアンカーの証明書をインポートする必要があります。
この検証を省略するには、このトラストストアを無効にするか、WebAuthn ポリシーの設定項目 "Attestation Conveyance Preference" を "none" に設定します。
8.7.6. ユーザーとして WebAuthn 認証情報の管理
8.7.6.1. WebAuthn オーセンティケーターの登録
WebAuthn オーセンティケーターの適切な登録方法は、ユーザーが Red Hat build of Keycloak にアカウントを登録しているかどうかにより異なります。
8.7.6.2. 新規ユーザー
必須アクション WebAuthn Register がレルムの Default Action である場合、新規ユーザーは最初のログイン後にパスキーを設定する必要があります。
手順
- ログインフォームを開きます。
- Register をクリックします。
- フォームの項目に入力します。
- Register をクリックします。
登録に成功すると、ブラウザーは、ユーザーに対して WebAuthn オーセンティケーターのラベルのテキストを入力するよう要求します。
8.7.6.3. 既存ユーザー
最初の例のように WebAuthn Authenticator
が必要に応じて設定されている場合、既存のユーザーがログインを試みる際に、WebAuthn オーセンティケーターを自動的に登録する必要があります。
手順
- ログインフォームを開きます。
- フォームの項目に入力します。
- Save をクリックします。
- Login をクリックします。
登録に成功すると、ユーザーのブラウザーは、ユーザーに対して WebAuthn オーセンティケーターのラベルのテキストを入力するよう要求します。
8.7.7. パスワードなしの WebAuthn と 2 つのファクターの組み合わせ
Red Hat build of Keycloak は、2 要素認証に WebAuthn を使用しますが、第一要素認証として WebAuthn を使用できます。この場合、passwordless
の WebAuthn 認証情報を持つユーザーは、パスワードなしで Red Hat build of Keycloak に対して認証できます。Red Hat build of Keycloak では、レルムおよび単一の認証フローのコンテキストで、パスワードレス認証および 2 要素認証のメカニズムとして WebAuthn を使用できます。
通常、管理者は、WebAuthn パスワードレス認証用にユーザーが登録したパスキーがさまざまな要件を満たしていることを要求します。たとえば、ユーザーが PIN を使用してパスキーに対して認証することを要求したり、より強力な認証局でパスキーを証明するように要求する場合があります。
このため、Red Hat build of Keycloak では、管理者は個別の WebAuthn Passwordless Policy
を設定できます。必須の Webauthn Register Passwordless
アクションタイプと、別の WebAuthn Passwordless Authenticator
オーセンティケータータイプがあります。
8.7.7.1. 設定
以下のように WebAuthn パスワードレスサポートを設定します。
-
すでに存在する場合は、WebAuthn パスワードレスサポートに新しい必須アクションを登録します。WebAuthn Authenticator 登録を有効にする で説明されている手順を使用します。
Webauthn Register Passwordless
アクションを登録します。 - ポリシーを設定します。ポリシーの管理 で説明されている手順と設定オプションを使用できます。管理コンソールのWebAuthn Passwordless Policy タブで、設定を実行します。通常、パスキーの要件は、2 要素ポリシーの要件よりも厳しくなります。たとえば、パスワードレスポリシーの設定時に、User Verification Requirement を Required に設定できます。
認証フローを設定します。WebAuthn 認証を Browser Flow に追加する で説明されている WebAuthn Browser フローを使用します。以下のようにフローを設定します。
- WebAuthn Browser Forms サブフローには、最初のオーセンティケーターとして Username Form が含まれます。デフォルトの Username Password Form オーセンティケーターを削除し、Username Form オーセンティケーターを追加します。このアクションでは、ユーザーに最初のステップとしてユーザー名を提供することを要求します。
- 必須のサブフローがある場合があります (例: Passwordless Or Two-factor)。このサブフローは、ユーザーが Passwordless WebAuthn 認証情報または Two-factor 認証で認証できることを示しています。
- フローには、第一の代替として WebAuthn Passwordless Authenticator が含まれます。
- 2 つ目の代替は、Password And Two-factor Webauthn (例) という名前のサブフローです。このサブフローには、Password Form および WebAuthn Authenticator が含まれます。
フローの最終的な設定は以下のようになります。
PasswordLess フロー
これをテストするために、Red Hat build of Keycloak ですでに認識されているユーザーに必須アクションとして WebAuthn Register Passwordless を追加できるようになりました。第一の認証時に、ユーザーはパスワードおよび第二要素の WebAuthn 認証情報を使用する必要があります。WebAuthn Passwordless 認証情報を使用する場合、ユーザーはパスワードおよび第二要素の WebAuthn 認証情報を提供する必要はありません。
8.7.8. LoginLess WebAuthn
Red Hat build of Keycloak は、2 要素認証に WebAuthn を使用しますが、第一要素認証として WebAuthn を使用できます。この場合、passwordless
の WebAuthn 認証情報を持つユーザーは、ログインやパスワードなしで Red Hat build of Keycloak に対して認証できます。Red Hat build of Keycloak は、レルムのコンテキストで、ログインレス/パスワードレスおよび 2 要素認証メカニズムとして WebAuthn を使用できます。
通常、管理者は、WebAuthn ログインレス認証用にユーザーが登録したパスキーがさまざまな要件を満たしていることを要求とします。ログインレス認証では、ユーザーがパスキーに対して (PIN コードや指紋などを使用して) 認証する必要があり、ログインレス認証情報に関連付けられた暗号化キーをパスキーに物理的に保存する必要があります。すべてのパスキーがそのような要件を満たしているわけではありません。ベンダーに問い合わせて、デバイスが 'ユーザー検証' と '検出可能な認証情報' をサポートしているかどうかを確認してください。サポートされているパスキー を参照してください。
Red Hat build of Keycloak により、管理者はログインレス認証を可能にするように WebAuthn Passwordless Policy
を設定できます。ログインレス認証は、WebAuthn Passwordless Policy
と WebAuthn Passwordless
クレデンシャルでのみ設定できることに注意してください。WebAuthn ログインレス認証と WebAuthn パスワードレス認証は同じレルムで設定できますが、同じポリシー WebAuthn Passwordless Policy
ポリシーを共有します。
8.7.8.1. 設定
手順
以下のように WebAuthn ログインレスサポートを設定します。
-
すでに存在する場合は、WebAuthn パスワードレスサポートに新しい必須アクションを登録します。WebAuthn Authenticator 登録を有効にする で説明されている手順を使用します。
Webauthn Register Passwordless
アクションを登録します。 -
WebAuthn Passwordless Policy
を設定します。Admin Console のAuthentication
セクションのPolicies
WebAuthn Passwordless Policy
タブで設定を実行します。ログインレスシナリオのポリシーを設定する場合は、User Verification Requirement を required に設定し、Require Discoverable Credential を Yes に設定する必要があります。専用のログインレスポリシーがないため、認証シナリオ (ユーザー検証なし/検出可能な認証情報なし) とログインレスシナリオ (ユーザー検証あり/検出可能な認証情報あり) を混在させることはできないことに注意してください。通常、パスキーではストレージ容量が非常に限られているため、パスキーに多くの検出可能な認証情報を保存することはできません。 - 認証フローを設定します。新しい認証フローを作成し、"WebAuthn Passwordless" 実行を追加して、実行の Requirement 設定を Required に設定します
フローの最終的な設定は以下のようになります。
LoginLess フロー
これをテストするために、Red Hat build of Keycloak ですでに認識されているユーザーに必須アクションとして WebAuthn Register Passwordless
を追加できるようになりました。必須アクションが設定されているユーザーは、認証を (ユーザー名/パスワードなどを使用して) 行う必要があります。その後、ログインレス認証に使用するパスキーを登録するように求められます。
8.7.8.2. ベンダー固有のマーク
8.7.8.2.1. 互換性チェックリスト
Red Hat build of Keycloak によるログインレス認証では、パスキーが以下の機能を満たしている必要があります。
- FIDO2 コンプライアンス: FIDO/U2F と混同しないでください
- ユーザー認証: ユーザーを認証するパスキーの機能 (第三者がパスキーを見つけてログインやパスワードなしで認証するのを防止する)
- 検出可能な認証情報: クライアントアプリケーションに関連付けられたログインと暗号化キーを保存するパスキーの機能
8.7.8.2.2. Windows Hello
Windows Hello ベースの認証情報を使用して Red Hat build of Keycloak に対して認証するには、WebAuthn Passwordless Policy
の Signature Algorithms 設定に RS256 値を含めるように設定します。一部のブラウザーでは、プライベートウィンドウ内でのプラットフォームパスキー (Windows Hello など) へのアクセスが許可されていないことに注意してください。
8.7.8.2.3. サポートされているパスキー
次のパスキーは、Red Hat build of Keycloak を使用したログインレス認証のテストに成功しました。
- Windows Hello (Windows 10 21H1/21H2)
- Yubico Yubikey 5 NFC
- Feitian ePass FIDO-NFC