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.

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

  1. Define z/OS RACF security definitions for SAF IDT
    Eclipse IDE users
    For Eclipse IDE clients, the option "Enable token authentication to Debug Profile Service" under IBM z/OS Debugger Preferences is enabled by default. When enabled, the IDE authenticates user credentials with RSED to obtain a SAF JWT token. The token is then used as the primary form of authentication for REST calls to the Debug Profile Service 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:
    VS Code IDE users
    For VS Code clients, the zOpenDebug connection Zowe profile supports the authenticationType property with either token or Basic. If token is specified, VS Code authenticates user credentials with Debug Profile Service to obtain a SAF JWT token. The token is then used as the primary form of authentication for REST calls to the Debug Profile Service that runs on the z/OS host.
    Debug Profile Service provides installation instructions to craete 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 about how to create EQAAPPL, see the following topics.
  2. 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.
  3. Verify SAF JWT Authentication
    1. Restart EQAPROF for the changes in eqaprof.env to take effect. Verify that 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.
Notes:
  • The logout endpoint can only invalidate SAF JWT tokens generated by the Debug Profile Service - Authentication Service API login endpoint.
  • SAF JWT invalidation triggered by the logout endpoint will not persist during server restarts.
  • SAF JWT invalidation 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.