Exchange oAuth Code Grant to Access Token

1 Purpose
- 1.1 Key points
2 Specification
3 Logic
4 Input parameters
5 Request structure
6 Authorize
7 Headers
8 Validation data request
- 8.1 Validate grant type
- 8.2 Validate grant code
- 8.3 Validate client
- 8.4 Validate redirect uri
- 8.5 Validate approvals
9 Processing
10 Response structure
11 HTTP status codes

Purpose

This WS is designed to exchange authorization code with requested scopes to access token for user and client.

Key points

This method must be performed only on applications back-end.
Value of client_secret must not be exposed to applications front-end.

Specification

Link	https://uaehealthapi.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/oauth/exchange-oauth-code-grant-to-access-token	Посилання на Apiary або Swagger
Resource	/oauth/tokens	Посилання на ресурс, наприклад: /api/persons/create
Scope	List of scopes that are required in application business logic, separated by space	Scope для доступу
Components	oAuth_system_component	Зазначається перелік бізнес компонентів, які використовують цей метод, наприклад: ePrescription
Microservices	mithril/api mithril_scheduler abac/api abac_log_consumer fe/auth-web mithril/fe mithril/gatekeeper-mithril fe/admin-gatekeeper-web	Перелік мікросервісів, які використовує метод API, наприклад: Auth, ABAC
Protocol type	REST	Тип протоколу, який використовується запитом, наприклад: SOAP \| REST
Request type	POST	Тип запиту API, наприклад: GET, POST, PATCH…
Sync/Async	Sync	Метод є синхронним чи асинхронним?
Public/Private/Internal	Public	Потрібно зазначити тип методу за ступенем доступності

Logic

Update grant code in mithril database, tokens table, set:
1. details.used = true
2. updated_at = now()
Generate ‘access token’ with requested scopes for user_id and client_id based on value of ACCESS_TOKEN_JWT configuration parameter:
- true - generate token in JWT format according to Access tokens JWT format
- false - generate token in existing format
Generate ‘refresh token’.
Save tokens that were generated in existing format to mithil database, tokens table, set:
1. id = token uuid
2. name = token name (‘access_token’ or ‘refresh_token')
3. value = hased token
4. expires_at = date and time when token will be expired in unix-time format
5. details = additional details of token (scopes, client_id, grant_type, applicant_user_id, applicant_person_id, app_id)
  1. applicant_user_id = value of details.applicant_user_id from grant code (if exists)
  2. applicant_person_id = value of details.applicant_person_id from grant code (if exists)
  3. app_id = uuid of approval between user_id, applicant_user_id and client_id
6. user_id = id of user
7. inserted_at = now()
8. updated_at = now()
Render a response according to specification.

Input parameters

Attributes

Token:

Attribute	Values	Type	Description	Example

Attribute	Type	Description	Example
client_id (required)	String	Medical Service provider ID issued after legal_entity registration. Used to identify the context of the MSP/Pharmacy	6498d88e-97fb-47e2-85a5-99e884f888aa
client_secret (required)	String	Medical Information System secret key issued upon integration request. Used to identify application developer	msp-001-secret-key
code (required)	String	oAuth code grant	299383828
grant_type (required)	String	oAuth Grant Type. Currently only `authorization_code` is supported	authorization_code
redirect_uri (required)	String	URL where user will be redirected after authentification. This url will receive `code` and `state` parameters in query string	Example Domain
scope (required)	String	List of scopes that is required in application business logic, separated by space. Different login forms will be shown based on scopes that you requested	capitation_contracts:view capitation_contracts:create patients:view patients:create

Request structure

See on Apiary

Example

{
  "token": {
    "client_id": "6498d88e-97fb-47e2-85a5-99e884f888aa",
    "client_secret": "msp-001-secret-key",
    "code": "299383828",
    "grant_type": "authorization_code",
    "redirect_uri": "https://example.com/",
    "scope": "capitation_contracts:view capitation_contracts:create patients:view patients:create"
  }
}

Authorize

Request to process the request using a token in the headers

Headers

Example:

Content-Type:application/json

X-CSRF-Token:my-csrf-token

Validation data request

Validate grant type

Check grant_type field exists in request and is not null
- in case of error - return 422 ('Request must include grant_type.')
Check grant_type field value equals to ‘authorization_code’
- in case of error - return 401 ('Grant type not allowed.')

Validate grant code

Check code field exists in request and is not null
- in case of error - return 422 ('can't be blank')
Check grant code with value = code and name = ‘authorization_code’ exists in mithril database, tokens table
- in case of error - return 401 ('Token not found.')
Check grant code is not expired in mithril database, tokens table (expires_at is in the future)
- in case of error - return 401 ('Token expired.')
Check grant code was not already used in mithril database, tokens table (details.used <> true)
- in case of error - return 401 ('Token has already been used.')

Validate client

Check client_id and client_secret fields exist in request and are not empty
- in case of error - return 422 ('can't be blank')
Check client is not blocked in mithril database, tokens table (is_blocked <> true)
- in case of error - return 401 ('Client is blocked)
Check client from grant code equals to client_id
- in case of error - return 401 ('Token not found or expired.')
Check client_secret belongs to client through mithril database, connections table
- in case of error - return 401 ('Invalid client id or secret.')

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 in request equals to redirect uri in grant code
- in case error - return 401 ('The redirection URI provided does not match a pre-registered value.')
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 approvals

Check that approval for scopes list by app_id from grant code still exists in mithril database, apps table
- in case of error - return 401 ('Resource owner revoked access for the client.')

Processing

API paragraph not found

Response structure

See on Apiary

Example:

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": {
    "value": "SnNRdCtvU0tTOENBV2dLRUZwNmIzZz09",
    "user_id": "3ff33ced-69dc-415a-b231-c6446898335a",
    "name": "access_token",
    "id": "3ff33ced-69dc-415a-b231-c6446898335a",
    "expires_at": 1498749591,
    "details": {
      "scope": "capitation_contracts:view capitation_contracts:create patients:view patients:create",
      "refresh_token": "my-oauth-refresh-token",
      "redirect_uri": "https://example.com/",
      "grant_type": "authorization_code",
      "client_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
    }
  }
}

HTTP status codes

HTTP status code	Message	What caused the error

HTTP status code	Message	What caused the error
201	Response