Identiy Provider

All systems making any HIE api call (except for Terminology Service) must have an "API Token". This token must be passed as "X-Auth-Token" header while making an API request.

To put in a very simplistic fashion, the following are the steps

The system and an user account for the system must be setup in the central Identity Provider (IdP). Please see the documentation regarding onboarding a system/facility for SHR integration.
- This is an offline process: an organization will request the authority (DGHS) for access to HIE (naming the components that they want to access) with intended purpose. There will be policies that the participating organization will have to comply and upon resolution of such aspects, the authority will grant access to the organization.
- Once the setup is done, the organization will be given the following details
  - API Token - this is a long living token and disclosed to and used only by organizations who have gone through the above procedure.
  - client_id - disclosed only to the organization, and this must be communicated with every API request
  - registered email and password for the user of that organization
Get hold of an "access_token" from the central Identity Provider (IdP)
- Make an HTTP POST to the IdP login api. see below for info
- an "access_token" will be returned. this access token is short lived and can be invalidated too by the user.
Make service calls with the "access_token" passed.
- Subsequent API calls to any HIE services, should pass only the "access_token". Note, at no point should you be sending your "API TOKEN" to any other service other than the IdP login service.

Authorization

Each service is responsible for deciding on authorization independently. This authorization decision depends on requesters profiles setup in IdP. For example, an organization can have rights to create a patient but not a clinical encounter. See below for more information

Additional details

Even trusted systems like SHR or MCI or other DGHS apps, must register themselves with HRM system as organizations. for example as "SHR @ DGHS MIS" or "MCI @ DGHS MIS". An api token is created for systems and provided and configured with the system beforehand.
Any invalid request with non-matching CLIENT_ID and X-Auth-Token, will result in HTTP 401 (unauthorized) error.

IdP API details

Login using IdP API

Request :

POST http://{IdP-URL}/api/1.0/sso/signin

Headers :

client_id = {client id of the user representing the organization}

X-Auth-Token = {Secret API Token given to the user representing the Organization}

Form Data :

email = {user email}

password = {user password}

Example response on successful login (HTTP Status code 200)

  "access_token": "UXmbhELOU47hC5bA7rvvtx2lMuePIF1kOTgyVAhcAX",

Example response on failed login (HTTP STATUS code 404)

{

"error": true,

"message": "Not authenticated",

"code": 401

}

Logout using IdP API

Request :

POST http://{IdP-URL}/api/1.0/sso/signout/{access_token}

Headers :

client_id = {client id of the user representing the organization}

X-Auth-Token = {Secret API Token given to the user representing the Organization}

content-type :application/x-www-form-urlencoded

Form Data :

email = {user email}

password = {user password}

Get user info from access token

Request :

GET http://{IdP-URL}/api/1.0/sso/token/{access_token}

Headers :

client_id = {client id of the user representing the organization}

X-Auth-Token = {Secret API Token given to the user representing the Organization}

Accessing a service/resource provider
As explained earlier, once an "access_token" is received, you may call other HIE APIs. All API calls must accompany the following details.
with headers:

- client_id = (client id of the user representing the organization)
- X-Auth-Token = (access token fetched earlier)
- from = (email id of the requester, one thats used for login)

More on authorization

There are 4 types of requester of a service or resource provider:

1. systems - facilities and other DGHS systems/apps
2. providers - CHWs, doctors etc
3. admins - administrators of services (example SHR, HRM or other DGHS apps etc)
4. individual users - patients

The above can be broadly categorized into human (provider, admin, individual users) and non-human users (facilities, other DGHS systems/apps)

A user can have multiple profiles; example: a user can be a provider, a patient herself. or a user can be a patient while he/she can be an administrator of a particular region.

IdP (HRM) will have such user/client information as profiles; so that each user can have multiple profiles. The service/resource provider makes its own decision to authorize a request based on user profile and groups user is associated with.

Identifying the catchment of a requester

Many services and applications like SHR, MCI, MCI admin applications need to find out the catchment of the requester to allow operations limited only to the catchment defined for the requester. For example: a facility can sync only their catchment patients, or MCI admins can approve updates only for patients in their defined catchment areas. IdP may send the catchment information as part of the profile info.

Systems (facilities, DGHS apps etc) - Each facility depending on its location and type has a catchment defined for it in facility registry. By default this is determined by the type of facility and their physical location, unless overridden.
Providers - If the requester is attached to a facility, then their catchment is that of the facility (as explained above) unless overridden.
Admins (administrators of services like SHR, HRM or other DGHS apps etc) - are associated with administrative areas.
Individual user (patient) - no catchment is defined.

For example: the following userinfo may be returned to the service provider, when they try to identify the requester (example, someone is trying to create/POST a patient). Note the profiles associated.

{
    "id": 6,
    "name": “Dr. X Y Z”,
    "email": "xyz@gmail.com",
    "is_active" : true,    
    "activated": true,
    "activated_at": null,
    "last_login": "2015-01-20 09:52:58",
    "access_token": "xyz_token",
    "created_at": "2014-09-04 13:26:14",
    "updated_at": "2015-01-20 09:52:58",
    "deleted_at": null,
    "groups": ["MCI Admin", "API Consumer"], 
    "profiles": [
      { 
         type: "provider",
         id: "123",
         catchment: ["302618","302614"]
      },
      {
         type: "admin",
         id: "2",
         catchment: ["3026"]
      }, 
      {
         type: "facility",
         id: "10000069",
         catchment: ["302618"]
      },
      {
         type: "patient",
         id: "10091232131",
         catchment: []
      }
    ]    
}