Exchange oAuth Code Grant to Access Token

Purpose

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

Key points

1. This method must be performed only on applications back-end.

2. Value of client_secret must not be exposed to applications front-end.

Specification

Logic

1. Update grant code in mithril database, tokens table, set:

   1. details.used = true

   2. updated_at = now()

2. 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

3. Generate ‘refresh token’.

4. 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()

5. Render a response according to specification.

Input parameters

Attributes

Token:

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