IBM Security Z Security

IBM Z Multi-Factor Authentication (MFA) version 2.0 supports Yubico One-Time Password (OTP) as an authentication factor.  Yubico OTP is implemented by Yubico's "YubiKey" hardware security tokens.

Which YubiKey?

Yubico OTP is implemented by most, but not all YubiKeys.  If you have an existing YubiKey, or you are considering purchasing a YubiKey to use with MFA, make sure the YubiKey implements Yubico OTP by referring to https://www.yubico.com/products/identifying-your-yubikey/

Any YubiKey that lists "Yubico OTP" as one of its "Primary Functions" can be used with MFA.

Configuring the YubiKey

Current generation YubiKeys that support Yubico OTP have two "slots".  The first slot is configured at the factory and the AES key for this slot is already defined to Yubico's "YubiCloud" cloud-based authentication service.  We recommend that you configure slot 2 for use with MFA, so slot 1 remains pre-configured for use with the YubiCloud service.

To configure slot 2 of our YubiKey, we downloaded and installed the YubiKey Personalization Tool on our workstation.  This tool can be downloaded from https://www.yubico.com/products/services-software/download/yubikey-personalization-tools/

After plugging our YubiKey into a USB port and launching the YubiKey Personalization Tool, we selected the "Settings" tab to ensure that the "Logging Settings" have "Log configuration output" checked and "Yubico format" selected in the drop-down box:


Then we selected the "Yubico OTP" tab and pressed the "Quick" button:


Then we selected "Configuration Slot 2" and pressed the "Write Configuration" button:


Then we saved the configuration CSV file to our workstation by pressing the "Save" button of the "File Save" dialog.  We made a note of the name and location of this file, as we will need it later.

At this point, our YubiKey is ready to go, but we made a couple of additional tweaks for convenience.  First, the YubiKey appears to the workstation as a USB keyboard.  When you press the button on the YubiKey, it types a unique OTP, then presses ENTER.  Because we want to use "in-band" authentication, with both the Yubico OTP and our RACF password, we want to stop the YubiKey from pressing ENTER after it types out the OTP.  To achieve this, we returned to the "Settings" tab in the YubiKey Personalization Tool and pressed the "Enter" button in the "Output Format" section, so it changed from blue (i.e. on) to grey (i.e. off):


Then we pressed the "Update Settings..." button at the bottom of the panel.  On the "Update YubiKey Settings" panel, we selected "Configuration Slot 2" then pressed the "Update" button:


There is no need to save the configuration again, so we cancelled the "Save" dialog that is displayed when the "Update" button is pressed.

For the YubiKey to produce the "slot 2" OTP, it is necessary to press and hold the YubiKey's button for more than 2 seconds.  A "short press of the YubiKey's button produces the slot 1 OTP.  Since we are going to use our YubiKey predominantly with MFA, we pressed the "Swap" button on the "Update YubiKey Settings" panel, to swap the slot configurations.

Again, there is no need to save the configuration, so we cancelled the "Save" dialog that is displayed when the "Swap" button is pressed.

At this point, we exited the YubiKey Personalization Tool and started a Windows "Notepad" session, to test the output from the YubiKey.  Doing two "short presses" of the YubiKey button produced two 44-character OTPs in succession, with no "line feed" in between:



Configure MFA

MFA is already installed and configured on our system and we have previously defined a PKCS#11 token record to hold the secret keys required by some MFA factors.

We started configuring YubiKey support by defining the necessary profiles to RACF for the AZFYUBI1 factor, using the following TSO commands:

RDEFINE MFADEF FACTOR.AZFYUBI1 UACC(NONE)
SETROPTS RACLIST(MFADEF) REFRESH
RDEFINE FACILITY IRR.RFACTOR.MFADEF.AZFYUBI1 UACC(NONE)
PERMIT IRR.RFACTOR.MFADEF.AZFYUBI1 CLASS(FACILITY) ID(admin_user) ACCESS(ALTER)
SETROPTS RACLIST(FACILITY) REFRESH​

Then we invoked the MFA administration application, AZFEXEC, from ISPF and selected option 11.  We entered the name of the existing PKCS#11 token record and a new key label for the AES key to be used to protect YubiKey information.  We enabled "Compound In-band Authentication" and set the "Initial Trace Level" to 3, to assist with diagnosing any problems.  We can set this to a lower value later, once YubiKey authentication is working as expected.


We pressed PF3 then ENTER to save the configuration, then we pressed ENTER to exit from AZFEXEC.

Now we stopped and started the AZF#IN00 started task to pick up these configuration changes.  We examined the started task's job log after the restart to ensure that the AZFYUBI1 factor initialized successfully.  The job log showed:

