Purpose

This WS is used to describe sign-up flow for patient via confidant person 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.
This flow requires user to be already authenticated to prove his relationship with person to be registered
Patient registration is performed using pre-signed request on PIS side.

Sequence diagram

title Sign-Up via confidant person

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"
note left of pis_fe: Prerequisites - user already authenticated\nand has access_token
pis_fe->user: Show registration form
user->pis_fe: Fill in 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\ntoken
auth-->be: Validate signature and extract data
be-->auth: <<Response>>
opt Unauthorized
    auth->pis_be: <<Error response>>
end
opt Invalid signature
    auth->pis_be: <<Error response>>
end

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: <<Register patient>>
    be-->be: Search patient
    note right of be: tax_id/document + name + other
    alt Only one patient found
        be->be: Check relationship between confidant and patient
        opt Not confirmed
            be->auth: <<Error response>>
        end
        be->be: Search user
        be->be: Create if not exists
        be->be: Generate authorization token
        be->auth: <<Authorization token>>
        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
    else
        alt Patient not found
            be->be: Create patient
            be->be: Create relationship
            be->auth: <<Info response>>
        else More than one patient found
            be->auth: <<Error response>>
        end
    end
end

Patient sign-up flow

PIS: Prepare patient sign-up data

Authenticate as existing user that has confirmed relationship with patient
Fill in patient registration request
Sign patient registration request, patient consents with digital signature
Submit pre-signed patient sign-up content to UA_PIS. Confidant patient sign-up 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	M	List of scopes that must be approved by user
user_data	M	Pre-signed patient sign-up content, base64 encoded
token	M	Token of authenticated user

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 scope exists and is not empty
  1. in case of error - return ‘Не вказано скоупів для авторизації’
4. check user_data exists and is not empty
  1. in case of error - return ‘Не вказано дані для авторизації’
5. check token 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. Confidant 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’

Headers:

Authorization: token from query params

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: Confirm patient sign-up form

Submit patients sign-up content with optional OTP to UA_PIS. Confidant 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’

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 UA_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 UA_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. Confidant 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: 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