[[_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.

==== Enable Recovery Codes required action

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 user has 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 him to setup 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.
. Select *Duplicate* from the *Action list* to make a copy of the built-in *Browser* flow.
+
For example enter *Recovery Codes Browser* as the name of the copy.
. Click *Duplicate*.
. In the flow *Recovery Codes Browser Browser - Conditional OTP*, click the *Add* (*+*) button and select *Add Execution*.
. Filter to find the *Recovery Authentication Code Form* and *Add* the execution.
. Set requirement to *Alternative* for the new step.
. Set requirement to *Alternative* for the *OTP Form* too.
+
.Recovery Codes Browser flow
image:images/recovery-codes-browser-flow.png[Recovery Codes Browser flow]
+
. Click the *Action* menu at the top of the screen.
. Select *Bind flow* from the drop-down list.
. Select *Browser flow* from the drop-down list to setup this new flow as the default flow for the realm.
. Click *Save*.

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 `OTP Form` will be displayed by default, but another option *Try Another Way* will be available that allows to select the *Recovery Authentication Code* to login.

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.
