Skip to main content

OAuth2 Authorization

Introduction​

When building your own healthcare App, you can use Medplum as an identity provider using the OAuth2 Authorization Code flow. Medplum provides OAuth2 endpoints to authenticate Patients and Practitioners and share data with your application.

This guide will go over the basics of Medplum's OAuth2 authorization code flow, and you can find more detailed documentation in the API Section.

We also have a minimal demo on Github that implements a simple authorization code login.

Create a Client Application​

The first step is to configure a Medplum Client Application for your application on the Medplum Server.

  1. Go to the Project Admin clients page, either by clicking "Project" on the left sidebar, or navigating to https://app.medplum.com/admin/project
  2. Click "Create New Client" to create your new ClientApplication resource
  3. Set the Redirect URI to the URL to where you would like Medplum to redirect the user after login.
  4. (Optional but recommended) Assign an Access Policy to your client to restrict the data your application has access to

Authorize your client​

Next your application will need to make an HTTPS GET request to the Medplum Server's /oauth2/authorize endpoint with the following URL parameters:

ParameterValue
client_idThe ID of your new Client Application
redirect_uriMust match exactly to the uri registered in the Medplum App (including trailing slashes, punctuation, etc.), as detailed in the OAuth2 Spec
response_typeFixed value: code
scopeFixed value: openid

See the oauth/authorize API documentation for more details about the possible request parameters.

Fetch your token​

After your user successfully authenticates, they will get an HTTP redirect response that is similar to this:

HTTP/1.1 302 Found
Location: https://YOUR_APP/redirect_uri?code=AUTHORIZATION_CODE

The last step of this flow is for your application to trade in the AUTHORIZATION_CODE for an access token.

  1. Read the code parameter from the query string to get the AUTHORIZATION_CODE
  2. Call the oauth/token endpoint with the body parameters (details: API Docs)
    • grant_type=authorization_code
    • client_id=YOUR_CLIENT_ID
    • code=AUTHORIZATION_CODE
  3. Use the access_token received in the response to make future API calls (See the Client Credentials tutorial for more details)

See Also​