Medplum SSO and identity integration guide

Which Medplum SSO setup fits your identity estate

Medplum Auth handles OAuth, OpenID Connect, SMART-on-FHIR and client credentials, so the main decision in an SSO project is how each identity from your corporate provider maps to a Medplum user, a role and an access policy. Settle that mapping before any configuration starts, because it decides who can open clinical records, which applications can launch from the EHR context, and which integrations can read or write data. Most rework in these projects traces back to a mapping that was never written down.

The job is harder than connecting one provider. A health platform rarely has a single identity source. Clinicians may sign in through one corporate directory, contractors through another, and partner staff through a third. Domain-level routing has to send each email domain to the correct provider, and you need a defined outcome for a person who exists in two providers. Medplum documents support for Medplum as an identity provider, external providers such as Google, Auth0 or AWS Cognito, domain-level corporate providers, client credentials for server-to-server access and multi-factor authentication. Multiple external providers for SSO, such as Okta, Azure and Auth0, are listed on the pricing page as an enterprise feature, so confirm the edition you need before you design around it.

MFA enforcement is a separate decision from provider choice. Decide whether MFA is enforced by the corporate provider, by Medplum, or by both, and confirm what happens when a user signs in through a route that does not carry the MFA result. Test each role with real accounts, including break-glass administrators, and confirm how a revoked provider account is removed from Medplum. Ask the vendor to confirm session lifetime, token expiry and how deprovisioning reaches existing sessions, because those answers determine your offboarding procedure more than the login screen does.

Self-hosting changes who owns the configuration. The Medplum Auth components ship as part of the platform, so provider registrations, redirect URIs, signing settings, client secrets for integrations and domain routing all live in your deployment and in your team's hands. Each upgrade may touch those settings, so add identity flows to the upgrade test plan rather than treating them as a one-time setup. Before design begins, inventory your identity sources, list which applications are SMART launches and which are server integrations, write the role mapping, and confirm the enterprise features your routing requires.

The Medplum auth components you will configure

Medplum SSO is not one setting. It is a set of authentication components, each with its own configuration, and several of them store state that must survive restarts and upgrades. The cards below cover the auth model, the identity provider options, the state stores beneath them and the login surfaces users and applications touch.

Medplum Auth and its three protocols

Medplum Auth implements OAuth, OpenID Connect and SMART-on-FHIR. Each protocol serves a different caller: users signing in to the web app, external applications requesting FHIR access, and EHR-launched apps that need patient or encounter context. Before configuring anything, list which applications will use which flow, because redirect URIs, scopes and launch parameters differ between them. Confirm the SMART-on-FHIR scopes and launch modes your target EHR or app expects against the Medplum authentication documentation.

Medplum as the identity provider

Medplum can act as the identity provider and hold user accounts, passwords and project membership itself. This is the simplest path and avoids a second directory, but it makes Medplum the system of record for user lifecycle. Decide early whether joiner, mover and leaver events will be handled in Medplum by hand or driven from your corporate directory. If the answer is the directory, Medplum-as-IdP becomes a stopgap, not the target state.

External identity providers such as Google, Auth0 or Cognito

Medplum can federate sign-in to external providers such as Google, Auth0 or AWS Cognito. Each provider needs its own client registration, redirect URI and claim mapping, and the mapping determines which Medplum profile a sign-in resolves to. Check how the provider returns email, subject and group claims, and test with accounts that are deliberately mismatched. Multiple external providers for SSO are listed as an enterprise feature on Medplum's pricing page, so confirm the edition before design.

Domain-level corporate identity providers

Domain-level identity providers route sign-in by the user's email domain, so staff from a given organization reach the correct corporate directory automatically. The design questions are which domains map to which provider, what happens to a user whose domain is not registered, and whether a single domain can point to more than one provider during migration. Build a table of domains and owners, and agree who approves changes to it, because a wrong mapping sends users to the wrong tenant.

Client credentials for server-to-server access

Client credentials let integrations, Bots and backend jobs authenticate without a user present. Each integration should get its own client with the narrowest access policy it needs, and secrets should be rotated on a schedule your security team can audit. Record which system owns each client, what FHIR resources it may read or write, and how revocation works when an integration is retired. Shared clients across several services make later access reviews very hard.

