mirror of
https://github.com/keycloak/keycloak.git
synced 2026-01-25 16:42:34 +00:00
8624101701
Closes #40705 Signed-off-by: rmartinc <rmartinc@redhat.com> Co-authored-by: Alexander Schwartz <alexander.schwartz@gmx.net> Signed-off-by: Ricardo Martin <rmartinc@redhat.com>
60 lines
5.4 KiB
Plaintext
60 lines
5.4 KiB
Plaintext
|
|
[id="passkeys_{context}"]
|
|
=== Passkeys
|
|
|
|
{project_name} provides preview support for https://fidoalliance.org/passkeys/[Passkeys]. {project_name} works as a Passkeys Relying Party (RP).
|
|
|
|
Passkey registration and authentication are performed using the same features of xref:webauthn_{context}[WebAuthn]. More specifically *Passkeys* are related to xref:_webauthn_loginless[LoginLess WebAuthn] as they try to avoid any password during login.
|
|
Therefore, users of {project_name} can do Passkey registration and authentication by existing xref:_enabling_organization_[WebAuthn registration and authentication], using the *passwordless* variants. The *Passkeys* feature have been integrated seamlessly in the default authentication forms, so, when activated, both conditional UI and modal UI are available in the forms in which the username input is displayed.
|
|
|
|
*Passkeys* have been added to the following authenticator implementations:
|
|
|
|
. *Username Password Form*: The username and password form used by default in {project_name}.
|
|
. *Username Form*: The form in which the username is displayed alone and is typically followed by the password form. This authenticator is used when the username and password fields want to be presented to the user in two different steps. Authenticating using *Passkeys* in the *Username Form* skips the next *Password Form* execution. The *Password Form* implementation checks if the user was already authenticated using a passwordless WebAuthn credential and, if that is the case, no password is requested.
|
|
. *Organization Identity - First Login*: The organization form that is used when the <<_enabling_organization_, organizations>> feature is enabled for the realm. Using *Passkeys* in this step avoids the subsequent execution of the username and password form in the same way than in the previous form.
|
|
|
|
:tech_feature_name: Passkeys
|
|
:tech_feature_id: passkeys
|
|
include::../templates/techpreview.adoc[]
|
|
|
|
[NOTE]
|
|
====
|
|
Both synced Passkeys and device-bound Passkeys can be used for both Same-Device and Cross-Device Authentication (CDA).
|
|
However, Passkeys operations success depends on the user's environment. Make sure which operations can succeed in https://passkeys.dev/device-support/[the environment].
|
|
====
|
|
|
|
[[_passkeys-conditional-ui]]
|
|
==== Passkey Authentication with Conditional UI or autofill
|
|
|
|
The Conditional User Interface (UI) or autofill is a feature related to passkeys in which the username input (the field in which the username to login is typed) is tagged with a `webauthn` autofill detail token (for example using the attribute `autocomplete="username webauthn"`). When the user clicks in such an input field, the user agent (browser) can render a list of discovered credentials for the user to select from, and perhaps also give the user the option to _try another way_. If the user selects one of the presented passkeys, {project_name} initiates the WebAuthn authentication with that key and avoids any password typing.
|
|
|
|
Compared with xref:_webauthn_loginless[LoginLess WebAuthn], the authentication improves the user's experience of authentication.
|
|
|
|
.Passkey Authentication with Conditional UI Autofill using Chrome browser
|
|
image:images/passkey-conditional-ui-autofill.png[Passkey Authentication with Conditional UI Autofill using Chrome browser]
|
|
|
|
[NOTE]
|
|
====
|
|
This authentication uses the https://github.com/w3c/webauthn/wiki/Explainer:-WebAuthn-Conditional-UI/[WebAuthn Conditional UI].
|
|
Therefore, this authentication success depends on the user's environment.
|
|
If the environment does not support WebAuthn Conditional UI, the user should use the direct modal UI or username and password login.
|
|
====
|
|
|
|
==== Passkeys Authentication with Modal UI
|
|
|
|
Nevertheless, because conditional UI can sometimes not show all the credentials to the user, the modal UI can always be initiated using the button *Sign in with Passkey*. The Modal User Interface (UI) ensures all passkeys are usable, including the ones stored in hardware tokens or on other devices that cannot be enumerated without user interaction.
|
|
|
|
.Passkey Authentication with Modal UI using Chrome browser
|
|
image:images/passkey-modal-ui.png[Passkey Authentication with Modal UI using Chrome browser]
|
|
|
|
==== Setup
|
|
|
|
Set up Passkey Authentication for the default forms as follows:
|
|
|
|
. (If not already done) Check the required action for *WebAuthn Register Passwordless* is enabled. Use the steps described in <<_webauthn-register, Enable WebAuthn Authenticator Registration>>, but using *WebAuthn Register Passwordless* instead of *WebAuthn Register*.
|
|
|
|
. Configure the *WebAuthn Passwordless Policy* in the same way that is explained in xref:_webauthn_loginless[LoginLess WebAuthn]. Perform the configuration in the Admin Console, `Authentication` section, in the tab `Policies` → `WebAuthn Passwordless Policy`. Set *User Verification Requirement* to *required* and *Require discoverable credential* to *Yes* when you configure the policy for passwordless scenario.
|
|
+
|
|
NOTE: Storage capacity is usually very limited on hardware passkeys meaning that you cannot store many discoverable credentials on your passkey. However, this limitation may be mitigated for instance if you use an Android phone backed by a Google account as a passkey device or an iPhone backed by Bitwarden.
|
|
+
|
|
. In the same policy tab *WebAuthn Passwordless Policy* activate the *Enable Passkeys* option at the bottom. This switch is the one that really enables passkeys (both conditional and modal UI) in the default username forms. |