Keycloakはバージョン26.4でpasskeyをログイン画面に正式統合し、パスワードレス認証が実案件で現実的な選択肢になりました。WebAuthn Passwordless Policy、required action、discoverable credentialといった要素を、登録・認証の両フローと既存ユーザ展開の観点から実務目線で整理します。
01WebAuthnとpasskeyの整理
まず用語を実装者の目線で整理します。WebAuthnはW3C標準の認証API（正確にはWeb Authentication Level 2）で、ブラウザとauthenticator（認証器）の間で公開鍵暗号による認証を行う仕組みです。Keycloakは早くからこれをサポートしており、その経緯は公式ブログ（2019年）で確認できます。
passkeyは、このWebAuthnクレデンシャルのうち「discoverable（発見可能、旧称resident key）」なものを指す実質的な呼称です。discoverableであるとは、authenticator側にユーザ識別子を含むクレデンシャルが保存され、ユーザ名を先に入力しなくても認証を開始できる状態を意味します。加えて、プラットフォーム提供元（Apple/Google/Microsoft）によってデバイス間で同期される場合が多い、という運用上の性質もpasskeyのイメージに含まれます。
022つのWebAuthnポリシーと2つのrequired action
Keycloakを触り始めて最初に戸惑うのが、WebAuthn関連の設定が「2系統」に分かれている点です。ここを最初に押さえると全体が見通せます。
- WebAuthn Policy（Authentication → Policies）：2要素目（2FA）として使うWebAuthnの設定。対応するrequired actionは
webauthn-register（表示名「Webauthn Register」）。 - WebAuthn Passwordless Policy（同上）：パスワードレス／1要素目として使うWebAuthnの設定。対応するrequired actionは
webauthn-register-passwordless（表示名「Webauthn Register Passwordless」）。passkeyはこちらで扱います。
この2系統は独立したポリシーで、それぞれ別のクレデンシャル種別（credentialType）としてユーザに保存されます。つまり同じ物理authenticatorでも、2FA用として登録するか、passwordless用として登録するかで別クレデンシャルになります。設計時は「そのauthenticatorをどちらの役割で使わせるか」を先に決めてください。
02WebAuthn Passwordless Policyの要点設定
passkeyを扱うのはWebAuthn Passwordless Policyです。実案件で必ず確認する主なパラメータを挙げます（項目名は新しめのバージョン基準。細部はお使いのバージョンのServer Administration Guideで必ず確認してください）。
- Relying Party ID（RP ID）：クレデンシャルを紐づけるドメイン。空ならリクエストのホスト名が使われます。サブドメイン間で共有したい場合の設計に直結するので、SSO配置と合わせて最初に決めます。
- Require Discoverable Credentials（旧Require Resident Key）：passkey（1要素目でユーザ名入力を省く運用）を狙うなら基本的に有効側に倒します。2FA専用なら無効でも成立します。
- User Verification Requirement：PINや生体によるユーザ検証を必須にするか。パスワードレスとして「知識＋所持」を1操作で満たすには
required相当が前提です。 - Authenticator Attachment：
platform（端末内蔵のTouch ID/Windows Hello等）かcross-platform（YubiKey等の外付け）か。未指定なら両方許容します。 - Signature Algorithms：許可する署名アルゴリズム（ES256など）。空だとES256既定。
- Attestation Conveyance Preference：attestation（認証器の出所証明）を要求するか。
noneだと検証負荷が軽い一方で機種制限はできません。 - Acceptable AAGUIDs：許可するauthenticatorのモデル識別子（AAGUID）の許可リスト。特定の認定デバイスだけに絞る統制で使います。
- Timeout / Avoid Same Authenticator Registration：登録・認証のタイムアウト、同一authenticatorの二重登録防止。
03登録フロー：required actionで登録させる
passkey（passwordlessクレデンシャル）をユーザに登録させる主な経路は次の3つです。
- Required actionのデフォルト有効化：Authentication → Required actions で「Webauthn Register Passwordless」をdefault action にすると、次回ログイン時に全対象ユーザへ登録を促せます。全社展開の号砲として使えますが、対象を絞りたい場合は乱暴なので後述の個別付与を検討します。
- Account Console からの自己登録：ユーザがアカウント管理画面から任意で登録。段階展開に向きます。
- アプリ主導（AIA：Application Initiated Action）：アプリ側から
kc_action=webauthn-register-passwordlessを付けて認可リクエストを送り、登録画面へ誘導します。オンボーディング動線に組み込みやすい方式です。
AIAについて、26.4系ではWebAuthn登録アクション（webauthn-register／webauthn-register-passwordless）に skip_if_exists パラメータが追加され、「そのクレデンシャル種別を既に持つユーザには登録を促さずスキップする」制御が可能になりました。オンボーディングで毎回登録を促してしまう事故を避けられます。詳細は26.4のpasskey告知記事を参照してください。
04認証フロー：conditional UIとmodal UI
26.4での大きな前進は、passkeyがデフォルトのbrowserフローに正式統合され、フローを自作しなくてもログイン画面でpasskeyが使えるようになった点です。有効化は「WebAuthn Passwordless Policy の Enable Passkeys を有効にする」だけが起点になります。UIは2形態を使い分けます。
- conditional UI（autofill）：ユーザ名入力欄にフォーカスすると、ブラウザ／パスワードマネージャがpasskey候補を提示する方式。1PasswordやOS標準の資格情報マネージャと自然に連携します。ユーザ名を打たずにアカウント選択できる「本来のpasskey体験」はこちらです。
- modal UI：「Sign in with Passkey」ボタンを明示的に押して開始する方式。主にYubiKeyのようなハードウェアキー向けで、PIN入力や生体確認のプロンプトが出ます。
フロー内部では、passkeyが1要素目として使われたかを判定する「Conditional - credential」オーセンティケータが導入され、「passkeyでログインできた場合は2FAをスキップする」といった分岐が組めます。passkey自体が「所持＋ユーザ検証」で多要素相当を満たすため、この分岐はUXと保証レベルの両立に有効です。ここはstep-up的な設計とも絡むので、要件次第ではステップアップ認証の考え方も合わせて整理してください。
05既存ユーザへの展開設計
技術的にpasskeyを有効化するのは難しくありません。実案件で難しいのは「パスワードを持つ既存ユーザ数万人にどう段階展開するか」です。EMWがエンタープライズの認証基盤で実際に気をつけている論点を挙げます。
- いきなりパスワードレス必須にしない：まずpasskeyを「任意の追加手段」として登録可能にし、登録率が一定水準に達してから既定手段へ寄せます。default required actionを全ユーザに一斉付与すると、登録に失敗した層のログイン導線が詰まります。
- リカバリ手段を必ず残す：passkeyを紛失・機種変更した場合の復旧（別要素、ヘルプデスク経由の再登録）を先に設計します。passwordless必須化の前に、ここが埋まっていないと運用が止まります。
- 属性・グループで対象を絞る：required actionの一斉付与ではなく、AIA＋
skip_if_existsや対象グループ限定で段階ロールアウトすると事故が減ります。ロール/グループ設計はロール・グループ・属性設計の考え方と揃えておくと運用が一貫します。 - ブラウザ・OS前提の確認：conditional UIやplatform authenticatorはOS・ブラウザのバージョン差の影響を受けます。社内標準環境で必ず実機確認してください。
06実装・運用の注意点
- バージョン差に注意：passkeyのブラウザフロー正式統合や
skip_if_existsは26.4系での機能です。それ以前のバージョンでは自作フローが必要だったり、UI挙動が異なります。WildFlyベースの配布はKeycloak 17で非推奨化され、2022年6月にサポートが終了して以降のリリースには含まれておらず（削除済み）、現行の唯一の配布はQuarkusベースです。移行観点はQuarkus版への移行も参照してください。 - RP IDとドメイン設計：passkeyはRP IDに強く紐づきます。ログインドメインの変更・統合はクレデンシャル再登録を招くため、SSO配置と合わせて最初に固定します。
- attestation検証の負荷：厳格なattestation検証はメタデータ管理（MDS）の運用を伴います。「デバイス統制が本当に要件か」を確認し、不要ならnoneで運用負荷を下げる判断も現場ではあり得ます。
- 2FA用と1要素用の混在：WebAuthn PolicyとWebAuthn Passwordless Policyを同時に使う構成は可能ですが、ユーザが「どちらのクレデンシャルを登録したか」を混同しやすいので、UI文言と登録動線を丁寧に設計します。
Keycloakでの認証フロー全体の組み方は認証フロー設計に、より広い実装は導入事例にまとめています。
—まとめ
Keycloakのpasskey対応は26.4で実装ハードルが大きく下がり、WebAuthn Passwordless Policyの有効化を起点に、フロー自作なしでpasskeyログインが成立するようになりました。技術的な要点は「2つのポリシー×2つのrequired action」「discoverable credential」「conditional/modal UI」の3つに集約されます。一方で実案件の勝負どころは、既存ユーザへの段階展開とリカバリ設計という運用面です。まず任意登録から始め、登録率とログイン成功率を見ながら必須化へ進める——この順序を守ることが、パスワードレス移行を止めないコツです。