Securing your APIs with OAuth 2.0 in InterSystems API Management – Part 2

In this 3-part series of articles, is shown how you can use IAM to simply add security, according to OAuth 2.0 standards, to a previously unauthenticated service deployed in IRIS.

In the first part, was provided some OAuth 2.0 background together with some IRIS and IAM initial definitions and configurations in order to facilitate the understanding of the whole process of securing your services.

This part will now discuss and show in detail the steps needed to configure IAM to validate the access token present in the incoming request and forward the request to the backend if the validation succeeds.

The last part of this series will discuss and demonstrate the configurations needed to IAM generate an access token (acting as an authorization server) and validate it, together with some important final considerations.

If you want to try IAM, please contact your InterSystems Sales Representative.

Scenario 1: IAM as an access token validator

In this scenario, it will be used an external authorization server that generates an access token in a JWT (JSON Web Token) format. This JWT is signed using the algorithm RS256 together with a private key. In order to verify the JWT signature, the other party (in this case IAM) needs to have the public key, provided by the authorization server.

This JWT generated by the external authorization server also includes, in its body, a claim called “exp” containing the timestamp of when this token expires, and another claim called “iss” containing the address of the authorization server.

Therefore, IAM needs to verify the JWT signature with the authorization server’s public key and the expiration timestamp contained in the “exp” claim inside the JWT before forwarding the request to IRIS.

In order to configure that in IAM, let’s start by adding a plugin called “JWT” to our “SampleIRISService” in IAM. To do so, go to the Services page in IAM and copy the id of the “SampleIRISService”, we are going to use that later.

After that, go to Plugins, click the “New Plugin” button, locate the “JWT” plugin and click Enable.

In the following page, paste the “SampleIRISService” id in the “service_id” field and select the box “exp” in the “config.claims_to_verify” parameter.

Note the value of the parameter “config.key_claim_name” is “iss”. We are going to use that later.

Then, hit the “Create” button.

Done that, go to the “Consumers” section in the left menu and click in our previously created “ClientApp”. Go to the “Credentials” tab and click the button “New JWT Credential”.

In the following page, select the algorithm used to sign the JWT (in this case RS256) and paste the public key in the field “rsa_public_key” (this is the public key provided to you by the authorization server in PEM format).

In the “key” field, you need to insert the contents of the JWT claim that you entered in the field “config.key_claim_name” when adding the JWT plugin. Therefore, in this case, I need to insert the content of the iss claim of my JWT, which, in my case, is the address of the authorization server.

After that, click on “Create” button.

Now, with the JWT plugin added, it is no longer possible to send the request with no authentication. As you can see below, a simple GET request, with no authentication, to the URL

http://iamhost:8000/event/1

return an unauthorized message together with the status code “401 Unauthorized”.

In order to get the results from IRIS, we need to add the JWT to the request.

Therefore, first we need to request the JWT to the authorization server. The custom authorization server that we are using here, returns a JWT if a POST request is made together with some key-value pairs in the body, including user and client information, to the following URL:

https://authorizationserver:5001/auth

Here is what this request and its response looks like:

Then, you can add the JWT obtained from the response below in the authorization header as a Bearer Token and send a GET request to the same URL previously used:

http://iamhost:8000/event/1

Or you can also add it as a querystring parameter, with the querystring key being the value specified in the field “config.uri_param_names” when adding the JWT plugin which, in this case, is “jwt”:

Finally, there is also the option to include JWT in the request as a cookie, if any name is entered in the field “config.cookie_names”.

Continue reading to the third and last part of this series to understand the configurations needed to IAM generate an access token and validate it, together with some important final considerations.