Multi-factor authentication policy

Medplum supports multi-factor authentication, but the enforcement point matters. Decide whether MFA is required for every login, only for administrators, or only for sessions reaching clinical data, and whether your external identity provider already enforces it. Enforcing MFA in two places can lock out users, while enforcing it in neither leaves gaps. Document the policy, test enrollment and recovery paths, and confirm with your security team how MFA evidence will be retained for assessments.

Server, PostgreSQL and Redis state

The Medplum server holds session and configuration state in PostgreSQL, with Redis used as its cache. Losing or misconfiguring either store can invalidate sessions, break provider configuration or produce confusing sign-in failures across replicas. Plan database backups, Redis persistence expectations and network access rules, and test a restore that includes identity configuration. Confirm with your platform team how Redis failover behaves before relying on it for session continuity.

Web app and SDK as login surfaces

The Medplum web app and the SDK are where users and applications start the login and launch flows. Each surface needs its redirect URIs registered with the identity provider, and mismatches are a common cause of failed sign-ins after a hostname or certificate change. Inventory every front end, custom app and launch point, including staging environments, and register them consistently. Test the complete sign-in path from each surface after any DNS or TLS change.

Choosing the identity model before you configure anything

This table compares the four identity models Medplum supports, showing when each fits and what it asks of your team over time. Read each row against your own user population, because ownership of user lifecycle, offboarding and MFA enforcement moves between Medplum and your identity provider depending on the model you pick.

Model	When it fits	Who owns user lifecycle and offboarding	MFA enforcement and operating cost
Medplum as the identity provider	Small or pilot user groups with no corporate directory to connect, or a non-production environment	Medplum administrators create, disable and remove users inside Medplum; every offboarding is a manual step	MFA is set within Medplum; your team must track it separately from corporate policy and audit it yourself
Single external provider (Google, Auth0 or AWS Cognito)	One user population that already lives in that provider, such as a single product team or partner group	Lifecycle follows the external provider's account state; confirm how disabled accounts reach Medplum sessions	MFA comes from the external provider's settings; confirm enforcement scope for each user group
Domain-level corporate provider (Okta or Azure AD)	Workforce access across clinical, operations and IT staff who already sign in through corporate identity	Joiner, mover and leaver events stay in the corporate directory; your identity team owns deprovisioning	MFA follows corporate policy, usually the strongest option; confirm that Medplum sessions honor it end to end
Client credentials for server-to-server integrations	Systems, interfaces or Bots that call the FHIR API without a human signing in	No person to offboard; your team owns secret issuance, rotation and revocation for each integration	MFA does not apply to machine access; protect secrets through vault storage, scoped permissions and rotation schedules
Multiple external identity providers	Organizations that need several identity sources connected to one Medplum tenant	Lifecycle spans more than one directory, which raises reconciliation effort	Listed as an enterprise feature on Medplum's pricing page; confirm entitlement before designing around it

How to build Medplum SSO in sequence

This sequence takes Medplum from a configured corporate identity provider to working user login, role-based project access, MFA, SMART-on-FHIR app launch and client credentials for integrations. Each step ends with a check so the team knows it is safe to move on.

