Purpose

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

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

Specification

Specification

Apiary

Authorize

Verify the validity of access token

...

...

Get global parameters

...

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:

{
  "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",
    "default": "true"
 }
  }
 
}
}

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 422, "Such person isn't active"

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

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

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 & 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"

...

set default only for auth_method.type = THIRD_PERSON

...

optional field default must be only = TRUE

...

2. alias is required.

3. 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 = 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. 1. Validate

...

1. 1. value

...

1. 1. :

...

1. 1. 1. validate person.

...

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

...

1. 1. 1. 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 default 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 authentication method is undefined Person can't be authorized with NA authentication method “

Generate verification code

If auth_method_requests.auth_method_current = OTP 

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:

{
  "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"
      }
    ]
  }
}

{
  "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"
  }
}

HTTP status codes