Documentation for AIA

closes #25569

Signed-off-by: mposolda <mposolda@gmail.com>

Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>

docs/documentation/securing_apps/topics/oidc/javascript-adapter.adoc

@@ -396,7 +396,9 @@ provider instead. More info in the link:{adminguide_link}#_client_suggested_idp[
 is for step-up authentication. Example of use `{ values: ["silver", "gold"], essential: true }`. See OpenID Connect specification
 and link:{adminguide_link}#_step-up-flow[Step-up authentication documentation] for more details.
 * acrValues - Generates the `acr_values` parameter which refers to authentication context class reference and allows clients to declare the required assurance level requirements, e.g. authentication mechanisms. See https://openid.net/specs/openid-connect-modrna-authentication-1_0.html#acr_values[Section 4. acr_values request values and level of assurance in OpenID Connect MODRNA Authentication Profile 1.0].
-* action - If value is `register` then user is redirected to registration page, if the value is `UPDATE_PASSWORD` then the user will be redirected to the reset password page (if not authenticated will send user to login page first and redirect after authenticated), otherwise to login page.
+* action - If the value is `register`, the user is redirected to the registration page. See link:{adminguide_link}#_registration-rc-client-flows[Registration requested by client section] for more details.
+If the value is `UPDATE_PASSWORD` or another supported required action, the user will be redirected to the reset password page or the other required action page. However, if the user is not authenticated, the user will be sent to the login page and redirected after authentication.
+See link:{adminguide_link}#con-aia_server_administration_guide[Application Initiated Action section] for more details.
 * locale - Sets the 'ui_locales' query param in compliance with https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest[section 3.1.2.1 of the OIDC 1.0 specification].
 * cordovaOptions - Specifies the arguments that are passed to the Cordova in-app-browser (if applicable). Options `hidden` and `location` are not affected by these arguments. All available options are defined at https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/. Example of use: `{ zoom: "no", hardwareback: "yes" }`;
 

docs/documentation/server_admin/topics/assembly-managing-users.adoc

@@ -21,6 +21,8 @@ include::users/proc-setting-required-actions.adoc[leveloffset=+3]
 include::users/proc-setting-default-required-actions.adoc[leveloffset=+3]
 include::users/proc-enabling-terms-conditions.adoc[leveloffset=+3]
 
+include::users/con-aia.adoc[leveloffset=+2]
+
 include::users/proc-searching-user.adoc[leveloffset=+2]
 
 include::users/proc-deleting-user.adoc[leveloffset=+2]

docs/documentation/server_admin/topics/authentication/flows.adoc

@@ -403,6 +403,25 @@ Note when the login request initiates a request with the `claims` parameter requ
 one of the specified levels. If it is not able to return one of the specified levels (For example if the requested level is unknown or bigger than configured conditions
 in the authentication flow), then {project_name} will throw an error.
 
+[[_registration-rc-client-flows]]
+==== Registration or Reset credentials requested by client
+
+Usually when the user is redirected to the {project_name} from client application, the `browser` flow is triggered. This flow may allow the user to <<con-user-registration_{context}, register>> in case
+that realm registration is enabled and the user clicks `Register`on the login screen. Also, if  <<enabling-forgot-password, Forget password>> is enabled for the realm, the user can
+click `Forget password` on the login screen, which triggers the `Reset credentials` flow where users can reset credentials after email address confirmation.
+
+Sometimes it can be useful for the client application to directly redirect the user to the *Registration* screen or to the *Reset credentials* flow. The resulting action will match the action of when the 
+user clicks *Register* or *Forget password* on the normal login screen. Automatic redirect to the registration or reset-credentials screen can be done as follows:
+
+* When the client wants the user to be redirected directly to the registration, the OIDC client should replace the very last snippet from the OIDC login URL path (`/auth`) with `/registrations` . So the full URL
+might be similar to the following: `https://keycloak.example.com/realms/your_realm/protocol/openid-connect/registrations`.
+
+* When the client wants a user to be redirected directly to the `Reset credentials` flow, the OIDC client should replace the very last snippet from the OIDC login URL path (`/auth`) with `/forgot-credentials` .
+
+WARNING: The preceding steps are the only supported method for a client to directly request a registration or reset-credentials flow. For security
+purposes, it is not supported and recommended for client applications to bypass OIDC/SAML flows and directly redirect to other {project_name} endpoints (such as for instance endpoints under
+`/realms/realm_name/login-actions` or `/realms/realm_name/broker`).
+
 [[_user_session_limits]]
 === User session limits
 

docs/documentation/server_admin/topics/authentication/password-policies.adoc

@@ -100,4 +100,5 @@ The current implementation uses a BloomFilter for fast and memory efficient cont
 ===== Maximum Authentication Age
 
 Specifies the maximum age of a user authentication in seconds with which the user can update a password without re-authentication. A value of `0` indicates that the user has to always re-authenticate with their current password before they can update the password.
