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

PIS. Patient login

Owned by Dmytro Omelchenko (SoE eHealth)
Aug 29, 2023
4 min read

Purpose

This WS is designed to authenticate user using any of the supported authentication methods.

Key points

  1. This method should be reachable only by the eHealth authorization front-end application.

  2. User is authenticated using different grant types: password, digital_signature, change_password, authorize_2fa_access_token, refresh_2fa_access_token, pis_auth.

  3. Each grant type requires its specified set of fields with different validations.

Specification

Apiary

Validate request

Validate client

  • Check client_id is submitted

    • in case of error - return 422 ('can't be blank')

  • Check client_id exists in mithril database

    • in case of error - return 422 ('Invalid client id.')

Validate grant type

  • Check grant_type is submitted

    • in case of error - return 422 ('Request must include grant_type.')

  • Check grant_type is one of the values: password, change_password, digital_signature, authorize_2fa_access_token, refresh_2fa_access_token

    • in case of error - return 401 ('Grant type not allowed.')

  • Check grant_type is allowed to be issued by client (value exists in allowed_grant_types setting for client)

    • in case of error - return 401 ('Client is not allowed to issue login token.')

Validate ‘pis_auth’ grant type

  • Check signed_content and signed_content_encoding are submitted

    • in case of error - return 422 ('can't be blank')

  • Check signed_content field is a valid base64 string

    • in case of error - return 422 ('Invalid signed content')

  • Check signed_content_encoding field value equals to 'base64'

    • in case of error - return 422 ('is invalid')

  • Check digital signature is valid

    • in case of error - return 401 with digital signature validation error message

  • Check signed content is a valid JWT with aud = mithril-login

    • in case of error - return 401 ('JWT is invalid.')

Validate scope

  • Check requested scope is allowed for client type

    • in case of error - return 422 ('Scope is not allowed by client type.')

Service logic

Search and create user

Step is applicable only for pis_auth grant type

  1. Get drfo value from digital signature.

  2. Search for existing user in mithril database, users table, with tax_id = drfo from digital signature and is_active = true.

    1. If user is found - check it is not blocked (is_blocked <> true)

      1. in case blocked - return 401 ('User is blocked.').

      2. in case not blocked - save user_id and proceed to p.3.

    2. If user is not found - proceed to p.4.

  3. Search for existing person in mpi database, persons table, with id = person_id from found user, status = active and is_active = true

    1. in case person not found - return 401 ('Person not found.')

    2. in case person found - check its age is greater then no_self_auth_age global parameter

      1. in case of error - return 401 ('Incorrect person age for such an action.')

      2. in case persons age is correct - save user_id and proceed to PIS. Patient login | Generate token

  4. Search for existing active person in mpi database with data from digital signature (drfo, last_name and given_name) using Active person search algorithm based on drfo value:

    1. if drfo value equals to tax_id regexp (^[0-9]{10}$), field contains tax_id, use tax_id dataset for active person search,

    2. if drfo value equals to national_id number regexp (^[0-9]{9}$), field contains national_id number, use document dataset with type = 'NATIONAL_ID' for active person search,

    3. if drfo value contains at least one letter, perform reverse transliteration of field using existing algorithm (described here), then check that value equals to passport number regexp (^((?![ЫЪЭЁ])([А-ЯҐЇІЄ])){2}[0-9]{6}$), in case equals, field contains passport number, use document dataset with type = 'PASSPORT' for active person search

      1. If no active person was found - return 401 ('Person with tax id or document number not found.')

      2. If more than one active person was found - return 401 ('It is impossible to uniquely identify the person.')

      3. If one active person was found - proceed to p.5.

  5. Check age of found active person is greater then no_self_auth_age global parameter

    1. in case of error - return 401 ('Incorrect person age for such an action')

  6. Search for existing user in mithril database, users table, with person_id = person_id from found person and is_active = true.

    1. If user is found - check it is not blocked (is_blocked <> true)

      1. in case blocked - return 401 ('User is blocked.').

      2. in case not blocked - update user, set tax_id = drfo from digital signature, set settings.trusted_source = true, save user_id and proceed to PIS. Patient login | Generate token

    2. If user is not found - proceed to p.7.

  7. Create user for active person in mithril database, users table, set:

    1. id = autogenerate uuid

    2. settings = ‘{“trusted_source”: true}’

    3. priv_settings = ‘{"login_hstr": [], "otp_error_counter": 0}’

    4. inserted_at = now()

    5. updated_at = now()

    6. password_set_at = now()

    7. tax_id = drfo value from digital signature

    8. person_id = person_id of person that was found on p.4.c.

  8. Create global role for created user in mithril database, global_user_roles table, set:

    1. id = autogenerate uuid

    2. user_id = user_id of user created on p.4

    3. role_id = id of role with name ‘PATIENT’

    4. inserted_at = now()

    5. updated_at = now()

Generate token

  1. Generate token with following logic:

    1. If grant_type = pis_auth and not exists active authentication factor for user, generate token with name = ‘access_token’, scope = ‘app:authorize’ for user_id and client_id,

  2. Save token to mithil database, tokens table, set:

    1. id = token uuid

    2. name = token name

    3. value = hased token

    4. expires_at = date and time when token will be expired in unix-time format

    5. details = additional details of token (scopes, client_id, grant_type, applicant_user_id, applicant_patient_id), where

      1. scope = requested scope list

      2. client_id = client_id from request

      3. grant_type = grant_type from request

      4. applicant_user_id = user_id

      5. applicant_person_id = person_id linked to user_id

    6. user_id = uuid of user that requested token

    7. inserted_at = now()

    8. updated_at = now()

  3. Find all active tokens of the same name for user_id and client_id, if found - expire them in mithril database, tokens table:

    1. set expires_at = now()

  4. Calculate next step:

    1. if grant_type = pis_auth and not exists active authentication_method for user, then next_step = ‘REQUEST_APPS’

  5. Render a response according to specification.

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