AnalyticsOS - Cloud API Documentation v.1.0

  2. Home
  4. Docs
  6. AnalyticsOS – Cloud API Documentation v.1.0
  8. Authentication

Authentication

[bt_bb_section layout=”boxed_1200″ lazy_load=”yes” show_boxed_content=”no” allow_content_outside=”no”][bt_bb_row][bt_bb_column lazy_load=”yes” highlight=”no” align_to_edge_column=”no” width=”1/1″][bt_bb_text]

Summary

This document provides the information needed to authenticate to the AnalyticsOS℠ Cloud RESTful APIs. Please refer to the AnalyticsOS℠ Cloud API Specification document for the API details.

Version

This specification document corresponds to

  • AnalyticsOS℠ Cloud Sensor Ingestion v1.0
  • AnalyticsOS℠ Cloud Result Manager v1.0

Authentication Overview

AnalyticsOS℠ APIs utilize an OAuth Client Credentials Grant (as defined in OAuth 2.0 RFC 6749, section 4.4). The authorization server is provided by a 3rd party service, Auth0. Auth0 refers to this as a Machine-to-Machine (M2M) flow. Figure 1 below is provided by the Auth0 M2M documentation and demonstrates the basics of this flow. In this example, clients utilizing the AnalyticsOS℠ APIs are the “M2M App”.

Figure 1: Auth0 M2M Flow

Obtaining an Access Token

Access Tokens are obtained by making an HTTP POST to the appropriate token URL. An example of this call, along with parameters and response can be found below. Auth0 also provides a more detailed guide on making these requests.

Table 1: Access Token API Parameters

Parameter Name Description
AUTH_DOMAIN Token URLs are defined per environment in Table 2 below.
grant_type Set this to “client_credentials”.
client_id Provided by Lone Star to each client using the AnalyticsOS℠ APIs. A unique ID will be provided for each environment (staging/test and prod).
client_secret Provided by Lone Star to each client using the AnalyticsOS℠ APIs. A unique secret will be provided for each environment (staging/test and prod).
audience Audiences are defined per environment in Table 2 below.

Table 2: Auth Environment Configuration

Parameter Name Staging Production
AUTH_DOMAIN lonestaranalysis-staging.auth0.com lonestaranalysis.auth0.com
Audience https://cloud-staging.analyticsos.com/api https://cloud.analyticsos.com/api

Upon a successful request, an HTTP 200 response is returned containing the access_token (a signed JSON Web Token), token_type, and expires_in (seconds) values. Example:

Client Secret Changes

Lone Star may periodically rotate Client Secrets. All clients will be notified in advance of those changes, please see the AnalyticsOS℠ Cloud SLA document for more details.

To ensure as little downtime as possible, it is recommended that client applications store multiple secrets as a fallback when transitioning to a new secret. This way clients can update their application configurations in advance of Lone Star enabling the new secret.

Using the Access Token

After obtaining an access token, it can then be passed to the AnalyticsOS℠ API as a Bearer token in the Authorization header of your HTTP request. See the example below.

This provides the API with all the Authentication and Authorization information it needs in order to process the request appropriately.

Access Token Expiration

Typically access tokens are good for 24 hours after being issued. It is recommended the client cache this token when able and only refresh upon or before expiration. Clients should use the expires_in value to determine the token lifetime, as it could vary in the future. If an expired token is presented to an AnalyticsOS℠ API, an HTTP 401 response will be returned with the following payload:

References

Auth0 Compliance: https://auth0.com/security/

OAuth 2.0 RFC 6749: https://tools.ietf.org/html/rfc6749#section-4.4

Auth0 Machine-to-Machine (M2M) Flow: https://auth0.com/docs/flows/concepts/m2m-flow

Auth0 M2M Guide: https://auth0.com/docs/flows/guides/m2m-flow/call-api-using-m2m-flow

[/bt_bb_text][/bt_bb_column][/bt_bb_row][/bt_bb_section]