SMART on FHIR


The Veradigm and Altera FHIR API supports SMART on FHIR application development. For more information on SMART application development, go to HL7’s SMART App Launch page.


Authentication

There are three methods of authentication for FHIR applications. The first two methods are used by human users:

  • User/provider: authenticates with EHR application credentials
  • Patient: authenticates with patient portal (such as FollowMyHealth or AHC) credentials

In the third method, a computer system or third-party application calls the FHIR API. For example:

  • An insurance company might connect to the FHIR endpoint to query the next week of appointments for patients to perform prior authorization tasks.
  • The EHR might call the FHIR API to create data to send to another system in the FHIR format.
  • Requests for bulk data are initiated, monitored, and then eventually transferred.

Standalone launch (outside the context of an EHR)

The Veradigm and Altera FHIR API follows the standalone launch process recommended by HL7 described here. When a SMART application is launched in standalone mode, the application user selects a healthcare organization, and then enters the EHR credentials (for provider applications) or portal credentials (for patient applications).


The standalone launch for a provider application may require the user to select a patient when the patient is not included in the token response.


Note: A patient must have already registered with the patient portal (such as FollowMyHealth or AHC, formerly known as Allscripts Health Connect) to launch a FHIR application.


The application developer needs information about the client (healthcare organization) to successfully test the standalone launch. They can obtain that information directly from the client, or they can go to the Veradigm or Altera Endpoint Directory to obtain the client’s FHIR endpoint URLs. Before the developer tests the application against a client’s endpoint, they should communicate their intention to the client.


The application developer can get the Capability Statement from the metadata URL (R2 and R4) or can get the well-known SMART configuration information (R4 only) from the Veradigm and Altera FHIR API.


EHR launch (from within the EHR UI)

*The following sections apply to Veradigm Connect Integrator tiers or above.


The Veradigm and Altera FHIR API follows the EHR launch process recommended by HL7 described here. When the SMART application is launched from the EHR, the application provides two parameters:

  • iss: FHIR endpoint URL.
  • launch: Temporary launch authorization code provided by the EHR.

SMART application testing using an EHR launch in a Veradigm sandbox requires credentials. Use these credentials to connect to the appropriate Veradigm sandbox, and then sign into the EHR with the appropriate provider username and password.

Configure a SMART launch in TouchWorks EHR

Configuring a SMART application launch in TouchWorks EHR is performed by the client. Patient ID, encounter ID, and location ID context can be passed in the launch.

Note: A FHIR sandbox for TouchWorks EHR is not currently available.

  1. Log in to TouchWorks EHR with administrative privileges.
  2. Go to Site Map > TW Administration > General > Site Map Config.
  3. Click Add Site Map Entry in the group where you want to add the SMART app.
  4. In Site Map Entry Properties, define the properties of the application extension.
    • Display Name: App name.
    • Content Type: SMART on FHIR (for a DSTU2 application) or SMART on FHIR R4 (for an R4 application).
    • Address: Launch URL. TouchWorks includes a sample value that can be used to build the launch URL for the application.
    • Launch Target: Where the content should display.
  5. For the Embedded Workspace Page launch target, you can specify if the patient banner should be displayed in the workspace when the custom Site Map entry is accessed: Always, If Patient Exists (if patient is in context), or Never (default).
  6. If the custom entry should prompt the user to load a patient if a patient is not in context and the entry is accessed, select Prompt for Patient.
  7. Click Save.

The custom entry is added to the end of the selected group and displays an Added badge to distinguish it. By default, it is added as Inactive so that you can test the configuration and assign security. To test and configure access to the Site Map entry:

  1. Using the security code that is generated and displayed near the bottom of Site Map Entry Properties, grant yourself access to the new entry so that you can test it. A corresponding enforced security gate is also generated. (The security code and gate are deleted if you delete the custom Site Map entry later.)
  2. Using the same security code, grant security access for the users who should have access to the entry after you have tested it.
  3. On Site Map Config, deselect Site Map Entry Is Inactive so that the custom Site Map entry is available in application menus.

Configure a SMART launch in Veradigm EHR

Configuring a SMART application launch in Veradigm EHR is performed by the client. Patient ID context can be passed in the launch.

