Activation of OATH OTP authentication happens by enrolling an authenticator app on the end-user's mobile phone. The activation is based on the so-called shared secret. IAM creates this shared secret when establishing OATH OTP for an end-user on the IAM authentication server. The shared secret is a binary string, but is shown to the end-user as either a QR code or in the Base32 format (Loginapp). Additionally, it is possible to display the secret as HEX in the Adminapp.
During the activation process, the end-user either scans the QR code with or manually enters the digital code into the authenticator app. The codes are provided by IAM during the activation flow.
Within IAM, there can only be one shared secret per end-user.
Activating OATH OTP (by enrolling an authenticator app) can be done on several occasions:
- After receiving a hard copy activation letter including the activation QR-code.
- During the authentication flow, when the end-user is prompted to migrate to OATH OTP as second factor authentication.
- During a self-registration flow performed by a new end-user, where the end-user selects OATH OTP as an additional authentication method.
- As part of protected self-services, where the end-user has the opportunity to activate an (additional) OATH OTP authenticator app.
The activation letter can be ordered in the Adminapp, see also section "Token management" further below. To configure the other three use cases, you have to add the OATH OTP Activation Step to the respective flows. See the following instructions.
Activating OATH OTP during an authentication flow
In the authentication flow use case, the end-user will be prompted to migrate to OATH OTP as second factor authentication when logging in to your application. Proceed as follows to configure this use case:
- Go to
Loginapp >> Applications and Authentication >> <your application> >> Authentication Flow - In the Steps list, create or edit a Migration Selection Step plugin (below the Selection Step plugin for second factor selection).
- In the Migration Selection Step plugin dialog, go to the Basic Settings section. In the Available Options list, create and edit a Simple Migration Selection Option plugin, as follows:
- Display Name field: Give the plugin an easily recognizable display name, such as
Migration to OATH OTP
. - Target Auth Method field: Specify
OATH_OTP
as the target authentication of the migration. - Steps list: Create and edit an OATH OTP Activation Step plugin, as follows:
- Display Name field: Give the plugin an easily recognizable display name, such as
Activate OATH OTP
. - OATH OTP Settings field: Select the previously defined OATH OTP Settings plugin.
- Overwrite Existing Shared Secret: This checkbox specifies whether to overwrite an already existing OATH OTP shared secret associated with the respective end-user. This property can be used for two purposes: Either to create a new shared secret or to display an existing secret to register an additional device.
- If the Overwrite Existing Shared Secret property is enabled (the default), IAM will replace the existing shared secret by a new shared secret when enrolling a (new) authenticator app. As a consequence, the end-user can no longer use already activated authenticator apps based on the "old" secret. This is of use if the end-user's OATH OTP device is lost or has been stolen: It prevents third parties from illegally using the already enrolled authenticator app on the lost or stolen device.
- If the Overwrite Existing Shared Secret property is disabled, IAM will read the existing shared secret from the database and reveal it to the end-user when enrolling a new authenticator app. In this case, it is possible to continue using already activated OTP tokens (authenticator apps) based on the existing secret. This makes sense if an end-user wants to enroll an additional authenticator app in the protected self-services.
The above is only possible for authenticator apps using time-based OTP (TOTP).
For an authentication flow, we recommend keeping the Overwrite Existing Shared Secret property enabled.
- Activate your configuration.
- You have now enabled the activation of OATH OTP during the authentication flow.
Activating OATH OTP during self-registration
In the self-registration use case, the end-user can select OATH OTP as additional authentication method, when self-registering to your application. Proceed as follows to configure this use case:
- Go to
Loginapp >> Self-Registration >> <default flow> - In the Steps list of your default self-registration flow, create or edit a Selection Step for User Self-Registration plugin.
- In the Selection Step for User Self-Registration plugin dialog, go to the Basic Settings section. In the Available Options list, create and edit a Selection Option for User Self-Registration plugin, as follows.
- Display Name field: Give the plugin an easily recognizable display name, such as
OATH OTP Registration
. - Name field: Enter a name for this option (e.g.,
OATH_OTP_ACTIVATION
). - Condition field: Enter
Always True
. - Steps list:
- Create and edit an OATH OTP Activation Step plugin as described in step 6 of the previous instructions ("Activating OATH OTP during an authentication flow"). Note that the setting of the property Overwrite Existing Shared Secret has no effect in the self-registration use case: Because the respective end-user is new and has no OATH OTP account yet, IAM will always create a new OATH OTP secret.
- Create and edit a Set Authentication Method Step plugin, to set the default authentication method for the self-registering end-user. In the plugin's Basic Settings, select
OATH_OTP
as User Auth Method.
- Return to the User Self-Registration Flow plugin dialog. In the Steps list, create a User Persisting Step plugin, if it is not there yet.
- In the User Persisting Step plugin dialog, go to the Basic Settings section. In the Token Insertion Handlers list, add an OATH Token Insertion Handler plugin. Keep the default settings.
- Activate your configuration.
- You have now enabled the activation of OATH OTP during a self-registration flow.
Activating OATH OTP in protected self-services
The protected self-services use case allows activating an (additional) OATH OTP authenticator app in protected self-services. Proceed as follows to configure this use case:
- Go to
Loginapp >> Protected Self-Services >> Protected Self-Service Flows - In the Flows list, create and edit a Custom Protected Self-Service Flow plugin, as follows:
- Display Name field: Give the plugin an easily recognizable display name, such as
OATH OTP Registration Flow
. - Flow ID field: Define a unique ID for this flow, e.g.,
oath-otp-activation
. - Steps list: Create and edit an OATH OTP Activation Step plugin as described in step 6 of the instructions "Activating OATH OTP during an authentication flow" above. In the protected self-services use case, it is useful to disable the Overwrite Existing Shared Secret property, allowing the end-user to register several authenticator apps in the protected self-services, based on the same shared secret.
- All other settings: Keep the default values.
- Activate your configuration.
- You have now enabled the activation of an (additional) OATH OTP authenticator app in protected self-services.