Allowing users to self-enroll their tokens

Allowing users to self-enroll their YubiKey token on the web enrollment page lets you activate users for Yubico OTP. Use the self-enrollment process when you do not need to control which user has which specific YubiKey token. Yubico OTP is the only supported Yubico format.

Before you begin

Note: As described in the YubiKey documentation, the Yubico OTP generated by the YubiKey token represents a single authentication factor. It is recommended that you use Yubico OTP authentication together with another authentication method.

About this task

The azfyubi1_ingest command has the parameters shown in Table 1.
Table 1. azfyubi1_ingest Parameters
Parameter Description
SCAN Iterates over the entire input file, attempts to validate each line as a Yubico format token descriptor, and determines whether a IBM® MFA record already exists for the parsed token Public ID. Must be uppercase.
INGEST mode without COMMIT Includes the SCAN behavior, and indicates which IBM MFA record additions would have been made. Must be uppercase.
INGEST mode with COMMIT Includes the SCAN behavior, and indicates which IBM MFA record additions were made. Must be uppercase.
CLEAN mode without COMMIT Includes the SCAN behavior, and indicates which IBM MFA record deletions would have been made. Must be uppercase.
CLEAN mode with COMMIT Includes the SCAN behavior, and indicates which IBM MFA record deletions were made. Must be uppercase.

Procedure

  1. Enable Yubico enrollment services must be enabled, as described in Configuring server options.
  2. Add the /opt/IBM/MFA/bin directory to your PATH.
    export PATH=/opt/IBM/MFA/bin:${PATH}
  3. Run the ./azfyubi1_ingest program with the SCAN parameter and check for errors.
    Note: The output is for example purposes and contains only one CSV record.

    The message AZFDB:PubId not found is informational and indicates that the public IDs of the Yubikey tokens are not already in the IBM MFA database.

    ./azfyubi1_ingest yubikey.csv SCAN
    Proceeding in SCAN mode
    2019-08-08-12-58-39.410906 AZFDB:PubId not found
    AZF Yubico OTP Settings:
      PKCS#11 Token Name: azf
      PKCS#11 Key Label:  AZFYUBI1.AESKEY
    
    Ingest Utility Results:
      Valid CSV records in input file:       1
        Those with PubID already in DB:    0
      Number of DB records written:        0
      Number of DB records deleted:        0
    Total input file lines processed: 1
    
  4. Run the ./azfyubi1_ingest program with the INGEST parameter without the COMMIT parameter and check for errors.
    ./azfyubi1_ingest yubikey.csv INGEST
    Proceeding in INGEST mode with committing OFF
    2019-08-08-13-13-23.345807 AZFDB:PubId not found
    Skipped attempt to create a new DB record for token with public ID vvjkeehkbkuj
    AZF Yubico OTP Settings:
      PKCS#11 Token Name: azf
      PKCS#11 Key Label:  AZFYUBI1.AESKEY
    
    Ingest Utility Results:
      Valid CSV records in input file:       1
        Those with PubID already in DB:    0
      Number of DB records written:        0
      Number of DB records deleted:        0
    Total input file lines processed: 1
    
  5. Run the ./azfyubi1_ingest program with the INGEST parameter with the COMMIT parameter.
    ./azfyubi1_ingest yubikey.csv INGEST
    COMMITProceeding in INGEST mode with committing ON
    2019-08-08-13-15-59.207569 AZFDB:PubId not found
    Added a new DB record for token with public ID vvjkeehkbkuj
    AZF Yubico OTP Settings:
      PKCS#11 Token Name: azf
      PKCS#11 Key Label:  AZFYUBI1.AESKEY
    
    Ingest Utility Results:
      Valid CSV records in input file:       1
        Those with PubID already in DB:    0
      Number of DB records written:        1
      Number of DB records deleted:        0
    Total input file lines processed: 1
    
  6. Create an input file in the following format:
    Note: The bulk provisioning feature is described in Provisioning users in bulk for IBM MFA. The Yubico OTP-specific steps are summarized here for your convenience.
    user-name policy-name AZFYUBI1

    For example:

    USERA YUBI AZFYUBI1
    USERB YUBI AZFYUBI1
    USERC YUBI AZFYUBI1
    USERD YUBI AZFYUBI1
    USERE YUBI AZFYUBI1
    USERF YUBI AZFYUBI1
    USERG YUBI AZFYUBI1 ADD USERNAME=USERG
    
    In this example, USERA through USERF are existing IBM MFA users. USERG is a new user being added to the IBM MFA database.
  7. Run the azfbulk program without the COMMIT parameter.
    ./azfbulk input-file
  8. Check the resulting azfprov1.sh files.
    Important: azfbulk generates a azfprov2.sh file that is not needed or functional in this workflow. Do not run the azfprov2.sh file.
  9. Correct any errors in your input file and re-run the azfbulk command.
  10. Run the azfbulk program with the COMMIT parameter.
    ./azfbulk input-file COMMIT
  11. Run the azfprov1.sh shell script.
    sh azfprov1.sh
  12. Instruct the user to insert the YubiKey into a USB port on their Windows system.
  13. Instruct the user to launch the YubiKey enrollment page:
    https://server-name:port/AZFYUBI1/enroll
    Instruct the user to provide their user name and MFA password, and tap the YubiKey to generate an OTP in the YubiKey OTP field. The MFA password is a special password that allows the user to log in to the IBM MFA server for IBM MFA-specific actions.
    The user receives a message that the YubiKey was associated with their account.
    Information
    Your YubiKey device was successfully associated with your account.
  14. Verify the provisioned users in the IBM MFA GUI.
    Note that the authentication method state changes to ACTIVE.
  15. The user must now use the YubiKey token to log in.
  16. Inform users to use the IBM MFA Out-of-Band web server login page that you configured, such as
    https://server:port/mfa/policy-name
    where port is the server authentication port you configured and policy-name is the policy the user must use. You may want to have the user bookmark this URL.
  17. When the user visits the IBM MFA Out-of-Band web login page,
    user-specific information about the methods required for the user to log in is displayed.