2026.11.06 セキュリティ

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の節は、パスワードレス用に別のポリシー・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などのソースが使う識別子です。WebAuthnの登録と認証の仕組みそのものはWebAuthnとはでコードとともに解説しました。

26.3のプレビューから26.7のMediation追加までのパスキー機能の版ごとの変化

パスキーの設定手順は、26系の中でも版によって画面の場所が違います。リリースノートと、各版の管理ガイドのソースを比べると次のとおりです。

版	変化
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でPASSKEYSが既定で有効と定義されており、26.4.0以降は起動オプションの追加が要りません。

Username Password Formの条件付きUIとパスキー用ボタンの動き

管理ガイドのPasskeysの節によると、スイッチを入れると、ユーザー名欄が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では、Discoverable credentialとUser Verification Requirementがどちらもrequiredです。2要素目用のWebAuthn Policyはどちらも指定なしなので、パスキー用のほうが条件は厳しくなります。

kcadm.shでパスワードレス用ポリシーとパスキー有効化を一括設定する手順

画面の項目は、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のレルム更新とauthentication/required-actionsです。curlでトークンを取って同じ更新を送る書き方はKeycloak APIの使い方にまとめました。

Relying Party IDを空欄にしたときの既定とサブドメインをまたぐ設定の注意

WebAuthn Policyの項目表によると、Relying Party IDが空欄ならKeycloakのベースURLのホスト名が使われます。上の例で空欄にするとauth.example.comに紐づくパスキーになります。

登録済みのパスキーはRP IDに結びつくため、後から値を変えると既存の鍵ではログインできなくなります。将来Keycloakを別のサブドメインへ移す予定があるなら、最初から親ドメインのexample.comを入れておきます。ただし、親ドメインにした鍵は同じドメイン配下の別サイトでも使える範囲になるので、社外向けサービスと同居させるかどうかで決めてください。

Passkey Mediationの5つの値とログイン画面の開き方の違い

Passkey Mediationは、ブラウザのnavigator.credentials.get()に渡すmediationの値です。管理ガイドのPasskey Mediationの節は次の5つを挙げています。

値	ログイン画面を開いたときの動き
conditional（既定）	ユーザー名欄の自動入力候補にだけ出る
none	自動では何もせずボタンから使う
optional	選択画面を自動で出す・閉じてもよい
required	選択画面を出し、使うか閉じるまで進めない
silent	画面を出さずに試す・失敗しやすい

実務での開始時に選ぶ値は、既定のconditionalです。管理ガイドは、requiredとsilentの動きがブラウザによって違うと注記しています。optionalを選ぶのは、全員が登録を終えた社内システムで選択画面を毎回出したい場合に限られます。

既存ユーザーにパスキーを登録させるRequired ActionとAIAの組み込み方

スイッチを入れただけでは、誰もパスキーを持っていません。登録の入口を作る作業が、導入で一番手間のかかる部分です。

Webauthn Register Passwordlessの既定と全員の登録設定

DefaultRequiredActions.javaでは、Webauthn Register Passwordlessは有効の状態でレルムに登録されます。AuthenticationのRequired ActionsタブでDefault Actionをオンにすると、新しく作るユーザーに初回ログインで登録を求めます。

既に存在するユーザーには付きません。全員に登録させたい場合は、ユーザーごとにrequiredActionsへwebauthn-register-passwordlessを足します。この配列は丸ごと置き換わるため、メール確認などの既存の値を取得してから足して送ってください。一括付与の書き方と注意点は、OTPの例でKeycloak 認証フローの設定手順に載せています。

kc_actionで登録画面を開くAIAのURLと登録済み利用者を省く指定

強制ではなく、利用者が自分のタイミングで登録する形にしたいなら、アプリ側に「パスキーを登録」ボタンを置きます。管理ガイドのAIAの節のとおり、通常の認可リクエストに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の説明では、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の脆弱性対応の手順で扱う更新作業の一覧に入れておくと漏れません。

パスワードを残すか消すかの判断とパスキー導入で詰まりやすい場面

運用に入ってからの問い合わせは、ほとんどが次の4つから来ます。

Enable Passkeysはパスワードを残す方式でありパスワードレス専用ではない点

Enable Passkeysを入れても、Username Password Formのパスワード欄は残ります。パスキーを使わない利用者は従来どおりパスワードで入れるため、フィッシングで盗まれたパスワードが通る経路も残ります。

パスワードを使えなくするには、管理ガイドのLoginLess WebAuthnのように、WebAuthn PasswordlessだけをRequiredにしたフローを別に作ります。この構成では、端末を失くした利用者は自分でログインできません。管理者が資格情報を削除して登録をやり直させる窓口と、本人確認の手順を先に決められないなら、パスワードを止める段階には進まないでください。パスワードとの併存期間の設計はパスキー移行の実装手順で解説しています。

LDAP連携ユーザーでuser.idが64バイトを超えて登録できない制約

管理ガイドのWebAuthnの節は、WebAuthnのuser.idの上限が64バイトだと注記しています。Keycloakは内部IDをそのまま渡し、通常のユーザーでは36文字のUUIDなので問題はありません。

LDAPなど外部のユーザーフェデレーションから来た利用者は、IDがf:<provider-id>:<user-id>の形になります。プロバイダーのIDとユーザーのIDがどちらも36文字のUUIDなら、合計75バイトで上限を超える計算です。Active Directoryと連携しているレルムでは、パスキーを有効にする前に、検証用のユーザーで登録が通るかを必ず確かめます。連携の設定はKeycloak LDAP連携にまとめました。

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で確かめられます。社内の標準端末とブラウザの組み合わせで、登録・同じ端末でのログイン・スマートフォンを使う別端末のログインの3つを試してから展開してください。

独自ログインテーマでautocomplete属性を消すと条件付きUIが出ない問題

パスキーの自動入力候補は、ユーザー名欄のautocomplete="username webauthn"を手がかりにブラウザが出します。FreeMarkerやKeycloakifyでログイン画面を作り直したときにこの属性を落とすと、Sign in with Passkeyボタンでしかパスキーを使えなくなります。

テーマを作り込むほど、版を上げるたびに既定テーマとの差を取り込む作業が増えます。ログイン画面のデザイン、パスキーとOTPの組み合わせ、LDAP連携ユーザーの制約の確認まで含めて任せたい場合は、一創の認証基盤・ID管理システム開発で支援しています。

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のパスキー実装手順で解説しました。パスキーという方式そのものの利点と社内への説明はパスキー認証とはが参考になります。