KEYCLOAK-11745 Multi-factor authentication documentation

Co-authored-by: rpo <harture414@gmail.com>
Co-authored-by: mposolda <mposolda@gmail.com>

release_notes/topics/8_0_0.adoc

@@ -45,6 +45,18 @@ In this release, we added initial support for W3C Web Authentication (WebAuthn).
 however we are working on further improvements in this area. Thanks to https://github.com/tnorimat[tnorimat] for the contribution. Also thanks to
 https://github.com/ynojima[ynojima] for the help and feedback.
 
+== Support for password-less authentication, multi-factor authentication and multiple credentials per user
+
+With the arrival of W3C Web Authentication support, we've refined the authentication flow system to be able to allow a user to select which authentication method he
+wishes to use during his login (for example, to choose between his OTP credential and his WebAuthn credential). The new mechanisms also allow an administrator to
+craft flows for password-less login, for example just using WebAuthn as an authentication method. Please note that with these changes, any custom authentication
+flow you have created may need to be adapted to the new flow logic.
+
+As a result of these changes, it is now also possible for users to have multiple OTP devices and multiple WebAuthn devices. The same system that allows a user
+to select which type of device to use during login also allows him to select which specific device to use. Thanks to the https://github.com/cloudtrust[Cloudtrust] team:
+https://github.com/AlistairDoswald[AlistairDoswald], https://github.com/fperot74[sispeo] and https://github.com/Fratt[Fratt] for their contributions, and
+to https://github.com/harture[harture] and https://github.com/lagess[Laurent] for their help.
+
 
 = Other Improvements
 
@@ -68,9 +80,9 @@ Thanks to https://github.com/jonkoops[jonkoops] now it's possible to enable or d
 
 == Credentials support removed from the JavaScript adapter
 
-The option to provide client credentials in the JavaScript adapter was removed. Thanks to https://github.com/jonkoops[jonkoops] 
+The option to provide client credentials in the JavaScript adapter was removed. Thanks to https://github.com/jonkoops[jonkoops]
 
-== Updates for Gatekeeper 
+== Updates for Gatekeeper
 
 * Secure token and logout endpoint were included in Gatekeeper. Thanks to https://github.com/fredbi[fredbi]
 * There was a bug on Gatekeeper which was making cookies to be applied to subdomains. Thanks to https://github.com/daniel-ac-martin[daniel-ac-martin] the issue was fixed

server_admin/topics/authentication/flows.adoc

@@ -5,7 +5,14 @@
 An _authentication flow_ is a container for all authentications, screens, and actions that must happen during login, registration, and other
 {project_name} workflows.
 If you go to the admin console `Authentication` left menu item and go to the `Flows` tab, you can view all the defined flows
-in the system and what actions and checks each flow requires.  This section does a walk-through of the browser login flow.  In the
+in the system and what actions and checks each flow requires.
+
+==== Built-in flows
+
+{project_name} comes with a certain number of built-in flows. These flows cannot be modified, but the requirements can be modified to
+suit your needs.
+
+This section does a walk-through of the built-in browser login flow.  In the
 left drop-down list select `browser` to come to the screen shown below:
 
 .Browser Flow
@@ -15,41 +22,187 @@ If you hover over the tooltip (the tiny question mark) to the right of the flow
 flow is and does.
 
 The `Auth Type` column is the name of authentication or action that will be executed.  If an authentication is indented
-this means it is in a sub-flow and may or may not be executed depending on the behavior of its parent.  The `Requirement`
-column is a set of radio buttons which define whether or not the action will execute.  Let's describe what each radio
-button means:
+this means it is in a sub-flow and may or may not be executed depending on the behavior of its parent. The `Requirement`
+column is a set of radio buttons which define whether or not the action will execute. Let's describe what each radio
+button means in this context:
 
 Required::
-  This authentication execution must execute successfully.  If the user doesn't have that type of authentication mechanism
+  This authentication execution must execute successfully. If the user doesn't have that type of authentication mechanism
   configured and there is a required action associated with that authentication type, then a required action will be attached
