5 Using the OAuth 2.0 protected API

5.1 Prerequisites

Prerequisites for using the OAuth protected API are as follows:

• HDR FHIR is successfully registered with an OAuth Server as a Resource Server (that is protecting its endpoints).

• A client representing the HDR FHIR API admin user has been registered with OAuth Server as an OAuth Client and is authorized to invoke HDR FHIR APIs.

5.2 How It Works

Figure 5-1 Access Token Process

1. Client application or user authenticates with the OAuth Server (at say, the /ms_oauth/oauth2/endpoints/tokens endpoint) using the client ID and secret. The client ID and secret would have been obtained at the time of registering the OAuth client with OAuth Server.

2. OAuth Server validates the client ID and secret.

3. OAuth Server responds with an Access Token.

4. Client application or user uses the Access Token to call an HDR FHIR API.

5. HDR FHIR server intercepts the request and validates the Access Token.

6. HDR FHIR API responds with requested data.

5.3 Obtaining the Access Token from the OAuth Server

The client/user can ask the OAuth Server for tokens for any of the authorized applications by issuing the following API call:

curl --request POST \
  --url https://example.oauthserver.com/ms_oauth/oauth2/endpoints/tokens \
  --header 'content-type: application/json' \
  --data '{"client_id":"CqwUDq2VQ6AH416sf7n42CZ2rNyElkDW","client_secret":"iA6bJ9OQ-tMWhVNUZylx6Km1_9tMuxVyKC4xNfWtPye72MjXyC3f1GJ38ttQ0oH9","audience":"hdr_fhir_api","grant_type":"client_credentials"}'

In this example, client_id and client_secret are assigned random representative values. You should change these values with the actual client Id and secret, obtained after registering the client with OAuth Server.

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI........N7KT4ig",
  "token_type": "Bearer",
  "expires_in":600
}

You can now extract the access_token property value from the response to make authorized requests to your API.

5.4 Calling the HDR FHIR API with an Access Token

You can use this bearer token with an Authorization Header in your request to obtain authorized access to the HDR FHIR API.

curl --request GET \
  --url  http://<SERVER BASE URL>/fhir/Medication \
  --header 'accept: application/json' \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsI........N7KT4ig'

5.5 Error Messages

Here is a list of a few common OAuth-related error messages that can be thrown by HDR FHIR APIs and the associated remediation steps.