AZF2109I Authenticator initialized : entry 0x1FC5C098, name AZFYUBI1 (strong)​

Turn on Passphrase Support

Because we want to use MFA compound in-band authentication, we need all logon panels in our system (e.g. TSO, CICS, IMS, session manager) to support long passwords or passphrases.

As an example, we implemented passphrases for TSO by adding the following command to our IKJTSO00 PARMLIB member:

LOGON PASSPHRASE(ON)​

Then we activated the change by issuing the following MVS operator command (Note: this will change the TSO logon panel for all users of the LPAR):

SET IKJTSO=00​

Provision a RACF User

We logged on to z/OS UNIX with our MFA administrator signon, which also has RACF "SPECIAL" authority.  We created a file, called "yubikey.input", which contains the YubiKey key material that we saved to a CSV file when we configured the YubiKey (above), and a mapping to the TSO user ID, "ADCDE", that will use this YubiKey, as follows (Note: the record from the CSV file is enclosed in double quotes):

ADCDE *NONE* AZFYUBI1 "10166725,vvlfugjjnjnu,f5733f06d24c,050b391e26a88f96f44bc6c9d25bd396,000000000000,2019-07-08T21:08:50,"​

We added the MFA "bin" directory to our PATH by issuing the following UNIX command:

$ export PATH=/usr/lpp/IBM/azfv2r0/bin:$PATH​

We created shell scripts to provision our RACF user to use MFA credentials by issuing the following command:

$ azfbulk yubikey.input COMMIT​

We then invoked the two shell scripts created by the above command to complete the user provisioning:

$ sh azfprov1.sh
ALU ADCDE MFA(FACTOR(AZFYUBI1) NOACTIVE NOPWFALLBACK NOTAGS)
ALU ADCDE MFA(FACTOR(AZFYUBI1) TAGS(REGSTATE:OPEN))
$ sh azfprov2.sh
userid: ADCDE
Existing AZFYUBI1 tag data for user ADCDE:
REGSTATE:       OPEN
SERIAL: (not set)
PUBNAME:        (not set)
PRIVID: (not set)
SECRET: (not set)
CREATED:        (not set)
MODIFIED:       0
YKCTR:  0x00
YKUSE:  0x0
YKTSL:  0x00
YKTSH:  0x0
Parsed CSV successfully; pending AZFYUBI1 tag data for user ADCDE:
REGSTATE:       WANTSYNC
SERIAL: 10166725
PUBNAME:        vvlfugjjnjnu
PRIVID: wRlqHwuIpFocaqIiIWXKZkofH1CC/q50S+DhXRdYt0E=
SECRET: Ujt8MUgGhvSIotHVDZDocLT3or6r46mmqxucsfSAMX/YTGU5B581yeSVObcuh/kV
CREATED:        2019-07-08T21:08:50
MODIFIED:       0
YKCTR:  0x00
YKUSE:  0x0
YKTSL:  0x00
YKTSH:  0x0
Committed AZFYUBI1 factor data for ADCDE.

Log On to TSO

Now we attempted to log on to TSO using our provisioned user, ADCDE, specifying a password by pressing the YubiKey button to produce the 44-character OTP, then typing a colon (:) followed by our RACF password.  If the hidden password field were visible, this is what the full password field would look like:


Then we pressed ENTER and received confirmation of successful authentication by MFA:


Closing Thoughts

If you want to deploy a large number of YubiKeys for MFA, you do not need to explicitly assign each YubiKey to a particular RACF user ID.  Instead, you can configure the batch of YubiKeys, capturing the key material for each YubiKey into a single CSV file which is imported into MFA.  Then you distribute these YubiKeys to intended users and they can "enroll" their key through the MFA Web Services web interface.  As part of this process, the user logs on with their RACF user ID and password.  This establishes the association between the RACF user ID and their YubiKey.  For details, consult chapter 21 - "Configuring IBM MFA for IBM MFA for
YubiKey" of the Installation and Customization Guide (see References below).

If you don't want to enable passphrases, you can use "Out-of-band Authentication" in MFA to allow users to provide their credentials (typically their RACF user ID, Yubico OTP and RACF password) via a web interface and receive an 8-character "cache token", which they can then paste into the 8-character password field of the logon panel.  MFA will accept this cache token as a valid password and sign the user on.  For details, consult chapter 14 - "Configuring IBM MFA Out-of-Band
authentication" of the Installation and Customization Guide (see References below).

References

IBM Z Multi-Factor Authentication Installation and Customization (SC27-8447-30)
https://www-01.ibm.com/servers/resourcelink/svc00100.nsf/pages/zOSV2R3sc278447?OpenDocument