Using IBM MFA with PassTickets

The RACF® PassTicket is a one-time-only password that is generated by a requesting product or function. It is an alternative to the RACF password and password phrase that removes the need to send RACF passwords and password phrases across the network in clear text.

Before you begin

You must have already configured an application to use PassTickets. A PTKTDATA class profile that contains application-specific SSIGNON key data is used by the security manager to create and validate a PassTicket. This profile is used for all users, whether they are IBM® MFA provisioned or not, for PassTicket processing. This section assumes that this profile already exists.
Note: When using PassTickets for the first time, it is recommended that testing with a PassTicket be performed using a non-IBM MFA provisioned user, and any issues corrected, before testing with a PassTicket using an IBM MFA provisioned user.
Every RACF PassTicket must be generated for the specific application that authenticates using the PassTicket. When an authenticating application performs a SAF RACROUTE REQUEST=VERIFY request using the PassTicket, it must perform one of the following actions:
  • Explicitly specify the APPL= parameter to provide an application-determined application name to be used during PassTicket validation.
  • Omit the APPL= parameter, which causes a RACF-derived application name to be used during PassTicket validation, as documented in the z/OS Security Server RACF Security Administrator's Guide in the section Determining PTKTDATA profile names.

If the application name used to generate the PassTicket does not match the application name used during RACROUTE REQUEST=VERIFY processing, the PassTicket will fail validation when IBM MFA calls the R_GenSec service to check if it is a valid. In this case, the PassTicket is treated as an IBM MFA credential.

Note: You should not assume that the VTAM Application ID (APPLID) value used to connect to an application will also be used as the RACF application name. The RACF application name is determined solely by the authenticating application. An application may choose to use the VTAM APPLID as the RACF application name, but it does not have to do so.

About this task

If you are using a "strong" factor such as TOTP, IBM MFA with SecurID, or Certificate Authentication for a user, you can also specify PassTickets. (There is no practical benefit to specifying PassTickets alone because IBM MFA would not be involved.)
You can configure IBM MFA to allow the use of a PassTicket only after a recent successful IBM MFA authentication. A successful IBM MFA authentication can occur in-band by using IBM MFA credentials to log on to any application, or out-of-band by authenticating using IBM MFA credentials to obtain a CTC. The time at which the successful IBM MFA authentication occurs is saved in the user's AZFPTKT1 tag data.
Note: An unsuccessful IBM MFA authentication attempt by the user, either in-band or out-of-band, will cause the IBM MFA PassTicket integration to clear its record of the user's last successful IBM MFA authentication time. This prevents the user from successfully authenticating with a PassTicket until the user completes another successful IBM MFA authentication.

In both cases, IBM MFA then calls R_GenSec with the user ID, the 8-character PassTicket, and the application name to evaluate the PassTicket.

Important: Make sure that you tell the application users when to log on with their PassTicket, and specifically whether they must first log on with their IBM MFA credentials.

