Custom HTTPS Business Operation that supports OAUTH 2.0 Client Credentials

To implement a custom HTTPS Business Operation supporting OAuth 2.0 Client Credentials for receiving HL7 data, a streamlined approach can leverage InterSystems IRIS’s built-in functionalities.

Key Steps:

1. Configuration of OAuth 2.0 Settings:
   The recent version, InterSystems IRIS 2024.3, introduces simplified settings for OAuth 2.0 authentication with Client Credentials. In your Business Operation (based on the HTTP Outbound Adapter), new OAuth settings allow you to specify:

   • Access Token Placement (Header | Body | Query)
   • Grant Type (Password | JWT Authorization | Client Credentials) 1.

2. OAuth 2.0 Client Definition:
   You must configure the OAuth Client within the System Management Portal:

   • Navigate to System Administration -> Security -> OAuth 2.0 -> Client.
   • Define the Issuer Endpoint of the OAuth server, SSL/TLS settings, and supported grant type “Client Credentials.”
   • Enter the client-specific configuration (Client ID, Client Secret), which align with the requirements from the remote authentication server 2.

3. Authorization and Token Handling in Custom Code:
   In the custom Business Operation:

   • Utilize the HTTP Outbound Adapter to handle requests.
   • Use the %SYS.OAuth2 classes to manage tokens. For example:
     

     Method AuthorizeMe(Output AccessToken As %String) As %Status {
         Set isAuth = ##class(%SYS.OAuth2.AccessToken).IsAuthorized("TestClientA",,,.accessToken,.responseProperties,.error)
         If 'isAuth {
             $$$QuitOnError(##class(%SYS.OAuth2.Authorization).GetAccessTokenClient("TestClientA",,,.error))
             $$$QuitOnError(##class(%SYS.OAuth2.AccessToken).IsAuthorized("TestClientA",,,.accessToken,.responseProperties,.error))
         }
         Set AccessToken = accessToken
         Quit $$$OK
     }
     

     • Replace "TestClientA" with the Client Name configured in the Management Portal 2.

4. Payload Transmission:
   Ensure to place the access token in the request’s HTTP Headers for authentication:

   Set tSC = pRequest.HTTPHeaders.SetAt("Bearer "_AccessToken, "Authorization")
   

   This lets the remote server authenticate your application using OAuth Client Credentials 2.

Benefits:

• You don’t need to write complex custom scripts for OAuth handling; you can rely on InterSystems IRIS built-in features and toolkits.
• These configurations simplify the exchange of HL7 data securely using HTTPS and OAuth 2.0.

Additional References:

If issues arise during implementation or additional customizations are needed, consult the OAuth Integration documentation and the System Administration settings for advanced configurations 12.

Sources:

Hey Gigi.

In the past I have had to create a custom HL7 HTTP Operation that heavily relies on the code used by the built in Operation. Doing so comes with some risk risk, but in my use case it was required (the response could only be read using %Parser.ParseIOStream and not %Parser.ParseFramedIOStream). My change was effectively a copy of the SendMessage Method, with a single line changed.

In your case, I think you will want to do similar, but instead I think the following will need to be your approach:

1. Create a new Operation that copies EnsLib.HL7.Operation.HTTPOperation.
2. Add in a new Method that follows the format of what the bot has shared for the Method "AuthorizeMe", but tweaked to reference the client setup for OAuth2 
3. At the start of the existing Method "SendMessage", as a line at the start that calls the "AuthorizeMe" Method. Something like:
   1. $$$QuitOnError(..AuthorizeMe())
4. Add a new line prior to the line that makes the HTTP Request which adds in the authorisation header. Something like:
   1. Set tSC = tHttpRequest.SetHeader("Authorization","Bearer "_AccessToken)

This should hopefully add in the OAuth2 bearer token to the Http request as you need.

You will still need to configure your instance to be able to generate the OAuth token to be able to then make use of this.

If this is your first time working with OAuth2 in IRIS, I would start with making sure you are able to set this up and generate a token. Once configured within the management portal, you can try testing this by manually running the calls being made in the "AuthorizeMe" method and seeing if you get a valid token back (or add it to an adhoc classmethod so you can call that on each test instead of needing to manually run the required lines).

I've written this, it still requires a bit of work for dealing with errors correctly as it does not yet use the reply action codes correctly.