To begin, you must first create a developer account and register your application. When you register your application, you will need to have a callback URL (aka redirect URI) to assign to your application, which will be used during the authorization flow. If you will be creating a mobile application, or a web application that cannot securely store the Client Secret, you will also need to check the Use PKCE for Authentication checkbox to enable the PKCE authorization flow.
In addition, you need to define the scope, which is used to define the authorization components of the Health Chain customer that will be using your application. The Health Chain API has implemented the SMART App Launch: Scopes and Launch Context to manage access to a Health Chain customer's data.
Currently, the following scopes are available and enabled by default:
| Scope | Grants |
|---|---|
| https://hcdeveloperportal.onmicrosoft.com/fhir/patient.all.read | This scope permits your application to access the supported resources for the Health Chain customer that has logged into your application. |
| openid | This scope permits your application to retrieve information about the currently logged-in Health Chain customer. |
| offline_access | This scope permits your application to keep the data in your system. |
After registering your application, you will be assigned a Client ID and Client Secret. Store your Client Secret in a safe location. The Client Secret should only be used if it can be kept confidential, such as communication between your server and the Health Chain API.
Note: If the Code Secret can not be safely stored, you will need to implement the PKCE authorization flow, which is detailed in the Proof Key for Code Exchange (PKCE) Application Code Flow section below.
You will use the Client ID and Client Secret that you received after registering your application in an exchange with the Identity Server to receive your JSON Web Token (JWT).
Standard Authorization Code Flow
In the standard authorization code flow, to connect to the Patient Access API, you will need to use the OAuth 2.0 and OpenID Connect (OIDC) flow for authentication. This flow should only be used by sites that can safely protect the Client ID and Client Secret, such as a site running on a secure server.
In this flow, after your application has been selected by a Health Chain customer, your application will send a request to the Health Chain Identity Server to perform authentication. Then the Health Chain Identity Server will redirect the Health Chain customer to a Health Chain login screen. There, the Health Chain user will login, and they will authorize the data that your application will be able to access on their behalf.
Upon the Health Chain customer successfully logging in and providing authorization, the Identity Server will redirect the user back to your application at your registered redirect URI, and the authorization code will be included in the query parameters. The authorization code can then be exchanged for a JWT. The JWT should be included in FHIR requests as an authentication bearer token (within the request header). This token gives your application access to the FHIR server on behalf of the Health Chain customer that logged in, allowing you to pass data back to the Health Chain customer.
Request authorization from user
To allow a user to authorize your application, direct them to Health Chain’s /authorize endpoint: https://hcdeveloperportal.b2clogin.com/hcdeveloperportal.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/authorize. This allows the user to securely login on behalf of your application.
The request must include the response_type set to code, your application’s client_id, and your application’s redirect_uri. In addition, you will need state and nonce fields that your application can use to identify the authorization request.
The following is an example of a web application's authorization request:
GET https://hcdeveloperportal.b2clogin.com/hcdeveloperportal.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/authorize?nonce=123456&response_type=code&state=123456&client_id=xX01xx001Xx&scope=openid%20read%20search&redirect_uri=https://yourhealthapp.com://redirect_uri%3A%2F%2Foauth
Authorize Components
- URL protocol: https
- Domain: The domain of the Health Chain developer portal.
- Nonce: A random string that your application generates.
- Response_Type: code
- State: A random number that your application generates.
- Client ID: The Client ID that you received when you registered your application.
- Scope: https://hcdeveloperportal.onmicrosoft.com/fhir/patient.all.read openid offline_access
- Redirect URI: endpoint on your system that receives the callback from the Health Chain API. You entered this URL when you created your application and assigned it as the callback URL.
Exchange Code for Token
After sending the authorization request, the Health Chain customer will be directed to a Health Chain sign in page through browser re-directs, where they will provide their Health Chain credentials to authenticate themselves. Upon completing sign-in, the Health Chain customer will be presented with an authorization page. Once the customer authorizes your application, your application can now exchange the code provided in the redirected request for a full token to make calls to the Health Chain FHIR server.
You will send a POST request to the Health Chain /token endpoint: POST https://hcdeveloperportal.b2clogin.com/hcdeveloperportal.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/token
The POST request must contain the following in the request body:
grant_type: "authorization_code"
code: "code-received-in-redirect-url"
redirect_uri: "https://yourhealthapp.com://oauth"
client_id: "xX01xx001Xx"
client_secret: "x10Xi20ghou"
The response body will contain the following:
{
"access_token": "xxXX889xX8jioOJInhuo899NHFUjjoierKOjOIojfoijj",
"refresh_token": "xxx880xxsijit80c",
"patient": "12345",
"scope": "search read openid",
"id_token": "xX808xkjoughou8989jiOJkIOUnogjourKJOIJOo88098n8",
"token_type": "bearer",
"expires_in": 3599
}
You can now use this token within the request header in your calls to the Health Chain FHIR server.
Proof Key for Code Exchange (PKCE) Application Code Flow
The PKCE authorization code flow is used to add security for interactions when the following conditions are true:
- There is no client secret.
- The browser or operating system is being used to perform the authentication request.
- A native mobile application is consuming the redirect from the authentication request, and performing an exchange of code for access tokens at the /token endpoint.
In the PKCE authorization code flow, your application will be responsible for generating a random string and performing a hash (SHA256 + BASE64URL) on this string. The initial string must be persisted for use at the /token endpoint, and both the hash and the hash method are presented at the /authorize endpoint.
The Health Chain Identity Server, upon receiving the hash and the method, persists this value against the issued authorization code. When the authorization code is presented at the /token endpoint, along with the initially generated string, the hash method is applied to the presented string and checked against the string presented at the /authorize endpoint. If the two match, the request to the /token endpoint is successful; however, if they do not match, the request is rejected.
To use PKCE, you must have configured your application by checking the Use PKCE for Authentication checkbox when you registered your application. When this is enabled, the following conditions apply:
- A new parameter, code verifier, is required in the request to the /token endpoint. This is a cryptographic string of sufficient entropy such that an attacker cannot predict or guess its value, as specified in section 4.1 of the Internet Engineering Task Force (IETF) RFC. This value is used with the code_challenge_method presented in the /authorize request to produce the value to check against the code_challenge, which is also presented at /authorize.
- Two new parameters, code_challenge and code_challenge_method, are required in the request to the /authorize endpoint. The code_challenge is the product of the code_verifier and the code_challenge_method. The code_challenge must be the product of the SHA256 + BASE64URL encoding, as specified in section 4.2 of the IETF RFC. The code_challenge_method applied to the code_verifier as presented at the /token endpoint, which is used to check the value of code_challenge. The value of the code_challenge_method must be S256, as specified in section 4.2 of the RFC.
The PKCE processing flow is as follows:
- Your application generates a code_verifier, and computes a code_challenge using the code_challenge_method.
- Your application makes a request to Health Chain's /authorize endpoint (https://hcdeveloperportal.b2clogin.com/hcdeveloperportal.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/token).
- The Health Chain Identity Server performs standard OAuth request validation for the /authorize call.
- The Identity Server checks for the presence of the code_challenge and code_challenge_method.
- The Identity Server stores the code_challenge and code_challenge_method against the authorization code.
- The Identity Server returns an authorization code response.
- Your application presents the authorization code to the /token endpoint, including the additional code_verifier.
- The Identity Server performs standard OAuth request validation for the /token endpoint.
- The Identity Server generates its own code_challenge, using the presented code_verifier and the stored code_challenge_method.
- The Identity Server compares its generated code_challenge to the value which was presented in the initial request to the /authorize endpoint (and stored against the authorization code).
- If the two match, then an access_token is issued. If the two do not, the request is rejected.
Request Authorization from User
The following is an example of a mobile application's authorization request, where yourapp.com.appfhirexample is the mobile application identifier.
GET https://hcdeveloperportal.b2clogin.com/hcdeveloperportal.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/authorize?nonce=123456&response_type=code&state=123456&client_id=vpQE8i9lazYLshaNPV5v&scope=openid%20read%20search&redirect_uri=yourapp.com.appfhirexample%3A%2F%2Foauth&code_challenge=SSa8BbRUOZiD3YM9znT7eOnmvff7LKqR-2QlD0CKXbQ&code_challenge_method=S256
Note: There are two options for mobile application redirect URIs; that shown above or https://yourapp.com.appfhirexample. For more information please refer to the Redirect URLs for Native Apps article.
Authorize Components
- URL protocol: https
- Domain: The domain of the Health Chain developer portal.
- Nonce: A random string that your application generates.
- Response_Type: code
- State: A random number that your application generates
- Client ID: The Client ID that you received when you registered your application.
- Scope: patient/*.read openid fhirUser
- Redirect URI: endpoint on your system that receives the callback from the Health Chain API. You entered this URL when you created your application and assigned it as the callback URL.
- Code Challenge: The code_challenge must be the product of the SHA256 + BASE64URL encoding, as specified in section 4.2 of the IETF RFC.
- Code Challenge Method: The value of the code_challenge_method must be S256, as specified in section 4.2 of the RFC.
Exchange Code for Token
After sending the authorization request, the Health Chain customer will be directed to a Health Chain sign in page through browser re-directs, where they will provide their Health Chain credentials to authenticate themselves. Upon completing sign-in, the Health Chain customer will be presented with an authorization page. Once the customer authorizes your application, your application can now exchange the code provided in the redirected request for a full token to make calls to the Health Chain FHIR server.
You will send a POST request to the Health Chain /token endpoint:
POST https://hcdeveloperportal.b2clogin.com/hcdeveloperportal.onmicrosoft.com/B2C_1A_SIGNUP_SIGNIN/oauth2/v2.0/token
The POST request must contain the following in the request body:
grant_type: "authorization_code"
code: "code-received-in-redirect-url"
redirect_uri: "yourapp.com.appfhirexample://oauth"
code_verifier: "0mAXBW6gDOTERvn7jph3sqs4kgkcBh7JJ457Xxwlb7k"
client_id: "xX01xx001Xx"
client_secret: "x10Xi20ghou"
The response body will contain the following:
{
"access_token": "xxXX889xX8jioOJInhuo899NHFUjjoierKOjOIojfoijj",
"refresh_token": "xxx880xxsijit80c",
"patient": "12345",
"scope": "search read openid",
"id_token": "xX808xkjoughou8989jiOJkIOUnogjourKJOIJOo88098n8",
"token_type": "bearer",
"expires_in": 3599
}
You can now use this token within the request header in your calls to the Health Chain FHIR server.
User Information
An authenticated user may obtain their patient id by using the $userinfo operation. The patient id shall be used as a search param value for all requests within the patient compartment.
Example Request:
GET https://hdig-apim.azure-api.net/api/fhir/Patient
Example Response:
{
"id": "userinfo",
"parameter": [
{
"name": "patient",
"valueString": "2094842"
}
],
"resourceType": "Parameters"
}
Note: A patient may be linked to multiple patient records
Scenario — Using the patient id given at the $userinfo endpoint. You may find all your related patient ids with the below request:
https://hdig-apim.azure-api.net/api/fhir/Patient/${patient-id}
Example Response: