KEYCLOAK-847 Add documentation for the step-up mechanism

KEYCLOAK-847 Changes after Review


Add implications about different acr inputs

server_admin/topics/authentication/flows.adoc

@@ -171,7 +171,7 @@ To illustrate the creation of flows, this section describes creating an advanced
 .The common part with the browser flow
 image:images/Passwordless-browser-login-common.png[]
 +
-. Click *Actions for the *Forms* execution.
+. Click *Actions* for the *Forms* execution.
 . Select *Add execution*.
 . Select *Username Form* from the drop-down list.
 . Click *Save*.
@@ -235,6 +235,136 @@ Creating an advanced flow such as this can have side effects. For example, if yo
 * In the *Bindings* menu, change the reset credential flow from *Reset Credentials* to *Reset Credentials for password-less*
 ====
 
+[[_step-up-flow]]
+==== Creating a browser login flow with step-up mechanism
+
+This section describes how to create advanced browser login flow using the step-up mechanism. The purpose of step-up authentication is to allow access to clients or resources based on a specific authentication level of a user.
+
+.Procedure
+. Click *Authentication* in the menu.
+. Click the *Flows* tab.
+. Click *New*.
+. Enter `Browser Incl Step up Mechanism` as an alias.
+. Click *Save*.
+. Click *Add execution*.
+. Select *Cookie* from the item list. 
+. Click *Save*.
+. Click *Alternative* for the *Cookie* authentication type to set its requirement to alternative.
+. Click *Add flow*.
+. Enter *Auth Flow* as an alias.
+. Click *Save*.
+. Click *Alternative* for the *Auth Flow* authentication type to set its requirement to alternative.
+
+Now you configure the flow for the first authentication level.
+
+. Click *Actions* for the *Auth Flow*.
+. Click *Add flow*.
+. Enter `1st Condition Flow` as an alias.
+. Click *Save*.
+. Click *Conditional* for the *1st Condition Flow* authentication type to set its requirement to conditional.
+. Click *Actions* for the *1st Condition Flow*.
+. Click *Add execution*.
+. Select *Conditional - Level Of Authentication* from the item list.
+. Click *Save*.
+. Click *Required* for the *Conditional - Level Of Authentication* authentication type to set its requirement to required.
+. Click *Actions* for the *Conditional - Level Of Authentication*.
+. Click *Config*.
+. Enter `Level 1` as an alias.
+. Enter `1` for the Level of Authentication (LoA).
+. Set Store LoA in user session *ON*.
+. Click *Save*
++
+.Configure the condition for the first authentication level
+image:images/authentication-step-up-condition-1.png[]
+
+. Click *Actions* for the *1st Condition Flow*.
+. Click *Add execution*.
+. Select *Username Password Form* from the item list.
+. Click *Save*.
+. Click *Required* for the *Username Password Form* authentication type to set its requirement to required.
+
+Now you configure the flow for the second authentication level.
+
+. Click *Actions* for the *Auth Flow*.
+. Click *Add flow*.
+. Enter `2nd Condition Flow` as an alias.
+. Click *Save*.
+. Click *Conditional* for the *2nd Condition Flow* authentication type to set its requirement to conditional.
+. Click *Actions* for the *2nd Condition Flow*.
+. Click *Add execution*.
+. Select *Conditional - Level Of Authentication* from the item list.
+. Click *Save*.
+. Click *Required* for the *Conditional - Level Of Authentication* authentication type to set its requirement to required.
+. Click *Actions* for the *Conditional - Level Of Authentication*.
+. Click *Config*.
+. Enter `Level 2` as an alias.
+. Enter `2` for the Level of Authentication (LoA).
+. Set Store LoA in user session *OFF*.
+. Click *Save*
++
+.Configure the condition for the second authentication level
+image:images/authentication-step-up-condition-2.png[]
+
+. Click *Actions* for the *2nd Condition Flow*.
+. Click *Add execution*.
+. Select *OTP Form* from the item list.
+. Click *Save*.
+. Click *Required* for the *OTP Form* authentication type to set its requirement to required.
+
+Finally, change the bindings.
+
+. Click the *Bindings* tab.
+. Click the *Browser Flow* item list.
+. Select *Browser Incl Step up Mechanism* from the item list. 
+. Click *Save*.
+
+.Browser login with step-up mechanism
+image:images/authentication-step-up-flow.png[]
+
+.Request a certain authentication level
+To use the step-up mechanism, you have to specify a requested level of authentication (LoA) in your authentication request. The claims parameter is used for this purpose:
+
+[source]
+----
+https://{DOMAIN}/auth/realms/{REALMNAME}/protocol/openid-connect/auth?client_id={CLIENT-ID}&redirect_uri={REDIRECT-URI}&scope=openid&response_type=code&response_mode=query&nonce=exg16fxdjcu&claims=%7B%22id_token%22%3A%7B%22acr%22%3A%7B%22essential%22%3Atrue%2C%22values%22%3A%5B%22gold%22%5D%7D%7D%7D
+----
+
+The claims parameter is specified in a JSON representation:
+[source]
+----
+claims= {
+            "id_token": {
+                "acr": {
+                    "essential": true,
+                    "values": ["gold"]
+                }
+            }
+        }
+----
+
+NOTE: To request the acr_vale as text (such as `gold`) instead of a numeric value, you have to configure the mapping between the ACR and the LoA at the client level. For configuration see <<_mapping-acr-to-loa,ACR to LoA Mapping>>)
+
+For more details see the https://openid.net/specs/openid-connect-core-1_0.html#acrSemantics[official OIDC specification].
+
+.Flow logic 
+
+The logic for the previous configured authentication flow is as follows: +
+If a client request a high authentication level, meaning Level of Authentication 2 (LoA 2), a user has to perform full 2-factor authentication: Username/Password + OTP. However, if a user already has a session in Keycloak, that was logged in with username and password (LoA 1), the user is only asked for the second authenticaton factor (OTP). 
+
+The *option in the condition to store the achieved LoA in the user session* determines wheather the user will be asked to present the authentication factor again during a subsequent authentication. If true, the user will not be re-authenticated with this level during subsequent authentication. If false, it means that subsequent authentications will re-authentication with that level again. This is useful for operations that require higher security in the application (e.g. send payment) and always require authentication with the specific level.
+
+.Implications about possible acr inputs in authentication request
+[cols="2",options="header"]
+|===
+| Authentication Request | Implication 
+| *No acr claim* is requested | Minimum authentication  (*1st Condition Flow*) is executed
+| *No essential claim* is requested in the acr claim | Default is *false*
+| *Unknown acr* value is requested | If essential false, minimum authentication is executed. If essential true, the outcome is a failed authentication attempt
+| User is re-authenticated via a *cookie* | Acr value in access token und ID token is `0`
+|===
+
+NOTE: A conflict situation may arise when an admin specifies several flows, sets different LoA levels to each, and assigns the flows to different clients. However, the rule is always the same: if a user has a certain level, it needs only have that level to connect to a client. It's up to the admin to make sure that the LoA is coherent.
+
 ifeval::[{project_community}==true]
 === Script Authenticator
 

server_admin/topics/clients/oidc/con-advanced-settings.adoc

@@ -88,3 +88,13 @@ The procedure to select the algorithm is:
 . Open the client's *Settings* tab.
 . Open *Fine Grain OpenID Connect Configuration*.
 . Select the algorithm from *ID Token Encryption Content Encryption Algorithm* pulldown menu.
+
+[[_mapping-acr-to-loa]]
+*ACR to Level of Authentication (LoA) Mapping*
+
+In the advanced settings of a client, you can define which `Authentication Context Class Reference (ACR)` value is mapped to which `Level of Authentication (LoA)`. The ACR can be any value, whereas the LoA must be numeric.
+The acr claim in also included in the access token and ID token.
+
+image:images/client-oidc-map-acr-to-loa.png[alt="ACR to LoA mapping"]
+
+For further details see  <<_step-up-flow,Step-up Authentication>> and  https://openid.net/specs/openid-connect-core-1_0.html#acrSemantics[the offical OIDC specification].