diff --git a/server_admin/images/authentication-step-up-condition-1.png b/server_admin/images/authentication-step-up-condition-1.png new file mode 100644 index 0000000000..62ce59f14f Binary files /dev/null and b/server_admin/images/authentication-step-up-condition-1.png differ diff --git a/server_admin/images/authentication-step-up-condition-2.png b/server_admin/images/authentication-step-up-condition-2.png new file mode 100644 index 0000000000..e51c9448ac Binary files /dev/null and b/server_admin/images/authentication-step-up-condition-2.png differ diff --git a/server_admin/images/authentication-step-up-flow.png b/server_admin/images/authentication-step-up-flow.png new file mode 100644 index 0000000000..6122827128 Binary files /dev/null and b/server_admin/images/authentication-step-up-flow.png differ diff --git a/server_admin/images/client-oidc-map-acr-to-loa.png b/server_admin/images/client-oidc-map-acr-to-loa.png new file mode 100644 index 0000000000..606373f77d Binary files /dev/null and b/server_admin/images/client-oidc-map-acr-to-loa.png differ diff --git a/server_admin/topics/authentication/flows.adoc b/server_admin/topics/authentication/flows.adoc index f0a6460744..a44be21ad8 100644 --- a/server_admin/topics/authentication/flows.adoc +++ b/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 diff --git a/server_admin/topics/clients/oidc/con-advanced-settings.adoc b/server_admin/topics/clients/oidc/con-advanced-settings.adoc index 5f2deedd3b..8e81b13f0a 100644 --- a/server_admin/topics/clients/oidc/con-advanced-settings.adoc +++ b/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]. \ No newline at end of file