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
-
Enable Yubico enrollment services must be enabled, as described in Configuring server options.
-
Add the /opt/IBM/MFA/bin directory to your PATH.
export PATH=/opt/IBM/MFA/bin:${PATH}
-
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
-
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
-
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
-
Create an input file in the following format:
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.
-
Run the azfbulk program without the COMMIT
parameter.
-
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.
-
Correct any errors in your input file and re-run the azfbulk command.
-
Run the azfbulk program with the COMMIT
parameter.
./azfbulk input-file COMMIT
-
Run the azfprov1.sh shell script.
-
Instruct the user to insert the YubiKey into a USB port on their Windows system.
-
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.
-
Verify the provisioned users in the IBM MFA GUI.
Note that the authentication method state changes to
ACTIVE.
-
The user must now use the YubiKey token to log in.
-
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.
-
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.