Example #1 Authentication

Authentication Examples

The Data API uses OAuth2 authentication framework to authenticate and authorise requests for client data. The OAuth2 framework is widely supported by identity providers.

Kalibrate use Azure Active Directory as it's identity provider for API client credentials.

To access the API, each request must provide an access token in the Authorization header. This access token must be requested from the data api identity provider.

Token Request

The following RAW HTTP example shows the POST request to the microsoft AD Tenant requesting an access token:

POST / HTTP/1.1
Host: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id=0525B217-CBB9-4D4A-B8A1-7551C30098CF
&client_secret=1234
&grant_type=client_credentials
&scope={scope}

Token Response

The output result is a JSON document containing the authorisation details:

{
    "token_type":"Bearer",
    "expires_in":3599,
    "ext_expires_in":3599,
    "access_token":"abcefgh...."
}

The most important element being the access_token which must be provided as an Authorization header with every request to the data API.

Access token's retrieved this way cannot be refreshed. Once they timeout (3599 seconds) a new token must be requested in the same fashion as the original request.

Worked Example - Python

We can readily implement the authentication process using various development languages. Python is a freely available and widely supported scripting language.

Import useful libraries

First we need to import some basic python libraries.

import requests
import json
import os
import logging

Parameters

The Client ID, Client Secret and Scope are key parameters that we need to pass to the authentication endpoint. One way that we might retrieve these is by setting them as environment variables and then we can retrieve them in our script.

client_id = os.environ.get("API_CLIENT_ID")
client_secret = os.environ.get("API_CLIENT_SECRET")
scope = os.environ.get("API_SCOPE")

Authentication Endpoint

Kalibrate will have provided an authentication endpoint from which to retrieve tokens. This will be different for Non Production and Production environments.

The following endpoint is for Non Production environments like the customer development environment (Sandpit)

authURL = 'https://login.microsoftonline.com/efa98c7b-2114-46e8-be99-954a4f1a2d9c/oauth2/v2.0/token'

Construct the request

We can now construct the request to the authentication endpoint to retrieve our token

# Build the request body data
postBody = {
    'client_id': client_id,
    'client_secret': client_secret,
    'scope': scope,
    'grant_type': 'client_credentials'
}

# Post the request to the authentication endpoint
resp = requests.post(authURL, data=postBody)

# Check the return code
if resp.status_code != 200:
    logging.error("Request failed [%s]" % resp.text)
    quit()

# Parse the response (JSON)
jsonbody = json.loads(resp.text)

# extract the access token from the response body
token = jsonbody["access_token"]

We can then use this in our API requests, like so:

# Note that we set the User Agent (You can set it to whatever you like.)
# Our API Gateway does not like script kiddies and will reject any python requests that 
# have the default user agent set.

authHeader = {"Authorization": "Bearer %s" %token, 'User-Agent': 'API-CLIENT'}

# The Data API endpoint (status)
response = requests.get('https://dev.data.thekalibratecloud.com/api/status', 
    headers=authHeader, timeout=60)

# Check the response
if response.status_code != 200:
    logging.error("API Request failed [%s]" % response.text)
    quit()

logging.info("Successfully executed query [%s]" % queryURL)

rawdata = json.loads(response.text)

The status endpoint is a good way of checking that the API is up and running and that credentials are valid.

{
    "token": "{bearer token}",
    "audience": "api://dev.data.thekalibratecloud.com/c770a337-3c7e-4bbe-a8cb-2fbc9601b94f",
    "issuer": "https://sts.windows.net/efa98c7b-2114-46e8-be99-954a4f1a2d9c/",
    "version": "1.0",
    "clientId": "{client-id}",
    "tenantId": "c770a337-3c7e-4bbe-a8cb-2fbc9601b94f",
    "expirationTime": "2020-09-18T15:28:40+00:00"
}

You can find the complete sample script here

← Excel