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/auth/login

• The full URL is the base URL of the API service plus /auth/login. If the application has the base URL with /api/v1, the full URL could have the format: https://hostname:port/api/v1/auth/login.

• Credentials are provided in the JSON request:

  {
      "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://localhost:10080/api/v1/auth/login" -d "{ \"username\": \"zowe\", \"password\": \"zowe\"}"

The following output describes the status of the JWT:

POST /api/v1/auth/login 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

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://localhost:10080/api/v1/auth/query"

The following output describes the status of the JWT:

GET /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"
}

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://{gatewayUrl}:{gatewayPort}/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://localhost:10080/api/v1/auth/refresh" -d '{"username":"zowe","password":"zowe"}'

The following output describes the status of the JWT:

POST /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

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"
}