Authentication
This page helps you choose the correct authentication method for your application, whether it's a browser, a server, or a device. The primary goal is to guide you to the right documentation page based on your use case.
For user-facing applications (web or mobile apps), use browser-based authentication.
The Medplum App (https://app.medplum.com) is an administrative tool for clinical users and developers. Patients cannot log in to this application directly. To provide patient access, you must build a custom patient portal using the Medplum SDK.
For applications running in a trusted, back-end environment, use server-side authentication.
Browser-based Authentication
This category is for user-facing applications that connect directly to Medplum. These applications run in untrusted environments (browsers, native apps) and use identity providers to authenticate a user.
| Method | Choose to... |
|---|---|
| Medplum as IDP | (default) Get going fast, and don't have external compliance requirements. |
| External IDP | Connect to an external IDP, like Google Auth, Auth0, or AWS Cognito. |
| Domain-level IDP | Use your enterprise, domain-level corporate identity solution. |
| Direct External Auth | Authenticate directly with an external IDP token, without a token exchange flow (self-hosted only). |
Mobile activation before account creation
Some mobile apps need to verify an activation code before the patient or user account exists. For example, a clinic may create a Patient, send an activation code, and ask the patient to finish account setup in an iOS or Android app.
Do not embed a long-lived client_secret in a mobile binary. Treat native mobile apps as public clients. Use a short-lived, narrowly scoped activation credential that can only call the activation workflow. The activation workflow should validate the code, expiration, intended patient, and retry limits before creating or linking the Medplum user account. After activation, use the normal authentication flow for future sessions.
Server-side Authentication
This category is for back-end services. These applications do not directly authenticate a user but operate on behalf of an application or device. They can be used to:
- integrate with legacy systems
- connect to a medical device
- build a proxy API
- connect to a CI/CD pipeline
Use the Client Credentials Flow to allow your application to use its own client key and secret to obtain a token. When working through proxy API layers, you can enable on-behalf-of authentication with client credentials to act on behalf of other entities.
For issuer-initiated workflows such as wallet handoff or magic links, use Pre-Authorized Code to mint a one-time code and redeem it at the token endpoint without an authorization redirect.
User Management
See our User Management section for more information:
- scoping users, and distinguishing Project vs Server Scoped users
- enabling Open Patient Registration
- using External ID's
- creating Custom Emails for user invites
Security Best Practices
Regardless of the authentication method you choose, always follow these best practices:
- Principle of Least Privilege: Ensure your
ClientApplicationand user access policies are as restrictive as possible. - Secrets Management: Never store credentials or tokens directly on disk. Use a secrets management service.
- Network Isolation: Restrict host access via a VPC or firewall to prevent access from the public internet.