Overview - Authentication and Authorization

About the process

At a high level, authentication of a SMART-on-FHIR application uses OAuth authentication. For users, this is usually the 'authorization code' workflow which broadly comprises gathering several pieces of information including login credentials and user permissions, and then submitting that information to a security endpoint in order to obtain an OAuth Access Token and a Refresh Token. These tokens enable the app to access clinical data.

How it works

Launch and Endpoint Discovery
In a typical scenario, a SMART-on-FHIR app that has been registered on the Developer Platform first obtains the URL for the security endpoint to which the app must connect to authenticate. This information is retrieved from the conformance statement that is served from the FHIR server’s /metadata endpoint.

Authentication and Consent
Once the app has the security endpoint URL, the authentication process can begin. The app identifies itself to the security endpoint using the unique identifier that was assigned to it when it was registered on the Developer Platform (this is called a Client ID), and then the app requests permission to access the FHIR resources it requires – these permissions are referred to as scopes.

The security endpoint responds with a screen that enables the user of the app to enter their login credentials and grant consent to the permission scopes that the app requested.

Authorization
Once the user authenticates and grants consent to the requested scopes, the security endpoint issues two tokens:

An Access Token, which is submitted by the app to the FHIR endpoint in the header of every FHIR request the app makes; as proof that the app and user are permitted to access the FHIR endpoint and data. This token has a fixed expiration date, beyond which it will no longer enable access to the FHIR endpoint.

A Refresh Token, which is used by the app (without requiring any additional user interaction) to obtain a new Access Token from the security endpoint once the current Access Token expires. The length of the Refresh Token's validity varies based on whether the user consented to permit the app to remain authenticated during a single user session ('online_access' scope), or permit the authentication to last across multiple sessions ('offline_access' scope).

Whenever a new Access Token is issued, a new Refresh Token is also issued. Once the Refresh Token is no longer valid, the app must prompt the user to reauthenticate. This restarts the authentication process from the beginning.

See it in action

We are currently in the process of creating:

For a detailed walkthrough of standalone authorization along with the source code, refer to the Standalone Authentication Walkthrough page
A place which contains a source code for the tutorial. This is particularly useful for those of you who would like to deploy the code yourself. Note that in such a case, you will need to Publish it via your dashboard and use your own client ID and tenant ID.