ЕСОЗ - публічна документація

MIS authorization

Owned by Edward Voloshin (Unlicensed)
Last updated: Sep 30, 2019 by Гліб Ущенко (Unlicensed)
3 min read

Purpose & Requirements

  1. separate MIS API-key has to be introduced
  2. API-key would be issued for new specific user-type in mithrill (i.e. MIS)
  3. each MIS would have list of allowed scopes as per mithril spec
  4. MIS API key authorization has to take precedence over all other user (i.e. MSP/client) authorization checks. For example: if MIS is unauthorized to register Declaration, but MSP is authorized, request has to be REJECTED, because MIS check has higher priority.
  5. we have to decide on a specific error message to be returned in case of unauthorized MIS. Message should be very specific, and not overlapping with any other messages in the system, i.e "403 Forbidden Client"


Implementation 

MIS API-key

For identifiers MIS clients (client_type = MIS) we use term API-key.  We store API-key in `secret` attribute 'clients` table.


Condition for validate MIS API-key mandatory

For some clients (client_type = MSP, PHARMASY, ..) we need require mandatory access only transfer across MIS (MIS is a broker).  
Proposed use new attribute `access_type` with values (`DIRECT`, `BROKER`) in JSON object in column `client.priv_settings` for mark such clients.

We extract client access type from token, analyze `access_type` = BROKER, and require  brokers (not own) API-key in WS request. 

client_typePurposeaccess_type

Auth_FE

Auth frontEndDIRECT
MSPMedical service providerBROKER
MISMedical information systemDIRECT
NHS_AdminAdmin console of the NHSDIRECT
MITHRIL ADMINAdmin console of the Mithril itselfDIRECT
PHARMACYPharmacyBROKER
UADDRESSES ADMINAdmin of UA adressesDIRECT


For create new clients need validate object `client.priv_settings` on mandatory attribute `access_type` & mapping values (client_type :: access_type)


Send & Get API-key

Some clients (which `access_type` = BROKER) must be send (mandatory) API-key as a attribute `API-key` in HEADER all request.

Example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer mF_9.B5f-4.1JqM" \
     --header "API-key: d09vQUFlWTZ6Q0RXRDJISldUOVQ3dz09" \
     --data-binary "{
  \"medication_request_request\": { 
....

Manage MIS broker scope 

For some clients (client_type = MIS) which provide transfer for call API - we need mandatory validate possibility access to API endpoints.

Proposed use new attribute `broker_scopes` in JSON object in column `client.priv_settings`.

If attribute `broker_scopes` not exist in `client.priv_settings` - we don`t need validate access over broker!

Client_typePurposeclient.priv_settings

Auth_FE

Auth frontEnd
MSPMedical service provider
MISMedical information system"broker_scopes": "legal_entity:read declaration:read employee:read"
NHS_AdminAdmin console of the NHS
MITHRIL ADMINAdmin console of the Mithril itself
PHARMACYPharmacy
UADDRESSES ADMINAdmin of UA adresses

For clients (client_type = MIS) on which we will check access for call API endpoint - we need describe the list `broker_scopes`. 
Proposed manage & store list  `broker_scopes` in attribute `priv_settings` in table `clients`. 

Example:

{
  "allowed_grant_types": [
    	"password",
    	"access_token"
  ],
  "access_type": "direct",
  "broker_scopes": 
  		"legal_entity:read
		 declaration:read
		 employee:read"
}

In case of need complex disconnect MIS for transfer of call API endpoints - we need full clear him `broker_scopes`.
Clear, but not delete!

Validate MIS transfer scope

When MSP call specific API endpoint over (transfer) MIS we need validate possibility to access.

  1. Get `client_id` from `token`
  2. Read `clients` for `client_id`.   (further in the text - `REQUEST_CLIENT`)
  3. Extract `access_type` from `priv_settings`. 
  4. If `access_type` = `BROKER` 
    1. Read   `API-key` from HEADER
      1. if API-key missing - return 401 error  "API-KEY header required !" 
    2. Validate  `API-key`.
      1. Validate exists `secret` in table `clients`
        1. if invalid - return 401 error  "API-KEY header required !" 
      2. Read `clients` with `secret`(API-key) in header.  (further in the text - `BROKER_CLIENT`)
      3. Extract `broker_scopes` from `priv_settings` . 
        1. if not found `broker_scopes` -  return 401 error  "Incorrect broker settings!" 
      4. Read needed scopes for call API Endpoint (read from GateWay configuration - "/gateway-config.yaml")
      5. Validate exist needed scopes in `broker_scopes` of `BROKER_CLIENT`.
        1. if invalid - return 403 error " Scope is not allowed by broker"
  5. If `access_type` = `DIRECT` 
    1. break validation.


Configuration examples 

Commentsclients.priv_settings
MSP{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "broker" }
Incorrect MSP{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "direct" }
Normal MIS{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "direct", "broker_scopes": "legal_entity:read declaration:read employee:read" }
Full blocked MIS{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "direct", "broker_scopes": "" }
Non broker MIS{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "direct" }

Tests

MIS Authorization Test Page 

ЕСОЗ - публічна документація