Getting an Access Token

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.

Types of Clients

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.

SMART Client Registration

HIEBus will only issue access tokens to registered applications, so you must register your SMART client with the system.

Registering Your App on the Public Test Server

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.

1. Select the app from the list in the sidebar.
2. Edit its information as needed.
3. Select “Update” to save or “Delete” to delete.

Registering Your App on a Production Server

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.

OAuth Endpoints

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.

User Permissions

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.

Scopes

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

Permission scopes control what access the resulting token will have.

Other Scopes

Other scopes request additional information in the token response, or other special behavior.

Backend Services Authorization

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:

1. Select “Use Backend Services Authentication” from your account home screen to find the client details.
2. Create a JSON Web Token (JWT) assertion using the “client ID”, “issuer”, and desired scopes.
3. Sign the JWT assertion using the “private key.”
4. Submit the JWT to the “token end point” to obtain an access token.

For more information, including detailed sequence charts, see the FHIR backend services authorization guide.

Generating Test Tokens

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.