Purpose

This WS is used to describe patient sign-up flow to using Patient Information System (PIS).

Key points

This flow is based on current Auth Sign-up UI FE page with existing and modified back-end calls.
Patient registration is performed using pre-signed request on PIS side.

Sequence diagram

title Auth Sign-Up with DS

participant User as user
participant PIS FE as pis_fe
participant PIS BE as pis_be
participant Auth UI as auth
participant mithril + BE as be

user->pis_fe: Go to "Register patient in eHealth"
opt Prefill some data
    pis_fe<-->pis_be: Get patient's data
    pis_fe->pis_fe: Prefill form
end
pis_fe-->pis_be: Prepare data to sign
pis_be-->auth: Get nonce
auth-->pis_be: <<Response>>
pis_be-->pis_fe: Return data to sign
note left of pis_be: JWT
pis_fe->user: Show registration form
user->pis_fe: Change or confirm patients data
pis_fe->user: Prompt to sign registration request
user->pis_fe: Sign registration request
pis_fe-->auth: Redirect to auth service with signed request
note right of pis_fe: scopes\nredirect_uri\nsigned request
auth-->be: Validate signature
be-->auth: <<Response>>
opt Invalid signature
    auth->pis_be: <<Error response>>
end
auth<-->be: Search user
note right of auth: tax_id
opt User found
    auth-->pis_be: <<Error response>>
end
auth-->be: Search patient
note right of auth: tax_id + name
be-->auth: <<Response>>
alt Patient found
    note left of auth: found only one record
    auth<-->be: Create user
else Not found or found more than one
    auth->user: Show form with patient data to confirm
    alt Reject
        user-->auth: Reject form
        auth-->pis_be: <<Error response>>
    else Confirm
        user-->auth: Confirm form
        auth<-->be: Create patient
        auth<-->be: Create user
    end
end
auth->user: Show prompt to approve scopes
alt Reject scopes
    user->auth: Reject scopes
    auth-->pis_be: <<Reject response>>
    pis_be-->pis_fe: Show error
else Approve scopes
    user->auth: Approve scopes
    auth<-->be: Create/update approvals
    note left of be: grant_code
    auth-->pis_be: <<Success response>>
    note left of auth: grant_code
    pis_be-->be: Exchange code grant to access token
    note right of pis_be: code_grant + secret
    be-->pis_be: <<Access token>>
    note left of be: access_token\nrefresh_token
end

Patient sign-up flow

PIS: Prepare patient sign-up data

Obtain nonce (one time JWT) from Get Nonce endpoint
Prepare filled patient registration request
Sign patient registration request, patient consents and nonce with patients digital signature
Submit pre-signed patient sign-up content to UA_PIS. Patient sign-up eHeath Auth page as query parameter according to table:

query param	M/O	Comment

query param	M/O	Comment
client_id	M	PIS `client_id`
redirect_uri	M	PIS `redirect_uri`
scope	O	List of scopes that must be approved by user
user_data	M	Pre-signed patient sign-up content, base64 encoded

Auth UI: Validate query parameters

Validate query params, obtained from PIS.
1. check client_id exists and is not empty
  1. in case of error - return 'Не вказаний ідентифікатор додатку для авторизації'
2. check redirect_uri exists and is not empty
  1. in case of error - return ‘Не вказано адресу зворотнього визову’
3. check user_data exists and is not empty
  1. in case of error - return ‘Не вказано дані для реєстрації’

Auth UI: Initialize sign-up request validation

Submit sign-up content to UA_PIS. Patient sign-up validation endpoint, fill in fields according to table:

Parameter	Comment

Parameter	Comment
`signed_content`	`user_data` from query params
`signed_content_encoding`	Const: ‘base64’

Validate methods response:

in case 200 with patien data and jwt is returned - proceed to ‘Show patient data to confirm’, save jwt
in case error is returned - show error page with error message from endpoint response

Auth UI: Show patient data to confirm

In case sign-up request validation step completed successfully, Auth UI front-end renders patient data from sign-up validation endpoint response to confirm registration in the system with button ‘Accept and proceed’.

All rendered fields must be read-only.

Auth UI: Validate phone number

Submit patients phone number from sign-up content to Verify phone number endpoint, fill in fields according to table:

Parameter	Comment

Parameter	Comment
`factor`	`person.authentication_methods.phone_number` from sign-up content
`type`	Const: ‘SMS’
`content_hash`	MD5 hash of base64 decoded `signed_content`

Add Authorization header with jwt.

Validate methods response:

in case 200 with result = ‘OTP sent’ and next_step = ‘REQUEST_OTP’ - add field for patient to input OTP, obtained from SMS, after code is submitted - proceed to ‘Confirm patient sign-up form’
in case 200 with result = ‘Verified’ - proceed to ‘Confirm patient sign-up form’
in case error is returned - show error page with error message from endpoint response

Auth UI: Confirm patient sign-up form

Submit patients sign-up content with optional OTP to UA_PIS. Patient sign-up registration endpoint, fill in fields according to table:

Parameter	Comment

Parameter	Comment
`signed_content`	`user_data` from query params
`signed_content_encoding`	Const: ‘base64’
`otp`	OTP, if necessary

Add Authorization header with jwt.

Validate methods response:

in case 201 with patient data, user data and session token is returned - proceed to ‘Show consent page’
in case error is returned - show error page with error message from endpoint response

Auth UI: Show consent page

Obtain list of scopes, that must be approved by patient (from query params or based on user roles and global user roles).
Obtain translations for list of scopes.
Show consent page with user and client data, as well as list of scopes translations with button ‘Accept and proceed’.

Auth UI: Accept scopes

Submit content to Authorize an Approval endpoint, fill in fields according to table:

Parameter	Comment

Parameter	Comment
`client_id`	`client_id` from query params
`redirect_uri`	`redirect_uri` from query params
`scope`	`scope` from query params based on user roles and global user roles

Add Authorization header with session token.

Validate methods response:

in case 201 with session token is returned - redirect grant code to client
in case error is returned - show error message at Show consent page

Auth UI: Redirect grant code to redirect_uri

Redirect user with grant_code to redirect_uri from Authorize an Approval response

PIS: Obtain access and refresh token

Submit content to Exchange oAuth Code Grant to Access Token endpoint, fill in fields according to table:

Parameter	Comment

Parameter	Comment
`grant_type`	Const: authorization_code
`code`	Obtained grant code
`client_id`	`client_id` from query params
`client_secret`	Client secret value
`redirect_uri`	`redirect_uri` from query params

Validate methods response:

in case 201 with access and refresh tokens is returned - save their values to PIS back-end
in case error is returned - show error message at PIS FE

E-Health

UA_PIS. Patient sign-up flow

Purpose

Key points

Sequence diagram

Patient sign-up flow

PIS: Prepare patient sign-up data

Auth UI: Validate query parameters

Auth UI: Initialize sign-up request validation

Auth UI: Show patient data to confirm

Auth UI: Validate phone number

Auth UI: Confirm patient sign-up form

Auth UI: Show consent page

Auth UI: Accept scopes

Auth UI: Redirect grant code to redirect_uri

PIS: Obtain access and refresh token