UKNEONATALSUMMARY - Client Authentication

Overview

Each request to the BadgerNet Spine must be authenticated by including an access token as part of the request. To obtain an access token, Spine Client Systems must make a token request to the BadgerNet Identity Provider. Access tokens expire after five minutes and should be re-used for multiple requests within that time period.

1. Getting Credentials

As part of the onboarding process for a Spine Client System, a unique set of credentials will be generated which must be securely stored within the Client System and used to authenticate access token requests. It is crucial that these credentials are kept private, and they should be treated in the same way as any other system password (i.e. the Spine Client System must be a Confidential Client). The credentials will consist of two values:

Client ID: similar to a username
Client Secret: similar to a password

2. Getting an Access Token

Spine Client Systems use the OAuth 2.0 Client Credentials Flow to make a request to a Token Endpoint to obtain access tokens. The steps below explain the details of a manual HTTP request to obtain an access token, however most software platforms have widely-used authentication libraries which handle the token request process automatically. It is recommended that Spine Client Systems make use of a well-established OAuth 2.0 client authentication library for their chosen platform.

For example:

For .Net: IdentityModel
For Java: OAuth Libraries for Java

Making a Token Request

Make a POST request to the Token Endpoint which includes a body containing the following parameters:

grant_type: client_credentials
scope: fhir

The Content-Type of the message must be application/x-www-form-urlencoded.

The request must be authenticated using Basic Authentication which consists of an Authorizationheader formed by separating the credentials with a colon character, and Base64 encoding the value.

i.e. Base64("myClientId:myClientSecret") ➡️ bXlDbGllbnRJZDpteUNsaWVudFNlY3JldA==

If your client platform doesn’t support Basic Authentication, an Alternative Method can be used.

Example Token Request

NONE

POST /connect/token HTTP/1.1
Host: server.example.com
Authorization: Basic bXlDbGllbnRJZDpteUNsaWVudFNlY3JldA==
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=fhir

Token Response

The Token Endpoint responds with a JSON model containing the following elements:

access_token: this is the access token string that you should include in future requests to the Spine API
expires_in: the number of seconds the token is valid for
token_type: the token should be used as a Bearer Token in API requests
scope: the token can be used for requests to the FHIR Spine

Example Token Response

CODE

{
    "access_token": "eyJhbGciOiJSUzI.....",
    "expires_in": 300,
    "token_type": "Bearer",
    "scope": "fhir"
}

3. Using an Access Token

To authenticate requests to the Spine API, pass the access token within the Authorization header of the request as a Bearer Token.

Example Spine API Request

NONE

GET /Patient/cfe633f9-5d03-4c07-b8ba-360db7d07d4c/$everything HTTP/1.1
Host: server.example.com
Authorization: Bearer eyJhbGciOiJSUzI.....
Accept: application/fhir+json

Each access token issued by the BadgerNet Identity Provider should be re-used for multiple requests during the period for which the token is valid (i.e. five minutes), and it is recommended that Spine Client Systems include a mechanism for caching tokens and request new tokens before expiry. Once the access token expires, the Spine API will respond with an error status code: 401 - Unauthorized.

Alternative Method of Authenticating Token Requests

In circumstances where a client authentication library does not support Basic Authentication, the BadgerNet Identity Provider also allows a client to authenticate by passing the credentials within the body of the request.

In this example, the client credentials are sent alongside the other parameters in a token request, instead of within a Basic Authentication header.

Example Token Request without Basic Authentication

NONE

POST /connect/token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=fhir&client_id=myClientId&client_secret=myClientSecret