Authenticating with SAF JSON Web Tokens (JWT)

Authentication Service API uses a service called SAF JWT Service to provide SAF JSON Web Token (SAF JWT) authentication functions through login, query, and logout endpoints.

Internally, the SAF JWT Service interface with the z/OS security software, System Authorization Facility (SAF) provider. It invokes RACROUTE REQUEST=VERIFY authentication, where the application ID (APPLID) is passed as a parameter, to generate and authenticate SAF Identity Token (IDTs) in the form of JWT tokens. The APPLID is defined by z/OS RACF security definitions for SAF IDTs, and must be configured first. This configuration is necessary for RACROUTE process to call the expected APPLID that generates or validates IDT tokens based on z/OS RACF profile definitions.

For more information about SAF IDT, see "Activating and using the IDTA parameter in RACROUTE REQUEST=Verify” in the z/OS Security Server RACROUTE Macro Reference documentation.
For more information about the error return codes it produces, see RACROUTE REQUEST=VERIFY (Standard Form) under “z/OS Security Server RACF” > “z/OS Security Server RACROUTE Macro Reference” > “System Macros”

To get started with SAF JWT as an authenticator provider, complete the following steps:

Define z/OS RACF security definitions for SAF IDT
Eclipse IDE users

For Eclipse IDE users who have enabled token authentication in their preference settings, the IDE authenticates user credentials with RSED to obtain a SAF JWT token. This token is then used as the primary authentication method for REST calls to the Debug Profile Service server running on the z/OS host.

To support this, the SAF JWT Service must be configured with the same RSE Daemon (RSED) application ID (APPLID) named FEKAPPL. This ensures that both the Debug Profile Service and RSED running on the z/OS host use the same SAF JWT provider for JWT authentication by Eclipse IDE. Additionally, ensure that users or groups have READ access to the APPLID.
For more details, see the following topics in the "Security Definitions" section in IBM Explorer for z/OS Host Configuration Guide:
- Define the application protection for RSE
- Define SAF JSON Web Token (JWT) support for RSE
All other users

Debug Profile Service provides installation instructions for creating a new application ID (APPLID) named EQAAPPL. However, if an existing APPLID already exist from a different product, then it is possible to use the existing one. This allows Debug Profile Service to use the same SAF JWT provider during JWT authentications.
For more information on creating EQAAPPL, see the following topics.
- Define the application protection for Debug Profile Service
- Defining SAF JWT support for Debug Profile Service
Debug Profile Service configurations for SAF JWT Service
1. To enable or disable SAF JWT Service, specify safJwtIsEnabled to true or false in the eqaprof.env file.
2. To configure application ID (APPLID) for SAF JWT Service, specify safJwtApplID with the name of the APPLID in the eqaprof.envfile.
Verify SAF JWT Authentication
1. Restart EQAPROF for the changes in eqaprof.env to take effect, and verify the user can retrieve a JWT token, and authenticate with it by calling the Authentication API endpoints as described in Authentication Service API diagnostics section.

Note:

The logout endpoint can only invalidate SAF JWT tokens generated by the Debug Profile Service - Authentication Service API login endpoint.
SAF JWT invalidation’s triggered by the logout endpoint will not persist during server restarts.
SAF JWT invalidation’s triggered by the logout endpoint are not propagated across LPARs in a sysplex, where each LPAR runs its own instance of the EQAPROF server.
Application ID (APPLID) is defined in the IDTDATA class <Identity Token (IDT) type>.<APPLID>.<user ID>.<IDT issuer name>.
Support for SAF JWT requires z/OS 2.4 or later.
Support for SAF JWT for Eclipse users requires z/OS Explorer Host 3.3.6 or later.