Table of Contents

minLevel	1
maxLevel	3

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

Apiary

Authorize

Verify the validity of access token
- Check user scope append_auth_method:write in order to perform this action

Get global parameters

...

Page Properties

Link	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/persons/create-authentication-method-request
Resource	/api/persons/{{id}}/authentication_method_requests
Scope	authentication_method_request:write
Components	Patient registry
Microservices	mpi/api fe/admin-web
Protocol type	REST
Request type	POST
Sync/Async	Sync
Public/Private/Internal	Public

Global and configurable parameters

Variable	Values	Description
phone_number_auth_limit		Check if in table person_authentication_methods with `ended_at`is empty or > now() & type = `OTP` > N, then `error 422, such a phone already exists more N times`
third_person_limit		In table person_auth_methods with type =

...

THIRD_

...

`PERSON` > N, then error 422 `This fiduciary person is present more than N times in the system`
third_person_term		parameter is used for calculation of ended_at data for authentication method type = THIRD_PERSON
person_with_third_person_limit		In table person_auth_methods with type = THIRD_PERSON >N, then error 422 `Limit of authentication methods with THIRD_PERSON type is exhausted`
no_self_auth_age		In table person now()-birth_date <=N & person_auth_methods with type = `OTP` OR `OFFLINE`, then error 422 `Such person cannot have self authentication method`

cURL example

Expand

title	Request example

Code Block
curl -X GET \

...

{:host}/prm/api/global_parameters

...

Validate request

...

Input parameters

Input parameter

Values

Type

Description

Example

id

String

Person identifier.

Required

b075f148-7f93-4fc2-b2ec-2d81b19a9b7b

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

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

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

if action = update

Code Block
{

...

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

Code Block
{ "$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"

...

 : "+380656779678",

...

"alias": "roksolana"
    }

...

Validate person id

Fiend value is person.id

...

validate person_id UUID

in case error return 422

...

Search auth requests by person id

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

Change status of all found person requests:

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

Validate by actions

if action = `deactivate`

Field type must be THIRD_PERSON (where person_auth_method.id = $authentication_method.id), 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`

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"
alias is required.
Check if authentication_method_current != NA, else return error 422 “Person can't be authorized with NA authentication method"

if action = `insert`

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
3. validate that il.authentication_method_request.authentication_method.phone_number is in DB.VERIFICATION.VERIFIED_PHONES
if type = OFFLINE
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
if type = THIRD_PERSON
1. value ,phone_number, alias are required
2. Validate value:
  1. validate person.id is UUID
    - in case error return 422
  2. search person by person.id in MPI
    - in case error return

...

1. 1. - 404, "

...

1. 1. - such person doesn't exist"

Validate

Field type must be third_person.

Generate verification code

Invoke Initialize OTP to generate one time password and send it to third_person number (that is added as a new auth method). At this stage, the patients receive an SMS message.

...

1. 1. search person 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, "Incorrect person age for such an action"
  3. validate third_person.auth_method != (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.

...

cURL example

1. phone_number where mpi.person_auth_method.person_id = auth_method_request.authentication_method.value
2. auth_method_current != null (null is set if MPI.person_auth_methods.ended_at <= now())
3. 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
4. validate if THIRD_PERSON != person, else return error 422 Person can't add himself as THIRD_PERSON
5. 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
6. 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 != 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 error - “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

Expand

title	Request example

Code Block
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

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:

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

HTTP status codes

Page Properties

HTTP status code	Message	What caused the error
201	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

Versions Compared

Old Version 7

New Version Current

Key

Purpose

Specification

Authorize

Get global parameters

Global and configurable parameters

Validate request

Input parameters

Dictionaries

Request structure

Authorize

Headers

Request data validation

Validate Patient

Validate request

Validate person id

Search auth requests by person id

Validate by actions

if action = `deactivate`

if action = `update`

if action = `insert`

Validate

Generate verification code

Processing

Set auth_method_current

Generate verification code

Generate upload URL

Response structure

HTTP status codes

Page Comparison

Versions Compared

Old Version 7

New Version Current

Key

Purpose

Specification

Authorize

Get global parameters

Global and configurable parameters

Validate request

Input parameters

Dictionaries

Request structure

Authorize

Headers

Request data validation

Validate Patient

Validate request

Validate person id

Search auth requests by person id

Validate by actions

if action = deactivate

if action = update

if action = insert

Validate

Generate verification code

Processing

Set auth_method_current

Generate verification code

Generate upload URL

Response structure

HTTP status codes

if action = `deactivate`

if action = `update`

if action = `insert`