OAuth Data Flow

An application must get an access token before using any API in Cytomic Orion. To do this, certain information must be exchanged with the CAS server.

Protocol Used for the Data Exchange

OAuth uses the HTTPS protocol to exchange information flows between the application and the CAS server to get authorization for the Cytomic Orion APIs. This data exchange uses the HTTP protocol POST command. For security reasons, all commands sent and responses received travel encrypted using HTTPS.

Access Types Supported by the CAS Server and Data Required

The OAuth protocol supports multiple types of authentication and authorization depending on the application that accesses the Cytomic Orion API. In the specific case of Cytomic Orion, the type of access allowed by the CAS server is “password”, which must be specified in the “grant_type” parameter of the initial request from the application.

With grant_type password, the CAS server requires this data to allow access to the Cytomic Orion API for an application:

Information Flows Generated to Authorize Access

Communication in the authentication phase between the application and the CAS server works as follows:

OAuth communication between an application and the CAS server

The diagram illustrates a complete OAuth data exchange:

  • The application sends its credentials and the client’s credentials to the CAS server. The CAS server validates the application credentials on the IdP server. If validation is successful, it checks the client’s credentials to generate and issue both an access token and a refresh token.

  • The application uses the access token to access the Cytomic Orion API and retrieve the required data.

  • After the access token expires, the CAS server rejects it. The application sends the refresh token to get a new access token and a new refresh token.

Authentication, Authorization, and Access Token Generation

The Application Requests the Authorization Token

