When I was younger (a question about exactly how much younger is outside the scope of this article), the word “token” meant fun. You see, just a couple of times a year, I would get to go to an arcade and play some amusing video games with my friends.

These days, tokens signify security. JSON Web Token (JWT) Authentication has become one of the most popular standards for securing REST APIs. Fortunately for IRIS users, we have a straightforward way to set up applications to be protected this way. Yet, the idea is still similar to my old arcade days. If you wish to play games, you need to fetch some tokens!

The Setup

Our first order of business will be to prepare IRIS to enable users to acquire tokens. We will start by allowing the JWT authentication system-wide. To do it, we will open our System Management Portal and sign in. Then we will go to System Administration > Security > System Security > Authentication\Web Session Options. It is the same area where we authorize other authentication alternatives, e.g., LDAP and two-factor authentication. Near the bottom of the list of variants, we will find a field called "JWT Issuer Field" where we must type some value to identify the token issuer. It can be any unique string, but it is often a URL or domain. It should be agreed upon by the API and front-end developers beforehand. You may select the URL that users will send requests to when accessing the API. In my examples, I will opt for www.myurl.com.

Next, we will need to configure a web application in our System Management Portal. To do it, we will first go back to System Administration > Security > Applications > Web Applications. Then, we will select REST and set your application's dispatch class in the usual way, except this time you should check the "Use JWT Authentication" box below. You may also choose to adjust the time limits for access and refresh tokens, but the defaults are typically sufficient. Then you should save your application. The result should resemble the screenshot below.

Once we do it, IRIS will automatically add a few endpoints to our API. By default, they will be /login, /logout, /refresh, and /revoke. If you want to customize them, you can define some parameters in your dispatch class for that. For instance, if I wish to preface them all with “/auth”, you could include the following in your dispatch class:
 

Parameter TokenLoginEndpoint = "jwtlogin";
Parameter TokenLogoutEndpoint = "jwtlogout";
Parameter TokenRevokeEndpoint = "jwtrevoke";
Parameter TokenRefreshEndpoint = "jwtrefresh";

It would modify all of those endpoints by adding "jwt" in front of their names. However, for our purposes today, I prefer to leave them at their defaults.

Logging In

Now we will make sure those token machines work properly. You can access these endpoints just like you would any other API endpoint. I will give an example of accessing the login endpoint using ObjectScript and a %Net.HttpRequest object. You can customize it for your own purposes if you are accessing such an API from IRIS:
 

Class User.JWTTest Extends %RegisteredObject
{
    ClassMethod getToken(Output tokenobj) As %Status
    {
        try{
            set myreq = ##class(%Net.HttpRequest).%New()
            set myobj = ##class(%Library.DynamicObject).%New()
            set myreq.Server = "localhost"
            set myreq.Location = "/iris/jwtauth/login"
            set myreq.ContentType = "application/json"
            do myobj.%Set("user","APIUser")
            do myobj.%Set("password","mypassword")
            do myobj.%ToJSON(myreq.EntityBody)
            do myreq.Post()
            set tokenobj = ##class(%Library.DynamicObject).%FromJSON(myreq.HttpResponse.Data)
            return $$$OK
        }
        catch ex{
            write ex.DisplayString()
            return ex.AsStatus()
        }
    }
}

Here is a quick troubleshooting tip: if you are trying to access your login endpoint but keep getting a "404 not found" HTTP status, it is probably because your web application is not configured correctly, or the URL you are attempting to access is incorrect. However, you can also face a 404 error if you have forgotten to set the ContentType of the request to application/json or if you tried to use a GET request instead of a POST.

At this point, we can run the following command in a terminal session in the namespace below:

set sc = ##class(User.JWTTest).getToken(.tokenobj)

It will give us a dynamic object containing the response from the login request. If you examine this object, you will see several properties:

Therefore, we can use tokenobj.%Get(“access_token”) to obtain the token. Yet, now that we have successfully retrieved a JWT, what the heck is it?!

JWT Token Structure

A far cry from the mass-produced fake coins of my youth, each JSON Web Token is unique and distinct. The access token is encoded, which you might have guessed based on its gibberish appearance. It is also divided into three pieces separated by periods. Those segments include a header, a payload, and a signature. The first two are quite easy to decode. We can take a closer look at our terminal session with a few commands below:
 