Confirm the identity provider OIDC configuration and claims
The identity team confirms the OpenID Connect settings in Okta, Azure AD, Google or Auth0: the issuer URL, the client ID and secret for the Medplum application, the scopes granted, and the claims that will carry identity and group membership. Write down the exact claim names, such as the email, name and group claims, because later steps depend on them. Ask the IdP administrator to confirm whether group claims are emitted in the ID token or require a separate userinfo call. Done means you can open the issuer's discovery document in a browser and every value you plan to use appears there, and a sample token from a test user shows the expected claims.
Register Medplum redirect URIs with the provider
Register the Medplum callback URLs in the identity provider's application settings for each environment, including the Medplum server and web app hostnames your deployment uses. The redirect URIs must match exactly, including scheme, host, port and path, because the OIDC flow rejects any mismatch. Confirm the exact callback paths against the Medplum authentication documentation for your version rather than assuming them. Done means the provider's allowed redirect list contains the entries for every environment, and an attempted login from an unregistered host fails with a redirect error, which confirms the restriction is working.
Configure the domain-level identity provider in Medplum
Create the external identity provider record in Medplum for your email domain, using the issuer, client ID and secret from step one. Medplum's domain-level provider configuration lets users whose email matches your domain be routed to the corporate IdP at sign-in. Confirm with your Medplum administrator whether your plan and version support multiple external providers, since the pricing documentation lists this as an enterprise feature. Done means a sign-in with a corporate account redirects to the IdP, returns to Medplum, and creates or matches a Medplum user, with the login recorded in your audit trail.
Map groups and attributes to project membership and policies
Translate the IdP groups or attributes into Medplum project membership and access policies. Decide which groups grant project membership, which roles map to clinical, administrative or read-only access, and which accounts are never granted admin rights through SSO. Keep the mapping in version-controlled configuration so changes are reviewed. Involve your privacy or compliance lead in the access design, since it determines who can see protected health information. Done means a non-admin test account in each mapped group receives only the intended membership and policy, and a user outside every mapped group is refused access.
Enable MFA at the correct layer
Decide whether multi-factor authentication is enforced in the identity provider, in Medplum, or both, and document the decision. Enforcing MFA in the IdP covers every application that uses it, while Medplum-side MFA applies to accounts that authenticate directly. Confirm which factors are accepted, how recovery works and whether break-glass accounts are excluded from SSO. Done means a test user is prompted for the second factor on every fresh sign-in, and an account without the factor enrolled cannot complete login under your policy.
Register SMART-on-FHIR apps and test the launch
Register each SMART-on-FHIR application in Medplum, specifying its launch type, redirect URI and requested scopes. Limit scopes to the FHIR resources each app needs, and review any app that requests broad access before approval. Test an EHR-style launch and a standalone launch with a non-admin clinical test user, and confirm the token response contains only the granted scopes. Done means the app completes launch, receives a token with the expected scopes, and cannot read resources outside those scopes when tested against a restricted resource.
Issue client credentials for server-to-server integrations
Create client credentials for each back-end integration, such as an interface engine or scheduled Bot, and give each one its own identifier and a narrowly scoped access policy. Store secrets in your secrets manager, set a rotation process with an owner, and never reuse a human user's account for integrations. Decode a sample access token to inspect the subject, scopes and expiry before the integration goes live. Done means the integration obtains a token, reads only the resources its policy allows, and a token inspection confirms the expected client, scope and expiry values.

What drives SSO effort and how to keep it down

This table lists the factors that expand Medplum SSO work and the design choices that keep each one contained. Read each row as a decision: the cost sits in the number of identity providers, groups, client credentials, environments and evidence obligations, so reducing those counts is the main lever. The biggest saving usually comes from one primary identity provider with a clear group-to-role mapping and a short list of scoped client credentials.

Driver	Why it adds effort	How to keep it down
Identity providers and domains	Each external IdP or corporate domain needs its own connection, claim mapping, test cases and ownership of certificates or secrets.	Standardize on one primary IdP for staff. Add domain-level providers only for a named business need, and confirm with Medplum which providers its plan supports.
Group and role model	Every IdP group that maps to a Medplum role or access policy must be designed, reviewed and tested, and drift between the IdP and Medplum creates access errors.	Define a short role catalogue before configuration. Map IdP groups to roles in one place, and keep group names owned by the identity team.
SMART apps and client credentials	Each SMART-on-FHIR app launch and each server-to-server integration needs its own client, scopes, secret rotation and review.	Keep the number of SMART apps and client credentials small. Scope each credential to the minimum resource types and operations it needs, and retire unused clients on a fixed review cycle.
Environments (dev, staging, production)	Each environment needs its own redirect URIs, IdP applications, test users and secrets, so every change is repeated per environment.	Use infrastructure-as-code or a documented runbook to apply identity settings identically across environments. Keep test identities in non-production only.
MFA and conditional access	Requirements such as step-up authentication for clinicians, device or network conditions, and session lifetimes must be agreed with the IdP team and tested end to end.	Write the MFA and session policy once, enforce it at the IdP where possible, and confirm which controls Medplum enforces itself versus those inherited from the IdP.
Audit and compliance evidence	Assessors commonly ask for access reviews, change records for identity settings, and logs showing who signed in and which app or client acted.	Decide the evidence list up front, such as exported group-to-role mappings, sign-in logs and client credential inventories. Confirm retention with your compliance lead, since DeployOpen prepares evidence but does not issue assessments.

