This document describes graphQL createAuthMethRequest mutation purpose and validations.
Purpose
To allow NHS Admin/Data Stuart (NHS employee with assigned appropriate scopes) to CREATE/UPDATE/DEACTIVATE authentication methods for a Person, based on Person’s official request to NHS, which is actually a legal authorisation for changes in his personal data. Without Digital signature.
Schemas
Processing of request
Flow of statuses
Specification
Key points
The process is initiated by any NHS employee with necessary scopes and involves the transfer (by graphQL mutation) of data, needed for the following actions
: INSERT, UPDATE, DEACTIVATE
. Message (request) includes:
personId
- id of an existing person,action
- action (INSERT, UPDATE, DEACTIVATE
),authenticationMethod {
id
- id of a Person’s auth method (in case ofUPDATE, DEACTIVATE
actions),alias
- alias for Person’s authentication method (used in case ofINSERT, UPDATE
actions)phoneNumber
- phone number (in case ofINSERT
actions for typeOTP
method)value
- id of a third person (in case ofINSERT
actions for typeTHIRD_PERSON
method)type
- type (in case ofINSERT
actions) }
It has similarities to update part of Create authentication method request process, but there are some main differences:
Authentication_method_request record is created in BE directly in status
COMPLETED
based JSON from FE. Without interim records to DB with such statuses asNEW
.During update process of Person’s authentication method in
MPI.person_authentication_methods
table (by usingIL.authentication_method_requests
entity), there is no need in ONLINE/OFFLINE approve from Person. I.e. not necessary to generate OTPs and links for uploading of documents to Bucket.authentication_method_requests.(new record).authentication_method_current = null
It is allowed to create new auth method for Person with not verified phone.
DEACTIVATION
can be done forOTP, OFFLINE, THIRD_PERSON
(not only forTHIRD_PERSON
, as it is in the standard process). SoAUTH_REQUEST_SECURITY_REDUCTION
parameter is not used as a control in this mutation.Scope is used:
authentication_method_request:write_nhs
And there are other differences in fields, values and controls:
IL.authentication_method_request.(new record).channel = 'NHS'
Scope and roles
scope New
| roles
| description Scope for creation of authentication methods for |
Authorize
Verify the validity of access token
Return 401 in case validation fails
Verify that token is not expired
in case of error - return (401, 'Invalid access token')
Check user scope
authentication_method_request:write_nhs
in order to perform this actionReturn 403 in case invalid scope(s)
Validate legal entity
Extract client_id from token.
Check client scopes has
authentication_method_request:write_nhs
in case of error - return 403 (“Your scope does not allow to access this resource. Missing allowances: authentication_method_request:write_nhs”)
Check legal entity status (status = ACTIVE)
In case of error - return 409 ('client_id refers to legal entity that is not active')
Get global parameters
Invoke Global parameters to get parameters, used for validations during creation (action: INSERT
) of new authentication method for Person:
gp.phone_number_auth_limit (
get this parameter ifUSE_PHONE_NUMBER_AUTH_LIMIT
=true
)how many times same phone_number can be used as authentication method for different persons. E.g. no more than 600 times.
gp.third_person_limit
how many times some Person, as a
THIRD_PERSON
may be an authoriser for other Persons. E.g. 6 times.
third_person_term
what period can be active an authentication method
THIRD_PERSON
type for adult person. It is used to set ended_At. E.g. 2 years from moment of creation of an authentication method..
gp.person_with_third_person_limit
how many authentication methods with the
THIRD_PERSON
type one Person may have. This parameter is used duringINSERT
action. E.g. no more than 6 times
gp.no_self_auth_age
age for which authentication methods OFFLINE and OTP type are not allowed. E.g. till 14 years.
These global parameters are stored in PRM.global_parameters
cURL example
curl -X GET \ {:host}/api/global_parameters |
Validate request
personID is a text:
Person:9f45775f-2dc8-472f-bd98-b072780f7482
coded in base64
authentication_method’s id is a text:
PersonAuthenticationMethod:86ee6615-7c19-71ce-35e6-2337fb9894fd
coded in based64
value
is an id of a third person, which is a textPerson:UUID
coded in base64
if action = deactivate
{ "$schema": "http://json-schema.org/draft-05/schema#", "type": "object", "properties": { "personId": "UGVyc29uOjlmNDU3NzVmLTJkYzgtNDcyZi1iZDk4LWIwNzI3ODBmNzQ4Mg==" "action": "DEACTIVATE", "authenticationMethod": { "id": "UGVyc29uQXV0aGVudGljYXRpb25NZXRob2Q6ODZlZTY2MTUtN2MxOS03MWNlLTM1ZTYtMjMzN2ZiOTg5NGZk" } } }
if action = update
{ "$schema": "http://json-schema.org/draft-05/schema#", "type": "object", "properties": { "personId": "UGVyc29uOjlmNDU3NzVmLTJkYzgtNDcyZi1iZDk4LWIwNzI3ODBmNzQ4Mg==" "action": "UPDATE", "authenticationMethod": { "id": "UGVyc29uQXV0aGVudGljYXRpb25NZXRob2Q6ODZlZTY2MTUtN2MxOS03MWNlLTM1ZTYtMjMzN2ZiOTg5NGZk", "alias": "roksolana" } } }
if action = insert
{ "$schema": "http://json-schema.org/draft-05/schema#", "type": "object", "properties": { "personId": "UGVyc29uOjlmNDU3NzVmLTJkYzgtNDcyZi1iZDk4LWIwNzI3ODBmNzQ4Mg==" "action": "INSERT", "authenticationMethod": { "type": "THIRD_PERSON", "value": "UGVyc29uOmE1NGZiOTgwLTMzMjYtNDQ1MS1hYzZmLWYzYzNhNTY3MDY4ZQ==", "phoneNumber" : "+380656779678", "alias": "roksolana" } } }
{ "$schema": "http://json-schema.org/draft-05/schema#", "type": "object", "properties": { "personId": "UGVyc29uOjlmNDU3NzVmLTJkYzgtNDcyZi1iZDk4LWIwNzI3ODBmNzQ4Mg==" "action": "INSERT", "authenticationMethod": { "type": "OTP", "phoneNumber" : "+380656779678", "alias": "railway" } } } { "$schema": "http://json-schema.org/draft-05/schema#", "type": "object", "properties": { "personId": "UGVyc29uOjlmNDU3NzVmLTJkYzgtNDcyZi1iZDk4LWIwNzI3ODBmNzQ4Mg==" "action": "INSERT", "authenticationMethod": { "type": "OFFLINE", "alias": "mydocs" } } }
Validate $.personId
Check $.personId
is ID from MPI.person.id
validate
$.personId
is UUID and UUID is version 4in case of error, return
422
search person
$.personId
inMPI.person.(id = $.personId)
andMPI.person.(id = $.personId).is_active = true then ok
in case of error, return
404
, "Such person doesn't exist"
validate that person is active
MPI.person.(id = $.personId).status = ‘active’
in case of error, return
409
, "Such person isn't active"
Validation and processing of message by actions
Definition
OTP and OFFLINE - are Primary auth method
Person can have only one Primary auth method
Secondary auth method - THIRD_PERSON. Person can have many of them.
if action = deactivate
Primary auth method can be deactivated also
validate
$.authenticationMethod.id is UUID
andUUID is version 4
in case of error, return
422
validate availability in
MPI.person_authentication_methods
whereis_active = true and person_id = $.personId and id = $.authenticationMethod.id then ok
in case of error, return
404
, "such authentication method was not found for this person"
validate ended_At in
MPI.person_authentication_methods
whereended_At > now ()
in case of error, return
422
, "Such method is expired"
validate $.authenticationMethod.type in
(OTP, OFFLINE, THIRD_PERSON)
.
No necessity to check current method of Person: auth_method_current ($.personId)
if action = update
validate
$.authenticationMethod.id is UUID
andUUID is version 4
in case of error, return
422
validate availability in
MPI.person_authentication_methods where
is_active = true and person_id = $.personId and id = $.authenticationMethod.id then ok
in case of error, return
404
, "such authentication method was not found for this person"
validate
ended_At in MPI.person_authentication_methods where
ended_At > now ()
in case of error, return
422
, "Such method is expired"
alias
is required.
No necessity to check current method of Person: auth_method_current ($.personId)
if action = insert
1 | if |
|
2 | if |
|
3 | if |
|
Processing (execution)
Cancel pending auth requests
Search by $.personId
and cancel pending auth requests
To prevent requests duplication:
search in
IL.authentication_method_requests
:where IL.authentication_method_requests.person_id = $.personId
and IL.authentication_method_requests.status = NEW
,
then
Change status of all found and pending authentication_method_requests:
SET IL_DB.authentication_method_requests.status = 'CANCELED' WHERE IL_DB.authentication_method_requests.id IN (:LIST) |
Create new record in IL.authentication_method_requests
Assignment of “authorisation with” field (auth_method_current
)
Set default auth method of person on IL.auth_method_request.auth_method_current
= null
Explanation: Based on authentication_method_request:write_nhs scope NHS Admin has right to create/update/deactivate authentication methods without online/offline authorisation by Person. I.e. without OTP and without uploading of documents
Create/Update/Deactivate method in MPI.person_authentication_methods
Based on $.action
methods are created/updated/deactivated in MPI.person_authentication_methods
With setting of fields updated_at, inserted_at, inserted_by, updated_by
Deactivate methods
Action insert
if
$.type = OTP
or$.type = OFFLINE then
all active methods of a Person inMPI.person_authentication_methods
where(person_id = $.personId and is_active = true and ended_At > now())
with(type in OTP, OFFLINE)
deactivated .set
MPI.person_authentication_methods.(:LIST).ended_at
=now()
if
$.type = THIRD_PERSON then
active method of a Person inMPI.person_authentication_methods
where(person_id = $.personId and is_active = true and ended_At > now() and value = $.authenticationMethod.value and type = 'THIRD_PERSON')
deactivated .set
MPI.person_authentication_methods.(found id).ended_at
=now()
Action deactivate
Appropriate method deactivate by setting auth method’s
ended_At
tonow()
MPI.person_authentication_methods.(person_id = $.personId and id = $.id).ended_at = now()
Set is_active field
In case of
INSERT
actionis_active = true
In case of
UPDATE/DEACTIVATE
actionDo not change
is_active
AsUPDATE/DEACTIVATION
is possible only for fields withis_active = true
, as it was described earlier within this document.
Set the started_at
, end date of the person_ausentication_method.ended_at
For action insert.
These params set only if auth method is being created
If person has auth_method =
third_person
,add in table
MPI.person_authentication_methods
row withtype
=THIRD_PERSON
,value
= id (i.e. third_person_id),alias
Calculate term of person_authentication_method:
Start date:
start_date = Current_date()
End date:
if (person.age < gp.no_self_auth_age) { end_date = end_date =birth_date + gp.no_self_auth_age - 1d; } else { end_date = start_date + gp.third_person_term; } |
Check if Person should be sent for verification
If action = insert
then Update Person’s record in MPI.persons
according to the following validations https://edenlab.atlassian.net/wiki/spaces/EH/pages/2986803342/Approve+auth+method+request+copied+from+pub#Validations-and-processing-related-to-Verification-of-a-Person-process