IBM Cloud Identity is a cloud based identity-as-a-service platform that supports multi-factor authentication among other features. Cloud Identity Verify (CIV) is the feature that supports authentication-as-a-service which enables users to enroll in various forms of second authentication factors. We implemented CIV along with the IBM Verify Gateway for RADIUS and the IBM Verify app in our zPET environment that was already running IBM Z Multi-Factor Authentication V1R13 on z/OS V2R3. The following is a summary of the steps that we took. Note that some of the webpage selections or other settings may have changed since we performed these tasks in Spring of 2019. The following should not be considered the “recommended” or “suggested” settings for how to implement these features. It is the way that we were able to implement this in our zPET test environment.
Cloud Identity Server
To set up our server, we accessed the IBM Cloud provisioning portal for Cloud Identity Free Edition, available at URL https://www.ibm.com/account/reg/us-en/signup?formid=urx-30041. (With an IBM ID you can register for the free edition.) We logged in, provided our desired hostname, followed the instructions and navigated to our new server at https://<hostname>.ice.ibmcloud.com
We started configuring our new site by selecting the person icon on the far right and clicking on switch to admin. We then clicked on the 3 line hamburger icon in the upper left and selected Configuration. With the API Access tab selected and API Clients highlighted we clicked on the Add API Client button.
We then filled in a name for the client and selected the following APIs:
- Authenticate any user
- Manage authenticator configuration
- Manage authenticator registrations for all users
- Manage second-factor authentication enrollment for all users
- Manage second-factor authentication method configuration
- Read users and groups
After the API client was saved, values for Client ID and Client Secret were generated. These values were needed when setting up our IbmRadiusConfig.json file described later in this document. The Client ID was displayed on the screen after the API client was created, but to see the Client Secret we had to hover on the client listing and click the pencil edit icon and then click on the eyeball reveal icon next to the client secret.
While still in the API Access section, we selected Allowed Domains and clicked on the Add Domain button. We added a domain of the format https://<company>.com/* which in our case was https://ibm.com/* We also changed the Regular Expression setting from Off to On.
We left the Configuration section by clicking on the hamburger icon, selecting Security and then selecting the Authentication Factors tab. Scrolling down to the IBM Verify Authentication section we changed the value for User Presence from On to Off and confirmed that the value for Fingerprint was set to On. This enforces that fingerprint authentication is needed when using IBM Verify.
The Hamburger icon button was then used to go to Users and Groups. With the Users tab selected, we clicked on Add. The Identity Source of Cloud Directory was selected. A new User name was entered and information for this user (Given name, Surname, Email and Mobile number) was filled in. A country code was not required to be entered in this field, but our understanding is that it is needed for the function to work, so we added +1 on the front of the number for the United States. The Enabled and Email New Account settings were left in the On position. When the new user was created, the owner received an email at the address specified. We refer to this new user id as a CIV user in this document and the configuration that the owner had to do will be described later.
IBM Verify Gateway for RADIUS
On our Windows server, we used Firefox to logon to the following URL and download the IBM Verify Gateway for RADIUS app: https://exchange.xforce.ibmcloud.com/hub/extension/cb468c6c4539fad9c64eff7a1b107e86
Note: Our first attempt at downloading failed and we found that prerequisites mentioned in the documentation for the app had to be downloaded before we could successfully download the app.
We installed the app on the Windows server in C:\Program Files\IBM\IbmRadius and put in place a file called IbmRadiusConfig.json that looked like:
{
"address":"::",
"port":2812,
/* "trace-file":"c:/tmp/ibm-auth-api.log", */
"ibm-auth-api":{
"client-id":"<value from API Client above>",
"client-secret":"<value from API Client above>",
"protocol":"https",
"host":"<hostname>.ice.ibmcloud.com",
"port":443,
"max-handles":16
},
"clients":[
{
"name":"z2",
"address": "<ip address of our z2 system>",
"secret":"<shared secret>",
"auth-method":"password-and-device",
"use-external-ldap":false
},
{
"name":"z4",
"address": "<ip address of our z4 system>",
"secret":"<shared secret>",
"auth-method":"password-then-transsmsotp",
"use-external-ldap":false
}
],
"policy":[
]
}
- The port used was 2812 rather than the standard 1812 because we were already using port 1812 in our MFA configuration for SafeNet RADIUS which is running on the same Windows server as this RADIUS Gateway.
- The client-id and client-secret values are the ones that were generated when we added an API client on our Cloud Identity server.
- The host is the URL of our Cloud Identity server that was created earlier.
- The two clients, z2 and z4 are two of our z/OS LPARS from the same sysplex that share the same RACF database, MFA environment and TKDS.
- The address values listed are the ip addresses of the z/OS systems. We obtained them by typing ping z2 and ping z4 from option 6 on z/OS.
- The value for secret matches the value used for Shared Secret on z/OS in AZFEXEC option 4 Generic Radius, although the Shared Secret value is not displayed in AZFEXEC.
- The auth-method of password-and-device used for z2 involves pushing a notification to a device running the IBM Verify app.
- The auth-method of password-then-transsmsotp used for z4 involves sending a text to a mobile number.
We added IBM Radius to the list of tasks on our Windows server by going into Task Manager>File>Run new task and pointing to C:\Program Files\IBM\IbmRadius\IbmRadius.exe
In Task Manager>More details>Services we right clicked on ibmradius and selected Open Services
This opened Services (Local) where we right clicked on IBM RADIUS Service and selected Properties
In here we set the Startup type to Automatic so that it would start on its own. Service status had been set to stopped so we clicked on start.
We then configured a rule in our firewall via Administrative Tools>Windows Firewall with Advanced Security>New Rule
A Rule Type of Program was selected and we specified the path to the location of our ibmRadius.exe file
Continuing through the Rule Wizard, we chose to allow the connection, to have the rule apply for Domain, Private and Public, and we gave the rule a name of ibmradius.
IBM Z Multi-Factor Authentication configuration
On our z/OS system, we issued the following RACF commands:
===> RDEF MFADEF FACTOR.AZFRADP1 UACC(NONE) OWNER(<MFA Owner>)
===> RDEF FACILITY IRR.RFACTOR.MFADEF.AZFRADP1 UACC(NONE) OWNER(<MFA Owner>)
===> PE IRR.RFACTOR.MFADEF.AZFRADP1 CLASS(FACILITY) ID(<MFA Admin>) ACC(UPDATE)
===> SETR RACLIST(FACILITY MFADEF) REFRESH
We then invoked the MFA panels by executing the command AZFEXEC and went into option 4 for Generic Radius where we filled in the following values:
PKCS#11 Token Name . . . . . . . AZFTOTP.TOKEN
Key Label . . . . . . . . . . . . AZFSTC
Primary Server Host Name. . . . <ip of our windows server running Radius Gateway>
Primary Server Port . . . . . . . 2812
Secondary Server Host Name. . .
Secondary Server Port . . . . . . 0
Tertiary Server Host Name . . .
Tertiary Server Port. . . . . . . 0
Number of Retries . . . . . . . . 3
Timeout . . . . . . . . . . . . . 10
Shared Secret . . . . . . . . . <shared secret>
Connection type . . . . . . . . . 1 1. UDP 2. TCP
Enable Compound In-band Authentication. . N
Compound In-band Credential Order . . . . 1 1. MFA Credential First
2. RACF Credential First
Compound In-band Factor Separator . . . . : Default :
Initial Trace Level . . . . . . . . . . . 3
To pick up this change we stopped and started the MFA started tasks AZF#IN00 and AZF#IN01 on each system where they were running. (AZF#IN00 on Z2 and Z4, AZF#IN01 on Z2)
We modified an existing z/OS userid to use MFA Generic Radius and associated it with a CIV ID by issuing the RACF command:
===> ALU <z/OS USERID> MFA(FACTOR(AZFRADP1) TAGS(RADUSERID:<CIVID>) ACTIVE)
Where <CIVID> is the user we created on the Cloud Identity server previously.
Enrolling a device for a new CIV User
When a user was created on the Cloud Identity server, the owner of the new id received an email at the address specified within the new CIV user information. The email contained a link to the server https://<hostname>.ice.ibmcloud.com/ui along with the new CIV user name and a temporary password. We logged in to the server with the new CIV ID and set a new password. Under the person icon in the upper right we selected Security Settings. We then clicked on Add new method.
Within IBM verify app, we selected Add device.
We were then presented with instructions for downloading the IBM Verify app on our device and we followed these to install IBM Verify on an iPad.
After installing IBM Verify on the iPad, we returned to the Cloud Identity server and chose Next: Connect your account and were then presented with a QR code and followed the instructions to connect the app on our device to our account.
From within the IBM Verify app on the iPad, we touched the squares icon in the upper left and pointed the iPad's camera at the QR code. We were presented with the options: Use Touch ID or No, Thanks. We selected Use Touch ID and performed a finger scan to complete the setup. Returning to the Cloud Identity server, we selected Next: Verify your device which caused a notification to be sent to our device which required us to select the checkmark and scan our finger on the iPad before telling us that it had been verified.
Logging on to z/OS
We logged on to the z4 system with the z/OS userid associated with CIV. The password for the CIV ID was entered (rather than the password for the z/OS ID). The following message was received on the z/OS screen:
ICH70008I IBM MFA Message:
Enter OTP 0984:
***
The Mobile number listed for the CIV ID received the following text:
Your passcode is:
3749-372446.
It expires in 5 minutes
We entered 372446 in the z/OS password field and then received:
ICH70008I IBM MFA Message:
AZF1903I: RADIUS AUTHENTICATION SUCCESSFUL
We were successfully logged on to z/OS, confirming that our MFA set up using CIV with an auth-method of password-then-transsmsotp was working.
We then logged onto Z2 with our z/OS ID and again provided the password for the CIV ID. This time we received the following message on the z/OS screen:
ICH70008I IBM MFA Message:
A push notification has been sent to your device :MFA iPad (iPad):. Please refresh your IBM Verify application if you did not receive it.
On the Verify app on the iPad, we received the following message:
Do you approve this request from Z2?
IBM Cloud Identity
Confirmation #3b28cb5e
Verify with Touch ID
We selected the checkmark, performed a finger scan and received a request verified message. We then returned to the z/OS logon screen, hit enter to clear the message, hit enter again and we were successfully logged on to z/OS. Once again this confirmed that MFA using CIV was working; this time using an auth-method of password-and-device.
Issues encountered
Along the way we ran into issues. Some have already been mentioned and others are documented here.
When first trying to enroll our device with IBM Verify, the iPad would not capture a picture of the QR code. It turned out that the screen was zoomed in to a level where the entire QR code was not visible. Reducing the image on the screen corrected this.
After capturing a picture of the QR code, we received an error message saying the JSON data supplied was invalid. IBM Verify had been installed on the iPad previously for generic TouchToken. After going to the app store and updating our version of IBM Verify we were able to scan the QR code without encountering the error.
Our IbmRadiusConfig.JSON file, originally contained the line "reject-on-missing-auth-method":false. With this, if a user replied No Thanks to the Use Touch ID prompt when enrolling a device, they could logon to z/OS by providing the CIV password without any further authorization. After removing this line, if the user replied No Thanks during enrollment, their z/OS logon attempt failed as expected.
Conclusions
This implementation included setting up products and tools that we had never used before and took some time to research (and contribute to) documentation, ask questions and experiment with settings. The result is a new, cutting-edge way to access our z/OS environment using multi-factor authentication. The hope is that our efforts make this type of implementation easier for other z/OS clients.