Get Started: Concepts: Authorization

Authorization

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

• OAuth 2
• OpenID Connect
• SMART

Note: 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 describes the authorization code flow:

Once the patient or provider (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 Allscripts EHR.

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

Note: The examples here demonstrate what is happening. It is recommended that you do not code an OAuth client yourself. For suggestions on OAuth clients, see here.

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 is asked to log in. If they do not have credentials, they are asked to confirm their identity before creating credentials. If this is the first time they have used the app, they are asked to confirm that they want to use the application (authorizing the application).

After the user authenticates, they receive an authorization code. 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

Allscripts FHIR API supports the following types of clients:

• Confidential clients: 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 and mobile clients written in the native technology of the platform.
• Public: Clients that cannot be trusted to keep the secret safe.

Tokens

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 operations on 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 a specific patient's demographics or problems. In those cases, the following authorization rules apply:

If the user is a patient or user is a proxy for 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.