Apps using System Authorization Recipe

Sample Use Case

An app builder wants to synchronize schedules between their systems and an EHR system using a backend service.  The app builder then wants to provide a mobile app to their customer (the patient) for scheduling with a clinician at a healthcare system.

In this use case, the app isn't a SMART app because it isn't providing the patient with authorization using the patient's credentials, but instead provides a service using system authorization.

Step 1: Configuring Your Data Adapter

The first step in setting up this integration is to configure your iO Data Adapter.  For example, if integrating with Epic App Orchard sandbox, you would create a new data adapter with the following settings:

You could use any form of backend authorization between your data adapter and the target system.

Step 2: Configure your Gateway

The second step in setting up this integration is to configure your iO Gateway to use the iO Data Adapter you just created.  

Step 3: Create your App

The third step in setting up this integration is to configure your App.  In this case, your App is not a SMART on FHIR app, so some values (like launch URL) are not necessary and will be ignored.

Note, for testing purposes, you can utilize your Client secret and Client Id to generate an OAuth Token from interopiO.  The following code snippet may be used by Postman to generate an OAuth Token for the interopiO where "authString" is a Base64-encoded string of: [some client id]:[some secret value].

pm.sendRequest({
  url: 'https://interopio.com/auth/token?grant_type=client_credentials', 
  method: 'POST',
  header: {
    'Accept': 'application/json',
    'Content-Type': 'application/x-www-form-urlencoded',
    'Authorization': 'Basic ' + authString
  }
}, function (err, res) {
  if (err) {
    console.log("Failed to get token from " + interopio)
  } else {
    var token = res.json().access_token;
  }
}

Step 4: Activating your App on your Gateway

After creating your app, activate it on the gateway you created in Step 2.

Step 5: Updating the App Activation to use Backend Auth

After activating your app on your gateway, additional configuration is needed for your activation.  

1. Change the activation's "EHR authentication type" to be "System", then select "Backend auth"
2. Enter your "Client ID" provided by Epic App Orchard
3. Enter your App Name from Epic App Orchard
4. Press Generate Public/Private Key Pair to generate a key pair for your activation
5. Press Download PEM File to download your PEM file.
6. Enter the token URL (ex: https://apporchard.epic.com/interconnect-aocurprd-oauth/oauth2/token) and press Save
7. In Epic App Orchard, upload the PEM file to the public key of the app

Additional Configuration for Private APIs

If your app is needing to support Epic private APIs, you'll need to reach out to our team to complete this additional configuration:

Step 1: Data Adapter External Auth

We need the following pieces for the Data adapter External Auth:

1. Pick backendAuthEnabled : true and provide the following items in the JSON configuration.

{"useStagingEnvironment":false,"backendAuthEnabled":true,"epicR4Endpoint":"https://apporchard.epic.com/interconnect-aocurprd-oauth/api/FHIR/R4","hl7OverHttpEndpoint":"https://apporchard.epic.com/interconnect-aocurprd-oauth/api/epic/2015/EDI/HTTP/HL7v2/128139","hl7OverHttpProcessingId":"T"}

1. • Save, Edit again
2. Pick the radio button “External auth”:

   • “Client ID” : client ID from Epic App Orchard for the corresponding Altais app registered there

   • “Client Secret” : We need this because Epic has private APIs which need Basic header auth value to call. This value will come from the Basic header on “Try It” feature for any of the private APIs e.g. (Authorization: Basic <TBD> 3Epic-Client-ID: {Pass Non-Production Client ID of your App})

     • 
   • Client API endpoint: https://apporchard.epic.com/interconnect-aocurprd-username/
   •