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

RC (PCAB) PIS Authorization

Owned by Nickolay Kolotov (SoE eHealth)
Nov 13, 2023
2 min read

Purpose

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

Key points

 

  1. For identifiers of PIS clients (as a broker) we use term API-key. PIS must mandatory send api-key when called any eHealth API.

  2. API-key is a pis_client_secret - Patient Information System secret key issued upon integration request.

  3. API-key is dispatched in Request HEADER as a API-key attribute.

  4. 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.

  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` (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"

  5. 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" }

 

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