The documentation is pretty good on how to install and configure MFA on z/OS.
The blog posts below give additional information, and the definitions I used to get it working.
Length of password fields.
Some z/OS applications only support passwords of length up to 8 characters. z/OS has had pass-phrase support for many years. A pass phrase must be between 14 to 100 characters in length (inclusive).
If you are going to use MFA where you combine a One Time Password and your password (such as 123456:passw0rd) the applications need to be able to support passwords longer than 8 characters. If your application does not support long passwords you will need to use out-of-band MFA.
See here on how to configure TSO to support pass phrase. Once this has been done, the TSO logon panel has a long password field. Once you have configured TSO to support pass phrases you can configure RACF and individual userids to use pass phrases.
In-band and out-of-band
With some applications you enter two factors to logon to the application. For example, I can logon to TSO with a “password” 983211:passw0rd - where 983211 is a one time code (which changes every minute) and passw0rd is my RACF password. This is in-band (you enter the combined password >IN<to the application). To be able to use in-band authentication you need to be able to enter long “passwords”.
If you cannot use in-band authentication, you can use multiple factors to logon to a web page, get a one time password and enter that into the application logon screen. This is indirect, or out-of-band authentication; you set up the password >OUT<side of the application. Your application does not need to change to be able to use out-of-band authorisation.
If you try to configure a userid with two factors, for example AFZTOTP1, and AZFYUBI1, you will get a message AZF2214E A user with multiple active Strong factors cannot authenticate in-band. If you try to logon to TSO with password and your Yubikey, how does MFA know if you are entering a AZFTOTP1 or a AZFYUBI1 password.
If you are going to configure a userid to logon out of band, using AZFTOP1 and AZFYYUBI1 then you will need to configure both the factors. If you want to logon in-band, just specify the single factor you want to use.
Pre-requisites
To be able to use the web browser interface to configure users for MFA you need to have AT-TLS working. AT-TLS logs to syslogd, so you need the SYSLOGD daemon running. My daemon is configured to log into /var/log/. For AT-TLS you need keyring(s) and certificate(s). Get these set up (and tested) before you try to configure MFA.
TCPIP port configuration
You need to decide which TCP ports you will use.
- The Server Port. This is used between the MFA web server started task and the main MFA started task. The default is 6792.
- The Server Authentication Port. This is used when end users connect to the MFA web server, for example to define a One Time Passcode connection. The default is 6793. This port needs to be configured in AT-TLS.
- The Mutual Authentication Port. This is used when client connect to the MFA web server using client certificate authentication. The default is 6794. If you intend to use client certificate authentication this port needs to be configured to AT-TLS
These ports are configured via the AZFEXEC processing. If you are using Communications Server IP filtering, or a firewall, you will need to enable these ports.
What shape is your configuration?
Each LPAR needs an instance of the AFZ#IN00 started task.
For the MFA web server started task (AZF#IN01), you can use:
- one MFA web server on each LPAR, with a different URL for each LPAR
- a VIPA address, and one (or more) MFA web servers running, and one URL. Request will go to one server. If that server is shutdown, the traffic will be rerouted to another (active) MFA web server
- a sysplex distributor, and one URL. A connection request is routed to any available MFA web server running in the sysplex, in a Round Robin, or workload balanced fashion.
See HA Liberty web server – introduction to using VIPA to provide high availability connectivity. and talk to your network people.
You can specify which TCPIP instance MFA uses.
Administering MFA
You need to define RACF profiles for MFA. MFA stores information in some of these profiles.
You also provide information in the MFA segment for userids.
MFA is configured using AZFEXEC which displays ISPF panels. There is granular control, you can give a userid read or update access to a specific RACF FACILITY profile like IRR.RFACTOR.MFADEF.AZFTOTP1 (for the AZFTOTP1 component).
You should plan which userids (or groups) have read or update authority to which factor. It is easy to change at a later date. You could start with a generic profile IRR.RFACTOR.MFADEF.* .
Define and activate AT-TLS definitions
MFA provides a TLS session for the MFA web browser, so it can display the secret information need to configure authenticating applications.
See Usage notes on Certificates and Keyrings, and what access is required for which functions.
Strictly you need to provide two keyrings – but I used the same keyring for both.
The server identification keyring.
This contains a certificate used to identify the server. This certificate needs a private key. If you want to specify which label in the keyring to use, add ServerCertificateLabel to the TTLSConnectionAdvancedParms AZFConnAdvParms1
definiton.
TTLSConnectionAdvancedParms AZFConnAdvParms1
{
ServerCertificateLabel ...
Client certificate authentication
If you are using client certificate authentication then you need a keyring with certificates which can validate the certificate sent from the client. This keyring will usually contain certificate authority certificates. If the client is using self signed (not best practice) you will need these certificates in the z/OS keyring.
Some AT-TLS return codes are documented here
When you configure the AT-TLS procedure you configure where any output is put. I have it going to /var/log/ATTLS
You can use the Unix command pasearch > aa to write the current AT-TLS configuration to the file. You can then check the configuration is as you expect.
Steps
You need to define at least one authentication factor configured before MFA will successfully start. One Time Passcode is an easy one to define.
My approach to getting MFA configured for user was:
- Get one function working such as Timed One Time Password (TOTP) so you can logon with just TOTP (and no password) to TSO.
- Change the configuration to use Compound In-band Authentication, where you need TOTP and a password, so you enter 123456:passw0rd. You need to decide if you want password:code or code:password, and what the separator character is.
- Develop a policy for out-of-band authentication for applications which do not accept a long or compound password.
- Implement another factor.
- Migrate users to use MFA