RC (PCAB) PIS Authorization

1 Purpose
2 Key points
3 Service logic
- 3.1 PIS API-key
- 3.2 Send API-key
- 3.3 Manage PIS broker scope
- 3.4 Validate PIS transfer scope
- 3.5 Configuration examples

Purpose

This process is designed to perform and validating authorization of PIS clients.

Key points

For identifiers of PIS clients (as a broker) we use term API-key. PIS must mandatory send api-key when called any eHealth API.
API-key is a pis_client_secret - Patient Information System secret key issued upon integration request.
API-key is dispatched in Request HEADER as a API-key attribute.
If PIS don't send api-key in Request HEADER, API return 401 error wih message "API-KEY header required".

Service logic

PIS API-key

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

Send API-key

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

Example:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9" \
     --header "API-key: d09vQUFlWTZ6Q0RXRDJISldUOVQ3dz09" \
     --data-binary "{
  \"signed_content\": { 
....

Manage PIS broker scope

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

We used attribute `broker_scopes` in JSON object in column `client.priv_settings`.

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

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

Validate PIS transfer scope

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

Get `client_id` from `token`
Read `clients` for `client_id`. (further in the text - `REQUEST_CLIENT`)
Extract `access_type` from `priv_settings`.
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` (see details: RC (PCAB) [Internal] Apikey verify )
  1. Validate exists `secret` in table `connections`
    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
  5. Validate exist needed scopes in `broker_scopes` of `BROKER_CLIENT`.
    1. if invalid - return 403 error " Scope is not allowed by broker"
If `access_type` = `DIRECT`
1. break validation.

Configuration examples

Comments	clients.priv_settings

Comments	clients.priv_settings
Normal PIS	{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "direct", "broker_scopes": "app:read_pis app:delete_pis profile:read confidant_person:login" }
Full blocked PIS	{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "direct", "broker_scopes": "" }
Non broker PIS	{ "allowed_grant_types": [ "password", "access_token" ], "access_type": "direct" }

E-Health