The application sends an HTTPS POST command to the CAS server (https://auth.pandasecurity.com) with these parameters:

POST /oauth/token HTTP/1.1

Host: auth.pandasecurity.com

Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type =password

&client_id ={CLIENT_ID}

&client_secret = {CLIENT_SECRET}

&username = {USER_NAME}

&password = {USER_PASSWORD}

&scope ={SCOPE}

Alternatively, you can use an Authorization header to specify the client_id and client_secret encoded as Base64:

POST /oauth/token HTTP/1.1

Host: auth.pandasecurity.com

Content-Type: application/x-www-form-urlencoded; charset=utf-8

Authorization: Basic client_id:client_secret.

 

grant_type=password

&username={USER_NAME}

&password={USER_PASSWORD}

&scope={SCOPE}

The meaning of the parameters is this:

Parameter Description

grant_type

Required. It sets the value to “password”. It indicates that the application will directly provide the credentials of the application account to which the protected resource belongs.

client_id

Required. It is the ID of the Cytomic Orion client to which the application belongs.

client_secret

Required. It is the password of the Cytomic Orion client to which the application belongs.

username

Required. The name of the account of the application created in the Cytomic Orion console. See Enable Access to the API from External Programs.

password

Required. The password of the account of the application created in the Cytomic Orion console. See Enable Access to the API from External Programs.

scope

The scope of access. It sets the value to “orion.api”.

Parameters required by the CAS server to get the access token
Successful Response from the CAS Server

The response is a JSON object with the access token and other data:

HTTP/1.1 200

{

"access_token":"{ACCESS_TOKEN}",

"refresh_token":"{REFRESH_TOKEN}",

"expires_in":{EXPIRATION_TIME},

"token_type":{TOKEN_TYPE}

}

The meaning of the fields is this:

Field Description

access_token

Access token. It consists of a character string encoded in Base64.

refresh_token

Refresh token. It consists of a character string encoded in Base64.

expiration_time

The time in seconds that the access token is valid for.

token_type

By default, “Bearer”. It indicates that the token is a self-contained token that contains all the resources required to authorize access. The CAS server issues signed JWT (JSON Web Token) access tokens.

Response from the CAS server with the access token and the refresh token
Unsuccessful Response from the CAS Server

The server could not generate a valid token with the information supplied:

HTTP/1.1 400 Bad request

{

"error":"{ERROR_CODE}",

"error_description":"{ERROR_DESC}"

"error_uri":"{ERROR_URI}"

}

The meaning of the fields is this:

Field Description

error

Error code: see table Return Codes.

error_description

Brief description of the error. The content of this field is not prepared to be shown directly to the application user. Messages should instead be adapted to the application.

error_uri

Optional.

Incorrect response from the CAS server

Refresh an Expired Access Token

Because the scope of access for an application can change over time, the access token that an application uses to access the Cytomic Orion API expires in 20 minutes, after which time the Cytomic Orion API rejects it and prevent access to the resource. To prevent the sending of the parameters specified in section Authentication, Authorization, and Access Token Generation, whenever an access token expires, the application sends the refresh token to the CAS server. As such, the refresh token acts as a reference to the original conditions that led to the authorization of the application on the CAS server. If these conditions have not changed, the CAS server reissues an access token to the application. The refresh token has a longer lifespan than the access token.

Send the Refresh Token

The application sends an HTTPS POST command to the CAS server (auth.pandasecurity.com) with these parameters:

POST /oauth/token HTTP/1.1

Host: auth.pandasecurity.com

Content-Type: application/x-www-form-urlencoded; charset=utf-8

 

grant_type = refresh_token

&refresh_token = {REFRESH_TOKEN}

&client_id = {CLIENT_ID}

&client_secret = {CLIENT_SECRET}

&scope = {ORIGINAL_SCOPE}

The meaning of the parameters is this:

Parameter Description

grant_type

Required. It sets the value to refresh_token to indicate that the application sends a refresh token in exchange for the CAS server issuing a new access token.

refresh_token

The refresh token required for the CAS server to generate a new access token.

client_id

Required. This is the ID of the Cytomic Orion client.

client_secret

Required. This is the password of the Cytomic Orion client.

scope

Optional. If you do not include it, the CAS server returns an access token with the same scope as the original request. If you include it, it must contain the same scope as the original request.

Parameters required by the CAS server to generate a new access token
Successful Response from the CAS Server

The CAS server response to the application is the same as the one generated in the original request for the access token. The CAS server can include a new refresh token which will be used the next time the access token is renewed. If the CAS server does not include a new refresh token, it is assumed that the previous token is still valid.

Unsuccessful Response from the CAS Server

The server could not generate a valid token with the information supplied:

HTTP/1.1 400 Bad request

{

"error":"invalid_request"

}

Error Codes

Code Description

200

The operation completed successfully.

400

Error.

Return codes

Error Messages

Error code Description

unrecognized_client_id

The client ID is incorrect or does not exist. Contact the Cytomic support department.

unrecognized_client_secret

The client password is incorrect or does not correspond to the client_id sent. Contact the Cytomic support department.

unauthorized_client

The client is authenticated but is not authorized to make the request.

invalid_client

Any other error related to the validation of clients’ credentials. Contact the Cytomic support department.

unsupported_grant_type

The grant_type sent is not supported. Use “password”.

invalid_grant

The access token received is invalid (it is not recognized or has expired), or the application is not authorized to access the API.

invalid_scope

The scope received is incorrect. This parameter must always be “orion.api”.

access_denied

Wrong user name or password.

invalid_request

The request has an incompatible parameter or does not have all the required parameters.

temporarily_unavailable

The CAS server is currently unable to handle the request due to a temporary overloading or maintenance.

server_error

Internal server error.

Authorization process error messages

Example of How to Get an Access Token and a Refresh Token from the CAS Server

This example shows a call to the CAS server with the username, password, client_id, client_secret, grand_type, and scope parameters required to retrieve the access token and the refresh token needed for future calls to the Cytomic Orion API.

#Uses the requests library to connect to the OAuth server

import requests

from requests.auth import HTTPBasicAuth

#Sets the client_id, client_secret, username, password, and scope

client_id = ’aaf1461b7a8a593199665’

client_secret = ’YaDzUdHmlrivXYaAFhJDFiNe5x0mI4’

username = ’7e0aa013282249cdebd15a08f84d’

password = ’jEshWDjjS2h6bCxrZKCy8iVbBHNcCzMxxUe362CfUwz0eAKXRdlz9uOuVzFp3g’

grant_type = ’password’

token_url = ’https://auth.pandasecurity.com/oauth/token’

scope = ’orion.api’

headers = {

’Content-Type’: ’application/x-www-form-urlencoded’,

}

#Configures the HTTP message body. The client_id and

#client_secret credentials are set in the message headers

body = {

’username’: username,

’password’: password,

’scope’: scope,

’grant_type’: ’password’

}

#Encodes the client_id and client_password in Base64 and launches the HTTPS request

r = requests.post(token_url, auth=HTTPBasicAuth(client_id, client_secret),

headers=headers, data=body, verify=False)

#If there are no errors, the response is converted to a JSON object to enable #access

if r.status_code==200:

data = r.json()

#Loads the access and refresh tokens on the variables

token_access=data[’access_token’]

token_refresh=data[’refresh_token’]

Example of How to Use an Access Token and a Refresh Token

All calls to the Cytomic Orion API must include, in the HTTP headers, the access token generated after the authentication and authorization process. However, 20 minutes after the access token is issued, it expires and you must get a new one by using the refresh token. For this reason, you must check each call to the Cytomic Orion API to make sure it does not return an invalid token error. If that is the case, request a new access token and retry the request with the new token.

#Example call to the indicator API

#Sets the required parameters

alert_from='1572595090000' #from 11/01/2019

alert_to='1575187090000' #until 12/01/2019

 

#Prepares the HTTP header with the access token to make the call to the API

h_request = {

’Authorization’: f’Bearer {access_token}’,

’Accept’: ’application/json’

}

 

url_alert = f'https://api.orion.cytomic.ai/api/v1/applications/alerts/{alert_from}/{alert_to}'

r = requests.get(url_alert, headers=h_request, verify=False)

#After authentication is successful, checks whether the access token has expired in each call

if r.status_code==401:

body_refresh = {

’grant_type’:’refresh_token’,

’refresh_token’:token_refresh,

’client_id’:client_id,

’client_secret’:client_secret,

}

#Requests a new access token and a new refresh token

r = requests.post(token_url, headers=headers, data=body_refresh,verify=False)

data = r.json()

#Updates variables with the new access and refresh tokens

token_access=data[’access_token’]

token_refresh=data[’refresh_token’]