Personal Access Tokens for the Zowe API Mediation Layer

{Core} Personal Access Tokens (PAT) are ubiquitous today where most of the applications that we use or develop consume and rely on remote services that require secure and independent authentication. The main reason one would want to use a PAT is to avoid having to send the username and password as part of the authentication request. Oftentimes one would also want to limit the access of an authenticated application to just a subset of the full scope that the associated user account has. However, for The Open Mainframe Project’s Zowe and the mainframe platform, the most desirable feature of PATs is that they live independently of the associated mainframe account credentials and this is why they were implemented in the Zowe API Mediation Layer.

The personas that would most benefit from this new feature of the Zowe API Mediation Layer are the system integrators, the people that design and construct the mainframe DevOps infrastructure for their organization. You may need to enable secure authentication for your hybrid cloud environment to access the mainframe services. You may also want to provide instructions for your fellow mainframe developers on how to set up their workstations to be able to easily access and work with their source code there. Endevor® Bridge for Git by Broadcom is a good example of how this enhancement can be used to authenticate users with PATs instead of their account credentials.

Constructing DevOps infrastructure, however, is just one of the use cases that could leverage the use of PATs, in fact there are many other integrations that could benefit as well. Any client side applications that consumes REST APIs through the Zowe API Mediation layer would have yet another secure and convenient way of authentication.

With the release of Zowe 2.3 and the API Mediation Layer version 2.3.1, the Zowe users will have the following APIs available to manage PATs:

• User APIs: generate, validate, invalidate a specific token, invalidate all tokens
• Security Administrator APIs: invalidate all tokens for a user, invalidate all tokens for a service, evict non-relevant tokens and rules

The authentication to access the PAT APIs can be achieved via the other existing API ML methods, i.e. via username and password or a client certificate.

The base paths to all API ML Gateway PAT endpoints would have the following structure: https://{gatewayUrl}:{gatewayPort}/gateway/api/v1/

The calls to all those APIs would return code 200 in case of a successful operation or 401 in case of failure. All cached values involved in their operations are protected by the API ML client certificate.

User Personal Access Token APIs

Generate a Token

An authenticated user can generate a token by calling the following endpoint:

POST /auth/access-token/generate
Body: {
    “validity”: <days>,
    “scopes”: [“<serviceId_1>, <serviceId_2>”]
}

Where the validity period is specified in number of days and the scope is a list of services the PAT would be valid for. The token value is returned in the response body as plain text.

Validate a Token

An authenticated user can validate a token by calling the following endpoint:

POST /auth/access-token/validate
Body: {
    “token”: “<token>”,
    “serviceId”: “<serviceId>”
}

Where a combination of a token value and a service ID is used to validate the access token. The same validation is also performed every time a token is used to access a service.

Revoke a Token

An authenticated user can revoke a token by calling the following endpoint:

DELETE /auth/access-token/revoke
Body: {
    “token”: “<token>”
}

Where a token value is specified to be revoked. The PAT is then stored by the Catching Service under the invalidTokens key and thus effectively is being revoked.

Revoke All Tokens

An authenticated user can revoke all their tokens by calling the following endpoint:

DELETE /auth/access-token/revoke/tokens
Body: {
    “timestamp”: “<timestamp>”
}

Where a timestamp value specifies the moment, before which all PATs for the authenticated user would be revoked. The provided user rule is stored by the Catching Services under the invalidUsers key and thus effectively revoking all tokens for the user.

Security Administrator Personal Access Token APIs

An authenticated user with privileged access to SAF resources is able to invalidate all tokens based on criteria established by rules about user IDs or services scopes. These criteria would define the level of access control and would restrict access in advance allowing for prompt reactions against security breaches.

Revoke All Tokens for a User

A call to the following endpoint would allow the revocation of all tokens issued for a user prior to the specified timestamp.

DELETE /auth/access-token/revoke/tokens/users
Body: {
    “userId”: “<userId>”,
    “timestamp”: “<timestamp>”
}

Where the user ID refers to the user in question and the timestamp value specifies the moment, after which all PATs for the relevant user would be revoked. The provided user rule is stored by the Catching Services under the invalidUsers key and thus effectively revoking all tokens for the user.

Revoke All Tokens for a Service

A call to the following endpoint would allow the revocation of all tokens issue for a service prior to the specified timestamp.

DELETE /auth/access-token/revoke/tokens/scope
Body: {
    “serviceId”: “<serviceId>”,
    “timestamp”: “<timestamp>”
}

Where the service ID refers to the service in question and the timestamp value specifies the moment, after which all PATs for the relevant service would be revoked. The provided service rule is stored by the Catching Services under the invalidScopes key and thus effectively revoking all tokens for the service.

Evict Non-Relevant Tokens and Rules

A call to the following endpoint would allow the eviction of all invalidate tokens that have expired and the related to them rules.

DELETE /auth/access-token/evict

The main purpose of the eviction is to maintain the cache size within reasonable parameters. The token verification processes require the validation of all rules, including those no longer applicable. As such, maintaining the cache size within reasonable limits would reduce the processing cost for stored rules that are no longer relevant. In case of a successful eviction call, the response is an empty body with a status code of 204. In case the eviction fails due to insufficient permissions, the status code is 403.

Use of PAT for Authentication

Ultimately, the purpose of the Personal Access Tokens is to be used for authentication as part of a Single Sign On operation, in which an authorized service is accessed by a user that has a valid token at the time of the call. There are two ways how to provide the token value in the request:

• Using a secure HttpOnly cookie with the name personalAccessToken

GET /<allowed-service>/api/v1/request HTTP/1.1
Cookie: personalAccessToken=eyJhbGciOiJSUzI1NiJ9…
HTTP/1.1 200
…

• Using a request header with the name PRIVATE-TOKEN

GET /<allowed-service>/api/v1/request HTTP/1.1
PRIVATE-TOKEN: eyJhbGciOiJSUzI1NiJ9…
HTTP/1.1 200
…

In the examples above, the return codes indicate successful authentication. In case the authentication fails for any of the possible reasons, i.e., expired token, access to unauthorized service, incorrect token value, the X-Zowe-Auth-Failure error header is set and passed in the response. The error message contains a reason for why the provided authentication is not valid.

Reference: Zowe API Mediation Layer Personal Access Token

If you enjoyed this blog, and would like to learn more about Zowe, check out more Zowe blogs here. You are also welcome to ask questions and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the Open Mainframe Project slack channel register here.