-  to that account.  For example, if you switch `OTP Form` to `Required`, users that don't have an OTP generator configured
+  to that account.  For example, if you switch the `Browser - Conditional OTP` sub-flow to `Required`, users that don't have an OTP generator configured
   will be asked to do so.
-Optional::
-  If the user has the authentication type configured, it will be executed.  Otherwise, it will be ignored.
-Disabled::
-  If disabled, the authentication type is not executed.
 Alternative::
   This means that at least one alternative authentication type must execute successfully at that level of the flow.
+Disabled::
+  If disabled, the authentication type is not executed.
+Conditional::
+  This requirement type can only be set on sub-flows, indicating that it will only be executed if its condition evaluates to true.
 
 This is better described in an example.  Let's walk through the `browser` authentication flow.
 
 . The first authentication type is `Cookie`.  When a user successfully logs in for the first time, a session cookie is set.
-  If this cookie has already been set, then this authentication type is successful.
-  Since the cookie provider returned success and each execution at this level of the flow is _alternative_, no other execution is executed and this results in a successful login.
-. Next the flow looks at the Kerberos execution.  This authenticator is disabled by default and will be skipped.
-. The next execution is a subflow called Forms.  Since this subflow is marked as _alternative_ it will not be executed if the `Cookie` authentication type passed.
-  This subflow contains additional authentication type that needs to be executed.
-  The executions for this subflow are loaded and the same processing logic occurs
-. The first execution in the Forms subflow is the Username Password Form.  This authentication type renders the username and password page.
+  If this cookie has already been set, then this authentication type is successful. In this case,
+  since the cookie provider returned success and each execution at this level of the flow is _alternative_, no other execution is executed and this results in a successful login.
+. The second execution of the flow looks at the `Kerberos` execution.  This authenticator is disabled by default and will be skipped.
+. The third execution is the `Identity Provider Redirector`. It can be configured through the `Actions` > `Config` link to automatically redirect to another IdP for <<_identity_broker, identity brokering>>.
+. The next execution is a sub-flow called `Forms`.  Since this sub-flow is marked as _alternative_ it will not be executed if the `Cookie` authentication type passed.
+  This sub-flow contains additional authentication type that needs to be executed.
+  The executions for this sub-flow are loaded and the same processing logic occurs.
+. The first execution in the Forms sub-flow is the Username Password Form.  This authentication type renders the username and password page.
   It is marked as _required_ so the user must enter in a valid username and password.
