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

PIS. Patient sign-up registration

Owned by Dmytro Omelchenko (SoE eHealth)
Last updated: Aug 30, 2023
5 min read

Purpose

This WS is designed to register patient in the system based on data received from Patient Information System

Key points

  1. This method must be used only by Auth front-end

  2. Validates session token (jwt) that was obtained as a result of signed content as well as patient data validation by PIS. Patient sign-up validation and signed content, skips revalidation of patient data.

  3. Creates user as well as patient in the system

  4. Generates access token for further actions

Specification

Apiary

Validate signed content

  • Check signed_content and signed_content_encoding are submitted

    • in case of error - return 422 ('required property signed_content was not present' or ‘required property signed_content_encoding was not present')

  • 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 ('value is not allowed in enum')

  • Check digital signature is valid

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

  • Check that drfo from digital signature belongs to person in registration request, based on field format:

    • if value equals to tax_id regexp (^[0-9]{10}$), field contains tax_id, use tax_id field from registration request to compare;

    • if value equals to national_id number regexp (^[0-9]{9}$), field contains national_id number, use documents.number field with documents.type = 'NATIONAL_ID' to compare;

    • if 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 documents.number field with documents.type = 'PASSPORT' to compare;

      • in case of error - return 409 ('Registration person and person that sign should be the same')

  • Check that last_name from digital signature belongs to person in registration request, last_name field

    • in case of error - return 422 ('Input name doesn't match name from digital signature')

  • Check that first_name from registration request is present in string given_name from digital signature

    • in case of error - return 422 ('Input name doesn't match name from digital signature')

Validate JWT

  • validate JWT signature

  • validate issuer (iss = Ehealth)

  • validate aud (aud = pis-registration)

  • validate expiration (exp in the future)

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

  • validate content_hash equals to MD5 hash value of signed_content field

    • in case of error - return 401 ('Unauthorized.')

Verify otp

  • Get value of PIS_VALIDATE_ALL_PHONES config parameter

    • if it set to false - check that phone from authentication_methods field must be verified (number does not exists in verified_phones table in verifications database), if phone must be verified, check that value from $.otp field in request equals to verification code that was sent to phone and md5 hash of encoded $.signed_content equals to stored value (through verifications table in verification database)

    • if it set to true - check that value from $.otp field in request equals to verification code that was sent to phone and md5 hash of encoded $.signed_content equals to stored value (through verifications table in verification database)

      • in case of error - return 422 ('Invalid verification code')

Service logic

Update otp

  1. If otp verification was invoked, update record for otp and phone number in verifications table in verification database, set:

    1. status = ‘verified’

  2. If otp verification was invoked, check existance of record for phone number in verified_phones table in verification database, if not exists - create record, set:

    1. id = autogenerate uuid

    2. phone_number = number of verified phone from request

    3. updated_at = now()

Search user

  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 PIS. Patient sign-up registration | Search or create person

  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 sign-up registration | Generate authorization token

Search or create person

  1. Search for existing active person in mpi database with data from person registration request according to existing process, described here PIS. Patient sign-up registration | Search or create person
    Calculate score of comparison between found active persons and person registration request using existing deduplication process, described here Deduplication process NEW
    Compare found score with PIS_ONLINE_DEDUPLICATION_MATCH_SCORE config parameter, set to ‘0.95’:

    1. If one active person with match score > PIS_ONLINE_DEDUPLICATION_MATCH_SCORE was 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 person_id and proceed to p.2.

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

    3. If no active person with match score > PIS_ONLINE_DEDUPLICATION_MATCH_SCORE was found - proceed to p.3.

  2. 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 sign-up registration | Generate authorization token

    2. If user is not found - proceed to PIS. Patient sign-up registration | Create user

  3. Create new patient in mpi database, set values in following tables based on person registration request:

    1. persons table

    2. person_phones table

    3. person_addresses table

    4. person_documents table

    5. person_authentication_methods table

  4. Save signed content to media storage

  5. Submit person on verification - create record in person_verifications table for person_id, set values for each verification stream:

    1. Manual NHS verifiation

      1. IF $.person.documents contains document with type = 'PERMANENT_RESIDENCE_PERMIT' or  $.person.unzr is not empty and first 8 digits of $.person.unzr != $.person.birth_date
        or $.person.documents contains document with type from PIS_PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter
        - scan copies of persons documents must be uploaded to media storage after persons registration using https://e-health-ua.atlassian.net/wiki/spaces/EH/pages/17525606880

        1. set nhs_verification_status = NOT_VERIFIED

        2. set nhs_verification_reason = DOCUMENTS_TRIGGERED

      2. else - scan copies of persons documents are not needed, set verification status according to logic, described here: Sign person request | Manual NHS verification

    2. DRFO registry verification - according to logic, described here: Sign person request | DRFO registry verification

    3. DRACS death acts registry verification - according to logic, described here: Sign person request | DRACS death acts registry verification

  6. Calculate cumulative person verifiation status according to logic, described here: Sign person request | Calculate cumulative verification status

Create user

  1. Create user for active patient 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 or created on ‘Search or create patient’ step.

  2. 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 authorization token

  1. Generate auth_token with scope app:authorize for user_id and client_id of Auth UI (from env)

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

    1. id = token uuid

    2. name = token name (‘access_token’)

    3. value = hashed token

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

    5. details = additional details of token (scope, client_id, grant_type), where

      1. scope = ‘app:authorize’

      2. client_id = client id of Auth UI

      3. grant_type = ‘pis_auth’

    6. user_id = id of user

    7. inserted_at = now()

    8. updated_at = now()

  3. Render a response according to specification.

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