Retrieving JWT access tokens

JSON Web Token (JWT) is an open standard (RFC 7519) that is used to encode user credentials so they can be securely passed to services that consume them. The IBM Streams security service grants JWT access tokens associated with a specific security realm. These tokens can be passed to other IBM Streams services belonging to the same security realm for authentication and authorization.

Obtaining token for a security realm

A JWT access token is obtained by issuing a request to the following security service REST url.

POST - https://host:port/streams/rest/security/realms/[realm]/accesstokens

Request

The request body has the following json format. The audience value is a string array identifying the IBM Streams services that will accept the access token. The audience values are described below; they can be used to restrict the access token to specific IBM Streams services or to make the token useable by all services.


{"audience":["streams"]}

The audience attribute is optional; the default value is streams if not explicitly provided. The streams value indicates that all IBM Streams services belonging to the security realm will accept the access token.

The following values can be specified in the audience array:

streams
Identifies all IBM Streams services.
streams.[namespace]
Identifies all IBM Streams services for a specific namespace.
streams-instance
Identifies all IBM Streams instances.
streams-instance.[namespace]
Identifies all IBM Streams instances for a specific namespace.
[release]-instance.[namespace]
Identifies a specific IBM Streams instance.
streams-build
Identifies all IBM Streams build services.
streams-build.[namespace]
Identifies all IBM Streams build services for a specific namespace.
[release]-build.[namespace]
Identifies a specific IBM Streams build service.

Response

The response has the following json format:


{"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9...",
 "expireTime":"[Unix-Epoch-time]",
 "issueTime":"[Unix-Epoch-time]"
}

See Processing REST API requests for more details on obtaining a JWT access token from a java program.

Token validation

IBM Streams services do the following validation of JWT access tokens:

Ensure access token has not expired.
Ensure access token issuer matches the configured security service.
Ensure access token security realm matches the configured security realm.
Ensure at least one access token audience value identifies the current service.
Validate the current operation against user roles.

Token Expiration

By default, the JWT access token expires after 4 hours. This value is configurable by setting the security.accessTokenTimeout attribute in the security service configuration. The value is expressed in seconds with a minimum value of 30 seconds.