This article describes the setup for a remote/external client application (the “client app”) to access secure xMart API endpoints. This applies both to the OData web service and the start origin web service.

Setup Summary

Who/what Action needed
Data Consumer Register client application in Azure Active Directory (obtain Client ID).
xMart service team Authorize Client ID at system-level (ie Expose an API)
Mart Admin Authorize Client ID at mart-level. See (see Authorizing a client app)
Client app Authenticate using OAuth 2 by sending client id, client secret and xMart client id (contact xMart service team for xMart client ID)
Client app Access the xMart secured API

Register client application

To be performed by the end-user

In the AzureAD Portal, get the Application (client ID) of the application that needs access to the xMart API needs is required.

If the application does not exist, create it.

Let’s call this clientID remoteClientID for future references.

image

Generate a client secret

To be performed by the end-user

In the same AzureAD page, click Certificates & Secrets > New client secret. We’ll refer to this secret by remoteClientSecret.

image

Authorize Client ID at system-level

To be performed by the xMart service team

Request the xMart team (xmart@who.int) to allow your client ID to consume xMart API.

For xMart team: In WHO AzureAD Portal, find xMart API (Env) in App Registrations. Get the clientID, we’ll call it xmartapiClientID. It will need to provided to the remote app developer.

Open the app and select Expose an API, click Add a client application and paste the remoteClientID. image

Authorize Client ID at mart-level

To be performed by the end-user

In xMart Admin UI of your mart, create or use an existing role that has DATA_VIEW permission for the mart or view(s) that need to be consumed by the remote app.

Then, in Users, click the Add a Client application button.

Fill in the remoteClientID received from previous step and wisely chosen friendly name. image

Authenticate using OAuth 2

To be performed by the client app

Request an accessToken to WHO AzureAD

POST request to https://login.microsoftonline.com/f610c0b7-bd24-4b39-810b-3dc280afb590/oauth2/token using the following body

grant_type: client_credentials 
client_id: 
client_secret: 
resource:

Note, the resource parameter is not supported by oauth2/v2.0/token, it would be require a scope instead.

The AzureAD will return an accessToken.

image

Access the xMart secured API

To be performed by the client app

This is an example of accessing the OData API, but also applies to other API end-points such as the start origin web service.

GET request to https://portal-uat.who.int/xmart-api/odata/MART/VIEW_OR_TABLE HTTP Header

Authorization: Bearer

ALLOWED ✔️

image