Authorization (Token/HMAC)

In general, when communicating with the ThreatConnect API using the TcEx Framework, the App developer does not need to handle authorization. If using any of the Resource Classes in tcex_resources, the authorization headers are automatically added. This allows the App to run from within the ThreatConnect platform or the Integration server without having to change any code.

The tcex() module also has the session property, which is a Python Requests Session (http://docs.python-requests.org/en/master/user/advanced/#session-objects) with ThreatConnect authorization added. API calls to the ThreatConnect API can be made with the native Requests interface with authorization and token renewal built in.

Note

The latest version of the ThreatConnect platform supports both token-based and HMAC authorization. The ThreatConnect Environment server supports HMAC or token-based authorization, depending on the version.

Token Refresh

Token-ased authorization requires that the token be renewed upon expiration. The ThreatConnect platform passes the tc_token and tc_token_expires arguments to the App. The TcEx Framework automatically handles the token refresh when using session.

HMAC Authorization

HMAC authorization is typically only used for running Apps outside the ThreatConnect platform. Generation of the authorization headers when using HMAC will utilize the api_access_id and api_secret_key arguments. These arguments are not automatically sent by the ThreatConnect platform and are required to be added to the :ref:install_json file. In the ThreatConnect UI, these inputs will automatically be hidden in favor of token-based authorization. However, on certain versions of the Environment server these arguments may be required.

Example install.json param section:

<...snipped>
{
  "label": "ThreatConnect API Access ID",
  "name": "api_access_id",
  "required": true,
  "sequence": 1,
  "type": "String",
  "validValues": [
    "${USER:TEXT}",
    "${ORGANIZATION:TEXT}"
  ]
}, {
  "encrypt": true,
  "label": "Local ThreatConnect API Secret Key",
  "name": "api_secret_key",
  "required": true,
  "sequence": 2,
  "type": "String",
  "validValues": [
    "${USER:KEYCHAIN}",
    "${ORGANIZATION:KEYCHAIN}"
    ]
}
<snipped...>

For proper HMAC authorization, the HTTP method and the Uniform Resource Identifier (URI) with query string arguments are required when building the authorization string. Therefore, the authorization string has to be built after the URI and query parameters are built and before the request is sent.