-. The next execution is the OTP Form.
-  This is marked as _optional_.  If the user has OTP set up, then this authentication type must run and be successful.  If the user doesn't
-  have OTP set up, this authentication type is ignored.
+. The second execution in the Forms sub-flow is a new sub-flow: the `Browser - Conditional OTP` sub-flow. Since this sub-flow is _conditional_, whether it is executed depends on the result of the
+  evaluation of the `Condition - User Configured` execution. If it is, the executions for this sub-flow are loaded and the same processing logic occurs
+. The next execution is the `Condition - User Configured`. This checks if the other executions in the flow are configured for the user.
+  Meaning that the `Browser - Conditional OTP` sub-flow will only be executed if the user has an OTP credential configured.
+. The final execution is the `OTP Form`. This is marked as _required_, but because of the setup in the _conditional_ subflow, it will only be run if the user
+  has an OTP credential set up. If he doesn't, the user will not see an OTP form.
+
+==== Creating flows
+
+This section explains in greater depth how flows work, and how to create your own flows. Note that there are important functionality and security
+considerations when designing your own flow. A badly created flow could either let no one log in, let users in with less verification than you would
+like, or simply result in an error.
+
+To create a flow, you can either:
+. Copy and then modify an existing flow. To do this select an existing flow (for example the `Browser` flow), and press the `Copy` button.
+  This will then ask you to set a name for the new flow, before creating it.
+. Create a new flow from scratch. To do this press the `New` button. Since this is the more general case, we will use this for our example.
+
+When creating a new flow, you will have to create a top level flow
+
+.Create a top level flow
+image:{project_images}/Create-top-level-flow.png[]
+
+With the following options:
+
+Alias::
+  The name of the flow.
+Description::
+  The description you can set to the flow.
+Top Level Flow Type::
+  The type of flow. the type `client` is used only for the authentication of clients (applications). For all other cases choose `generic`.
+
+Once the flow is created, in addition to the `New` and `Copy` buttons, you now have, `Delete`, `Add execution` and `Add flow`.
+
+.An empty new flow
+image:{project_images}/New-flow.png[]
+
+What a flow finally does is determined by the structure of the flow and sub-flows, the executions in those flows, and the requirements set on the
+sub-flows and the executions.
+
+Executions can be added with the `Add execution` button. Executions can have a wide variety of actions, from sending a reset email to validating an OTP. If you hover over the
+tooltip (the tiny question mark) next to `Provider`, this will describe what the execution does.
+
+.Adding an authentication execution
+image:{project_images}/Create-authentication-execution.png[]
+
+These can be divided into _automatic executions_ and _interactive executions_. _Automatic executions_ are similar to the `Cookie` execution, and will automatically
+perform their action when they are encountered in the flow. _Interactive executions_ will halt the flow, usually to get some user input. Executions that execute
+successfully will get the _success_ status. This is important, because this is part of whether a flow is successful or not. For example, an empty `Browser` flow
+would not allow anyone to log in. For that it would need at least one execution that successfully evaluates, for example a `Username Password Form` that is corrected
+filled and submitted.
+
+Sub-flows can be added in top level flow with the `Add flow` button, which opens a `Create Execution Flow` page that is very similar to the `Create Top Level Form`
+page. The only difference is that the `Flow Type` can be either `generic` (like before), or `form`. The `form` type is used to construct a sub-flow that generates
+a single form for the user, like what is done for the built-in `Registration` flow. Sub-flows are a special type of execution that evaluate as successful
+depending on how the executions they contain evaluate (and this includes the evaluation of their contained sub-flows). And the logic of this evaluation
+depends on the Requirement of each execution and sub-flow.
+
+Fully understanding this requires a more complete explanation of how requirements work when evaluating a flow, and this also applies to sub-flows:
+
+Required::
+  For a flow to be evaluated as successful, all required elements in the flow must evaluate as successful. This means that all _Required_ elements in the flow
+  must be sequentially executed, from top to bottom, unless one the the elements causes the flow to fail. However, this is only true for the current flow.
+  Any _Required_ element within a sub-flow is only processed if that sub-flow is entered.
+Alternative::
+  When a flow contains only _Alternative_ elements, only a single element must evaluate as successful for the flow to evaluate as successful.
+  Because the _Required_ flow elements within a flow are sufficient to mark a flow as successful, any _Alternative_ flow element within a flow
+  that contains _Required_ flow elements will never be executed. In this case, they are functionally _Disabled_.
+Disabled::
+  Any _Disabled_ element is not evaluated and does not count to mark a flow as successful.
+Conditional::
+  This requirement type can only be set on sub-flows. A _Conditional_ sub-flow can contain a "Condition" execution. These "Condition" executions must evaluate as
+  logical statements. If all "Condition" executions evaluate as _true_ then the _Conditional_ sub-flow acts as _Required_. If not, the _Conditional_ sub-flow
+  acts as _Disabled_. If no "Condition" execution is set, the _Conditional_ sub-flow acts as _Disabled_. If a flow contains "Condition" executions and is not set to
+  _Conditional_, the "Condition" executions are not evaluated, and can be considered functionally _Disabled_.
+
+Note that after adding an execution, you should check that the Requirement is set to the correct value. Even if there is only a single possible Requirement, it
+can happen that it is not set.
+
+When constructing a flow, all elements added to the flow will have an `Actions` menu on the right-hand side. All elements added to the flow have a `Delete`
+option in this menu to remove it from the flow. Executions can contain a `Config` menu option to configure the execution, as is the case for the
+`Identity Provider Redirector`. Sub-flows can also have executions and sub-flows added to them, with their `Add execution` and `Add flow` menu options.
+
+Finally, since the order of execution is important, you can move executions and sub-flows up and down within their respective flows with the up and down buttons
+that are set to left of their name.
+
+==== Creating a password-less browser login flow
+
+To illustrate the creation of flows, this section describes the creation of a more advanced browser login flow. The purpose of this flow is to allow a
+user to choose between logging in in a password-less manner using <<_webauthn, WebAuthn>>, and a two-factor authentication with password and OTP.
+The flow to create is similar to the standard browser login, but diverges when reaching the username selection. Instead of copying the flow however, you'll be
+creating the flow from the start:
+
+* Select a realm, click on Authentication link
+* Select "new", and give the new flow a distinctive Alias, i.e. "Browser Password-less"
+* Select "Add execution", and using the drop-down select "Cookie". After pressing "Save", set its Requirement to _Alternative_.
+* Select "Add execution", and using the drop-down select "Kerberos".
+* Select "Add execution", and using the drop-down select "Identity Provider Redirector". After pressing "Save", set its Requirement to _Alternative_.
+* Select "Add flow", and choose an representative Alias, e.g. "Forms". After pressing "Save", set its Requirement to _Alternative_.
+
+.The common part with the browser flow
+image:images/Passwordless-browser-login-common.png[]
+
+* Using the `Actions` menu on the right-hand side of the "Forms" subflow, select "Add execution". Using the drop-down select
+  "Username Form". After pressing "Save", set its Requirement to _Required_.
+
+The Username form is similar to "Browser" flow's Username Password Form, but only asks for a username, allowing a user to do perform a password-less login.
+However, note that this inevitably allows a user enumeration attack on your {project_name} server. This is an unavoidable security risk for the convenience,
+so the flow should make sure that an attacker cannot just have to guess a password to be able to enter.
+
+* Using the `Actions` menu on the right-hand side of the "Forms" subflow, select "Add flow". Choose an representative Alias, e.g. "Authentication".
+  After pressing "Save", set its Requirement to _Required_.
+* Using the `Actions` menu on the right-hand side of the "Authentication" subflow, select "Add execution". Using the drop-down select
+  "Webauthn Authenticator". After pressing "Save", set its Requirement to _Alternative_.
+* Using the `Actions` menu on the right-hand side of the "Authentication" subflow, select "Add flow". Choose an representative Alias, e.g. "Password with OTP".
+  After pressing "Save", set its Requirement to _Alternative_.
+* Using the `Actions` menu on the right-hand side of the "Password with OTP" subflow, select "Add execution". Using the drop-down select
+  "Password Form". After pressing "Save", set its Requirement to Required.
+* Using the `Actions` menu on the right-hand side of the "Password with OTP" subflow, select "Add execution". Using the drop-down select
+  "OTP Form". After pressing "Save", set its Requirement to Required.
+* In the "Bindings" menu, change the browser flow from "Browser" to "Browser Password-less"
+
+The final flow that is produced is the following:
+
+.A password-less browser login
+image:images/Passwordless-browser-login.png[]
+
+After entering the username, the way this flow works is the following:
+
+* If the user has any WebAuthn credentials recorded, he will be able to use any of them to log in directly. This is the password-less login.
+  The user also has a drop-down allowing him to select "Password with OTP". He can do this because the "WebAuthn" execution and the "Password with OTP"
+  flow are set to _Alternative_. Were they set to _Required_ the user would have to enter WebAuthn, password, and OTP.
+* If the user selects the "Password with OTP" from the drop-down, or if the user doesn't have any WebAuthn credentials, he will have to first enter his
+  password, and then his OTP. If the user has no OTP credential, he will be asked to record one.
+
+It is important to note that since the WebAuthn execution is set to _Alternative_ instead of _Required_, this flow will never ask the user to register a WebAuthn credential. For a user
+to have a Webauthn credential, he must have a required action added to him by an administrator. This is done first by making sure that that the `Webauthn Register`
+required action is enabled in the realm (see the <<_webauthn,WebAuthn>> documentation), and then by setting the required action by using the `Credential Reset` part of a
+user's <<user-credentials,Credentials>> management menu.
+
+Creating a more advanced flow such as this one can have some subtle side effects. For example, if you were to enable the ability to reset the password
+for the user, then this would be accessible from the password form. In the default "Reset Credentials" flow, the user has to enter his username. Since
+he's already entered his username earlier in the "Browser Password-less" flow, this would be unnecessary for {project_name}, and a sub-optimal in terms of user
+experience. To correct this, you could:
+
+* Copy the "Reset Credentials" flow, setting its name to, for example "Reset Credentials for password-less"
+* Use the `Actions` menu on the right-hand side of the "Choose user" execution, select "Delete"
+* In the "Bindings" menu, change the reset credential flow from "Reset Credentials" to "Reset Credentials for password-less"
 
 ifeval::[{project_community}==true]
 === Executions
 