How SSO differs across self-hosted deployment models

The AWS deployment with CDK and CloudFormation is the option Medplum's self-hosting docs recommend, so it is the baseline most teams will compare other paths against. Identity configuration follows the infrastructure: the load balancer, certificate, and DNS record that expose the Medplum API and app determine the public hostname that your identity provider sees.

What to plan for:

Public hostname: Choose the API and app domains before registering the application with your identity provider, since changing them later means updating every redirect URI.
TLS termination: Confirm where TLS ends (load balancer or application) and that the certificate covers each hostname used for sign-in.
Redirect URIs: Register one set per environment (development, staging, production) rather than sharing a single callback across them.
Stack parameters: Keep the domain and identity settings in version-controlled CDK configuration so each environment's values are reproducible.
Rollback: Test a redeployment in a non-production stack to see which identity settings are recreated and which must be re-entered.

Before relying on this path, confirm with Medplum's self-hosting documentation which identity settings the CDK stack exposes and which you must set after deployment.

Securing logins, tokens and integration secrets

These cards cover the controls that decide whether Medplum SSO is trustworthy after go-live. Each one addresses a point where a login, token or integration credential can be copied, reused or changed without a record. Review them together with your identity provider settings and your own compliance obligations, since Medplum's compliance documentation states that compliance is a shared responsibility between Medplum and its customers.

Client secret storage

Client credentials used for server-to-server integrations are secrets that Medplum must be able to read at runtime, so they belong in a dedicated secrets manager rather than in configuration files, container images or CI variables that many people can read. Confirm where each integration secret lives, who can retrieve it, and how it is rotated when a team member leaves or an integration is retired. Record the owner of every client credential.

Short token lifetimes

Access tokens issued through Medplum Auth should expire quickly enough that a stolen token has limited value, and refresh behavior should be deliberate rather than defaulted. Confirm the access token and refresh token lifetimes in your Medplum configuration and in each connected identity provider, then test what happens to a clinical app session when a token expires mid-task. Document the values so auditors and security reviewers can trace them.

Least-privilege access policies

Medplum access policies control what each user, role and client can read and write across FHIR resources, so a login that works is not evidence that its permissions are correct. Map each clinical and integration role to the resource types it needs, and test denied requests as carefully as allowed ones. Review policies whenever a new resource type or Bot is added, because broad policies tend to accumulate over time.

Restricting who can create client credentials

Creating a client credential grants a new non-human identity with access to patient data, so the ability to create one should be limited to a small named group and performed through a reviewed process. Confirm which administrator roles can create, modify or delete client credentials, and whether those actions are logged with the requester's identity. Ask for an inventory of existing credentials and remove any that no current integration uses.

Protecting the login redirect path

The redirect URI registered with each identity provider determines where authorization codes and tokens are sent after sign-in, so loose or wildcard redirect entries create an opening for token theft. Register exact callback URLs for each environment, use the authorization code flow with PKCE for browser and mobile apps, and confirm that the redirect host is served over TLS on the public domain. Re-check these entries after every domain change or environment copy.

Avoiding shared admin accounts

A shared administrator login makes it impossible to tell which person changed a policy, rotated a secret or disabled MFA, and it survives staff turnover. Give each administrator a named account in the identity provider, enforce multi-factor authentication for those accounts, and keep at least one break-glass account with its credentials held under dual control. Verify that Medplum audit records show the individual identity for administrative actions.

Change control for IdP configuration

Changes to identity provider settings, such as claim mappings, group-to-role rules, MFA requirements and domain-level connections, alter who can access patient data, so they should go through the same review and approval path as application code. Keep the IdP configuration in version-controlled records or exported snapshots, require a second reviewer for changes to group mappings, and test changes in a non-production tenant before production. Keep a dated log of each change and its approver.

