Configure AZFTOTP1

You must configure the AZFTOTP1 settings for use with both TOTP and generic TOTP.

Before you begin

You must have already configured PKCS#11 tokens and AT-TLS before you configure the AZFTOTP1 settings.

About this task

Configuration data for AZFTOTP1 is stored in the RACF® database. The AZFTOTP1 configuration data include settings related to the AZFTOTP1 authentication load module.


  1. Execute AZFEXEC and choose AZFTOTP1.
  2. Provide the following:
    Table 1. AZFTOTP1 Factor Attributes
    Setting Description
    PKCS#11 Token Name The name of the PKCS#11 token to be used for cryptographic operations. You created this token in Configuring a PKCS#11 token.
    Key Label The name of the key label that is used to encrypt user registration information. The PKCS#11 key label has a limit of 32 characters. The value you specify for PKCS#11 key label is used if it already exists and is created if it does not exist.
    Use Single-key Encryption Specifies whether single-key encryption should be used for a newly-registered user. If enabled, a single factor-level TKDS encryption key is used when user registration information is encrypted. If disabled, a new TKDS object is created to hold the TOTP secret for each new enrolling user.
    Single-key encryption reduces the proliferation of TKDS encryption keys. You should use single-key encryption whenever possible.
    Important: Single-key encryption requires that all systems that share the same RACF database have the relevant PTFs for APAR PH20136. (See If enabled, new user-registration information will be unusable on systems that do not support single-key encryption. Existing user registration information will remain unchanged.
    The default is determined as follows:
    • If previous AZFTOTP1 settings exist, or exist with the value set to N, the default is N.
    • If previous AZFTOTP1 settings do not exist, or exist with the value set to Y, the default is Y.
    Realm Name Enter the realm name for your web services server. This setting is used in combination with the SAF User ID to generate a default label for a user's TOTP account. The generated label takes the form <User ID>@<Realm Name>. For example, a user with SAF User ID "USER1" provisioned with a TOTP account using the realm name of "MYREALM" would receive the default TOTP account label of "USER1@MYREALM".

    If you intend to provision TOTP accounts from systems controlled by separate enterprise security manager (ESM) databases, set the realm name differently across those various ESM databases. This can help to ensure that a user enrolled for TOTP across multiple environments will be able to distinguish between their various TOTP accounts at a glance, even within the same TOTP client application running on their device.

    Initial Trace Level The initial trace level for AZFTOTP1 web services. Valid values are 0 through 3, where the higher number increases the level of verbosity. The default is zero.
    Digest Algorithm Choose the default digest algorithm. AZFTOTP1 uses the digest algorithm, the shared secret key, and the current time to generate the TOTP value. Possible values are SHA1, SHA256, SHA384, and SHA512. The default is SHA256.
    Token Code Length Choose the number of digits in the generated token. Possible values are 6, 7, and 8. The default is 8.
    Token Period Choose the time (in seconds) between changes in value for the token. This number determines how long a one-time password is active before the next one-time password generates. Possible values are 15, 30, and 60. The default is 30 seconds.
    Window Enter the skew intervals of the algorithm. The skew intervals consider any possible synchronization delay between the server and the client that generates the one-time password. For example, a skew interval of 2 means a one-time password in up to two intervals in the past, or two in the future, are also valid. If it is interval 563, and intervals are 30 seconds, then one-time passwords for intervals 561- 565 are computed and checked against within a range of 2.5 minutes. The maximum is 10.
    Initial Trace Level The trace level used for tracing events within the AZFTOTP1 plug-in. Valid values are 0 through 3, where the higher number increases the level of verbosity. The default is zero.
    Start of changeSuspension ThresholdEnd of change Start of changeSee the note following the table for important information before you set Suspension Threshold.

    The Suspension Threshold limits the number of times a user consecutively fails to provide a valid TOTP code. Valid values are 0 through 255.

    Note: The Suspension Threshold setting is separate and distinct from a RACF revoked status. The Suspension Threshold setting is most useful in IBM® MFA Out-of-Band authentication to prevent brute force attacks. To prevent any conflict or user confusion with the RACF revoke count for in-band authentication, you should set the Suspension Threshold setting to a number significantly higher than the RACF revoke count.
    The default is determined as follows:Start of change
    • If a previous setting does not exist, Suspension Threshold is enabled by default, with a default setting of 100.
    • If a previous setting exists, the existing value is maintained.
    End of change

    A value of 0 indicates that brute force protection is not enabled for the AZFTOTP1 authentication method. Any numeric value greater than zero is treated as the number of times a user may consecutively fail to provide a valid TOTP code. If a user fails exactly this number of times and then provides a valid TOTP code:

    • Authentication succeeds.
    • Their failure count is reset to zero.
    If the user fails more than this number of times:
    • Authentication fails.
    • Their SUSPENDED tag is set to YES
    • Their failure count is reset to zero.
    End of change
    Important: The Suspension Threshold setting is incompatible with versions of IBM MFA prior to Version 2.0. Do not enable this setting unless all of the IBM MFA systems have the relevant PTFs for APAR PH20136. (See
    If you do inadvertently set Suspension Threshold for an IBM MFA version prior to 2.0, you must do the following:
    1. Set Suspension Threshold to zero and restart the IBM MFA started task.
    2. For each user already provisioned for TOTP authentication, delete the SUSPENDED and FAILCOUNT tags to remove them from the user's stored IBM MFA data:
      If invoked on a system running a previous release, this command generates a warning because the SUSPENDED and FAILCOUNT tags are not recognized. The tags are deleted and you can ignore this warning.
  3. See Next Steps: Configure IBM MFA Compound In-Band for information about configuring IBM MFA Compound In-Band.
The PKCS#11 token name you specify on this panel is used when creating an AZFTOTP1 user session-object when a user registers. If you change the PKCS#11 token name or key label values, all user registrations will become inaccessible, and users must re-register.