Documentation for Delete Credential action and related changes (#31719)

closes #31718


Signed-off-by: mposolda <mposolda@gmail.com>
Signed-off-by: Marek Posolda <mposolda@gmail.com>
Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>
This commit is contained in:
Marek Posolda 2024-07-30 10:05:14 +02:00 committed by GitHub
parent a79761a447
commit 5b52117351
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 30 additions and 4 deletions

View file

@ -6,7 +6,7 @@ With this workflow, users will have to use an UPDATE_EMAIL action to change thei
The action is associated with a single email input form. If the realm has email verification disabled, this action will allow to update the email without verification. If the realm has email verification enabled, the action will send an email update action token to the new email address without changing the account email. Only the action token triggering will complete the email update.
Applications are able to send their users to the email update form by leveraging UPDATE_EMAIL as an AIA (Application Initiated Action).
Applications are able to send their users to the email update form by leveraging UPDATE_EMAIL as an <<con-aia_{context},AIA (Application Initiated Action)>>.
:tech_feature_name: UpdateEmail
:tech_feature_id: update-email

View file

@ -39,18 +39,35 @@ 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,
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.
In case the policy is not configured, it is also possible to configure it on the required action itself in the <<proc-setting-default-required-actions_{context}, Required actions tab>>
when configuring the particular required action. If the policy is not configured in any of those places, it 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.
* If <<_step-up-flow,Step-up authentication>> is enabled and the action is to add or delete a credential, authentication is required with the level corresponding
to the given credential. This requirement exists in case the user already has the credential of the particular level. For example, if `otp` and `webauthn` are configured in the authentication flow as 2nd-factor authenticators
(both in the authentication flow at level 2) and the user already has a 2nd-factor credential (`otp` or `webauthn` in this case), the user is required to authenticate with an existing 2nd-factor credential to add another 2nd-level credential.
In the same manner, deleting an existing 2nd-factor credential (`otp` or `webauthn` in this case), authentication with an existing 2nd-factor level credential is required. The requirement exists for security reasons.
[id="con-aia-parameterized_{context}"]
== Parameterized AIA
Some AIA can require the parameter to be sent together with the action name. For instance, the `Delete Credential` action can be triggered only by AIA and it requires a parameter to be sent together with the name
of the action, which points to the ID of the removed credential. So the URL for this example would be `kc_action=delete_credential:ce1008ac-f811-427f-825a-c0b878d1c24b`. In this case, the
part after the colon character (`ce1008ac-f811-427f-825a-c0b878d1c24b`) contains the ID of the credential of the particular user, which is to be deleted. The `Delete Credential` action
displays the confirmation screen where the user can confirm agreement to delete the credential.
NOTE: The <<_account-service,{project_name} Account Console>> typically uses the `Delete Credential` action when deleting a 2nd-factor credential. You can check the Account Console for examples if you want
to use this action directly from your own applications. However, relying on the Account Console is best instead of managing credentials from your own applications.
[id="con-aia-available-actions_{context}"]
== Available actions

View file

@ -13,7 +13,7 @@ action can require the user to update the <<user-profile, User profile>> as long
The following are examples of required action types:
Update Password::
Update Password::
The user must change their password.
Configure OTP::
@ -25,3 +25,7 @@ Verify Email::
Update Profile::
The user must update profile information, such as name, address, email, and phone number.
NOTE: Some actions do not makes sense to be added to the user account directly. For example, the `Update User Locale` is a helper action to handle some localization related parameters. Another
example is the `Delete Credential` action, which is supposed to be triggered as a <<con-aia-parameterized_{context}, Parameterized AIA>>. Regarding this one, if the administrator wants to delete the credential of some
user, that administrator can do it directly in the Admin Console. The `Delete Credential` action is dedicated to be used for example by the <<_account-service,{project_name} Account Console>>.

View file

@ -22,3 +22,8 @@ Because of security concerns, the redirect URI verification now performs a exact
The full wildcard `*` can still be used as a valid redirect in development for http(s) URIs with those characteristics. In production environments a exact valid redirect URI without wildcard needs to be configured for any URI of that type.
Please note that wildcard valid redirect URIs are not recommended for production and not covered by the OAuth 2.0 specification.
= Deprecated Account REST endpoint for removing credential
The Account REST endpoint for removing the credential of the user is deprecated. Starting at this version, the Account Console no longer uses this endpoint. It is replaced by the `Delete Credential` application-initiated
action, which is triggered by the Account Console when a user want to remove the credential of a user.