190 lines
11 KiB
Text
190 lines
11 KiB
Text
|
[[_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 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.
|
||
|
|
|
||
|
|
The major restriction is as follows :
|
||
|
|
|
||
|
|
- A user can register only one WebAuthn supporting Authenticator (called WebAuthn authenticator here).
|
||
|
|
- On registering the WebAuthn authenticator, its https://www.w3.org/TR/webauthn/#attestation-statement[Attestation Statement] is not verified.
|
||
|
|
- Only the Two-Factor Authentication (2FA) scenario is supported.
|
||
|
|
|
||
|
|
==== 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.
|
||
|
|
|
||
|
|
Enable 2FA by Webauthn Authenticator::
|
||
|
|
|
||
|
|
An administrator carries out the following operations on the `Admin Console` :
|
||
|
|
|
||
|
|
- Open the `Authentication -> Flows` tab.
|
||
|
|
- Copy and create the new browser flow.
|
||
|
|
- Add the `WebAuthn Authenticator` execution below the `User Password Form` execution.
|
||
|
|
- Set `REQUIRED` to the `WebAuthn Authenticator` execution's requirement.
|
||
|
|
- Open the `Authentication -> Bindings` tab.
|
||
|
|
- Select the created new browser flow as `Browser Flow`.
|
||
|
|
- Click `Save`.
|
||
|
|
|
||
|
|
==== Register WebAuthn Authenticator
|
||
|
|
|
||
|
|
The appropriate method to register a WebAuthen authenticator depends on if the user has or has not already registered an account on {project_name}.
|
||
|
|
|
||
|
|
User without their account::
|
||
|
|
|
||
|
|
A 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.
|
||
|
|
|
||
|
|
User with their account::
|
||
|
|
|
||
|
|
When such the 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.
|
||
|
|
|
||
|
|
==== Authenticate by WebAuthn Authenticator
|
||
|
|
|
||
|
|
After registering their WebAuthn authenticator, the user carries out the following operations :
|
||
|
|
|
||
|
|
- Open the login form.
|
||
|
|
- Fill in items, 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.
|
||
|
|
|
||
|
|
==== View Registered WebAuthn Authenticator
|
||
|
|
|
||
|
|
An administrator and a user can view the following information :
|
||
|
|
|
||
|
|
- https://www.w3.org/TR/webauthn/#credential-id[Credential ID]
|
||
|
|
- Label (WebAuthn authenticator's label the user entered on registering it)
|
||
|
|
- https://fidoalliance.org/specs/fido-v2.0-rd-20180702/fido-metadata-statement-v2.0-rd-20180702.html#authenticator-attestation-guid-aaguid-typedef[AAGUID]
|
||
|
|
|
||
|
|
An administrator carries out the following operations on the `Admin Console` :
|
||
|
|
|
||
|
|
- Open the `Users -> (user) -> Credentials` tab.
|
||
|
|
- View the `Manage WebAuthn Authenticator` area.
|
||
|
|
|
||
|
|
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`.
|
||
|
|
|
||
|
|
==== Delete Registered WebAuthn Authenticator
|
||
|
|
|
||
|
|
An administrator can delete the users' registered WebAuthn authenticators.
|
||
|
|
|
||
|
|
An Administrator carries out the following operations on the `Admin Console` :
|
||
|
|
|
||
|
|
- Open the `Users -> (user) -> Credentials` tab.
|
||
|
|
- On the `Disable Credentials` area, add `webauthn` to `Disable Types`.
|
||
|
|
- Click `Disable Credential Types`.
|
||
|
|
|
||
|
|
==== Re-Register WebAuthn Authenticator
|
||
|
|
|
||
|
|
A user can re-register their WebAuthn authenticator. Newly registered WebAuthn authenticator overrides the old registered one.
|
||
|
|
|
||
|
|
At first, an administrator carries out the following operations on the `Admin Console` to require the user to register their WebAuthn authenticator after their login :
|
||
|
|
|
||
|
|
- Open the `Users -> (user) -> Details` tab.
|
||
|
|
- Set `WebAuthn Register` on `Required User Actions`.
|
||
|
|
- Click `Save`.
|
||
|
|
|
||
|
|
After that, the user carries out the following operations :
|
||
|
|
|
||
|
|
- 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.
|
||
|
|
|
||
|
|
==== Configuration
|
||
|
|
|
||
|
|
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 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 WebAuthn authenticator.
|
||
|
|
For more details, see https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialparameters[WebAuthn Specification].
|
||
|
|
|
||
|
|
|Relying Party ID
|
||
|
|
|This is the ID as 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 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. However, {project_name} does not verify the Attestation Statement so that only "none" option can be selected. This is an optional configuration item that is applied to the operation of registering 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 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 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 WebAuthn authenticator and authenticating the user by 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 WebAuthn authenticator] and https://www.w3.org/TR/webauthn/#dom-publickeycredentialrequestoptions-userverification[WebAuthn Specification for authenticating the user by WebAuthn authenticator].
|
||
|
|
|
||
|
|
|Timeout
|
||
|
|
|It specifies the timeout value in seconds for registering WebAuthn authenticator and authenticating the user by 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 WebAuthn authenticator] and https://www.w3.org/TR/webauthn/#dom-publickeycredentialrequestoptions-timeout[WebAuthn Specification for authenticating the user by 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 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 WebAuthn authenticator. If no entry is set on this list, any WebAuthn authenticator can be registered.
|
||
|
|
|
||
|
|
|===
|