Purpose

This WS is designed to authorize users scopes. Requested scopes should be allowed for user role, client type and clients broker scopes.

Key points

1. This method should be reachable only by the eHealth authorization front-end application.

2. This method is idempotent.

3. After creating Approval user should be redirected to redirect_uri with code and state (if it was specified in request) query parameter.

Specification

Apiary

Validations

Validate token

• Check Authorization header with Bearer token exists

  • in case of error - return 401 ('Authorization header is not set or doesn't contain Bearer token')

• Check that token is valid and not expired

  • in case of error - return 401 ('Invalid access token')

Validate user

• Extract user_id from token

• Check user is not blocked (is_blocked <> true)

  • in case of error - return 401

• Check user scopes in order to perform this action (scope = 'app:authorize')

  • in case of invalid scope - return 403 (“Your scope does not allow to access this resource. Missing allowances: app:authorize”)

Validate client

• Check client_id field exists in request and is not empty

  • in case of error - return 422 ('can't be blank')

• Check client is not blocked (is_blocked <> true)

  • in case of error - return 401 ('Client is blocked)

Validate redirect uri

• Check redirect_uri field exists in request and is not empty

  • in case of error - return 422 ('can't be blank')

• Check redirect uri belongs to client through mithril database, connections table using client_id

  • in case error - return 401 ('The redirection URI provided does not match a pre-registered value.')

Validate scope

• Check scope field exists in request and is not empty

  • in case error - return 422 ('Requested scope is empty. Scope not passed or user has no roles or global roles.')

• Extract user_id from token. Search for user roles and global user roles in mithril database. Check that value in scope field exists in scopes for user roles or global roles

  • in case error - return 401 ('Scope is not allowed by user role.')

• Get client type scopes by client_id. Check that value in scope field exists in scopes for client type

  • in case error return 401 ('Scope is not allowed by client type.')

Validate confidant person and relationship (optional)

This additional validations must be done only for patients token - if person_id exists in token details and is not empty.

Get applicant_person_id from token details, compare it to person_id from token:

• if equal - check whether person corresponds to following rules:

  • persons age < no_self_registration_age global parameter;

  • persons age between no_self_registration_age and person_full_legal_capacity_age global parameters and person does not have document with type from PIS_PERSON_LEGAL_CAPACITY_DOCUMENT_TYPES config parameter;

  • persons age > person_full_legal_capacity_age global parameter and exists at least one active and approved confidant person relationship for person (using following process https://e-health-ua.atlassian.net/wiki/x/HIabFAQ with person_id = person_id from token details - expected :ok, :approved response)

    • if person does not correspond to rules - skip validation

    • if person corresponds to rules - check that requested scopes exist in PIS_READ_ONLY_SCOPES_ALLOWED config parameter

      • in case of error - return 422 ('Requested scopes do not match with allowed scopes for the user.')

• if not equal - get confidant person relationship status using following process https://e-health-ua.atlassian.net/wiki/x/HIabFAQ with person_id = person_id and confidant_person_id = applicant_person_id from token details:

  • if process returns :error, :not_found - return 401 ('Can’t confirm relationship')

  • if process returns :ok, :approved - skip validation

  • if process returns :ok, :not_approved - check that requested scopes exist in PIS_NOT_VERIFIED_RELATIONSHIP_SCOPES_ALLOWED config parameter

    • in case of error - return 422 ('Requested scopes do not match with allowed scopes for the user.')

Check relationship between patient and confidant person (optional)

This validation must be done only in case user_id and applicant_user_id are different as it means that it is a part of confidant person process. In such case we must ensure that relationship between both persons exist and is valid

Get person_id and applicant_person_id from token details

Check relationship using Relationship between Confidant Patient and Related Patient validation algorithm and having person_id and applicant_person_id

1. If relationship doesn’t exist - return 401 ('Can’t confirm relationship')

Maximum tokes limit for client (optional)

Get maximum tokens limit for client from maximum_tokens_limit field in priv_settings of client:

• if value exists and is not empty - get current tokens count of client from Redis database, key client_tokens_limit_<<client_id>> (with client_id = id of client from request; if key does not exist in Redis database - assume that count for client = 0), compare two values:

  • if current tokens count < maximum tokens limit - authorize an approval for a client, update current tokens count for client in Redis database (add 1 to key client_tokens_limit_<<client_id>> value)

  • if current tokens count >= maximum tokens limit - return 401 ('Maximum tokens limit for client exceeded')

• if value does not exist or is empty or NULL - skip validation

Service logic

1. Determine scopes to be approved

   1. If relationship confirmed - proceed with requested scopes

   2. If relationship exists but not confirmed - filter requested scopes with allowed scopes (env PIS_NOT_VERIFIED_RELATIONSHIP_SCOPES_ALLOWED). So get only scopes that is in allowed list

2. Approve requested scopes for client_id and user_id. (list of scopes determined in p.1)

3. Add or update approved scopes list for user and client in mithril database, apps table, set:

   1. id = autogenerate uuid (for new record)

   2. scope = scope

   3. user_id = user_id

   4. client_id = client_id

   5. applicant_user_id = value of details.applicant_user_id from Authorization header token, if exists, else user_id

   6. inserted_at = now() (for new record)

   7. updated_at = now()

4. Generate ‘authorization code’ token, save token to mithril database, tokens table, set:

   1. id = token uuid

   2. name = 'authorization_code'

   3. value = hashed token

   4. expires_at = date and time when token will be expired in unix-time format

   5. details = additional details of token (scope_request, client_id, grant_type, redirect_uri, applicant_user_id, applicant_person_id, app_id)

      1. applicant_user_id = value of details.applicant_user_id from Authorization header token (if exists)

      2. applicant_person_id = value of details.applicant_person_id from Authorization header token (if exists)

      3. app_id = uuid of approval between user_id, applicant_user_id and client_id

   6. user_id = user_id

   7. inserted_at = now()

   8. updated_at = now()

5. Generate urgent data – add authorization code token value to redirect_uri value.

6. Render a response according to specification.