Procedure

  1. Use RDEFINE to define an MFADEF class profile named FACTOR.AZFPTKT1.
    RDEF MFADEF FACTOR.AZFPTKT1
  2. Refresh the MFADEF class:
    SETROPTS RACLIST(MFADEF) REFRESH
  3. Verify the change. For example:
    RLIST MFADEF FACTOR.AZFPTKT1
  4. Use RDEFINE to create a FACILITY class profile named IRR.RFACTOR.MFADEF.AZFPTKT1.
    RDEF FACILITY IRR.RFACTOR.MFADEF.AZFPTKT1
  5. Refresh the FACILITY class:
    SETROPTS RACLIST(FACILITY) REFRESH
  6. Verify the change. For example:
    RLIST FACILITY IRR.RFACTOR.MFADEF.AZFPTKT1
  7. Authorize the administrators who execute the panels to the IRR.RFACTOR.MFADEF.AZFPTKT1 profile. Allow the access shown in Table 1:
    Table 1. Required levels of permission
    Permission Access
    READ Able to view configuration options, but may not update, create, or delete parameters.
    UPDATE, CONTROL, ALTER Able to create, update, delete, and view configuration options.
    For example:
    PERMIT IRR.RFACTOR.MFADEF.AZFPTKT1 ACCESS(ALTER) CLASS(FACILITY) 
    ID(user-id)
    SETROPTS RACLIST(FACILITY) REFRESH
  8. To allow IBM MFA to accept all PassTickets passed on a RACROUTE REQUEST=VERIFY, you must create a PTKTDATA class IRRPTAUTH.** profile and allow the user ID of the IBM MFA services started task AZF#IN00 READ access to the profile.

    In addition, because RACF always uses the most specific profile that matches a specified IRRPTAUTH.<appl>.<tuser> profile value when performing authentication checks, you must also permit IBM MFA READ access to any additional specific (or less generic) PTKTDATA class IRRPTAUTH.<appl>.<tuser> profiles that have been defined.

    Note: This step assumes that you have previously issued the following command and then defined the required profiles:
    SETROPTS CLASSACT(PTKTDATA) GENCMD(PTKTDATA) GENERIC(PTKTDATA) RACLIST(PTKTDATA)
    For example, assume that the following PTKTDATA class profiles exist:
    • IRRPTAUTH.<appl3>.<tusera>
    • IRRPTAUTH.*.<tuserb>
    • IRRPTAUTH.<appl1>.*
    • IRRPTAUTH.<appl2>.*
    To be able to accept all PassTickets passed on a RACROUTE REQUEST=VERIFY, IBM MFA requires READ access to the following PTKTDATA class profiles:
    • IRRPTAUTH.**
    • IRRPTAUTH.<appl3>.<tusera>
    • IRRPTAUTH.*.<tuserb>
    • IRRPTAUTH.<appl1>.*
    • IRRPTAUTH.<appl2>.*
  9. Execute AZFEXEC and choose AZFPTKT1.
  10. Choose from the following options:
    • Whether to require a successful IBM MFA logon prior to the PassTicket being evaluated.
      • If Y, the most recent IBM MFA authentication for the user must have occurred within the PassTicket evaluation window number of seconds. If the most recent IBM MFA logon is inside this window, IBM MFA calls R_GenSec. If the most recent IBM MFA logon is outside this window, the authentication is processed as an IBM MFA authentication and might therefore fail.
      • If N, IBM MFA calls R_GenSec without first requiring an IBM MFA logon.
    • PassTicket evaluation window, as a number of seconds. This is the length of time in seconds that PassTickets may be used to authenticate after a successful IBM MFA authentication. Valid entries are integer values between 30 and 86400 (24-hours), inclusive. The default is 600 (10 minutes).
      • If "Require MFA Logon prior to PassTicket Evaluation" is set to Y, the most recent IBM MFA authentication for the user must have occurred within the PassTicket evaluation window.
      • If "Require MFA Logon prior to PassTicket Evaluation" is set to N, the PassTicket evaluation window setting is ignored.
    • Trace level used for tracing events within the AZFPTKT1 plug-in. Valid values are 0 through 3, where the higher number increases the level of verbosity. The default is zero.
  11. Save the configuration, even if you did not make any changes, to complete the configuration process.
  12. Activate users for PassTickets:
     ALU LOGIN ID MFA(FACTOR(AZFPTKT1) 
    ACTIVE TAGS(WINDOW:numseconds MFAFIRST:Y|N))
    Where:
    • [Login ID] is the z/OS® user name.
    • ACTIVE activates the AZFPTKT1 authenticator for the user ID.
    • WINDOW sets the evaluation window, as a number of seconds.
    • MFAFIRST specifies whether to require a successful IBM MFA logon prior to the PassTicket being evaluated. The possible values are Y and N, and uppercase is required.
    If you set MFAFIRST or WINDOW for a user, it overrides the default setting.
  13. To return a user to the default tag settings:
    ALU LOGIN ID MFA(FACTOR(AZFPTKT1) DELTAGS(MFAFIRST
          WINDOW))