OAuth 2.0 Authentication Workflow

Introduction

This appendix describes a two-legged OAuth 2.0 flow that depicts app-to-app authentication. If you are not already familiar with the OAuth 2.0 authentication protocol, please refer to the following link for more detailed information on OAuth 2.0:

• https://auth0.com/docs/api-auth/which-oauth-flow-to-use

Components

The following components make up the authentication workflow:

• Partner client
• OAuth Authorization Server (part of the BaaS Platform)
  • Responsible for:
    • Issuing Credentials for clients – permanent
    • Issuing Access tokens (per provided Request tokens) – temporary
    • Validating Access tokens
• BaaS Platform API-s:
  • Any request to API-s must be made with an Access token, which will be validated by the API prior to executing it, per business logic.

The sequence in the diagram below, illustrates how Oauth2.0 authentication functions when making API calls.

Note: Step 0 (not in this diagram) assumes that valid credentials were issued to the Partner during the on-boarding process.

Client Credentials Flow

Endpoint: POST /authentication

This endpoint uses OAuth 2.0 and authenticates the client credential. It requests an access token that is required for all BaaS APIs. Access tokens are valid for a fixed period. Once expired, they must be requested again.

API Call Structure Parameters

• Authorization (String, Header) - Required. In the form of “Basic {ClientCredential}”, where Client Credential is Base64 encoded of ClientID followed by colon and clientSecret: “client_id:client_secret”.
• X-GD-RequestId (String, Header) - Required. A request identifier in UUID format.
• Content-Type (String, Header) - Required. Application/JSON.
• grant_type (String, Body) - Required.
• Scope (String, Body) - Optional. Note: Provide a value if specific scopes are requested.

Sample Request and Response

Request Details:-
POST /Authentication HTTP/1.1
Host:{BaaS Server}
X-GD-RequestId:e8459421-3cd1-497f-9dae-4507a37d2f56
Authorization:Basic c3RyaW5nOnN0cmluZw==
Content-Type":"application/json
Body:
{
  "grant_type":"client_credentials"
}

Response From Token Endpoint:-
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
Cache-Control:no-store
Pragma:no-cache
{
  "access_token":"{Access Token}",
  "token_type":"{Token Type}",
  "expires_in":{
    Lifetime in Seconds
  },
  "scope":"{Scopes}"
}

Oauth Access Token Validation

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}

Request Parameters

• X-GD-RequestID (String, Header) - Required. A request identifier in UUID format.
• Authorization (String, Header) - Required. In the form of “Bearer {Access_Token}”, where Access_Token is obtained using Authentication endpoint.
• accountIdentifier - (String, Path) - Required. A unique identifier for an account.
• programCode - (String, Path) - Required. A unique identifier for a program.

Request

GET …/programs/{programCode}/accounts/{accountIdentifier}

• Host: {BaaS Server}
• Authorization: Bearer 6ECC4zFnNAEZDwHM7twavw==

Response

If the request is not successful with invalid access token, the response message will be returned along with a 401 Unauthorized HTTP status code.

If the request is successful with valid access token, the request will be processed.