How to test that SSO works and fails safely

Test SSO as a set of pass and fail cases, each with an expected outcome written down before anyone signs in. For Medplum, the identity path runs from the identity provider (Okta, Azure AD, Google, Auth0 or a domain-level corporate provider) into Medplum Auth, which issues the OAuth, OpenID Connect and SMART-on-FHIR tokens that every downstream API call depends on. Build one test matrix that covers each connected provider separately, because a working login through one provider says nothing about the mapping configured for another. Confirm the exact identity provider settings, redirect URIs and group claims with your own tenant administrators, since those values differ by environment and are not something this page can specify. Positive and negative login cases. For each provider, test a successful login by a user who belongs to a mapped group and confirm the Medplum profile, role and project membership match the mapping you designed. Then test denial: a user who exists in the identity provider but is outside every mapped group should not gain a Medplum membership, and the attempt should appear in your logs. Test MFA enforcement with a user who has not enrolled, and with one whose factor has been removed, to confirm the challenge or block happens where your access policy says it should. Record which layer enforces each control, the identity provider or Medplum, because that determines where you must look when a test fails. Token claims, scopes and SMART launch. Decode a sample access token and an ID token and check the issuer, audience, subject, expiry and any custom claims against your design. Confirm that requested scopes are granted only as your policy allows. For SMART-on-FHIR, register a test app, launch it from a test context and confirm the patient or encounter context and the granted scopes match what the app asked for. For client credentials, issue a token for an integration client, call an allowed resource, then rotate its secret and confirm the old secret is rejected and the new one works. Session expiry should be tested by disabling the user or the identity provider and confirming that existing sessions stop being honored within the window your security team accepts. Failure drill. Schedule a drill in a non-production environment that disables one identity provider and revokes one client. Confirm that new logins through the disabled provider fail, that the revoked client receives rejection, and that already-issued tokens stop working within the expiry you measured. Then confirm the break-glass path: the named emergency administrator account, its credential storage, and its MFA should be tested so that someone can still reach the platform without the failed provider. Document how long each step took, who performed it, and what the audit log shows. Repeat the drill whenever the identity configuration changes. Evidence and ownership. Keep the test matrix, results, token samples with secrets redacted, and drill records together. These records support access control evidence for HIPAA-related reviews, but they do not by themselves establish compliance, and independent assessors decide that. Ask any implementation partner to deliver the matrix, the drill script and the break-glass runbook as named deliverables in the written scope, and confirm who owns retesting after each Medplum upgrade.

Running identity after go-live

This table lists the recurring identity controls a team must own once Medplum SSO is live, with the evidence to keep and the point where each control usually slips. Read it as a checklist for assigning owners before go-live, not as a schedule, since rotation intervals and review cadence should follow your own policy and your identity provider's defaults. The main takeaway is that most post-launch identity failures come from unowned client credentials and undocumented configuration rather than from the login flow itself.

Control	What to run or record	Where it usually slips
Failed login and token error monitoring	Alerts on failed sign-ins, rejected tokens and redirect mismatches from Medplum Auth and the identity provider logs, routed to a named on-call team	Logs are retained by the IdP but never forwarded to the team that runs Medplum
Client secret rotation	A dated rotation schedule for each client credential used by integrations and Bots, with a tested procedure for updating dependent systems	Secrets are rotated in Medplum but not in the integration that holds the old value
Group membership and access policy reviews	Periodic export of users, groups and Medplum access policies, compared against current HR and role records, with signed review records	Leavers keep access through a directly assigned membership or a forgotten group
Configuration backup and export	Versioned copies of identity provider settings, claim mappings, redirect URIs and Medplum project configuration, stored outside the live environment	Configuration exists only in admin consoles, so a rebuild after failure relies on memory
Identity provider configuration record	Documented provider settings, claim-to-field mappings, allowed redirect URIs and the owner of each client credential	Ownership is recorded at setup and not updated after staff changes
MFA and sign-in policy checks	Confirmation that MFA enforcement applies to every path users can reach, including external and domain-level providers	Policy changes in the IdP do not reach apps that authenticate through a second provider
Identity changes during Medplum upgrades	A test of login, token issuance and SMART app launch on each minor version in sequence, with rollback notes for identity settings	Teams upgrade to a later version directly and only discover identity behavior changes in production
Vendor advisory tracking	A named owner who follows Medplum releases and applies security patches within the vendor's stated targets for critical and high vulnerabilities	Patch windows are planned around clinical use, and the identity components are left on an older version

