The FHIR Interface protects health data (PHI) by requiring authentication on all operations. With the exception of the capability information, every request must contain an access token for authorization. To get an access token, FHIR uses SMART® Authorization (also known as “SMART on FHIR”), an authentication scheme built on the OAuth2 standard.
Contents
The FHIR standard defines two types of clients: SMART clients and backend clients.
SMART clients use the SMART App Launch Framework, and can be launched from within the CareEvolution web application or standalone, such as a mobile app. These apps will use the credentials of the user (typically a patient or clinician) who’s using them.
Backend clients typically run autonomously, without any direct user input. They may be doing bulk data exports or analytics. They have special security considerations, as described in FHIR’s Backend Services Authorization Guide. They are associated with a system user rather than a patient or clinician.
HIEBus will only issue access tokens to registered applications, so you must register your SMART client with the system.
On the CareEvolution public test server, you can register your own apps by selecting “Register SMART Clients” on your account home screen.
Enter your app’s name, the OAuth redirect URI(s), and an optional client secret. If you wish to use the more secure Proof Key for Code Exchange (PKCE) authentication model, check the PKCE box.
Once you’ve registered an app, the system will assign it a client ID. This is the identifier you will use in your OAuth requests to get access tokens. You can find your client ID on the “Register SMART Clients” screen.
You may register an additional app by clicking “New” and entering the app’s details. To edit or delete an existing app.
For productions servers, you will need to contact the local site administrator to have your app registered. They will provide you with your client ID.
The OAuth endpoint information is included in the capability statement. It is recommended that you look up the OAuth endpoints programmatically rather than coding them directly into your application, in case they ever change.
An access token is associated with a specific user, and only grants permission to resources that the user would have access to in the HIEBus web client. For example, a patient user would typically only see their own patient data. A clinician user would generally see only the patients they were responsible for.
All self-registered accounts on the public test server have clinician permissions, giving you access to a set of test patient data.
If you need to access things from a patient’s perspective, you can use one of the public patient accounts for your testing. From your account home screen, select “Test Patient Accounts” to view their usernames and passwords.
When you request an access token, you need to specify which OAuth scopes you want that token to have. A token can never access more than the associated user would be able to, but scopes can be used to limit what the token allows.
Permission scopes control what access the resulting token will have.
Scope | Description | Notes |
---|---|---|
patient/*.read |
Read-only access to the current patient’s records. | Applies to the patient associated with the user account. |
patient/*.* |
Read-write access to the current patient’s records. | Applies to the patient associated with the user account. |
user/*.read |
Read-only access any resources the current user has access to. | |
user/*.* |
Read-write access to any resources the current user has access to. | |
system/*.read |
Read-only access to system records for multiple patients/users. | Only available through backend services authorization. |
system/*.* |
Read-write access to user records. | Only available through backend services authorization. |
Other scopes request additional information in the token response, or other special behavior.
Scope | Description | Notes |
---|---|---|
launch/patient |
When launching outside the EMR, prompt for which patient to select. | |
openid fhirUser |
Permission to retrieve information about the current user. | See the HL7 site for details. |
If you wish to use backend services authorization for your app, the site administrator will need to set up a system account and associated client.
For the public test server, there is already a client/account set up for your use. To obtain an access token using this method:
For more information, including detailed sequence charts, see the FHIR backend services authorization guide.
You can generate a access token for test purposes by using the “Get Access Tokens” option on your account home screen. Simply specify the desired scopes and click “Request Token.” The system will then display a temporary access token associated with your user account.