Authenticating with a JSON Web Token (JWT)

Required roles: system administrator, security administrator

One user authentication method available in Zowe is via JSON Web Token (JWT), whereby a token can be provided by a specialized service, which can then be used to provide authentication information.

When a client authenticates with API Mediation Layer, the client receives the JWT which can then be used for further authentication. If z/OSMF is configured as the authentication provider and the client already received a JWT produced by z/OSMF, it is possible to reuse this token within API ML for authentication.

This article describes how services in the Zowe API ecosystem are expected to accept and use JWTs so that API clients have a stadardized experience.

tip

For more information about authenticating with JWTs, see the Medium blog post Single-Sign-On to z/OS REST APIs with Zowe.

By default, JWTs are produced by z/OSMF and the API Mediation Layer only serves as a proxy. For information about how to change who and how tokens are produced, see Authentication Providers within Enable Single Sign On for Clients.

JWT-based Login Flow and Request/Response Format

The following sequence describes how authentication through JWTs works:

First, The API client obtains a JWT by using the POST method on the /auth/login endpoint of the API service that requires a valid user ID and password.

Secondly, the API client stores the JWT or cookie and sends the token with every request as a cookie with the name apimlAuthenticationToken.

Obtaining a JWT

To obtain a JWT, call the endpoint with the credentials for either basic authentication or the client certificate.

• The full path for API ML is: /gateway/api/v1/auth/login.
  The full URL follows the format: https://<gateway-hostname>:<gateway-port>/gateway/api/v1/auth/login.

• Credentials are provided in the JSON request or in Basic Authentication. JSON Request Example:

  {
      "username": "...",
      "password": "..."
  }

• Successful login returns RC 204, and an empty body with the token in the apimlAuthenticationToken cookie.

• Failed authentication returns RC 401 without WWW-Authenticate.

Example:

curl -v -c - -X POST "https://<gateway-hostname>:<gateway-port>/gateway/api/v1/auth/login" -d "{ \"username\": \"zowe\", \"password\": \"password\"}"

note

<gateway-hostname> is the hostname of the API Gateway. <gateway-port> is the port on which the API Gateway listens. In the following examples, zowe is used as a placeholder hostname and 7554 as a placeholder port. Replace these placeholder values with your actual gateway hostname and port.

The following output describes the status of the JWT:

