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_url with code 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.')

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')

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.