Access Management 7.3.1

Upgrade device recovery codes

This section explains how to upgrade to AM 6.5 and later if you are providing the ability for ForgeRock Authenticator users to access and view device recovery codes.

AM versions earlier than 6.5 do not encrypt the recovery codes stored alongside registered push and OATH devices. This allows the codes to be viewed by users at any time in their dashboard page. However storing credentials in plain text is considered a potential security risk, and from AM 6.5 onwards the recovery codes are displayed once, and then stored in a one-way encryption format, meaning they can never be viewed after their initial display.

After upgrading to AM 6.5 or later, when a user accesses their dashboard page, the stored recovery codes for each registered device will be one-way encrypted, meaning existing codes can no longer be displayed to the user.

This DOES NOT affect the ability to use the existing recovery codes, only the ability to display them in plain text to the user.

If you do not want to encrypt the recovery codes, and therefore retain the ability to show the codes to the user when requested, you can start AM with a Java property, as follows:

Prevent AM from encrypting device recovery codes

Perform these steps to prevent AM 6.5 and later from encrypting device recovery codes.

It is STRONGLY recommended that you encrypt recovery codes.

  1. Locate or create the environment settings script for the container in which AM will run.

    For example, the environment settings script for Apache Tomcat is located in /path/to/tomcat/bin/, and should be named setenv.bat (Windows) or setenv.sh (Unix).

  2. In the relevant environment settings script, add the org.forgerock.openam.devices.recovery.use_insecure_storage=true property to the CATALINA_OPTS variable.

    For example:

    export CATALINA_OPTS="$CATALINA_OPTS -Dorg.forgerock.openam.devices.recovery.use_insecure_storage=true"

    For containers other than Apache Tomcat, perform an analogous step to add the Java option to the scripts used to startup the AM instance.

  3. Start the container in the usual manner.

    For example, ./startup.sh.

    AM will not encrypt device recovery codes when created, or when first accessed. When preventing AM from encrypting the stored recovery codes, be aware of the following points:

    • Users will only see registered devices on their dashboard that are of the same type that they have used to authenticate.

      For example, if they authenticated using a registered OATH device, they will not see any registered push or WebAuthn devices on their dashboard. This is to prevent users being able to see recovery codes for devices that they did not authenticate with.

    • The option to view the recovery codes for a device has been removed from the user interface.

      However, the recovery codes are returned in the JSON response when querying the /devices/2fa/ endpoint. You will need to provide a customized user interface to display these codes.

    • If the container in which AM is running is ever started without the org.forgerock.openam.devices.recovery.use_insecure_storage=true property, a query to any of the /devices/2fa/ endpoints will cause AM to one-way encrypt the recovery codes.