keycloak-scim/server_admin/topics/authentication/webauthn.adoc

[[_webauthn]]

=== W3C Web Authentication (WebAuthn)

{project_name} provides the limited support for https://www.w3.org/TR/webauthn/[W3C Web Authentication (WebAuthn)]. {project_name} works as a WebAuthn's https://www.w3.org/TR/webauthn/#rp-operations[Relying Party (RP)].

IMPORTANT: Please note that WebAuthn support is still in development and not yet complete, so we recommend that you use this feature experimentally. Also, this support's specification and user interfaces may change.

NOTE: Whether WebAuthn's operations succeed depends on a user's WebAuthn supporting authenticator, browser and platform. If you use this WebAuthn support, please clarify to what extent those entities support the WebAuthn specification.

==== Setup

The setup procedure of WebAuthn support for 2FA is the following :

===== Enable User Registration

An administrator carries out the following operations on the `Admin Console` :

- Open the `Realm Settings -> Login` tab.
- Set the `User Registration` to ON and click `Save`.

===== Enable Webauthn Authenticator Registration

An administrator carries out the following operations on the `Admin Console` :

- Open the `Authentication -> Required Actions` tab.
- Click `Register`.
- Select `Webauthn Register` as `Required Action`.
- Mark `Enabled` and `Default Action` checkbox.

===== Adding WebAuthn Authentication to a Browser Flow

* Select a realm, click on Authentication link, select the "Browser" flow
* Make a copy of the built-in "Browser" flow. You may want to give the new flow a distinctive name, for example "WebAuthn Browser"
* Using the drop down, select the copied flow
* Delete the `WebAuthn Browser Browser - Conditional OTP` sub-flow using its `Actions` menu

If you want to have WebAuthn required for all users:

* Using the `Actions` menu of the `WebAuthn Browser Forms`, click on `Add execution`
* Select `WebAuthn Authenticator` using the drop down and click on "Save"
* Set its Requirement to _Required_.

image:images/webauthn-browser-flow-required.png[]

Note that in this scenario, if a user doesn't have a WebAuthn credential, a required action will be set that forces that user
to register one.

Alternatively, you can have users log in with WebAuthn only if they have a WebAuthn credential registered, so instead of adding
the `WebAuthn Authenticator` execution:

* Using the `Actions` menu of the `WebAuthn Browser Forms`, click on `Add flow`
* Set the alias to "Conditional 2FA"
* Set the Requirement of `Conditional 2FA` to _Conditional_
* Using the `Actions` menu of the `Conditional 2FA`, click on `Add execution`
* Select `Condition - User Configured` using the drop down and click on "Save"
* Using the `Actions` menu of the `Conditional 2FA`, click on `Add execution`
* Select `WebAuthn Authenticator` using the drop down and click on "Save"
* Set its Requirement to _Alternative_.

image:images/webauthn-browser-flow-conditional.png[]

You can also allow the user to choose between using WebAuthn and OTP for his second factor:

* Using the `Actions` menu of the `Conditional 2FA`, click on `Add execution`
* Select `OTP Form` using the drop down and click on "Save"
* Set its Requirement to _Alternative_.

image:images/webauthn-browser-flow-conditional-with-OTP.png[]

==== Authenticate with WebAuthn Authenticator

After registering their WebAuthn authenticator, the user carries out the following operations :

- Open the login form.
- Select the credential or credentials that {project_name} must accept for login. Then click `Save` and  click `Login`.
- The list of registered Webauthn Authenticators' labels appears. Click `Authenticate`.
- The user's browser asks the user to authenticate by their WebAuthn authenticator.

==== Managing WebAuthn as an administrator

===== Managing Credentials

WebAuthn credentials are managed in a similar manner as other credentials, such as OTP, from the <<user-credentials, User credential management>>:

* Users can be assigned a required action to create a WebAuthn credential from the `Reset Actions` list, and selecting `Webauthn Register`
* The administrator can delete a WebAuthn credential by pressing `Delete`.
* The administrator can view the credential's data such as the AAGUID by selecting `Show data...`.
* The administrator can set a label for the credential by setting a value in the `User Label` field and saving the data.

===== Managing Policy

An administrator can configure WebAuthn related operations as `WebAuthn Policy` per realm.

An administrator carries out the following operations on the `Admin Console` :

- Open the `Authentication -> WebAuthn Policy` tab.
- Configure items and click `Save`.

The configurable items and their description follow.

|===
|Configuration|Description

|Relying Party Entity Name
|Human-readable server name as a WebAuthn Relying Party. This is a mandatory configuration, which is applied to the operation of registering the WebAuthn authenticator. The default setting is "keycloak".
 For more details, see https://www.w3.org/TR/webauthn/#dictionary-pkcredentialentity[WebAuthn Specification].

|Signature Algorithms
|It tells the WebAuthn authenticator which signature algorithms to use for the https://www.w3.org/TR/webauthn/#public-key-credential[Public Key Credential] that can be used for signing and verifying the https://www.w3.org/TR/webauthn/#authentication-assertion[Authentication Assertion]. Multiple algorithms can be specified. If no algorithm is specified, https://tools.ietf.org/html/rfc8152#section-8.1[ES256] is adapted. The default setting is ES256. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator.
 For more details, see https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialparameters[WebAuthn Specification].

