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.

Identity Provider Setup

During the initial setup process, the Orchestrate server is configured to use one or more identity providers. Each identity provider is identified with a unique ID.

The exact configuration will vary depending on your identity provider, but all will need to consider:

• Redirect URL - Where the user will be taken after authenticating.
• Client Security - How the connection is guarded against unauthorized client access.
• Claims - What information the identity provider needs to provide to Orchestrate.

Redirect URL

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 (using the base URL of your organization’s Orchestrate server). 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.

JWKS Endpoint

When utilizing client assertions, you’ll need the JSON Web Key Set (JWKS) containing the public keys for your Orchestrate server. These can be found at https://YOUR_ORCHESTRATE_SERVER_URL/smart/.well-known/jwks. You will configure this in your identity provider.

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 patient access is desired)

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.).

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.

Enabling Patient Access

When using the Identity Provider to access FHIR patients, such as through the Patient Access API, some additional considerations come into play.

Responsibilities

The following table summarizes the responsibilities of Orchestrate and the 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.

Using Microsoft Entra with Orchestrate

If you are using Microsoft Entra as your identity provider, refer to the Entra documentation on Registering an Application for instructions on how to register Orchestrate as an app. Before you start, you will need:

• The Redirect URL: https://YOUR_ORCHESTRATE_SERVER_URL/smart/signin-oidc
• The JWKS Details found at https://YOUR_ORCHESTRATE_SERVER_URL/smart/.well-known/jwks

Client Identification

Make note of the Application (client) ID and Directory (tenant) ID from the Entra application dashboard. You will need to provide this to the CareEvolution support team, and you will use it in the client credentials setup.

Client Credentials

Set up client credentials as described in Add and Manage Application Credentials. Use the following settings:

Claims

Configure the necessary claims for Orchestrate as described in Configure and manage optional claims.

• Use the token type “ID” so the claim is returned in the JWT ID token.
• Select the email, family_name, and given_name claims.

Restrict Access

Lastly, you should restrict access to authorized users/groups as described in Restrict a Microsoft Entra app to a set of users. Follow the instructions under “Assign the app to users and groups to restrict access” to select which users/groups should have access to the Orchestrate server.