Recovery codes documentation (#38407)

Closes #30702

Signed-off-by: rmartinc <rmartinc@redhat.com>


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

docs/documentation/server_admin/topics/authentication/recovery-codes.adoc

@@ -1,9 +1,59 @@
 [[_recovery-codes]]
 
-=== Recovery Codes (RecoveryCodes)
+=== Recovery Codes
 
-You can configure Recovery codes for two-factor authentication by adding 'Recovery Authentication Code Form' as a two-factor authenticator to your authentication flow. For an example of configuring this authenticator, see xref:webauthn_{context}[WebAuthn].
+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.
 
 :tech_feature_name: RecoveryCodes
 :tech_feature_id: recovery-codes
 include::../templates/techpreview.adoc[]
+
+==== 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.
+
+==== 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 <<2fa-conditional-workflow-examples, 2FA 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.