OAuth Configuration

Purpose

This tutorial introduces users to the Eightfold (EF) OAuth Authentication, including a general overview of Oauth server basics, information about types of Oauth flows, the Eightfold OAuth 2.0 process flow and will answer certain frequently asked questions about OAuth 2.0.

Audience

This document is created considering its use for solution architects, customers, and implementation partners.

Process Flow

Here is the process flow that is followed for Eightfold Oauth2.0 authentication:

Connect with auth server to validate the credentials
Acquire the token once the authorization prompt is visible and app request is approved
Use the token to access the resource server and access the data

📘
Note
In the initial stage we are going to implement this flow as that is the current use case of the client we are planning to satisfy.

Configuring OAuth

To configure OAuth, a user will have to follow two major steps. The first is to get the server credentials, the second is to use these credentials to get OAuth token, and the third is to use the token to validate your API calls.

Step 1 : Getting server credentials

Fetch the API Basic credentials and use the email as the user_id and the _api key _as the password to fetch the token from the authentication token endpoint. This can be found on the Admin Console. Here is the path for the same:

Integration > Eightfold API > Authentication > Generate API Key

1791 — Path to Generate API Key on Admin Console

Step 2 : Fetching the OAuth token

Use the credentials that you fetched from the Admin Console and pass it in the payload of the Authentication fetch token call.

For sending the authentication request, hit this URL.

https://apiv2.eightfold.ai/oauth/v1/authenticate

These calls are secured behind basic authentication. For using the token, add it to the header.

Please refer to the notes below for the regional domain list.

Authorization header: US Region

Authorization: Basic MU92YTg4T1JyMlFBVktEZG8wc1dycTdEOnBOY1NoMno1RlFBMTZ6V2QwN3cyeUFvc3QwTU05MmZmaXFFRDM4ZzJ4SFVyMGRDaw==

Authorization header: EU Region

Authorization: Basic Vmd6RlF4YklLUnI2d0tNZWRpdVZTOFhJOmdiM1pjYzUyUzNIRmhsNzd5c2VmNTgyOG5jVk05djl1dGVtQ2tmNVEyMnRpV1VJVQ==

Authorization header: Govt Accounts

Authorization: Basic UnRRM2NPa1doMlVtVHBHSFlobnl6YnhSOjU1UXcxYXZKclI3VjNRdUMxN2VwSWFadDFEd2hmaG5xempieFE4QlVRMUtFZzFzRg==

Authorization header: CA Region

Authorization: Basic Q3hTYzBvaVZuZ2llOFdQMXRsdkxSMlg3OlBJTjVndmRaUVRvc0p3d2Q4SFE1djJMcWNCbVR1d0kybmU5SEU2bFJLT0hLaVNGUw==

Authorization header: ME Region

Authorization: Basic NHhsY3BWaVRxa2dPMEd6NENCZXFjb3ZWOkI4MEVGT0J3NGx3M0lGbWd2ZUtzU0tMMTZvQ2IxaUM5dUhkcTFEQjVqZ3cwdzZ2Sg==

Authorization header: WU Region

Authorization Basic YVRmRzdwVkJKRUVzTGZBY2dITENHUFdLOmMzbkRaM3czRGNmcExLUko5c0JmUFJUME1WSGxqVU1wbTNsRHBwUUU1YVVRYmc3Mw==

Request type: Post
Payload Type: application/json

{
   "grantType": "password",
   "username": "[email protected]",
   "password": "afpstqpcfgbreylauixrdftyvequyadp"
}

{
   "data": {
       "access_token": "4YIaOAkSKDPe3ImZDFy6GGxwqsYX0ynpkBZVuHJINm",
       "expires_in": 864000,
       "scope": "global",
       "token_type": "Bearer"
   }
}

📘
Regional Eightfold API Domain list

apiv2.eightfold.ai - For US

apiv2.eightfold-eu.ai - For EU

apiv2.eightfold-gov.ai - For US government

apiv2.eightfold-ca.ai - For Canada

apiv2.eightfold-me.ai - For UAE

apiv2.eightfold-wu.ai - For US (Azure Cloud)

Here are the query parameters explained:

Request Parameters	Description
grantType	This tells the way the application gets an access token
username	The credentials of the user
password	The password available after generating the password grant

Response Parameters	Description
access_token	The authorization required by the application to make API requests on behalf of the user
expires_in	The lifetime of the access token set by the user
scope	One or more space-separated strings that indicates the permissions requested by the application. The specific OAuth API you’re using will define the scopes that it supports.
token_type	The type of access token used to make an API call

Sample Postman Call

Here is a sample request to help understand better:

curl --location --request POST 'https://apiv2.domain.ai/oauth/v1/authenticate' \
--header 'Authorization: {auth for given region}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grantType": "password",
    "username": "{from admin console}",
    "password": {from admin console}
}'

📘
Note:
The 'domain' under the authorization header will be as per the regional domain list. The user name and password will be from the admin console (Admin Console>Eightfold API>Authentication>OAuth 2.0

Step 3 : Using OAuth token

Once the authentication token is received, the user can this token to the authorization header to authenticate all API calls.

“Authorization”: “Bearer 4YIaOAkSKDPe3ImZDFy6GGxwqsYX0ynpkBZVuHJINm”

📘
Note:
Once the authentication token expires, the user will get a 403, urging them to request for a new authentication token before continuing.