Skip to main content

Domain-level Identity Providers

A Domain-level Identity Provider (DL-IDP) is a server-level configuration that sets up an external identity provider for all users from a given domain. This identity provider will be used for all Medplum applications the user logs into, including the Medplum App. Domain-level providers are primarily used to ensure that all practitioners access Medplum data via your corporate identity solution.

Once a DL-IDP is enabled for mydomain.com, any user that attempts to sign in with an email on that domain (name@mydomain.com) will be prompted to authenticate using the configured provider. Enabling DL-IDPs will apply to all emails at that domain, including dev accounts and name+text@mydomain.com type emails.

This guide demonstrates how to set up a DL-IDP, using Okta as an example provider.

Note

Setting up DL-IDPs on the Medplum Hosted instance requires an Enterprise account. If self-hosting, setting it up requires super admin privileges.

Example: Setting up Okta as a Domain-level Identity Provider​

Okta Setup​

Enabling Okta requires configuration on the Okta side and the Medplum side. You will need to be an Okta admin to set up a App Integration on Okta.

Click on "Create App Integration"

Okta Applications Page

When prompted, choose "OIDC - OpenID Connect" and "Web Application". Click "Next".

Okta App Integration Page

Use the following settings:

  • App integration name: Choose your preferred name, or "Medplum"
  • Grant Type
    • 🔲 Client Credentials - unchecked
    • ☑️ Authorization Code - checked
    • 🔲 Refresh Token - unchecked
    • 🔲 Implicit (hybrid) - unchecked
  • Sign-in redirect URIs
  • Sign-out redirect URIs: Leave blank
  • Trusted Origins: Leave blank

Okta Integration Config Page

Scroll down to the Assignments section:

  • Assignments
    • Controlled access
      • Choose the level appropriate for your organization
      • We recommend "Allow everyone in your organization to access" as a an account on Medplum is still required to be able to access
    • ☑️ Enable immediate access - checked

Then click "Save".

Okta Assignments Page

On the next page, note the "Client ID" and "Client Secret", take note of those - they will be needed for the Medplum set up.

Medplum Setup​

To configure Okta as an external authentication provider, you will need 5 pieces of data:

  • Authorize URL
  • Token URL
  • UserInfo URL
  • Client ID
  • Client Secret

Okta uses separate domains per organization. You will need your organization's Okta server. This is called the Okta "baseUrl". You can find it in the top-left menu of the Okta admin panel by clicking on your name when logged in.

Okta Find URL

The "baseUrl" could look something like this https://dev-71569655.okta.com or could be a named subdomain like https://mydomain.okta.com. Once you have obtained it, construct the Authorize, Token and UserInfo URLs as follows:

Client ID and Client secret will be the same as those obtained at the end of the previous section.

Create a DomainConfiguration resource:

  • Add the values for the five elements above
  • Leave "useSubject" unchecked
  • Set the domain field to the users' email domain (e.g. "mydomain.com") in all lower-case. Once the resource has been saved, all new authentication requests from that domain will use Okta authentication.
Note

Configuring a DL-IDP on the Medplum Hosted service requires a Medplum team member, contact us at hello@medplum.com to enable. For those self-hosting, setup below requires super admin privileges.