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.
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.
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.
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.
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.
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 ✔️
