Required parameters are marked with "*"

...

Purpose

...

This process describes adding an additional authentication method to an existing person, update authentication method and delete it.

Confluence - https://e-health-ua.atlassian.net/wiki/x/FwC_J

...

Use GET persom/{id}/ authentication_method to find authentication method' id of person.

Specification

Logic*

...

Global and configurable parameters

cURL example

curl -X GET \
    {:host}/prm/api/global_parameters

Input parameters

Dictionaries

• AUTHENTICATION_METHOD

• DOCUMENT_TYPE

Request structure

...

See on Apiary

Example:

Expand
title Request example
Code Block { "object": { "action": "DEACTIVATE", "authentication_method": { "id": "7b100a9c-daaa-490e-b88d-2a911059b055" } } }

Authorize

...

1. Verify the validity of access token

   • Check user scope authentication_method_request:write in order to perform this action

...

Headers

...

Content-Type:application/json

Authorization:Bearer

...

{{access_token}}

api-key:

...

{{secret}}

Request data validation

...

Validate Patient

• Get person_id from URL

• Validate id:

  • validate person.id UUID

    • in case error return 404

  • search person by person.id in MPI

    • in case error return 404, "Such person doesn't exist"

  • validate that person is active ( person.status = active & is_active = true)

    • in case error return 409, "Such person isn't active"

Validate request

if action = deactivate

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
  "action": "deactivate",
  "authentication_method": {
    "id": "057413fb-2c2e-4f33-b2d6-433469212744"
    }
  }
}

...

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
  "action": "update",
  "authentication_method": {
    "id": "057413fb-2c2e-4f33-b2d6-433469212744",
    "alias": "roksolana"
    }
  }
}

if action = insert

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
  "action": "insert",
  "authentication_method": {
    "type": "THIRD_PERSON",
    "value": "d12888c0-1159-4296-8f03-a592c136f673",
    "phone_number`number" : "+380656779678",
    "alias": "roksolana"
    }
  }
}

Validate ids

Fiend value is person.id

...

validate person.id UUID

• in case error return 404

...

search person by person.id in MPI or person.is_active = false

• in case error return 404, "Such person doesn't exist"

...

validate that person is active ( person.status = active)

• in case error return 409, "Such person isn't active"

validate that auth_method is active ( person.auth_method.ended_at > now())

...

Search auth requests by person id

 To prevent requests duplication search in il.auth_method_requests.person_id = $.person_id and il.authauthentication_method_requests.status = NEW, then

Change status of all found person requests:

SET   IL_DB.authentication_method_requests.status = 'CANCELED'
WHERE IL_DB.authentication_method_requests.id IN (:LIST)

Validate by actions

if action = deactivate

1. Field type must be THIRD_PERSON

...

1. (where person_auth_method.id = $authentication_method.id)

...

1. , else return error 422 “Only THIRD_PERSON authentication method type could be deactivated"

   1. Check this auth_method is not primary

...

1. 1. & there are more than one authentication method for person:

      1. in case of error return 422, “You can't deactivate the last authentication method“

   2. Check if authentication_method_current != NA, else return error 422 “Person can't be authorized with NA authentication method"

   3. Validate that auth_method is active ( person_authentication_methods.ended_at > now())

      • in case error return 422, “Authentication method isn’t active”

if action = update

1. validate authentication_methods.id belong to this person. Search auth method of this person where  MPI.person_authentication_method.person_id = $.person.id

   1. in case error return 422, "such authentication method does not belong to this person"

2. alias is required.

...

1. Check if authentication_method_current != NA, else return error 422 “Person can't be authorized with NA authentication method"

if action = insert

1. if type = OTP ,

   1. phone_number is required and value shouldn’t be set. And field alias is optional.

   2. validate that person.age >global_parameters.no_self_auth_age

...

1. 1. validate that il.authentication_method_request.authentication_method.phone_number is in DB.VERIFICATION.VERIFIED_PHONES

2. if type = OFFLINE

...

1. 1. phone_numberand value shouldn’t be set . And field alias is optional.

   2. validate that person.age > global_parameters.no_self_auth_age

   3. auth_method_current != OFFLINE

      1. error - "Person already has auth method OFFLINE"

   4. auth_method_current = OTP ( if config AUTH_REQUEST_SECURITY_REDUCTION =

...

1. 1. false)

      1. error - Person cannot set OFFLINE auth method if person had OTP

2. if type = THIRD_PERSON

...