Set token = tokenobj.%Get(“acess_token”)
Set tokenheader = $P(token,”.”,1)
Write $SYSTEM.Encryption.Base64Decode(tokenheader)
Set tokenpayload = $P(token,”.”,2)
Write $SYSTEM.Encryption.Base64Decode(tokenpayload)

After doing so, it will become apparent that those two elements are simply base64 encoded JSON objects. The header has just two fields: the alg field, which contains the signature algorithm, and the typ field, which includes the token type. In this case, we are only working with JWT tokens, which is reflected here. The token itself retains the same issued timestamp, expiration timestamp, and subscriber information we saw in the response to our original token request. It also incorporates the issuer, which should match the issuer field we entered in the System Management Portal (the web application we have signed into), and a session ID.

The third part of the token is slightly different from the other two. It is a signature that is encrypted based on the JWT Signature Algorithm setting in the System Management Portal. It is created by hashing and encrypting the contents of the previous two sections. When the server receives a token, it can recreate the signature based on the header and payload. If the reconstructed signature does not match the one on the token, the server concludes that the token has been tampered with and rejects it.

Using the Token

Now that we have a token, we get to play the game! Let’s make the dispatch class very simple:
 

Class User.JWTAuth Extends %CSP.REST
{
    XData UrlMap [ XMLNamespace = "http://www.intersystems.com" ]
    {
        <Routes>
            <Route Url="/test" Method="GET" Call="Test" />
        </Routes>
    }
    ClassMethod Test() As %Status
    {
        write "Success!"
        return $$$OK
    }
}

To access this endpoint, we must first send a request with an Authorization header containing “Bearer: ” and later the access token. We will consider the following method, which I have put into a class called User.JWTTest:
 

ClassMethod getTest(Output myreq) As %Status
{
    try{
        set sc = ##class(User.JWTTest).getToken(.tokenobj)
        set myreq = ##class(%Net.HttpRequest).%New()
        set myobj = ##class(%Library.DynamicObject).%New()
        set myreq.Server = "localhost"
        set myreq.Location = "/iris/jwtauth/test"
        set myreq.Authorization = "Bearer: "_tokenobj.%Get("access_token")
        do myreq.Get()
        return $$$OK
    }
    catch ex{
        return ex.AsStatus()
    }
}

We will now call this method in a terminal session:

set sc = ##class(User.JWTTest).getTest(.myreq)

Then we can examine the request object and its response When we review the response, we will notice that the HTTP status is 200 OK, and if we write out the response’s data, we will see “Success!” as expected.

Refreshing

Eventually, we will inevitably run into the “insert tokens to continue” screen. At that point, we will need to deal with the next endpoint, /refresh. If you paid attention to the timeout settings, you would have noticed that the refresh token always has a longer timeout compared to the access token. Once the access token has expired, the refresh token can be used to retrieve a new access token and a new refresh token, invalidating the old ones in the process, without losing a session and starting a new one. Another outcome of engaging this endpoint instead of the login endpoint is that the login will show up in the System Management Portal’s audit logging if you have it set to log login events. Since the refresh is not a true login, it will not be reflected that way in the audit log.

To use the refresh endpoint, we will send a very similar request to the login one, except that the body will be a bit different:
 

{
    "refresh_token": "(your refresh token goes here",
    "grant_type": "refresh_token"
}

When we send this request, we get a response structured exactly like the response from the login request. It always contains fresh access and refresh tokens. At this point, the old tokens get revoked, so even if your refresh token has not expired yet, you will not be able to reuse it.

If your refresh token has expired, this request will fail with an unauthorized error, and in that case, you will have to log in again.

Logging Out

Once we have played out all our tokens and collected our prizes, it is time to go home. We have two endpoints for options here: refresh and revoke. Why two, though? When we were setting up our web application, I forgot to mention the Group By ID field. Although, according to current documentation, this field should no longer be used, you may still run into older applications where it is set to a value. All applications that share a group by ID are also programmed to share authentication. It means that when you log in or out of one of them, you are logged in or out of all of them. If the group by ID is assigned, the logout endpoint will log out all sessions that share that group by ID. If the group by ID is not appointed, both endpoints function the same way (they invalidate the current access token and the associated refresh token). Those endpoints also demand a POST request with the authorization header set. However, they do not require a body, and they do not return a response with one. You will know they have completed the job successfully because the HTTP status will be 200 OK.

After that, any attempts to use the access token or refresh token will result in a 401 unauthorized HTTP status code.

I hope this article was helpful, and you can implement these tricks now. As for me, I am in the mood for some Donkey Kong!