How a SMART-on-FHIR launch uses Medplum Auth

A SMART-on-FHIR launch is the sequence that lets a third-party app obtain a token from Medplum Auth so it can read or write FHIR resources on a user's behalf. Medplum Auth implements OAuth, OpenID Connect and SMART-on-FHIR, so the app starts an authorization request, the user authenticates, and the app receives an authorization code that it exchanges for a token. The token carries the scopes the app asked for and the launch context, and the FHIR API enforces those scopes on every request. For a self-hosted deployment, your team should confirm with the vendor documentation exactly which SMART launch modes and scope formats your chosen Medplum version supports before writing app requirements.

The token alone does not decide what data the app sees. The Medplum user who signs in and the project membership tied to that user set the outer boundary, because the app can only reach resources that user is permitted to access within that project. A requested scope narrows the token further but cannot widen what the user is allowed to do. In practice, this means access policy design and project membership are part of the security review for every SMART app, not an afterthought. Ask your implementation partner to document, for each app, which user populations and project memberships are expected to launch it, and to test a user outside those groups to confirm the request is refused.

Where the identity provider's login sits depends on how the user is authenticated. When Medplum is the identity provider, the sign-in form is served by Medplum Auth during the authorization step. When a domain-level corporate identity provider or an external provider such as Google, Auth0 or AWS Cognito is configured, the user is redirected to that provider for login, and Medplum then issues its own token after the external identity is accepted. Multi-factor authentication is supported by the platform, but whether it is enforced at the Medplum step, at the identity provider step, or both is a design decision. Document which layer enforces it, because an app launch that skips the external login would bypass that control.

Several decisions should be settled before the first SMART app goes live. Choose whether each app uses the public launch flow or a confidential client, define the scopes each app needs and reject any that are broader, decide which Medplum project and membership model separates production data from test data, and agree how a user who leaves the identity provider loses access to active apps. Plan verification by running a launch as each user role, checking the token contents against the requested scopes, and confirming that revoking the user or the membership stops further access. Costs for this work come from the number of apps, the identity providers involved and the testing effort, and a quote should list each of those items separately.

Questions teams ask before configuring Medplum SSO

How much does Medplum SSO configuration cost?

The cost depends on the work scope, not on a fixed rate. The main drivers are how many identity providers you connect, whether you need domain-level corporate login, how much group and role design the access policy requires, and whether SMART-on-FHIR app launch and client credentials for integrations are in scope. Your Medplum edition also matters. Medplum's pricing page lists hosted plans and self-hosted editions, and it lists support for multiple external identity providers, such as Okta, Azure and Auth0, as an enterprise feature. Licensing and services are separate costs. Ask for a quote that splits one-time configuration, testing and documentation from any recurring support or retainer, and that names the identity providers and environments covered.

How long does it take to set up Medplum SSO?

The duration depends on the same drivers as cost: the number of identity providers, the complexity of group-to-role mapping, how many environments need configuration, and how quickly your identity team can respond. A single provider with a clear access policy and ready test accounts is far simpler than several domain-level providers with MFA rules and integration clients. Most delays come from waiting on IdP admin access, unresolved group design decisions and sign-off on the access policy, not from the Medplum configuration itself. Ask for a schedule tied to milestones (design sign-off, test environment, pilot users, production cutover) so that each dependency has a visible owner and date.

What does our team need to provide for Medplum SSO?

Four inputs decide how smoothly the work goes. First, administrator access to each identity provider, with rights to create applications, manage groups and change MFA policies. Second, a written group design that maps corporate groups to Medplum roles and projects, including who approves changes. Third, test accounts for each role, including users who should be denied access, so you can verify both paths. Fourth, a signed-off access policy covering session lengths, MFA requirements, and who may register client credentials for server-to-server integrations. You will also need to decide the redirect URIs and the environments (development, staging, production) that each identity configuration will cover.