-Executions can be used 
+Executions can be used
 
 .Script Authenticator
 A _script_ authenticator allows to define custom authentication logic via JavaScript.
@@ -82,7 +235,7 @@ The following script `javax.script.Bindings` are available for convenient use wi
 `LOG`::
 a `org.jboss.logging.Logger` scoped to `ScriptBasedAuthenticator`
 
-Note that additional context information can be extracted from the `context` argument passed 
+Note that additional context information can be extracted from the `context` argument passed
 to the `authenticate(context)` `action(context)` function.
 
 [source,javascript]
@@ -103,5 +256,5 @@ function authenticate(context) {
 
   context.success();
 }
-----                        
+----
 endif::[]

server_admin/topics/authentication/webauthn.adoc

@@ -8,24 +8,20 @@ IMPORTANT: Please note that WebAuthn support is still in development and not yet
 
 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.
+Also note that on registering the WebAuthn authenticator, its https://www.w3.org/TR/webauthn/#attestation-statement[Attestation Statement] is not verified.
 
 ==== Setup
 
 The setup procedure of WebAuthn support for 2FA is the following :
 
-Enable User Registration::
+===== 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::
+===== Enable Webauthn Authenticator Registration
 
 An administrator carries out the following operations on the `Admin Console` :
 
@@ -34,107 +30,67 @@ An administrator carries out the following operations on the `Admin Console` :
 - Select `Webauthn Register` as `Required Action`.
 - Mark `Enabled` and `Default Action` checkbox.
 
