--- title: "Keycloak パスキーの設定手順：Enable Passkeysとパスワードレスポリシー・登録の流れ" url: "https://www.issoh.co.jp/tech/details/19388/" published: 2026-11-06 updated: 2026-11-06 categories: ["セキュリティ"] publisher: "株式会社一創" --- # Keycloak パスキーの設定手順：Enable Passkeysとパスワードレスポリシー・登録の流れ Keycloakでパスキーを使うには、レルムの「Enable Passkeys」を有効にし、パスキー用の登録アクションを利用者に実行させます。26.4.0で正式機能になってからは、既定のログイン画面のユーザー名欄にパスキーの候補が出る作りに変わり、認証フローを作り込まなくても使える仕組みです。本記事では2026年11月6日時点の最新版Keycloak 26.8.2を前提に、管理コンソールとkcadm.shでの設定、WebAuthn Passwordless Policyの既定値、既存ユーザーに登録させる方法、パスキーでログインした利用者の2要素認証の扱いを順に解説します。 ## まとめ：Keycloakのパスキーは26.4以降スイッチと登録アクションの2か所で有効化 26.4.0以降は、Enable Passkeysのスイッチを入れるだけで、Username Password Formにパスキーの自動入力候補と「Sign in with Passkey」ボタンが付きます。26.7.0からスイッチはRealm settingsのLoginタブに移り、ページを開いたときの出方をPasskey Mediationで選べるようになりました。登録は「Webauthn Register Passwordless」のRequired Actionで行い、既存ユーザーにはこのアクションを付けるか、アプリからAIAで呼び出します。 この方式はパスワードを残したままパスキーを足す作りです。パスワードを使えなくするなら、専用のフローを組み、端末を失くした利用者の回復手段を先に決めておく必要があります。社員や会員の移行期間は、パスワードを残す既定の方式で始めるのが安全です。 ## Keycloakでパスキーを使う2つの方式と26.4以降のフォーム統合の仕組み KeycloakのWebAuthn対応は、2要素目として使う方式と、パスワードの代わりに使う方式の2系統に分かれています。パスキーは後者に属します。 ### WebAuthnの2要素目用とパスワードレス用で異なる設定と登録アクション [管理ガイドのPasswordless WebAuthnの節](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#%5Fwebauthn%5Fpasswordless)は、パスワードレス用に別のポリシー・Required Action・Authenticatorを用意していると説明しています。設定を入れる画面を取り違えると、登録はできてもパスキーとしては使えません。 | 項目 | 2要素目のWebAuthn | パスキー（パスワードレス） | | ------------------ | ----------------- | --------------------- | | ポリシー | WebAuthn Policy | パスワードレス用ポリシー | | 登録のRequired Action | webauthn-register | パスワードレス用の登録アクション | | 資格情報の種類 | webauthn | webauthn-passwordless | | ログインでの位置 | パスワードの後 | パスワードの代わり | 表のパスワードレス用ポリシーの画面上の名称はWebAuthn Passwordless Policyで、登録アクションの識別子はwebauthn-register-passwordlessです。2要素目用の設定とは区別し、パスキーの登録先を確認してください。表の資格情報の種類は、[26.8.2のDefaultAuthenticationFlows.java](https://github.com/keycloak/keycloak/blob/26.8.2/server-spi-private/src/main/java/org/keycloak/models/utils/DefaultAuthenticationFlows.java)などのソースが使う識別子です。WebAuthnの登録と認証の仕組みそのものは[WebAuthnとは](https://www.issoh.co.jp/tech/details/15375/)でコードとともに解説しました。 ### 26.3のプレビューから26.7のMediation追加までのパスキー機能の版ごとの変化 パスキーの設定手順は、26系の中でも版によって画面の場所が違います。[リリースノート](https://www.keycloak.org/docs/latest/release%5Fnotes/index.html#passkeys-integration-supported)と、各版の管理ガイドのソースを比べると次のとおりです。 | 版 | 変化 | | ------ | ---------------------- | | 26.3.0 | 既定のユーザー名フォームへ統合（プレビュー） | | 26.4.0 | 正式機能化・資格情報の条件を追加 | | 26.7.0 | Loginタブへ移動・Mediation追加 | | 26.7.0 | 発見可能な資格情報の3値を追加 | 表の26.4.0で追加された資格情報の条件の名称はCondition – credentialで、26.7.0の3値追加の対象はDiscoverable credentialです。移動先はRealm settingsのLoginタブで、26.4.0から26.6系までは、AuthenticationのPoliciesにあるWebAuthn Passwordless Policyタブの末尾にスイッチがあります。機能フラグは[Profile.java](https://github.com/keycloak/keycloak/blob/26.8.2/common/src/main/java/org/keycloak/common/Profile.java)でPASSKEYSが既定で有効と定義されており、26.4.0以降は起動オプションの追加が要りません。 ### Username Password Formの条件付きUIとパスキー用ボタンの動き [管理ガイドのPasskeysの節](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#passkeys%5Fserver%5Fadministration%5Fguide)によると、スイッチを入れると、ユーザー名欄が`autocomplete="username webauthn"`付きで描画されます。利用者が欄をクリックすると、ブラウザが保存済みのパスキーを一覧で出し、選べばパスワードを打たずにログインが終わります。 ブラウザの一覧に出ないパスキーもあります。ハードウェアキーや別の端末にある鍵がその例で、こうした鍵は「Sign in with Passkey」ボタンから開くモーダルの画面で使います。パスキーが組み込まれるのはUsername Password Form、Username Form、Password Form、組織機能の初回ログイン画面、外部IdP初回ログインの再認証画面の5つです。 ## 管理コンソールとkcadm.shでレルムのパスキーを有効にする設定手順 例として、レルム`corp`を`https://auth.example.com`で公開している環境に、パスキーを足します。 ### 26.7でLoginタブに移ったEnable Passkeysの場所と設定画面 26.7.0以降の画面では、Realm settingsのLoginタブにある「Login Screen Customization」の欄にEnable Passkeysがあります。スイッチの横の歯車からWebAuthn Passwordless Policyへ移動でき、スイッチを入れるとPasskey Mediationの選択欄が現れます。 管理ガイドは、パスワードレスポリシーの既定値で通常は足りるとしています。[WebAuthnPolicyPasswordlessDefaults.java](https://github.com/keycloak/keycloak/blob/26.8.2/server-spi-private/src/main/java/org/keycloak/models/WebAuthnPolicyPasswordlessDefaults.java)では、Discoverable credentialとUser Verification Requirementがどちらもrequiredです。2要素目用のWebAuthn Policyはどちらも指定なしなので、パスキー用のほうが条件は厳しくなります。 ### kcadm.shでパスワードレス用ポリシーとパスキー有効化を一括設定する手順 画面の項目は、[RealmRepresentation.java](https://github.com/keycloak/keycloak/blob/26.8.2/core/src/main/java/org/keycloak/representations/idm/RealmRepresentation.java)の`webAuthnPolicyPasswordless`で始まる項目に対応します。検証環境と本番で同じ値を入れるなら、次のように書いておくと差が出ません。 ``` #!/usr/bin/env bash # Keycloak 26.8 系：レルム corp でパスキーを有効にする set -euo pipefail REALM=corp kcadm.sh config credentials --server https://auth.example.com --realm master --user admin # 1. パスワードレス用ポリシーとパスキーのスイッチ kcadm.sh update realms/"$REALM" \ -s webAuthnPolicyPasswordlessRpEntityName="Example Corp" \ -s webAuthnPolicyPasswordlessRpId=example.com \ -s webAuthnPolicyPasswordlessResidentKey=required \ -s webAuthnPolicyPasswordlessUserVerificationRequirement=required \ -s 'webAuthnPolicyPasswordlessSignatureAlgorithms=["ES256","RS256"]' \ -s webAuthnPolicyPasswordlessPasskeysEnabled=true \ -s webAuthnPolicyPasswordlessMediation=conditional # 2. 登録用の Required Action を有効にする（既定で有効なら変化なし） kcadm.sh update authentication/required-actions/webauthn-register-passwordless \ -r "$REALM" -s enabled=true # 3. 反映を確かめる kcadm.sh get realms/"$REALM" \ --fields 'webAuthnPolicyPasswordlessPasskeysEnabled,webAuthnPolicyPasswordlessMediation,webAuthnPolicyPasswordlessRpId' ``` エンドポイントは[Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html)のレルム更新と`authentication/required-actions`です。curlでトークンを取って同じ更新を送る書き方は[Keycloak APIの使い方](https://www.issoh.co.jp/tech/details/19378/)にまとめました。 ### Relying Party IDを空欄にしたときの既定とサブドメインをまたぐ設定の注意 [WebAuthn Policyの項目表](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#%5Fwebauthn-policy)によると、Relying Party IDが空欄ならKeycloakのベースURLのホスト名が使われます。上の例で空欄にすると`auth.example.com`に紐づくパスキーになります。 登録済みのパスキーはRP IDに結びつくため、後から値を変えると既存の鍵ではログインできなくなります。将来Keycloakを別のサブドメインへ移す予定があるなら、最初から親ドメインの`example.com`を入れておきます。ただし、親ドメインにした鍵は同じドメイン配下の別サイトでも使える範囲になるので、社外向けサービスと同居させるかどうかで決めてください。 ### Passkey Mediationの5つの値とログイン画面の開き方の違い Passkey Mediationは、ブラウザの[navigator.credentials.get()](https://developer.mozilla.org/en-US/docs/Web/API/CredentialsContainer/get)に渡す`mediation`の値です。[管理ガイドのPasskey Mediationの節](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#%5Fpasskeys-mediation)は次の5つを挙げています。 | 値 | ログイン画面を開いたときの動き | | --------------- | -------------------- | | conditional（既定） | ユーザー名欄の自動入力候補にだけ出る | | none | 自動では何もせずボタンから使う | | optional | 選択画面を自動で出す・閉じてもよい | | required | 選択画面を出し、使うか閉じるまで進めない | | silent | 画面を出さずに試す・失敗しやすい | 実務での開始時に選ぶ値は、既定のconditionalです。管理ガイドは、requiredとsilentの動きがブラウザによって違うと注記しています。optionalを選ぶのは、全員が登録を終えた社内システムで選択画面を毎回出したい場合に限られます。 ## 既存ユーザーにパスキーを登録させるRequired ActionとAIAの組み込み方 スイッチを入れただけでは、誰もパスキーを持っていません。登録の入口を作る作業が、導入で一番手間のかかる部分です。 ### Webauthn Register Passwordlessの既定と全員の登録設定 [DefaultRequiredActions.java](https://github.com/keycloak/keycloak/blob/26.8.2/server-spi-private/src/main/java/org/keycloak/models/utils/DefaultRequiredActions.java)では、Webauthn Register Passwordlessは有効の状態でレルムに登録されます。AuthenticationのRequired ActionsタブでDefault Actionをオンにすると、新しく作るユーザーに初回ログインで登録を求めます。 既に存在するユーザーには付きません。全員に登録させたい場合は、ユーザーごとに`requiredActions`へ`webauthn-register-passwordless`を足します。この配列は丸ごと置き換わるため、メール確認などの既存の値を取得してから足して送ってください。一括付与の書き方と注意点は、OTPの例で[Keycloak 認証フローの設定手順](https://www.issoh.co.jp/tech/details/19386/)に載せています。 ### kc\_actionで登録画面を開くAIAのURLと登録済み利用者を省く指定 強制ではなく、利用者が自分のタイミングで登録する形にしたいなら、アプリ側に「パスキーを登録」ボタンを置きます。[管理ガイドのAIAの節](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#%5Fwebauthn%5Faia)のとおり、通常の認可リクエストに`kc_action`を足すだけで登録画面が開きます。 ``` # アプリの「パスキーを登録」ボタンのリンク先（改行は読みやすさのため） https://auth.example.com/realms/corp/protocol/openid-connect/auth ?client_id=member-portal &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback &response_type=code &scope=openid &kc_action=webauthn-register-passwordless:skip_if_exists ``` `:skip_if_exists`は26.3.0で入ったパラメーターで、既にパスキーを持つ利用者では登録を飛ばします。そのときアプリへ戻る`kc_action_status`はsuccessです。 ### アカウントコンソールのSigning in画面で利用者が自分で追加・削除する流れ Keycloak標準のアカウントコンソールでも登録できます。Account securityのSigning inを開くと、Passwordlessの欄に「Passkey」の項目があり、そこから追加と削除を行います。 2要素目のWebAuthnは同じ画面の別の欄に「Passkey」という同じ表示名で並ぶため、利用者は違いが分かりません。社内向けの手順書では、Passwordlessの欄から登録するよう画面写しで示しておくと、問い合わせが減ります。 ## パスキーでログインした利用者の2要素認証を省く条件と常に求める変更 パスキーは端末の生体認証やPINで本人確認まで済ませるため、既定ではその後のOTPを求めません。この動きを決めているのが「Condition – credential」です。 ### 既定ブラウザフローに入るCondition – credentialの設定値と動き DefaultAuthenticationFlows.javaは、PASSKEYS機能が有効なとき、Browser – Conditional 2FAの中にCondition – credentialをRequiredで置きます。設定は`credentials=webauthn-passwordless`です。 [ConditionalCredentialAuthenticatorFactory.java](https://github.com/keycloak/keycloak/blob/26.8.2/services/src/main/java/org/keycloak/authentication/authenticators/conditional/ConditionalCredentialAuthenticatorFactory.java)の説明では、`included`がfalseのとき、指定した資格情報が使われていない場合だけ真になります。既定の設定は`included`を持たないので、パスキーを使ったログインでは条件が偽になり、2要素目のサブフローごと飛ばされます。 ### kcadm.shで条件をDisabledにしパスキー利用者にもOTPを求める手順 管理ガイドは、常に2要素目を求めたいならこの条件をDisabledにするよう書いています。組み込みのbrowserフローでもRequirementは変えられます。 ``` # browser フローの Condition - credential を Disabled にする REALM=corp SUB="Browser%20-%20Conditional%202FA" kcadm.sh get "authentication/flows/${SUB}/executions" -r "$REALM" \ | jq -c '.[] | select(.providerId=="conditional-credential") | .requirement="DISABLED"' \ | kcadm.sh update "authentication/flows/${SUB}/executions" -r "$REALM" -n -f - ``` 取得した要素を丸ごと送り返すのは、更新処理が`priority`まで比べるためです。金融や医療の管理画面のように、端末を持っているだけで入れる状態を避けたいシステムで使います。パスキーはユーザー検証をrequiredにしていれば、それだけで所持と生体の2要素を満たすため、一般の会員サイトでは既定のままで構いません。 ### 古いレルムと複製フローでCondition – credentialの有無を確認 Condition – credentialは、既定フローを作るときに足される要素です。26.4.0より前に複製した独自のブラウザフローには入っていません。この状態でパスキーを有効にすると、パスキーでログインした利用者にもOTPが出ます。 確認は`kcadm.sh get authentication/flows/<フロー名>/executions`で`conditional-credential`の有無を見るだけです。足すときは、Conditional 2FAのサブフローに追加し、`credentials`に`webauthn-passwordless`を設定してRequiredにします。版を上げるたびの差分確認は、[Keycloakの脆弱性対応の手順](https://www.issoh.co.jp/tech/details/19094/)で扱う更新作業の一覧に入れておくと漏れません。 ## パスワードを残すか消すかの判断とパスキー導入で詰まりやすい場面 運用に入ってからの問い合わせは、ほとんどが次の4つから来ます。 ### Enable Passkeysはパスワードを残す方式でありパスワードレス専用ではない点 Enable Passkeysを入れても、Username Password Formのパスワード欄は残ります。パスキーを使わない利用者は従来どおりパスワードで入れるため、フィッシングで盗まれたパスワードが通る経路も残ります。 パスワードを使えなくするには、管理ガイドの[LoginLess WebAuthn](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#%5Fwebauthn%5Floginless)のように、WebAuthn PasswordlessだけをRequiredにしたフローを別に作ります。この構成では、端末を失くした利用者は自分でログインできません。管理者が資格情報を削除して登録をやり直させる窓口と、本人確認の手順を先に決められないなら、パスワードを止める段階には進まないでください。パスワードとの併存期間の設計は[パスキー移行の実装手順](https://www.issoh.co.jp/tech/details/17716/)で解説しています。 ### LDAP連携ユーザーでuser.idが64バイトを超えて登録できない制約 [管理ガイドのWebAuthnの節](https://www.keycloak.org/docs/latest/server%5Fadmin/index.html#webauthn%5Fserver%5Fadministration%5Fguide)は、WebAuthnのuser.idの上限が64バイトだと注記しています。Keycloakは内部IDをそのまま渡し、通常のユーザーでは36文字のUUIDなので問題はありません。 LDAPなど外部のユーザーフェデレーションから来た利用者は、IDが`f::`の形になります。プロバイダーのIDとユーザーのIDがどちらも36文字のUUIDなら、合計75バイトで上限を超える計算です。Active Directoryと連携しているレルムでは、パスキーを有効にする前に、検証用のユーザーで登録が通るかを必ず確かめます。連携の設定は[Keycloak LDAP連携](https://www.issoh.co.jp/tech/details/19380/)にまとめました。 ### Windows HelloのRS256やハードウェアキーの保存数とブラウザ差の事前確認 管理ガイドは、Windows Helloで使うにはパスワードレスポリシーの署名アルゴリズムにRS256を含めるよう書いています。上のスクリプトでES256とRS256を両方入れているのはこのためです。動作確認済みとして挙がっているのは、Windows Hello（Windows 10 21H1／21H2）、YubiKey 5 NFC、Feitian ePass FIDO-NFCです。 ハードウェアキーは保存できるパスキーの数が少なく、複数のサービスで使うと枠が埋まります。端末やブラウザごとに使える操作の違いは[passkeys.devのDevice Support](https://passkeys.dev/device-support/)で確かめられます。社内の標準端末とブラウザの組み合わせで、登録・同じ端末でのログイン・スマートフォンを使う別端末のログインの3つを試してから展開してください。 ### 独自ログインテーマでautocomplete属性を消すと条件付きUIが出ない問題 パスキーの自動入力候補は、ユーザー名欄の`autocomplete="username webauthn"`を手がかりにブラウザが出します。FreeMarkerやKeycloakifyでログイン画面を作り直したときにこの属性を落とすと、Sign in with Passkeyボタンでしかパスキーを使えなくなります。 テーマを作り込むほど、版を上げるたびに既定テーマとの差を取り込む作業が増えます。ログイン画面のデザイン、パスキーとOTPの組み合わせ、LDAP連携ユーザーの制約の確認まで含めて任せたい場合は、一創の[認証基盤・ID管理システム開発](https://www.issoh.co.jp/service/system/identity/)で支援しています。 ## Keycloakのパスキー設定で導入担当者からよく受ける質問と回答 パスキーを有効にする前後に出やすい疑問をまとめました。 ### Keycloakのパスキーは何版から使えますか？ 既定のログイン画面に統合された形で使えるのは26.3.0からで、このときはプレビュー機能でした。正式機能になったのは26.4.0です。26.3系で使うにはpasskeysの機能フラグを起動時に有効にする必要があります。2026年11月時点の最新は26.8.2なので、これから導入するなら26.7.0以降を選び、Realm settingsのLoginタブからスイッチを入れる手順にそろえるのが分かりやすい選択です。 ### パスキーだけでログインさせ、パスワードを使えなくできますか？ パスワードを使わないログイン構成への切り替えは可能です。WebAuthn Passwordlessの実行ステップだけをRequiredにしたブラウザフローを作り、レルムかクライアントに割り当てます。ただし、パスキーを登録していない利用者と端末を失くした利用者はログインできなくなります。全員の登録が済んだことをRequired Actionの残りで確かめ、管理者による再登録の手順を用意してから切り替えてください。 ### パスキーを失くした利用者はどうやってログインしますか？ 既定のEnable Passkeysの構成なら、パスワードでログインできます。2要素目にOTPを設定している場合は、パスワードに加えてそのOTPの入力も必要です。管理者はユーザーの資格情報の画面で失くしたパスキーを削除し、`webauthn-register-passwordless`を付けて登録をやり直させます。予備として2本目のパスキーを登録しておくよう、利用者向けの手順書に書いておくと復旧の件数が減ります。 ### スマートフォンのパスキーでPCのKeycloakにログインできますか？ できます。管理ガイドは、同期型のパスキーも端末固定のパスキーも、同じ端末での認証と別端末からの認証の両方に使えるとしています。PCのブラウザでSign in with Passkeyを押し、表示されたQRコードをスマートフォンで読み取る流れで、Keycloak側の追加設定は要りません。成否は端末とブラウザの組み合わせで変わるため、社内の標準環境で事前に確かめてください。 ### CognitoなどのIDaaSのパスキーとはどう違いますか？ Keycloakは自社でサーバーを運用する代わりに、RP IDやMediation、署名アルゴリズム、認証フローの組み方まで細かく決められます。Cognitoはサービス側の仕組みに合わせて有効化する形で、選べる項目は限られます。Cognitoでの手順は[Cognitoのパスキー実装手順](https://www.issoh.co.jp/tech/details/18516/)で解説しました。パスキーという方式そのものの利点と社内への説明は[パスキー認証とは](https://www.issoh.co.jp/column/details/15368/)が参考になります。 ## 関連記事 - [Keycloakとは？Oktaとの違いと連携手順｜Auth0・Cognito比較で導入を判断【2026年10月】](https://www.issoh.co.jp/tech/details/7663/)：Keycloakの機能の全体像と、他製品との違いです。 - [Keycloak 認証フローの設定手順：ブラウザフロー複製と条件付きOTP・Required Actions](https://www.issoh.co.jp/tech/details/19386/)：パスキーと組み合わせるOTPやロール条件の組み方です。 - [WebAuthnとは？パスキー認証の仕組みと登録・認証フローをコードで解説](https://www.issoh.co.jp/tech/details/15375/)：パスキーの登録と認証で何が送られているかの解説です。 - [パスキー移行の実装手順：パスワード併存からSignal API・CXPでの鍵移行まで](https://www.issoh.co.jp/tech/details/17716/)：パスワードからパスキーへ段階的に切り替える進め方です。 - [パスキー認証とは？仕組み・パスワードとの違い・企業の導入判断を解説](https://www.issoh.co.jp/column/details/15368/)：導入を社内で説明するときの判断材料です。 --- 出典: [Keycloak パスキーの設定手順：Enable Passkeysとパスワードレスポリシー・登録の流れ]()（株式会社一創）