Can our own team configure Medplum SSO without a partner?

Yes, a capable internal team can configure a single identity provider, provided it has administrator access to that provider and experience with OAuth 2.0 and OpenID Connect. Medplum's authentication documentation covers external identity providers, domain-level identity providers, client credentials and multi-factor authentication, so the configuration steps are documented. The harder work is the access policy: deciding who gets which role, how MFA is enforced, and how access is removed when people leave. Consider a partner when you connect several identity providers, need evidence for a HIPAA or SOC 2 assessment, must cut over many users at once, or lack staff who can own the configuration after handover.

Which Medplum edition supports multiple identity providers?

Medplum's pricing page lists multiple external identity providers for SSO, such as Okta, Azure and Auth0, as an enterprise feature. The edition therefore determines which identity features you can use, so confirm the feature list before you design the integration. The pricing page lists hosted plans (Free, Production, Premium and Enterprise) and self-hosting options (a free Community option and custom-priced Enterprise Self-Hosted). Do not assume that a self-hosted Community deployment includes every identity feature available in hosted plans. Ask Medplum in writing which identity features your chosen edition includes, and record the answer in the scope before any configuration begins.

How should MFA and access policy work with an external identity provider?

Decide first which layer is the authority for each control. Medplum supports multi-factor authentication, and external identity providers also offer their own MFA and conditional access rules. Running both without a plan can lock out users or create gaps. A common design is to enforce strong MFA at the identity provider, then map groups to Medplum roles and project membership, so that access follows the directory. Document session lengths, step-up requirements for administrators, and who approves role changes. Review the Medplum authentication documentation for the specific options available in your edition, and test each path with the role accounts you created.

What usually breaks during a Medplum SSO integration?

Most failures are configuration mismatches rather than defects. Common causes include redirect URIs that differ by a trailing slash or protocol from what the identity provider expects, incorrect issuer or discovery URLs, and group or role claims that the identity provider does not send, or sends only for some users. Users may land in the wrong project or lose access after a directory change. Client credentials for integrations can fail after a secret rotation that was not propagated to the consuming service. Check token claims with a test account before you enable production logins, and keep a documented rollback path to the previous login configuration.

How does SMART-on-FHIR app launch fit with Medplum SSO?

Medplum Auth supports OAuth, OpenID Connect and SMART-on-FHIR, so SMART app launch uses the same authorization server as your user logins. The design work is deciding which applications can request which scopes, how launch context such as patient or encounter is granted, and which users may approve access. Register each SMART application as a client with the narrowest scopes that work, and test each launch path with the role accounts that will use it. Confirm the exact SMART launch flows and scope handling for your Medplum version in the authentication documentation, since these details change between releases.

How DeployOpen scopes and hands over Medplum identity work

DeployOpen plans, implements, tests and documents Medplum SSO and identity integration inside your own infrastructure, including connections to your corporate identity providers and access policy design. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Inventory which identity providers, such as Okta, Azure AD, Google or Auth0, must sign users into Medplum.
Confirm whether domain-level corporate identity and SMART-on-FHIR app launch are in or out of the written scope.
Define which client credentials integrations need, the MFA requirements and the access policy roles to be designed.

How we build

Configure Medplum Auth for OAuth, OpenID Connect and SMART-on-FHIR flows against your chosen identity providers.
Set up client credentials for server-to-server integrations with scoped access and documented ownership.
Test sign-in, MFA enforcement, role mapping and token behavior in a non-production environment before cutover.

How we hand over

Deliver written configuration records covering each identity provider connection, redirect settings and access policies.
Document the test cases run, their results and the known limits of each integration path.
Walk your identity and platform staff through rotation, offboarding and troubleshooting steps for the integration.

How we support

Offer ongoing support and upgrades as a retainer, covering identity configuration changes after Medplum version upgrades.
Re-test sign-in and client credential flows whenever your identity provider or Medplum version changes.
Ask any support provider to confirm response scope, severity handling and what the retainer excludes before signing.