Customize a HealthShare OAuth 2.0 Server to Authorize CDS Hooks Requests

If you are deploying the InterSystems® Healthcare Action Engine alongside an instance of HealthShare® Unified Care Record (UCR) version 2022.1 or later, you can configure the HealthShare OAuth 2.0 serverOpens in a new tab to authorize CDS Hooks requests to your client applications. To do so, customize the HealthShare OAuth 2.0 server by performing the following steps:

1. Using a supported IDE, define a custom class which extends the %OAuth2.Server.JWT class. This custom class must be available within your UCR Registry namespace.

2. Within that class, implement an AddClaims() class method which adds an "iat" timestamp to the claims included in the token by the AddClaims() method of the parent class.

3. Within that class, implement a GenerateAccessToken() class method which assigns the key "subject" the value of "client_id" before invoking the GenerateAccessToken() method of the parent class. This is necessary to access FHIR resources.

4. If you are using HealthShare Unified Care Record version 2022.2 or later and you would like to include jku headers in your access tokens, the GenerateAccessToken() class method should also add a jku claim to the JWTHeaderClaims array. This should also occur before you invoke the GenerateAccessToken() method of the parent class.

   Note:

   It is not possible to customize JWT headers in versions of HealthShare prior to 2022.2.

5. Save and compile your custom class. The example which follows is a custom class implementing all the customizations described in the preceding steps (including the optional jku header):

   Class Test.EDS.Util.OAuth2.Server.Generate Extends %OAuth2.Server.JWT {
   
       /// Add a timestamp to the claims included by the AddClaims() method in the parent class
       ClassMethod AddClaims(claims As %ArrayOfObjects, properties As %OAuth2.Server.Properties, json As %DynamicObject) {
           do ##super(claims, properties, json)
           do json.%Set("iat",##class(%OAuth2.Utils).TimeInSeconds($ztimestamp,0),"number")
       }
   
       ///  Modify the properties used to generate the JWT by the GenerateAccessToken() method in the parent class
       ClassMethod GenerateAccessToken(properties As %OAuth2.Server.Properties, Output sc As %Status) As %String {
   
           // Add a jku header
           #dim tJWTHeaderClaims As %Collection.ArrayOfObj
           set tJWTHeaderClaims = properties.JWTHeaderClaims
           if 'tJWTHeaderClaims.IsDefined("jku") {
               set tNewClaim = ##class(%OAuth2.Server.Claim).%New()
               set tSC = tJWTHeaderClaims.SetAt(tNewClaim, "jku")
               $$$ThrowOnError(tSC)
           }
   
           // Assign the key "subject" to the value of "client_id".
           // Note: the method of the parent class is invoked in the %SYS namespace
           // because it calls code that is only available in %SYS.
           new $namespace
           set $namespace = "%SYS"
           do properties.ResponseProperties.SetAt(properties.CustomProperties.GetAt("client_id"), "subject")
           quit ##super(properties, .sc)
       }
   }

   

6. In the Management PortalOpens in a new tab for your UCR instance, navigate to System Administration > Security > OAuth 2.0 > Server and select the Customization tab.

7. Change the value of the Generate token class field to the name of the custom class you created in steps 1 through 5.

8. Select the General tab for your OAuth 2.0 Authorization Server Configuration and ensure that Audience required is selected.