Orchestrate Server Identity Providers

Orchestrate Server uses external OpenId Connect identity providers (such as Microsoft’s Entra or Okta) to authenticate users within FHIR’s SMART App Launch framework.

Contents

Identity Provider Setup
Client Security
Client Identification
Claims
Responsibilities
Delegated Access
Managing and Updating Access

Identity Provider Setup

During the initial setup process, the Orchestrate server is configured to use one or more identity providers. Each is identified with a unique ID. When a patient app initiates the user authorization process, the identity provider will authenticate the user and redirect back to Orchestrate’s sign-in URL with the authorization code.

The Orcherstrate sign-in redirect URL is [Base URL]/smart/signin-oidc. You will configure this in your identity provider.

Client Security

Identity provider integration supports the following methods of client authentication for security:

Client Secret
Client Assertion (public key)

In addition, Orchestrate supports PKCE to prevent CSRF and code injection attacks.

Tip
You must use either client authentication or PKCE, and can use both to maximize security.

Client Identification

During the authentication process, Orchestrate includes the name of the 3rd party application using the OIDC ACR value application. For example:

acr_values: "application:My SMART Health App"

The identity provider can use this information to let the user see/manage which applications have access their health data.

Claims

The following information must be supplied by the identity provider in the claims in the OIDC ID token:

a unique, stable user identifier (e.g., username or GUID; email address is not suitable since it may change)
first name
last name
the FHIR patient identifier(s) the user can access (if omitted, patient access is not permitted)

During the setup process, the Orchestrate team will work with you to determine which OIDC claims contain the necessary information, since this can vay by identity provider. Additionally, the team will establish other provider-specific details, such as what the FHIR patient identifiers refer to (source system, identifier type, etc.).

Responsibilities

The following table summarizes the responsibilities of Orchestrate and the identity provider.

Task	Responsible System
Authenticating the user and providing associated FHIR patients claim in either the userinfo endpoint, the access token, or the id token.	Identity Provider
Issuing an access token and refresh token to Orchestrate Server for the current user.	Identity Provider
Presenting a member selection screen where applicable.	Orchestrate Server
Presenting a consent screen based on scopes requested by the 3rd party application (e.g., Apple Health).	Orchestrate Server
Holding the list of 3rd party applications, e.g. client secret, redirect URLs.	Orchestrate Server
Issuing access and refresh tokens to 3rd party applications.	Orchestrate Server
Recording audit trail of patient resources accessed.	Orchestrate Server
Revoking access/refresh tokens as requested by member.	Identity Provider

For more information about the authorization sequence, see Authorization.

Keep in mind there are two sets of OIDC tokens:

Orchestrate access/refresh tokens are issued by Orchestrate to the patient application.
Identity provider access/refresh tokens are issued by the identity provider to Orchestrate.

Delegated Access

If a user is associated with multiple FHIR patients (such as themselves and their dependent children), Orchestrate can allow access to healthcare data from associated accounts. To enable this feature, the identity provider must provide a list of which FHIR patients the user can access. Depending on configuration, Orchestrate can receive this list through an OIDC claim in one of the following:

Access token
ID token
UserInfo endpoint

During the setup process, the Orchestrate team will work with you to determine the specific location/format of the patient access information. For example, the ID token may include a patients claim:

{
  "iss": "http://yourorchestrateserver.careevolution.com",
  "sub": "123456",
  "aud": "your_client_id",
  "exp": 1311281970,
  "iat": 1311280970,
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "patients": [ "5131bebb-6da3-4e54-b6b0-0f7a42e3d2b3", "b64e084b-085c-43b1-979a-f535ac0b1595" ]
}

Managing and Updating Access

Whenever the patient application uses a refresh token to request a new access token from Orchetrate, Orchestrate will in turn request a new access token from the identity provider. During this process:

If the identity provider rejects the refresh request (either because it has revoked a user’s access, or the user has revoked Orchestrate’s access), Orchestrate will revoke the patient app’s access tokens.
If the delegated access has changed, Orchestrate will update which patients the user has access to.

The identity provider can leverage the Client Identification provided by Orchestrate to let the user selectively revoke access for specific patient applications using Orchestrate.