POST /gateway/api/v1/auth/login HTTP/1.1
Accept: application/json, */*
Content-Length: 40
Content-Type: application/json

{
    "username": "zowe",
    "password": "password"
}

HTTP/1.1 204
Set-Cookie: apimlAuthenticationToken=eyJhbGciOiJSUzI1NiJ9...; Path=/; Secure; HttpOnly

The output shows that the JWT was successfully created and issued to the client.

• Status Code HTTP/1.1 204
  A 204 No Content status code indicates that the request was successful, the user's credentials were authenticated, and the server fulfilled the request without needing to return an entry body.

• The Set-Cookie Header
  The server is actively sending the token back to the client's browser/application via the apimlAuthenticationToken= cookie. The actual token payload is the encoded string beginning with eyJhbGciOiJSUzI1NiJ9....

Making an authenticated request

You can send a JWT with a request in two ways:

• Allow the API client to pass the JWT as a cookie header.
• Pass the JWT in the Authorization: Bearer header.

tip

The first option (using a cookie header) is recommended for web browsers with the attributes Secure and HttpOnly. Browsers store and send cookies automatically. Cookies are present on all requests, including those coming from DOM elements, and are compatible with web mechanisms such as CORS, SSE, or WebSockets.

Cookies are more diffcult to support in non-web applications. Headers, such as Authorization: Bearer, can be used in non-web applications. Such headers, however, are difficult to use and secure in a web browser. The web application needs to store these headers and attach these headers to all requests where headers are required.

Allow the API client to pass the JWT as a cookie header

One option to send a JWT with the request is for the API client to pass the JWT as a cookie header with the name apimlAuthenticationToken:

Example:

GET /api/v1/greeting HTTP/1.1
Cookie: apimlAuthenticationToken=eyJhbGciOiJSUzI1NiJ9...

HTTP/1.1 200
...

Pass the JWT in the Authorization: Bearer header

A second option to send a JWT with the request is to pass the JWT in the Authorization: Bearer header.

Example:

GET /api/v1/greeting HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

HTTP/1.1 200
...

Validating JWTs

The API client does not need to validate tokens. API services must perform token validation themselves. If the API client receives a token from another source and needs to validate the JWT, or needs to check details in the token, such as user ID expiration, then the client can use the /auth/query endpoint provided by the service.

The JSON response contains the following fields:

• creation
• expiration
• userId

These fields correspond to iss, exp, and sub JWT claims. The timestamps are in ISO 8601 format.

Execute the following curl command to validate the existing JWT, and to retrieve the contents of the token:

curl -k --cookie "apimlAuthenticationToken={token to query}" -X GET "https://<gateway-hostname>:<gateway-port>/gateway/api/v1/auth/query"

The following output describes the status of the JWT:

GET /gateway/api/v1/auth/query HTTP/1.1
Connection: keep-alive
Cookie: apimlAuthenticationToken=eyJhbGciOiJSUzI1NiJ9...

HTTP/1.1 200
Content-Type: application/json;charset=UTF-8

{
    "userId": "zowe",
    "creation": "2019-11-29T13:39:18.000+0000",
    "expiration": "2019-11-30T13:39:18.000+0000"
}

The specific details from the output confirms the status of the token:

• Status Code HTTP/1.1 200
  An HTTP 200 OK response means the query endpoint successfully processed the request and verified that the token provided in the cookie is authentic and valid.

• Active User Identity ("userId": "zowe")
  The output confirms that the token belongs to a valid, recognized user ID (zowe), mapping directly to the JWT sub (subject) claim.

• Token Lifespan Status
  The JSON body returns the exact lifespan metadata of the token, confirming it is within its valid operational window:

Refreshing the JWT

API Clients can refresh the existing token to prolong the validity period.

Use the auth/refresh endpoint to prolong the validity period of the token.

The auth/refresh endpoint generates a new token for the user based on the valid JWT. The full path of the auth/refresh endpoint appears as the following URL:

https://<gateway-hostname>:<gateway-port>/gateway/api/v1/auth/refresh

The new token overwrites the old cookie with a Set-Cookie header. As part of the process, the old token becomes invalidated and is no longer usable.

Notes:

• The endpoint is disabled by default. For more information, see Enable JWT endpoint.
• The endpoint is protected by a client certificate.
• The refresh request requires the token in one of the following formats:
  • Cookie named apimlAuthenticationToken.
  • Bearer authentication

For more information, see the OpenAPI documentation of the API Mediation Layer in the API Catalog.

The following request receives a valid JWT and returns the new valid JWT. As such, the expiration time is reset.

curl -v -X POST "https://<gateway-hostname>:<gateway-port>/gateway/api/v1/auth/refresh" -d '{"username":"zowe","password":"zowe"}'

The following output describes the status of the JWT:

POST /gateway/api/v1/auth/refresh HTTP/1.1
Accept: application/json, */*
Content-Length: 40
Content-Type: application/json

{
    "username": "zowe",
    "password": "zowe"
}

HTTP/1.1 204
Set-Cookie: apimlAuthenticationToken=eyJhbGciOiJSUzI1NiJ9...; Path=/; Secure; HttpOnly

The outpu explains the status of the JWTs involved:

• Status Code HTTP/1.1 204
  Just like the login flow, the 204 No Content status means the server successfully authorized the request and performed the action without needing to return a JSON response body.

• Issuance of a New JWT
  The Set-Cookie header contains a brand new apimlAuthenticationToken. Because this is a fresh token, its expiration timer has been completely reset, granting the client a prolonged validity window.

• Invalidation of the Old JWT
  While not explicitly visible in the string text of the cookie itself, the context of a successful 204 response at this endpoint indicates that the previous JWT is now invalidated and can no longer be used for authentication.

Token format

The JWT must contain the unencrypted claims sub, iat, exp, iss, and jti. Specifically, the sub is the z/OS user ID, and iss is the name of the service that issued the JWT.

note

For more information about JWT formatting, see the paragraph 4.1 Registered Claim Names in the Internet Engineering Task Force (IETF) memo that describes JSON Web Tokens.

The JWT must use the RS256 signature algorithm. The secret used to sign the JWT is an asymmetric key generated during installation.

Example:

{
  "sub": "zowe",
  "iat": 1575034758,
  "exp": 1575121158,
  "iss": "Zowe Sample API Service",
  "jti": "ac2eb63e-caa6-4ccf-a527-95cb61ad1646"
}