☰
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.
There are three methods of authentication for FHIR applications. The first two methods are used by human users:
In the third method, a computer system or third-party application calls the FHIR API. For example:
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 and 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/organization.
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.
*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:
Currently SMART application testing using an EHR launch in a Veradigm or Altera EHR sandbox requires RDS credentials, except for TouchWorks EHR, which is browser based and doesn’t need an RDS setup. Use these credentials to connect to the appropriate Veradigm or Altera EHR sandbox, and then sign into the EHR with the appropriate provider username and password.
Configuring a SMART application launch in TouchWorks EHR is performed by the client.
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:
Configuring a SMART application launch in Veradigm EHR is performed by the client.
Configuring a SMART application launch in Veradigm EHR is performed by the client.
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>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:
In cryptography, there is a concept of public and private key infrastructure.
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.
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.
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.
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. The following image illustrates an example of how the JWT is constructed using the client ID, audience (token URL), and JTI (random number).
public static void CreateClientAssertionForSmartOnFhirBackendServices_with_allscripts_client_credentials_user_()
{
var client_id = "your client id";
var audience = "http://server.com/authorization/connect/token"; // This is the token URL of the FHIR Auth Server, and can be retrieved from FhirSettings(TokenEndpoint)
var claims = new System.Security.Claims.Claim[]
{
new System.Security.Claims.Claim("sub", client_id),
new Claim("aud", audience),
new Claim("jti", CryptoRandom.CreateUniqueId(32)),
};
var jwt = CreateJwtToken(claims, audience,
client_id);
}
Call the token endpoint with the following in the body of the POST:
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.
