## Authentication Methods Overview

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_](/content/docs/auth#browser-based-authentication/index.html).

### Patient Login

The Medplum App ( [https://app.medplum.com](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_](/content/docs/auth#server-side-authentication/index.html).

## 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](/content/docs/auth/medplum-as-idp/index.html) | (default) **Get going fast**, and don't have external compliance requirements. |
| [External IDP](/content/docs/auth/external-identity-providers/index.html) | Connect to an external IDP, like [Google Auth](/content/docs/auth/google-auth/index.html), Auth0, or AWS Cognito. |
| [Domain-level IDP](/content/docs/auth/domain-level-identity-providers/index.html) | Use your enterprise, domain-level **corporate identity solution.** |
| [Direct External Auth](/content/docs/auth/direct-external-auth/index.html) | 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**](/content/docs/auth/client-credentials/index.html) 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](/content/docs/auth/on-behalf-of/index.html) 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**](/content/docs/auth/pre-authorized-code/index.html) to mint a one-time code and redeem it at the token endpoint without an authorization redirect.

## User Management

See our [User Management](/content/docs/user-management/index.html) section for more information:

- scoping users, and distinguishing [Project vs Server Scoped users](/content/docs/user-management/project-vs-server-scoped-users/index.html)
- enabling [Open Patient Registration](/content/docs/user-management/open-patient-registration/index.html)
- using [External ID's](/content/docs/user-management/external-ids/index.html)
- creating [Custom Emails](/content/docs/user-management/custom-emails/index.html) for user invites

## Security Best Practices

Regardless of the authentication method you choose, always follow these best practices:

- **Principle of Least Privilege**: Ensure your `ClientApplication` and 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.

- [Browser-based Authentication](/content/docs/auth#browser-based-authentication/index.html)
- [Mobile activation before account creation](/content/docs/auth#mobile-activation-before-account-creation/index.html)
- [Server-side Authentication](/content/docs/auth#server-side-authentication/index.html)
- [User Management](/content/docs/auth#user-management/index.html)
- [Security Best Practices](/content/docs/auth#security-best-practices/index.html)