Authorization flow

The Allscripts FHIR API uses OAuth 2 and Open ID Connect. It is based on the Smart Authorization description.

References:

The authorization code grant type is the only grant type supported in this release because it is considered secure. Other grant types, such as implicit flow, may be supported in future as the standards evolve.

The following diagram (from Smart) describes the authorization code flow:

Smart_Authorization

Once the patient or provider (hereafter referred to as the user) launches the app, you must authenticate the user by calling the authorize endpoint on the authorization server used by the EHR.

During the authentication step, provide the app’s client_id, but not the secret.

Note that the examples here illustrate what is happening. It is not recommended that you code an OAuth client yourself. For suggestions on OAuth clients, see link.

GET https://tw171.open.allscripts.com/authorization/connect/authorize?response_type=code&client_id=d34d06b8-63ff-414b-a93c-11dc998f54e1&redirect_uri=http://localhost:8000/launch.html&scope=launch%20openid%20profile

The redirect_uri urn:ietf:wg:oauth:2.0:oob is a special URL that is used in desktop clients. If you are developing a web client, you will use a URL pointing back to your website.

During the On Approval step, the user will be asked to log in. If they do not have credentials, they will be asked to confirm their identity before creating credentials. If this is the first time they have used the app, they will be asked to confirm that they want to use the application (authorizing the application).

After the user authenticates, you will receive an authorization code. You send the authorization code, along with the client_secret, to the token endpoint of the authorization server.

POST https://tw171.open.allscripts.com/authorization/connect/token
    code    f53e501a51f2909d1f7ac5dd0d148c46
    redirect_uri    urn:ietf:wg:oauth:2.0:oob
    client_id    C85533AE-E3A4-455C-BE5C-DAC0F695408F
    scope    patient/*.read
    client_secret    supersecret
    grant_type    authorization_code

The server returns the access token which the app then uses in subsequent calls to the API.

{
    "access_token" :  123.456.7890
    "expires_in": 1200,
    "token_type": "Bearer"    
}

Scopes

The Allscripts FHIR API authorization server uses the scopes defined for Smart on FHIR.

Confidential and public clients

The Allscripts FHIR API supports two type of clients: confidential clients and public clients.

Confidential clients are clients that can be trusted to keep the client_secret secure. Examples of confidential clients include:

Web clients written as server side HTML and where the client secret is stored on the server
Mobile clients written in the native technology of the platform

Public clients cannot be trusted to keep the secret safe.

Using a refresh token

To prevent a user from having to log in whenever the access token expires, use a refresh token. The refresh token will be valid for hours/days.

To get a new access token, call the token endpoint of the authorization server and present your bearer token.

If the bearer token has expired, you must call the authorization endpoint of the authorization server again so the user can login using their credentials.

Authorization for patient access

Certain resources and operation on the Allscripts FHIR API are not specific to a patient. For example, searching for a patient.

However, most API calls are patient specific. For example, retrieving patient demographics or problems.

In those cases the following authorization rules apply:

If the user is a patient:
- They have access to their own data.
- They have access to patients for whom they are caregivers or guardian.
- They will not have access to the data for any other patients.
If the user is a provider or other EHR user:
- They only have access to patients they are authorized to see in their EHR.
- They do not have access to patients they are not authorized to see in their EHR.
- Apps do not have access to the “break glass” privilege escalation functionality.