1. 1. value ,phone_number, alias are required

...

1. 2. Validate

...

1. 1. value

...

auth_method_current != NA

...

if config THIRD_PERSON_OFFLINE = False - validate that third_person has self method = OTP, else:

1. error THIRD PERSON can't have OFFLINE self auth method type

validate value:

...

1. 1. :

      1. validate person.id is UUID

         • in case error return 422

      2. search person

...

1. 1. 1. by person.

...

1. 1. 1. id in MPI 

         • in case error return

...

1. 1. 1. • 404, "such person doesn't exist"

      2. search person

...

1. 1. 1. by person.id in MPI and validate that is_active = true & status = active, else:

         • in case error return 422, "third person must be active"

      2. search third_person.age > prm.global_parameters.no_self_auth_age years:

         • in case error return 422, "

...

1. 1. 1. • Incorrect person age for such an action"

      2. validate third_person.auth_method !

...

1. 1. 1. = (MPI.person_auth_methods.ended_at <= now())

         • in case error return 422, "third person must has auth method OTP or OFFLINE"

   2. Validate phone_number with mpi.person_auth_method.phone_number where mpi.person_auth_method.person_id = auth_method_request.authentication_method.value

   3. auth_method_current != null (null is set if MPI.person_auth_methods.ended_at <= now())

   4. if config THIRD_PERSON_OFFLINE = False - validate that

...

1. 1. third_person has self method = OTP, else:

      1. error THIRD PERSON can't have OFFLINE self auth method type

   2. validate if THIRD_PERSON != person, else return error 422 Person can't add himself as THIRD_PERSON

   3. validate if person’s authentication method with type THIRD_PERSON with the same value, else return error 422 Such person id is already used in existing person's authorization methods

   4. check if person have authentication method with type THIRD_PERSON less person_with_third_person_limittimes, else return error 422, Limit of authentication methods with THIRD_PERSON type is exhausted

Processing

Set auth_method_current

Set default auth method of person on IL.auth_method_request.auth_method_current - use function in mpi, that return primary auth method.

• Validate that auth_method_current != NA null (null is set if MPI.person_auth_methods.ended_at <= now()) if

  • action = deactivate

  • action = update

  • action = insert and type= THIRD_PERSON and person.age>no_self_auth_method

• else errror error - “Person can't be authorized with NA authentication method “

...

Invoke Initialize OTP to generate one time password and send it where auth_method_requests.auth_method_current = OTP.

cURL example

curl -X POST \

...

  http://localhost:4000/verifications \

...

  -

...

H 'content-type: application/json'

...

 \
  

...

-

...

d '{

...

  "phone_number": "+380936235985"
}'

Generate upload URL

If auth_method_requests.auth_method_current = OFFLINE 

1. Generate URL's with type person.{$.person.documents.[:].type} (or Generate URL's with type third_person.{$.third_person.documents.[:].type})

If action = insert and il.auth_method_request.authentication_method.type = OFFLINE:

1. Generate URL's with type person.{$.person.documents.[:].type}

Response structure

...

See on Apiary

Example:

Expand
title Response example. Code: 201
Code Block { "meta": { "code": 201, "url": "https://example.com/resource", "type": "object", "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810" }, "data": { "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b", "status": "NEW", "channel": "MIS" }, "urgent": { "authentication_method_current": [ { "type": "OTP", "phone_number": "+38093*****81" } ], "documents": [ { "type": "PASSPORT", "url": "https://storage.ehealth.world" } ] } }

Expand
title Response example. Code: 422
Code Block { "meta": { "code": "422", "url": "https://example.com/resource", "type": "object", "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810" }, "error": { "type": "unverified", "message": "Unverified phone number" } }

Post-processing processes*

API paragraph not found

HTTP status codes

...

Page Properties

HTTP status code Message What caused the error 201  201      422    Response   404 Such person doesn't exist Validation error 409 Such person isn't active Validation error 422 Such a phone already exists more N times This fiduciary person is present more than N times in the system Limit of authentication methods with THIRD_PERSON type is exhausted Such person cannot have self authentication method Only THIRD_PERSON authentication method type could be deactivated You can't deactivate the last authentication method Person can't be authorized with NA authentication method Authentication method isn’t active Such authentication method does not belong to this person Third person must be active Incorrect person age for such an action Third person must has auth method OTP or OFFLINE Person can't add himself as THIRD_PERSON Such person id is already used in existing person's authorization methods Unverified phone number Validation error