-Enable 2FA by Webauthn Authenticator::
+===== Adding WebAuthn Authentication to a Browser Flow
 
-An administrator carries out the following operations on the `Admin Console` :
+* 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, i.e. "WebAuthn Browser"
+* Using the drop down, select the copied flow
+* Delete the `WebAuthn Browser Browser - Conditional OTP` sub-flow using its `Actions` menu
 
-- 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`.
+If you want to have WebAuthn required for all users:
 
-==== Register WebAuthn Authenticator
+* 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_.
 
-The appropriate method to register a WebAuthen authenticator depends on if the user has or has not already registered an account on {project_name}.
+image:images/webauthn-browser-flow-required.png[]
 
-User without their account::
+Note that in this scenario, if a user doesn't have a WebAuthn credential, a required action will be set that forces him
+to register one.
 
-A user carries out the following operations :
+Alternatively, you can have users login with WebAuthn only if they have a WebAuthn credential registered, so instead of adding
+the `WebAuthn Authenticator` execution:
 
-- 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.
+* 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_.
 
-User with their account::
+image:images/webauthn-browser-flow-conditional.png[]
 
-When such the users try to log in, they are required to register their WebAuthn authenticator automatically :
+You can also allow the user to choose between using WebAuthn and OTP for his second factor:
 
-- 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.
+* 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_.
 
-==== Authenticate by WebAuthn Authenticator
+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.
-- Fill in items, click `Save` and  click `Login`.
+- 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.
+- The user's browser asks the user to authenticate by their WebAuthn authenticator
 
-==== View Registered WebAuthn Authenticator
+==== Managing WebAuthn as an administrator
 
-An administrator and a user can view the following information :
+===== Managing Credentials
 
-- https://www.w3.org/TR/webauthn/#credential-id[Credential ID]
-- Label (WebAuthn authenticator's label the user entered on registering it)
-- AAGUID
+WebAuthn credentials are managed in a similar manner as other credentials, such as OTP, from the <<user-credentials, User credential management>>:
 
-An administrator carries out the following operations on the `Admin Console` :
+* 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 it's `Delete` button
+* 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.
 
-- 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
+===== Managing Policy
 
 An administrator can configure WebAuthn related operations as `WebAuthn Policy` per realm.
 
@@ -151,7 +107,7 @@ The configurable items and their description follow.
 |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].
@@ -187,3 +143,46 @@ The configurable items and their description follow.
 |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.
 
 |===
+
+==== 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`.