Note: If a vendor is testing a SMART app in the Veradigm sandbox, they cannot configure the launch button. Submit a support ticket on the Veradigm Connect portal. Set Request Type to Sandbox, and include the button label name and launch URL.

  1. Log into Veradigm EHR with credentials associated with a user who has read/write access in the Administration module.
  2. Go to Administration Module > Site Settings > SMART on FHIR Apps.
  3. Press Insert on your keyboard or click the green plus sign to display Smart App.
  4. Enter the name, description, and launch URL of the SMART app.
  5. Verify that Enabled is selected.
  6. Click OK.

Configure a SMART launch in Sunrise Clinical Manager

Configuring a SMART application launch in Veradigm EHR is performed by the client. Patient ID context can be passed in the launch.

  1. In the Sunrise Configuration tool, click the Clinical Manager Definition icon.
  2. Click Add Tab.
  3. On the Add Tab screen, complete the following:
    • Tab Name: SMART application name
    • Assembly Name: Click the File icon, select Sunrise.Clinicals.WebTab.dll, and then click Open.
    • Class Name: Sunrise.Clinicals.WebTab.WebTabController
    • Assigned Right: Select the rights from the Available Rights list to assign to the application.
  4. Click the Gear icon next to Assembly Name.
  5. On the Edit Web Tab Settings tab, click + next to Sub-Tabs, and complete the following:
    • Tab Header: SMART application name
    • Tab Type: URL
    • Browser Type: Chromium

    • Url Template: Application's launch URL (from the Veradigm Connect portal, FHIR App page, Launch URL), plus

      ?launch=<PatientGuid>&iss=<FHIRUrl>

      For example:

      https://inferno.healthit.gov/inferno/oauth2/static/launch?launch=<PatientGuid>&iss=<FHIRUrl>
  6. Click Save.

SMART on FHIR Backend Services (System Callers)

In the case of system applications, there are no user credentials on which to authenticate, and thus a form of cryptography is required.

A JSON Web Token (JWT) is used for authenticating a system application in the Veradigm and Altera FHIR API. In these types of authentication systems, there are two constraints on which the systems are trying to match:

  • Establish the identity of the caller
  • Ensure the highest level of security possible

Keys

In cryptography, there is a concept of public and private key infrastructure.

  • The private key is owned by the application developer and never shared. An option is to have only one private key to ensure it is easy to manage and not mistakenly exposed.
  • The public key is shared and used for verification with the different FHIR API implementations (such as the Veradigm and Altera FHIR API). The traditional method of creating a public key is to contact a certificate authority, and the authority signs the public key. The vendor then has a .CER file.

With that in mind, a piece of information is signed by a private key, and then verified by the public key.

When an application wants to access the FHIR API, it generates a JSON Web Token (JWT). This is referred to as the JWT Client Assertion (also known as a “system token”). This system token includes an expiration time, generally two to 20 minutes, and can only be used once.

JWKS endpoint

HL7 FHIR architects have implemented a mechanism to avoid expiring certificates. (This is different from an expiring system token.) For SMART on FHIR applications, the application developer specifies an endpoint at the time they register their application. That endpoint is where the public key can be retrieved.

It is expected that a SMART on FHIR application developer can stand up a JWKS endpoint for their public key. That way, the application developer can recycle the keys when necessary, without having to contact all the FHIR API vendors they communicate with.

Veradigm processes the certificate updates

As part of the Veradigm and Altera FHIR API implementation infrastructure, a nightly job is run “downtown” that cycles through all registered FHIR system applications. It downloads the JWKS information and updates the OAuth clients. If information has changed, then the normal mechanism of distributing OAuth information, including OAuth secrets, kicks in. That information is then downloaded to the client systems.

Authentication flow

The system application’s client credentials (client ID and client secret) establish the authentication flow. However, unlike user/provider and patient applications, the authentication workflow for system applications includes communication with only the FHIR API token endpoint, not the authentication and token endpoints.

The JWT is created programmatically, based on the information supplied by the application. For a code sample used to generate a token, go here.

Call the token endpoint with the following in the body of the POST:

  • client_assertion: the system token generated above
  • client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  • grant_type: client credentials
  • scope

If the verification passes, then an access token is granted, and the SMART on FHIR parameters are exchanged (if requested).

If you are testing the authentication in Postman, you can manually copy the access token and paste it into Authorization tab > Current Token section > Token. Enter the URL for the request, and then click Send.

  • LinkedIn
  • Twitter
  • YouTube
  • Facebook

© 2024 Veradigm LLC and/or its affiliates. All rights reserved.