Recovery Authentication Codes

Recovery codes are a Second Factor Authentication (2FA) method which can be used as a backup option to avoid losing access to your account. Therefore, they can be configured or enabled in the authentication flow to give another chance to login in case the OTP or WebAuthn device is unavailable (for example your phone or yubikey are broken or lost).

Technically the recovery codes are twelve sequential one-time passwords auto-generated by Keycloak. The authentication process asks the user for the next generated code in order. When that code is introduced, it is removed and the following code will be required in the subsequent login.

The default browser flow already contains recovery codes as a 2FA sub-step, but the authenticator is disabled by default. You just need to enable it to make it available for the login. In the administration console, Authentication → Flows, select the browser flow. Under the step Browser - Conditional 2FA, OTP Form is set to Alternative, but Recovery Authentication Code Form is Disabled. Change the latter to Alternative too.

With this configuration, both alternative methods are available to login. Recovery codes can be integrated in more complex authentication flows if needed.

The administrator can force any account to setup the recovery codes credentials assigning the Recovery Authentication Codes required action to that specific user. The administrator can also enforce the action to all new users setting the action as a default action (Authentication → Required Actions → Recovery Authentication Codes). In this regard, the recovery codes are just another required action that can be used normally inside Keycloak.

Via required action or just manually clicking this credential type in the account console, the user can setup and store the codes. The twelve passwords should be saved in a secure place.

In the account console, Account Security → Signing in, the Recovery authentication codes section will appear as soon as the step is enabled in the authentication flow. Click the Set up Recovery authentication codes link to start the setup.

Keycloak generates and presents the codes. The list of passwords needs to be copied or saved by the final user. To ensure this step is done, a checkbox is displayed: I have saved these codes somewhere safe. It needs to be acknowledged to complete the setup.

Now the recovery codes are configured in the account and can be used as 2FA to login.

The list of codes can be re-generated in the account console at any time.

With the previous steps completed, the user can access the Keycloak login page. The username and password form is presented.

If OTP is also configured for the account, the OTP form is displayed for the 2FA step. But this time, the OTP application is not available, because my phone is out of battery for example. The user clicks the Try Another Way button.

The Recovery Authentication Code option is selected.

Code #1 is requested because recovery codes are used for the first time. Remember they are requested and consumed in order.

The user enters the code, clicks Sign in, and the login will be completed successfully.

The account console warns you when the recovery codes are running out. The default warning threshold is four (less than four codes remaining), but this value can be modified in the required action configuration.

Recovery Codes and OTP can be configured by the user at the same time. The Configure OTP required action has a switch to enable this feature (Authentication → Required actions). When activated, the setup for OTP enforces the user to also configure recovery codes if the account has not configure them before.

As a final comment, the setup for recovery codes is also presented when the last code is used to login. This way, the list is re-generated again when all the passwords are consumed.