OAuth 2.0 Client Example

OAuth 2.0 is a multi step process to request an authentication token, which can then be used to make authenticated HTTP requests. See Introduction to OAuth 2.0 for a thorough explanation. Iguana connects with services which use OAuth 2.0 authentication, so it is important to know how this can be accomplished.

Basic Workflow

The basic OAuth 2.0 workflow is shown in the following diagram. There are three main steps.

The client is provided an “Authorization Grant”, a permanent (or semi-permanent, expiring after a period of months or years) token used for making an initial request to retrieve an access token. These are commonly in the JWT format.
The client sends the “Authorization Grant” to the OAuth server or service provider. The server verifies the legitimacy of the “Authorization Grant” and sends back an access token to the client. This access token will be impermanent and expire after a short period of time (often one hour).
The client sends their HTTP request, with the access token in the header, to the OAuth server. The server confirms the legitimacy of the access token and forwards the HTTP request to the web service endpoint, and forwards the response back to the client.

Sample Script

The following code is an example of a translator script which sends an HTTP request to a web service endpoint.

Before this can be done the function makeOAuthCall() is called to pass the provided JWT Authorization Grant and retrieve a temporary access token.
This access token is stored on a SQLite database in the Iguana config files, taking advantage of the store2 module.
The getAccessToken() function checks if there is a token which has not yet expired in the database, and if needed uses makeOAuthCall() to get a new access token
Finally, sendHL7API() is used to create an HTTP request where HL7 data is sent in the body of the request formatted as JSON data. Note that this is was a requirement for this implementation but is not needed for all OAuth uses.

Note that this code was developed by making use of a From HTTPS “echo” channel to aid in properly formatting the headers based on the endpoint and OAuth service provider requirements. This is explained below the sample code.

-- The main function is the first function called from Iguana.
-- The Data argument will contain the message to be processed.
local store2 = require 'store2'

--auth token api call
local function makeOAuthCall()
   return net.http.post{
      url = 'https://example.com/oauth/jwt/token',
      headers = {
         ['Accept-Encoding'] = 'gzip, deflate, br',
         ['Host'] = 'example.com',
         ['Connection']= 'Keep-Alive'
      },
      parameters = {
         grant_type = 'urn:ietf:params:oauth:grant-type:jwt-bearer',
         assertion = '' -- Insert JWT here
             },
      live = false
   }
end
-- Get token
local function getAccessToken()
   -- Fetch local store for token and expires
   local returnToken = ''
   local localStore = store2.connect(iguana.project.guid())
   local token = localStore:get("token")
   local expires = localStore:get("expires")
   -- Check if token expired
   if (token == nil or expires == nil)
      or
      (expires ~= nil and (expires + 0) <= os.ts.time())
      then
      local res, code = makeOAuthCall()
      -- Parse out authentication token
      if res ~= '' then
         local resData = json.parse{data=res}
         localStore:put("token", resData.access_token)
         localStore:put("expires", os.ts.time() + resData.expires_in)
         token = resData.access_token
      end
   end
   -- assign token either from local store or from call access token
   returnToken = token
   return returnToken
end
-- Post HL7 API call
local function sendHL7API(token, hl7data)
   -- Create body HL7 json
   local body = {}
   body.body = hl7data
   local bodyStr = json.serialize{data=body}
   -- make API call
   return net.http.post{
      url = 'https://example.com/webServiceEndpoint',
      headers = {
         ['Authorization'] = 'Bearer '..token,
         ['x-ref-id'] = '12345',
         ['x-doc-type']= 'HL7',
         ['x-org-facility-id']= '6789',
         ['Content-Type']= 'application/json',
         ['Host']= 'example.com',
         ['Connection']= 'Keep-Alive'
      },
      body = bodyStr,
      live = false
   }
end

function main(Data)
   
   local token = getAccessToken()
   trace(token)
   local res, code = sendHL7API(token, Data)
   trace(code)
end

NOTE: This code is specific to JWT workflow, and each OAuth provider will have specifics that may differ from this code

Using From HTTPS “Echo” channel to build HTTP requests

This works by setting up a From HTTPS channel as follows

In the script for this channel, all that is required is

This sets up the channel so that any HTTP request sent to http://localhost:6544/echo will receive as a response an echo of the request that was made. This can now be used to see what is being sent from other HTTP requests by switching the intended URL with the URL of the echo channel. The following is an example of how the http request can be updated and changes to what is being sent in the request are updated live and observed by using trace(response) where response was the variable the http request returns to. In this manner an HTTP request can be built iteratively, confirming that it is formatted correctly at each step. The final step would be to update the URL to the desired web service endpoint.

Iguana Concepts

OAuth 2.0 Client Example

Basic Workflow

Sample Script

Using From HTTPS “Echo” channel to build HTTP requests

Related pages