Skip to main content

Secure Client Requests to the Healthcare Action Engine

To fully comply with the security requirements of the CDS Hooks specification for synchronous decision support services, any client request to the InterSystems® Healthcare Action Engine’s CDS Hooks API endpoints must be authorized with an OAuth 2.0 bearer token which meets specific criteria (https://cds-hooks.hl7.org/2.0/#trusting-cds-clientsOpens in a new tab). Among other things, this bearer token must be single-use, and it must be specific to the audience (aud) endpoint for the request.

In the exercises on this page, you will add this final layer of security by configuring the Healthcare Action Engine demo instance’s built-in OAuth 2.0 server to issue tokens which meet these criteria. As with the example OAuth 2.0 workflow for fetching HL7® FHIR® data, the CDS Hooks token request in the Postman Collection uses HTTP Basic authentication, providing the client_id and client_secret as the username and password for a confidential client registered with the OAuth 2.0 server.

After you configure this second authorization workflow on your system, you will test that the authorization works by using a token to authorize a fresh discovery call.

Finally, you will complete a fully secured service call which involves three requests:

  1. A token request to the FHIR resource server’s OAuth 2.0 server, which acquires the bearer token to authorize the CDS Hooks request between the client and the Healthcare Action Engine.

  2. A token request to the Healthcare Action Engine’s OAuth 2.0 server, which acquires the bearer token to authorize the Healthcare Action Engine to fetch data from the FHIR resource server.

  3. A request invoking a Healthcare Action Engine demo rule, which provides both tokens.

Re-enable CDS Hooks Token Validation

From now on, your simulated client authorizes each request it sends to the Healthcare Action Engine with a valid bearer token, per the CDS Hooks specification. If you disabled the validation of client tokens within the Healthcare Action Engine as part of an earlier exercise, re-enable it now by performing the following steps:

  1. Access the Management Portal for the Healthcare Action Engine and switch to your Healthcare Action Engine namespace.

  2. Navigate to Interoperability > Production > Configuration.

  3. On the Production Configuration page, select the CDSHooks service from the Service column.

  4. In the settings tabs pane, select the Settings tab and expand the Security section.

  5. Clear the DisableAllTokenValidation and DisableTokenSigValidation checkboxes, as depicted in the following image:

    HAE production config with token validation enabled

  6. Select Apply.

Configure CDS Hooks Authorization

Configure Your OAuth 2.0 Server

To successfully authorize your simulated client to access the Healthcare Action Engine’s CDS Hooks endpoints, you must configure your OAuth 2.0 server to issue bearer tokens which conform to the CDS Hooks specification. See Configure the Authorization Server for guidance in this process.

For the purposes of this exercise, you can configure the OAuth 2.0 server included within the Healthcare Action Engine so that it issues CDS Hooks-compliant bearer tokens. To do so:

  1. Customize the Healthcare Action Engine OAuth 2.0 server as described in Customize a HealthShare OAuth Server.

  2. If you are not already there, navigate to System Administration > Security > OAuth 2.0 > Server within the Management Portal for your Healthcare Action Engine instance.

  3. Modify the OAuth 2.0 Authorization Server Configuration as follows:

    • Within the General tab:

      • Audience required must be selected.

      • Resource owner password credentials and Client credentials must be selected as Required grant types.

    • Within the Scopes tab:

      • Include the following scopes to the list of Supported Scopes:

        • launch

        • launch/patient

        • need_patient_banner

        • openid

        • patient/*.read

        • profile

        • user/*.read

        • user/*.write

      • Specify user/*.read as the Default scope.

Note:

Be sure to add this OAuth 2.0 server’s endpoints to the appropriate CDS Hooks allow lists.

Register a Confidential Client

Within the Healthcare Action Engine, you can register a client configuration for your OAuth 2.0 server which is compatible with the authorization workflow in this demonstration by performing the following steps:

  1. Within the Management Portal for your Healthcare Action Engine instance, navigate to System Administration > Security > OAuth 2.0 > Client.

  2. If you have not already defined an Issuer Endpoint for the OAuth 2.0 server which is authorizing access to the Healthcare Action Engine, select Create Server Description and define one. See Creating a Server Description (Using Discovery).

  3. Select the Client Configurations link associated with the OAuth 2.0 server’s Issuer endpoint.

  4. If you have already defined an OAuth 2.0 client configuration for authorizing access to the Healthcare Action Engine, select it from the Client Configurations list. If not, select Create Client Configuration.

  5. Configure and register a client configuration which meets the following criteria:

    • Client Type must be Confidential.

    • Resource owner password credentials and Client credentials must be selected as Required grant types.

    • Authentication type must be Basic.

    • Under the JWT Settings tab, you must select an appropriate algorithm in the Access token algorithms row for Signing access tokens.

If you are configuring your OAuth 2.0 server to authorize access the Healthcare Action Engine using a different workflow, edit the request 5. Acquire CDS Hooks Token for Discovery Call (and subsequent CDS Hooks token requests) appropriately.

Discover HAE Services Securely

Now that you have configured the authorization mechanism for the Healthcare Action Engine’s CDS Hooks API endpoints, you can now complete a discovery call that adheres to the security requirements of the CDS Hooks specification.

Request 5. Acquire CDS Hooks Token for Discovery Call

First, acquire a token to authorize your simulated client application’s request to the discovery endpoint by performing the following steps:

  1. Within Postman, access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and modify the Current Value of the following variables as needed:

    • hooksAuthBaseURL — the base issuer endpoint for the OAuth 2.0 server you are using to authorize access to the Healthcare Action Engine. If you are using the Healthcare Action Engine’s own OAuth 2.0 server for this purpose, you do not need to make any modifications to the Initial value, which constructs this URL using the value of haeBaseURL.

    • hooksClientID — the client ID for the OAuth 2.0 client which you registered on behalf of your simulated client.

    • hooksClientSecret — the client secret for the OAuth 2.0 client which you registered on behalf of your simulated client.

    Requests in subsequent steps use these variables to construct their target URLs.

  2. Select Save to save this update to your Variables.

  3. Select the request 5. Acquire CDS Hooks Token for Discovery Call. Note that this request is specific to the Healthcare Action Engine’s discovery endpoint (the value of the aud parameter); the token it receives cannot be used to authorize access to a different endpoint.

  4. Select Send to request a bearer token which authorizes access to the Healthcare Action Engine’s discovery endpoint.

  5. The body of the response to a successful token request includes the bearer token under the key access_token, as depicted in the following screenshot:

    Response to CDS Hooks token request

    Copy the value of access_token (excluding the quotation marks).

  6. Access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and update the Current Value of hooksToken to equal the value of access_token (which you copied in the preceding step).

  7. Select Save to save this update to your Variables.

Note:

In addition to being specific to a given endpoint (aud), a CDS Hooks bearer token is valid for a single use only. This means that in order to execute a successful request to the Healthcare Action Engine, it must be preceded by a dedicated token request like the one described in this section.

Request 6. Rediscover HAE Services (with CDS Hooks Token)

To execute the discovery request itself:

  1. Select the request 6. Rediscover HAE Services (with CDS Hooks Token) from the collection. Note that the request provides the value of hooksToken as a bearer token in its Authorization header.

  2. Select Send to send a discovery request to the Healthcare Action Engine.

If this request is successful, the body of the response contains the same information which was provided in response to the first (unsecured) discovery request that you completed.

Execute a Complete Service Call

You have now configured and tested all of the elements necessary to enable your simulated client to perform a fully CDS Hooks-compliant service call interaction with the Healthcare Action Engine using the delegated FHIR resource server access workflow.

Note:

The request for the CDS Hooks bearer token and the request for the token to access the FHIR resource server can be completed in the opposite order to the one described in the instructions which follow. All that matters is that the request to the service endpoint includes both tokens and that both tokens are valid.

Request 7. Acquire CDS Hooks Token for Service

Authorize your simulated client application’s request to the service endpoint as follows:

  1. Within Postman, access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and modify the Current Value of the following variables:

    • haeDemoRule2 — the name of the demo rule you want to invoke.

    • patientID2 — the ID for the patient whose data you want to evaluate using haeDemoRule2. The Healthcare Action Engine demo provides sample patient data for testing each synchronous demo rule; the FHIR resource server assigns IDs to the sample patients as you import this data. If you are using a HealthShare Operational Data Store FHIR endpoint as your FHIR server, you can easily search for the assigned MPIID using the Patient Registry.

    The service request invoked in steps which follow uses these variables to construct the service endpoint.

  2. Select the request 7. Acquire CDS Hooks Token for Service. Note that this request obtains a token authorizing access to the service endpoint for the rule specified by haeDemoRule2, specifically. The token is valid for a single use only.

  3. Select Send to request a bearer token which authorizes access to the Healthcare Action Engine for this service.

  4. Copy the value of access_token from the body of the response.

  5. Access the Variables tab for the Healthcare Action Engine Demo Walkthrough collection and update the Current Value of hooksToken to equal the value of access_token (which you copied in the preceding step).

  6. Select Save to save this update to your Variables.

Request 8. Acquire New FHIR Fetch Token

Unless the client is prefetching data, the client must also obtain an access token which authorizes the Healthcare Action Engine to fetch the data it requires from the FHIR resource server.

To do so, execute the request 8. Acquire New FHIR Fetch Token (Same as 3) from the collection using the same procedure that you used to execute Request 3: Acquire OAuth Access Token for FHIR Fetch. Note that unless you have made changes to your system, it is not necessary to modify any variables this time.

Be sure to update the Current value of the collection variable fhirAccessToken with the value of access_token you receive in response to this request.

Request 9. Service Request (with FHIR Fetch and CDS Hooks OAuth)

  1. Select the request 9. Service Request (with FHIR Fetch and CDS Hooks OAuth) from the collection. Note the following:

    • The target URL for this request is the service endpoint for the rule you want to invoke, haeDemoRule2.

    • The request’s Authorization header provides the bearer token to access this haeDemoRule2 endpoint.

    • The body of the service request includes the information necessary to fetch the necessary data from the FHIR resource server (including the token).

  2. Select Send.

If the request was successful, the body of the response contains any cards expected. In the screenshot which follows, the request invoked the demo rule EDSDemoVaccineMeningococcal to evaluate the sample patient Janet Jackson. The screenshot depicts an excerpt of a card in the response body, which warns the user of our simulated client application that Janet Jackson has not received a meningococcal vaccine in the last year:

Excerpt of card in response to secure service request

Alternative Workflow: Prefetch FHIR DataNext section
Previous sectionFetch and Evaluate FHIR Data
FeedbackOpens in a new tab