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/generateBody: {
“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/validateBody: {
“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/revokeBody: {
“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/tokensBody: {
“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/usersBody: {
“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/scopeBody: {
“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 namepersonalAccessToken
GET /<allowed-service>/api/v1/request HTTP/1.1Cookie: personalAccessToken=eyJhbGciOiJSUzI1NiJ9…
HTTP/1.1 200
…
- Using a request header with the name PRIVATE-TOKEN
GET /<allowed-service>/api/v1/request HTTP/1.1PRIVATE-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.
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.