mirror of
https://github.com/keycloak/keycloak.git
synced 2026-04-23 15:17:16 -04:00
236d2f9f62
closes #41836 Signed-off-by: Niko Köbler <niko@n-k.de> Signed-off-by: Alexander Schwartz <aschwart@redhat.com> Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
55 lines
3.9 KiB
Text
55 lines
3.9 KiB
Text
|
|
[[_recovery-codes]]
|
|
=== Recovery Codes
|
|
|
|
The Recovery Codes are a number of sequential one-time passwords (currently 12) auto-generated by {project_name}. The codes can be used as a 2nd Factor Authentication (2FA) by adding the `Recovery Authentication Code Form` authenticator to your authentication flow. When configured in the flow, {project_name} asks the user for the next generated code in order. When the current code is introduced by the user, it is removed and the next code will be required for the next login.
|
|
|
|
Due to its nature, the Recovery Codes work normally as a backup for another 2FA methods. They can complement the `OTP Form` or the `WebAuthn Authenticator` to give a backing way to log inside {project_name}, for example, if the software or hardware device used for the previous 2FA methods is broken or unavailable.
|
|
|
|
You can configure the `Configure OTP` required action to ask for recovery codes automatically by enabling *Add recovery codes*.
|
|
|
|
==== Check Recovery Codes required action is enabled
|
|
|
|
Check the Recovery Codes action is enabled in {project_name}:
|
|
|
|
. Click *Authentication* in the menu.
|
|
. Click the *Required Actions* tab.
|
|
. Ensure the *Recovery Authentication Codes* switch *Enabled* is set to *On*.
|
|
|
|
Toggle the *Default Action* switch to *On* if you want all the new users to register their Recovery Codes credentials in the first login.
|
|
|
|
==== Configure the Recovery Codes required action
|
|
|
|
From the *Required Actions* tab of the admin console, you have the option to configure the *Recovery Authentication Codes* required action. So far, there is a configuration option
|
|
*Warning Threshold* available. When a user has a smaller amount of remaining recovery codes on his account than the value configured here, account console will show warning to the user, which will
|
|
recommend them to set up a new set of recovery codes. The warning displayed to the user may look similar to this:
|
|
|
|
.Recovery Codes Account console warning
|
|
image:images/recovery-codes-account-console-warn.png[Recovery Codes Account console warning]
|
|
|
|
==== Adding Recovery Codes to the browser flow
|
|
|
|
The following procedure adds the `Recovery Authentication Code Form` as an alternative way of login in the default *Browser* flow.
|
|
|
|
. Click *Authentication* in the realm menu.
|
|
. Click the *Browser* flow.
|
|
. Locate the execution *Recovery Authentication Code Form* inside the *Browser - Conditional 2FA* sub-flow.
|
|
. Change the _requirement_ from _Disabled_ to _Alternative_ for that execution.
|
|
+
|
|
.Recovery Codes Browser flow
|
|
image:images/recovery-codes-browser-flow.png[Recovery Codes Browser flow]
|
|
+
|
|
With this configuration, both 2FA authenticators (`OTP Form` and `Recovery Authentication Code Form`) are alternate ways to log into {project_name}. If the user has configured both credential types, the credential with the highest priority will be displayed by default, but the *Try Another Way* option will appear so that the user has the alternative methods to log in.
|
|
|
|
You can see more examples of 2FA configurations in <<twofa-conditional-workflow-examples>>.
|
|
|
|
==== Creating the Recovery Codes credential
|
|
|
|
Once the Recovery Codes required action is enabled and the credential type is managed in the flow, users can request to create their own codes. The action is just another <<con-required-actions_server_administration_guide,required action>> that can be used in {project_name} (directly called by the user by using the Account Console or assigned by an administrator by using the Admin Console).
|
|
|
|
The required action, when executed, generates the list of codes and presents it to the user. The action offers to print, download, or copy the list of codes to help the user to store them is a safe place. In order to complete the setup, the checkbox *I have saved these codes somewhere safe* should be previously checked.
|
|
|
|
.Recovery Authentication Codes setup page
|
|
image:images/recovery-codes-setup.png[Recovery Authentication Codes setup page]
|
|
|
|
The Recovery Codes can be re-created at any moment.
|