IRRPTAUTH setup in RACF for Endevor API passticket

Products

• Endevor

Issue/Introduction

IBM MFA is installed on the system. Endevor passticket is enabled. 

Using Explorer for Endevor vscode extension, and encountered the similar error described in KB 401053

Tried to following IBM doc to enable passticket factor in IBM MFA, but the document is not really clear, should we define IRRPTAUTH.mfaapplname.* ACCESS(read or update?) CLASS(PTKTDATA) ID(userid) to allow the Endevor users to use passtickets with REST API clients such as Endevor Explorer ? Or is it just the MFA STC userid that needs access? Or neither? Or both? 

What should be the value of mfaapplname ? 

 

Environment

Endevor V19

Cause

Here is how passticket works when IBM MFA is involved:

- User attempts to connect to the MF with their own password/passphrase and 2-factor to satisfy 2 factor reqs.
- 2-factor consumed by IBM MFA product, userId and passphrase are consumed by Endevor backend.
- Endevor calls SAF service to verify userId and password/passphrase, if they are valid, Endevor calls authorized service to generate a passticket for the user.
- IBM MFA verifies 2nd factor and if it's valid, it starts countdown for 'PassTicket evaluation window' if it's enabled in global settings or in user profile 
- Subsequent calls include userId and passticket. Endevor backend calls a service to validate a passticket
- If passticket is valid, request is executed. If not - request fails and user need to provide userId/passphrase/password (and 2nd factor if IBM MFA is in use) again
- If MFAFIRST option is enabled, IBM MFA checks that 2nd factor evaluation was performed within evaluation window. If it wasn't performed - user or EWS client needs to send 2nd factor again

Here are the key points:
- after passticket is generated, it's not stored anywhere on the mainframe. When you configure/define a passticket you provide a secret key (or a certificate for enhanced passticket) which is stored in SAF and it's used for passticket generation and validation.
- it's important that IBM MFA product must be configured to allow passticket auth. If IBM MFA product is installed on the system, passticket won't work out of the box.

mfaapplname should be the value of MFAAPPL from C1DEFLTS.

Resolution

For Endevor there is no need to grant access to PTKTDATA IRRPTAUTH.ENDEVOR.* profile in basic setup. However, there are 2 exceptions:

- if you plan to use Endevor through Zowe APIML with Zowe JWT enabled. Then you need to grant UPDATE access to IRRPTAUTH.ENDEVOR.* for Zowe userId - the owner of the zowe server started task. It's mentioned in ZOWE documentation.
- if you use IBM MFA and it's described in IBM doc, for example if MFAAPPL=ENDEVOR is set in C1DEFLTS, run the following RACF commands to configure security: 

 

RDEF MFADEF FACTOR.AZFPTKT1
SETROPTS RACLIST(MFADEF) REFRESH
RDEF FACILITY IRR.RFACTOR.MFADEF.AZFPTKT1
SETROPTS RACLIST(FACILITY) REFRESH

PERMIT IRR.RFACTOR.MFADEF.AZFPTKT1 ACCESS(ALTER) CLASS(FACILITY) ID(ibm-mfa-administrator-user-id)
SETROPTS RACLIST(FACILITY) REFRESH

 

[
If not defined: 
RDEF PTKTDATA IRRPTAUTH.ENDEVOR.* UACC(NONE)
]

PERMIT IRRPTAUTH.ENDEVOR.* ACCESS(READ) CLASS(PTKTDATA) ID(ibm-mfa-stc-user-id)
SETROPTS RACLIST(PTKTDATA) REFRESH

where ibm-mfa-stc-user-id - IBM MFA STC user/owner
ibm-mfa-administrator-user-id - security admin who needs access to IBM MFA panels to configure IBM MFA passticket configuration. 

Start admin panels by running AZFEXEC and configure AZFPTKT1 as described in step 10 in the doc:
- Set Y to require a successful IBM MFA logon prior to the PassTicket being evaluated
- PassTicket evaluation window - must be default ( 600 (10 minutes)) or more (up to 68400 (24 hours)). It makes sense to set it to the the same value as passticket validity window

Then RACF admin must run a command for Endevor users who plan to use passticket to allow auth, for example:
ALU LOGIN ID MFA(FACTOR(AZFPTKT1))

Additional Information

 IRRPTAUTH.mfaapplname.* ACCESS(READ) for IBM MFA STC ID - to allow passticket validation. 

 IRRPTAUTH.mfaapplname.* ACCESS(UPDATE) for ZOWE STC ID - to allow passticket generation.