+See <<con-aia-reauth_{context}, AIA section>> for some additional details about this policy.
 

docs/documentation/server_admin/topics/users/con-aia.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// server_admin/topics/users.adoc
+
+[id="con-aia_{context}"]
+= Application initiated actions
+
+Application initiated actions (AIA) allow client applications to request a user to perform an action on the {project_name} side. Usually, when an OIDC client application
+wants a user to log in, it redirects that user to the login URL as described in the <<con-oidc_{context}, OIDC section>>. After login, the user is redirected back to the client application.
+The user performs the actions that were required by the administrator as described in the <<proc-setting-required-actions_{context}, previous section>>
+and then is immediately redirected back to the application. However, AIA allows the client application to request some required actions from the user during login. This can be
+done even if the user is already authenticated on the client and has an active SSO session. It is triggered by adding the `kc_action` parameter to the OIDC login URL with the value containing the requested action.
+For instance `kc_action=UPDATE_PASSWORD` parameter.
+
+NOTE: The `kc_action` parameter is a {project_name} proprietary mechanism unsupported by the OIDC specification.
+
+NOTE: Application initiated actions are supported only for OIDC clients.
+
+So if AIA is used, an example flow is similar to the following:
+
+* A client application redirects the user to the OIDC login URL with the additional parameter such as `kc_action=UPDATE_PASSWORD`
+
+* There is a `browser` flow always triggered as described in the <<_authentication-flows, Authentication flows section>>. If the user was not authenticated, that user needs to authenticate as during normal login.
+In case the user was already authenticated, that user might be automatically re-authenticated by an SSO cookie without needing to actively re-authenticate and supply the credentials again. In this case, that user will be
+directly redirected to the screen with the particular action (update password in this case). However, in some cases, active re-authentication is required even if the user has an SSO
+cookie (See <<con-aia-reauth_{context}, below>> for the details).
+
+* The screen with particular action (in this case `update password`) is displayed to the user, so that user needs to perform a particular action
+
+* Then user is redirected back to the client application
+
+Note that AIA are used by the {project_name} <<_account-service, Account Console>> to request update password or to reset other credentials such as OTP or WebAuthn.
+
+WARNING: Even if the parameter `kc_action` was used, it is not sufficient to assume that the user always performs the action.  For example, a user could have manually deleted
+the `kc_action` parameter from the browser URL. Therefore, no guarantee exists that the user has an OTP for the account after the client requested `kc_action=CONFIGURE_TOTP`. If you
+want to verify that the user configured two-factor authenticator, the client application may need to check it was configured. For instance
+by checking the claims like `acr` in the tokens.
+
+[id="con-aia-reauth_{context}"]
+== Re-authentication during AIA
+
+In case the user is already authenticated due to an active SSO session, that user usually does not need to actively re-authenticate. However, if that user actively authenticated longer than five minutes ago,  
+the client can  still request re-authentication when some AIA is requested. Exceptions exist from this guideline as follows:
+
+* The action `delete_account` will always require the user to actively re-authenticate
+
+* The action `update_password` might require the user to actively re-authenticate according to the configured <<maximum-authentication-age, Maximum Authentication Age Password policy>>.
+In case the policy is not configured, it also defaults to five minutes.
+
+* If you want to use a shorter re-authentication, you can still use a parameter query parameter such as  `max_age` with the specified shorter value or eventually `prompt=login`, which will always require user to
+actively re-authenticate as described in the OIDC specification. Note that using `max_age` for a longer value than the default five minutes (or the one prescribed by password policy) is not supported.
+The `max_age` can be currently used only to make the value shorter than the default five minutes.
+
+[id="con-aia-available-actions_{context}"]
+== Available actions
+
+To see all available actions, log in to the Admin Console and go to the top right top corner to click `Realm info` -> tab `Provider info` -> Find provider `required-action` .
+But note that this can be further restricted based on what actions are enabled for your realm in the <<proc-setting-default-required-actions_{context}, Required actions tab>>.

docs/documentation/server_admin/topics/users/con-required-actions.adoc

@@ -7,6 +7,10 @@
 
 You can set the actions that a user must perform at the first login. These actions are required after the user provides credentials. After the first login, these actions are no longer required. You add required actions on the *Details* tab of that user.
 
+Some required actions are automatically triggered for the user during login even if they are not explicitly added to this user by the administrator. For example `Update password` action can be
+triggered if <<_password-policies, Password policies>> are configured in a way that the user password needs to be changed every X days. Or `verify profile`
+action can require the user to update the <<user-profile, User profile>> as long as some user attributes do not match the requirements according to the user profile configuration.
+
 The following are examples of required action types:
 
 Update Password::