JSON Web Token (JWT) Authentication

Overview of JWT Authentication

A JWT is a compact, URL-safe means of authentication, authorization, or information exchange. In the case of authentication, a server provides a JWT to an already-authenticated client so that the client does not need to reprovide a password to access protected resources on the server until the JWT expires. The authentication flow can look like the following diagram:

Configuring JWT Authentication

To use JWT authentication, InterSystems IRIS must have a configuration for issuing JWTs so that the client can validate their integrity.

• The System Administration > Security > System Security > Authentication/Web Session Options page includes the following settings:

  • JWT Issuer field — Defines the iss claim in the JWT payload which identifies the issuer of the JWT to the client.

  • JWT Signature Algorithm — Determines the encryption algorithm that InterSystems IRIS uses for signing and validating the JWT.

  • Reset Key Store — Rotates the encryption keys. This invalidates all previously issued, unexpired JWTs.

Issuing JWTs is not the only configuration required. You must also configure the client receiving the JWT to accept and use them. REST web applications are among the clients that can use JWTs for authentication. The Create and Edit ApplicationsOpens in a new tab page describes these settings.

Support for JWT Usage

InterSystems IRIS supports JWT usage for authentication to a REST API and in the OAuth 2.0 framework.

With a REST API

Once configured for JWT authentication, a REST API gains four endpoints that should not be included in the UrlMap in the dispatch class:

• /login — A call to this endpoint using basic HTTP authentication or with valid credentials in the body of the request returns an access token and a refresh token that can be used in subsequent requests.

• /logout — A call to this endpoint, if not using Group-By-ID, invalidates the supplied access token and the associated refresh token. If using Group-By-ID, then all sessions with the current By-ID group are invalidated.

• /refresh — A call to this endpoint issues a new access and refresh token pair when invoked with a valid refresh token. This invalidates the previous access and refresh token pair.

• /revoke — If not using Group-By-ID, this is functionally the same as /logout. If using Group-By-ID, this revokes only the current access and refresh token pair.

You can customize the endpoint names in the dispatch class using the following:

Parameter TokenLoginEndpoint = "mylogin";
Parameter TokenLogoutEndpoint = "mylogout";
Parameter TokenRevokeEndpoint = "myrevoke";
Parameter TokenRefreshEndpoint = "myrefresh";

Accessing REST Endpoints with a JWT

You supply the access token in HTTP requests to the REST API in a header using the format of Authorization: Bearer ACCESS_TOKEN_HERE. Other than supplying this access token instead of your credentials in the request, you access your web application endpoints as normal except for the /login and /refresh endpoints. To retrieve the access token, you first access the /login endpoint.

The /login Endpoint

To access the /login endpoint and retrieve the access and refresh tokens, make an HTTP POST request without an authentication header and with your credentials in the body in JSON format as below:

{"user": "YOUR USER", "password": "YOUR PASSWORD"}

If the credentials are valid, you receive a response similar to the following:

{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2ODI3MDc0MTcuNzQ5OTQyLCJleHAiOjE2ODI3MDc0NzcsImlzcyI6IkludGVyU3lzdGVtcyIsInN1YiI6Il9TWVNURU0iLCJzaWQiOiJkWTAxYlJUMGZhQlJybldnQnEyYUZpa1ciLCJhcHAiOiIvYXBpL3R0cmcvIn0.OSxtKf2F6p23wfHKBxnPXvj6cs3fXKWNqc1c0yJ_t0Zpy5cLvLBlRTlufMQIOoNPnQHOHzcN8VWPBzisMoOM-A",
"refresh_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2ODI3MDc0MTcuNzQ5OTQyLCJleHAiOjE2ODI3MDgzMTcsImlzcyI6IkludGVyU3lzdGVtcyIsInNpZCI6ImRZMDFiUlQwZmFCUnJuV2dCcTJhRmlrVyIsImFwcCI6Ii9hcGkvdHRyZy8ifQ.-28BDQsQYtfTbMpCBxmYtbxiT4UNQSeKS7taKkzRk4tYZkE_5V_WMGffNMj-pU3NgtIku506CIcSuXIxGdEJ5Q",
"sub": "YOUR USER",
"iat": 1682707417.749942,
"exp": 1682707477
}

Using the /login access token as an example, the Authorization header for requests to your other REST API endpoints has the value of:

Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2ODI3MDc0MTcuNzQ5OTQyLCJleHAiOjE2ODI3MDc0NzcsImlzcyI6IkludGVyU3lzdGVtcyIsInN1YiI6Il9TWVNURU0iLCJzaWQiOiJkWTAxYlJUMGZhQlJybldnQnEyYUZpa1ciLCJhcHAiOiIvYXBpL3R0cmcvIn0.OSxtKf2F6p23wfHKBxnPXvj6cs3fXKWNqc1c0yJ_t0Zpy5cLvLBlRTlufMQIOoNPnQHOHzcN8VWPBzisMoOM-A

The /refresh Endpoint

You access the /refresh endpoint with an HTTP POST request without an access token. Instead, you send the following JSON-formatted data in the body of the request:

{
"refresh_token": "YOUR REFRESH TOKEN",
"grant_type": "refresh_token"
}

This returns a new access token and refresh token pair, similar to accessing the /login endpoint but without losing your session from a logout.