OAuth2 Authorization Code
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.
- Go to the Project Admin clients page, either by clicking "Project" on the left sidebar, or navigating to https://app.medplum.com/admin/project
- Click "Create New Client" to create your new ClientApplication resource
- Set the
Redirect URI
to the URL to where you would like Medplum to redirect the user after login. - (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:
Parameter | Value |
---|---|
client_id | The ID of your new Client Application |
redirect_uri | Must match exactly to the uri registered in the Medplum App (including trailing slashes, punctuation, etc.), as detailed in the OAuth2 Spec |
response_type | Fixed value: code |
scope | Fixed 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.
- Read the
code
parameter from the query string to get theAUTHORIZATION_CODE
- Call the
oauth/token
endpoint with the body parameters (details: API Docs)grant_type=authorization_code
client_id=YOUR_CLIENT_ID
code=AUTHORIZATION_CODE
- Use the
access_token
received in the response to make future API calls (See the Client Credentials tutorial for more details)