server_admin/topics/identity-broker/first-login-flow.adoc

@@ -72,8 +72,10 @@ In order to configure a first login flow in which users are automatically linked
 Create User If Unique::
 This authenticator ensures that unique users are handled. Set the authenticator requirement to "Alternative".
 
-Automatically Link Brokered Account::
-Automatically link brokered identities without any validation with this authenticator. This is useful in an intranet environment of multiple user databases each with overlapping usernames/email addresses, but different passwords, and you want to allow users to use any password without having to validate. This is only reasonable if you manage all internal databases, and usernames/email addresses from one database matching those in another database belong to the same person. Set the authenticator requirement to "Alternative".
+Automatically Set Existing User::
+Automatically sets an existing user to the authentication context without any verification. Set the authenticator requirement to "Alternative".
 
 NOTE: The described setup uses two authenticators, and is the simplest one, but it is possible to use other
-authenticators according to your needs. For example, you can add the Review Profile authenticator to the beginning of the flow if you still want end users to confirm their profile information.
+authenticators according to your needs. For example, you can add the Review Profile authenticator to the beginning of the flow if you still want
+end users to confirm their profile information. You can also add authentication mechanisms to this flow, forcing a user to verify his credentials. This
+would require a more complex flow, for example setting the "Automatically Set Existing User" and "Password Form" as "Required" in an "Alternative" sub-flow.

server_admin/topics/users/credentials.adoc

@@ -7,9 +7,31 @@ When viewing a user if you go to the `Credentials` tab you can manage a user's c
 .Credential Management
 image:{project_images}/user-credentials.png[]
 
-==== Changing Passwords
+The credentials are listed in a table, which has the following fields:
 
-To change a user's password, type in a new one.  A `Reset Password` button will show up that you click after you've typed everything in.
+Position::
+   The arrow buttons in this column allows you to shift the priority of the credential for the user, with the topmost credential having the highest priority.
+   This priority determines which credential will be shown first to a user in case of a choice during login. The highest priority of those available to the
+   user will be the one selected.
+Type::
+   This shows the type of the credential, for example `password` or `otp`.
+User Label::
+   This is an assignable label to recognise the credential when presented as a selection option during login. It can be set to any value to describe the
+   credential.
+Data::
+   This shows the non-confidential technical information about the credential. It is originally hidden, but you can press `Show data...` to reveal it for a
+   credential.
+Actions::
+   This column has two buttons. `Save` records the value of the User Label, while `Delete` will remove the credential.
+
+==== Creating a Password for the User
+
+If a user doesn't have a password, or if his password has been deleted, the `Set Password` section will be shown on the page.
+
+.Credential Management - Set Password
+image:{project_images}/user-credentials-set-password.png[]
+
+To create a password for a user, type in a new one. Click on the `Set Password` button after you've typed everything in.
 If the `Temporary` switch is on, this new password can only be used once and the user will be asked to change their password after they have
 logged in.
 