|Relying Party ID
|This is the ID as a WebAuthn Relying Party and determines the scope of Public Key Credentials. It must be origin's effective domain. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator. If no entry is entered, the host part of the base URL of {project_name}'s server is adapted.
 For more details, see https://www.w3.org/TR/webauthn/#rp-id[WebAuthn Specification].

|Attestation Conveyance Preference
|It tells the WebAuthn API implementation on the browser (https://www.w3.org/TR/webauthn/#webauthn-client[WebAuthn Client]) the preference of how to generate an Attestation Statement. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator. If no option is selected, its behavior is the same as selecting "none".
 For more details, see https://www.w3.org/TR/webauthn/#attestation-convey[WebAuthn Specification].

|Authenticator Attachment
|It tells the WebAuthn Client an acceptable attachment pattern of a WebAuthn authenticator. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator. If no option is selected, the WebAuthn Client does not consider the attachment pattern.
 For more details, see https://www.w3.org/TR/webauthn/#enumdef-authenticatorattachment[WebAuthn Specification].

|Require Resident Key
|It tells the WebAuthn authenticator to generate the Public Key Credential as https://www.w3.org/TR/webauthn/#client-side-resident-public-key-credential-source[Client-side-resident Public Key Credential Source]. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator. If no option is selected, its behavior is the same as selecting "No".
 For more details, see https://www.w3.org/TR/webauthn/#dom-authenticatorselectioncriteria-requireresidentkey[WebAuthn Specification].

|User Verification Requirement
|It tells the WebAuthn authenticator to confirm actually verifying a user. This is an optional configuration item that is applied to the operation of registering a WebAuthn authenticator and authenticating the user by a WebAuthn authenticator. If no option is selected, its behavior is the same as selecting "preferred".
 For more details, see https://www.w3.org/TR/webauthn/#dom-authenticatorselectioncriteria-userverification[WebAuthn Specification for registering a WebAuthn authenticator] and https://www.w3.org/TR/webauthn/#dom-publickeycredentialrequestoptions-userverification[WebAuthn Specification for authenticating the user by a WebAuthn authenticator].

|Timeout
|It specifies the timeout value in seconds for registering a WebAuthn authenticator and authenticating the user by a WebAuthn authenticator. If set to 0, its behavior depends on the WebAuthn authenticator's implementation. The default value is 0.
 For more details, see https://www.w3.org/TR/webauthn/#dom-publickeycredentialcreationoptions-timeout[WebAuthn Specification for registering a WebAuthn authenticator] and https://www.w3.org/TR/webauthn/#dom-publickeycredentialrequestoptions-timeout[WebAuthn Specification for authenticating the user by a WebAuthn authenticator].

|Avoid Same Authenticator Registration
|If set to "ON", the WebAuthn authenticator that has already been registered can not be newly registered. This is applied to the operation of registering a WebAuthn authenticator. The default setting is "OFF".

|Acceptable AAGUIDs
|The white list of AAGUID of which a WebAuthn authenticator can be registered. This is applied to the operation of registering a WebAuthn authenticator. If no entry is set on this list, any WebAuthn authenticator can be registered.

|===

==== Attestation Statement Verification

When registering a WebAuthn authenticator, {project_name} verifies an attestation statement generated by this WebAuthn authenticator. On this verification process, {project_name} validates this attestation statement's trustworthiness. It requires trust anchor's certificates. {project_name} uses the link:{installguide_truststore_link}[{installguide_truststore_name}]  so that you need to import these certificates onto it in advance.

If you want to omit this attestation statement trustworthiness validation, please disable this truststore or set the WebAuthn policy's configuration item "Attestation Conveyance Preference" to "none".


==== Managing WebAuthn credentials as a user

===== Register WebAuthn Authenticator

The appropriate method to register a WebAuthn authenticator depends on if the user has or has not already registered an account on {project_name}.

New user::

A new user carries out the following operations :

- Open the login form.
- Click the `Register` link.
- Fill in items on the register form and click `Register`.
- The user's browser asks the user to register their WebAuthn authenticator.
- After successful registration, the user's browser asks the user to enter the text as their just registered WebAuthn authenticator's label.

Existing user::

When existing users try to log in, they are required to register their WebAuthn authenticator automatically :

- Open the login form.
- Fill in items, click `Save` and  click `Login`.
- When the users log in, they are required to register their WebAuthn authenticator.
- After successful registration, the user's browser asks the user to enter the text as their just registered WebAuthn authenticator's label.

===== View Registered WebAuthn Authenticator

A user carries out the following operations on the <<_account-service, `User Account Service`>>  :

- View the `Account` page.

===== Edit Registered WebAuthn Authenticator

A user can edit the following information :

- Label (WebAuthn authenticator's label the user entered on registering it)

A user carries out the following operations on the <<_account-service, `User Account Service`>>  :

- View the `Account` page.
- Edit the text in `Public Key Credential Label`.
- Click `Save`.