@@ -18,13 +40,21 @@ them to reset their password.  Choose `Update Password` from the `Reset Actions`
 set the validity of the e-mail link which defaults to the one preset in `Tokens` tab in the realm settings.
 The sent email contains a link that will bring the user to the update password screen.
 
-==== Changing OTPs
+Note that a user can only have a single credential of type password.
 
-You cannot configure One-Time Passwords for a specific user within the Admin Console.  This is the responsibility of the user.
-If the user has lost their OTP generator all you can do is disable OTP for them on the `Credentials` tab.
-If OTP is optional in your realm, the user will have to go to the User Account Management service to re-configure a new
-OTP generator. If OTP is required, then the user will be asked to re-configure a new OTP generator when they log in.
+==== Creating other credentials
+
+You cannot configure other types of credentials for a specific user within the Admin Console. This is the responsibility of the user.
+You can only delete credentials for a user on the `Credentials` tab, for example if the user has lost his OTP device, or if a credential
+has been compromised.
+
+===== Creating an OTP
+
+If OTP is conditional in your realm, the user will have to go to the User Account Management service to re-configure a new
+OTP generator. A user can set up any number of OTP credentials in this manner. If OTP is required, then the user will be asked
+to re-configure a new OTP generator when they log in.
 
 Like passwords, you can alternatively send an email to the user that will ask them to reset their OTP generator.  Choose
 `Configure OTP` in the `Reset Actions` list box and click the `Send Email` button.  The sent email
-contains a link that will bring the user to the OTP setup screen.
+contains a link that will bring the user to the OTP setup screen. You can use this method even if the user already has an OTP credential,
+and would like to set up some more.

upgrading/topics/keycloak/changes.adoc

@@ -36,6 +36,35 @@ please take a look at link:{developerguide_jsproviders_link}[{developerguide_jsp
 
 In the previous releases, developers were allowed to provide client credentials to the JavaScript adapter. For now on, this capability was *removed*, because client-side apps are not safe to keep secrets.
 
+==== Authentication flows changes
+
+We did some refactoring and improvements related to the authentication flows, which requires some attention during migration.
+
+OPTIONAL execution requirement removed::
+    Regarding migration, the most important change is removing the support for OPTIONAL requirement from authentication executions and
+    replacing it with the CONDITIONAL requirement, which allows more flexibility. The existing OPTIONAL authenticators configured in previous version will be replaced with the CONDITIONAL subflows, where particular subflow will have
+    the `Condition - User Configured` condition configured as first execution, and the previously OPTIONAL authenticator (for example `OTP Form`) as second execution.
+    From the user's point of view, the behaviour during authentication should be same as in previous version.
+
+Changes in the Java SPI::
+    There are some changes in the Java Authentication SPI and Credential Provider SPI. The interface `Authenticator` is not changed,
+    but you may be affected if you're developing more advanced authenticators, which introduce some new credential types (subclasses of `CredentialModel`).
+    There are changes on the `CredentialProvider` interface and introduction of some new interfaces like `CredentialValidator`. Also you
+    may be affected if your authenticator supported the OPTIONAL execution requirement. It is recommended to double check latest authentication
+    examples in the server development guide for more details.
+
+Freemarker template changes::
+   There are also some changes in the freemarker templates. You may be affected if you have your own theme with custom freemarker
+   templates for login forms or some account forms, especially for the forms related to OTP. It is recommended to double check changes in
+   the Freemarker templates in latest {project_name} and align your templates according to it.
+
+==== User credentials changes
+
+We added more flexibility around storing of user credentials. Among other things, every user can have multiple credentials of same
+type, for example multiple OTP credentials. There are some changes in the database schema in relation to that, however the credentials from
+previous version should be automatically updated to the new format and users should be still able to login with their passwords or OTP
+credentials set in previous version.
+
 === Migrating to 7.0.0
 
 ==== Upgrade to Wildfly 17