Managing Access

📍 Location

Console	x.threatx.io
API	`api.threatx.com/tx_api/v2/login`

For details about the API endpoints and commands, see the API Reference Guide (requires a ThreatX account to access).

The login command uses an API key to return a temporary access token that authenticates your session.

The api_key, created within the ThreatX user interface ( Settings API Keys ), is used within the request for the api_token parameter. The response then provides a unique and temporary access_token string to be used in further endpoint commands.

Table 1. Login Command Object
Parameters	Type
`“command”: “login”`	String
`“api_token”: ”<api_key>”`	String

📌 Example 1. Login Command Usage

Request

$ curl api.threatx.com/tx_api/v2/login \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
    "command": "login",
    "api_token": "<api_key>"
}
EOF

Response

{
"Ok": {
    "status": true,
    "token": "<access_token>"
  }
}

Audit Log

📍 Location

Console	Settings Audit Log
API	`api.threatx.com/tx_api/v2/logs` (command: `audit_events` )

The ThreatX audit feature logs events, such as updating users, updating sites, and adding IP addresses to whitelists and blocked lists. The audit log lists all events by category and actions. As opposed to the Log Emitter, the audit log focuses mostly on user actions.

Table 2. Audit Log Event Categories and Actions
Category	Actions	Description
`Lists`	new_entry remove_entry	Lists are the whitelists and blocked lists. The Description column in the audit log identifies the list. The audit log monitors when IP addresses, called entries, are added to or removed from a list.
`Rules`	new_rule remove_rule update_rule	The audit log monitors whenever a rule is added, removed, or updated in the ThreatX platform.
`Sites`	new_site remove_site unset_field update_site	The audit log monitors whenever a site is added, removed, or updated in the ThreatX platform. The unset_field action occurs when a user nullifies a field within the site resource.
`Users`	new_user remove_user update_user	The audit log monitors whenever a user is added, removed, or updated in the ThreatX platform.
`User Actions`	blacklist_entity block_entity watch_entity whitelist_entity	The audit log monitors whenever a user blocks an IP address, adds an IP address to the blocked list or whitelist, or chooses to watch an IP address. Whenever a user adds an IP address to a list, the Lists category shows a new_entry action.

Each column in the audit log has a search icon which you can use to search for a string in that column. The search feature is case sensitive and requires an exact match. The table lists all the action strings you can use to search for a specific action.

📌 Example 2. Using the audit_events command of the logs endpoint

$ curl https://api.threatx.com/tx_api/v2/logs \
  --header 'Content-Type: application/json' \
  --data @- << EOF
{
       "command":"audit_events",
       "token":" <api_token>",
        "customer_name":"<tenant_name>",
        "limit": 100
}
EOF

The Log Emitter also exports the audit logs.

Managing user accounts

Console	Settings Users
API	`api.threatx.com/tx_api/v2/users`

Table 3. User Account Settings
Field	Description
`Email`	User’s email address, which is also the username used to log in. It cannot be changed once saved.
`Password Reset`	Available only when editing a user account. Click Send to send a password reset link.
`First Name`	The user’s given name
`Last Name`	The user’s surname.
`Active`	When selected, the user is active and can log in. When not selected, the account remains valid, but the user cannot log in.
`Read-Only`	When not selected, the user has full write access. Otherwise, they can make no modifications.
`Tenant Admin`	When selected, the user has administration permissions to manage users and sites. ️
`Channel Admin`	When selected, the user has administrator access to the main channel and all of its tenants. ️(Requires Channel Environment architecture).
`Site Groups`	Assigns the user to one or more user groups, where the user can access those sites only. If none are selected, the user can access all sites.

API Access

Generating and revoking API keys

If using the ThreatX API to access the ThreatX platform, you need first need to use an API key with the login command to receive a session token, after which you will be allowed to execute other commands.

To generate an API key:

Navigate to Settings API Keys
Click Add API Key in the top right corner
Complete the necessary fields
Click Save
Store your new key in a safe place! 🗝️

To revoke an API key:

Navigate to Settings API Keys
Click Edit API Key next to the API key you want to revoke
Click Revoke
Click Revoke a second time in the confirmation pop-up.

Generating and revoking sensor API keys

If you deploy sensors in your environment, you are asked to provide a Sensor API key.The sensor uses the key to authenticate to the ThreatX platform.

The Sensor API key is a not the same as the API key mentioned above.

To generate a Sensor API key:

Navigate to Settings Sensors Sensor Keys
Click Add Sensor Key
Store the key securely until you need to deploy a sensor 🗝️
1. If at any point you no longer require a sensor key, simply delete it.

Single Sign-on (SSO)

You can manage SSO configuration directly using the ThreatX API. Once SSO has been configured for a ThreatX tenant or channel, your users can sign in using your SSO identity provider, such as Okta or Azure Active Directory B2C, rather than logging in to the ThreatX web application with a username and password.

✔️ Prerequisites

SAML2 IDP metadata reference URL from your SSO provider (where the most up-to-date metadata file can be found.) Consult your IDP documentation.
Users must have accounts in both the IDP and ThreatX platform
User’s email address in the IDP must match that which is associated with their ThreatX username.
An API key with tenant or channel administrator permissions.
The name and UUID of your tenant or channel

Use the Customers:list command to retrieve the name and UUID of the tenant.

If you do not have access to your IDP metadata URL, you can alternatively provide a complete IDP metadata file. Contact ThreatX support if you want to provide an IDP metadata file instead of an IDP metadata URL.

📌 Example 3. IDP Metadata URLs

Okta

https://threat-x.oktapreview.com/app/exk8lh09bhSIfhupl0h7/sso/saml/metadata

Azure AD B2C

https://login.microsoftonline.com/daad3805-fde6-4334-817f-82c723533123/federationmetadata/2007-06/federationmetadata.xml

Additional prerequisites for Channel SSO

SP Metadata URL Prerequisites

Audience restriction setting (also called “Entity ID”) in the IDP must be set to the path:
```
https://x.threatx.io/sign-in
```

IDP metadata must provide the NameID in the format:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

We use the email address of the user to locate users within our database

ACS URL Prerequisites

When configuring the IDP, the Assertion Consumer Service URL (ACS) of our Service Provider (SP) is:
```
https://x.threatx.io/auth/v2/channels/\<your_threatx_channel_uuid>/acs
```
For IDPs that support Service Provider metadata, the metadata URL of our SP is:
```
https://x.threatx.io/auth/v2/channels/\<your_threatx_channel_uuid>/metadata
```

Configuring SSO access

Use the following steps to configure SSO access for your ThreatX tenant and channel partners:

Log into the API. Authenticate to the API using the Login command.
Gather the tenant or channel data you need using the Customers:list or Channels:list command.
- You need to copy the Customer or Channel Representation information response exactly and paste it into the body of the Customers:update or Channels:updat command with the UUID field omitted.
Assemble your tenant update API request.
Supply your Customer or Channel Representation information to the Customers:update or Channels:update command described in step 2. (See the examples below.)
Set the value of “sso” to an object and define these attributes:
- “enabled” (true),
- “required” (false)
- saml_metadata_url
Submit the tenant or channel update API request. If it succeeds, you should see Customer Update Response or Channel Update Response.
Test the new configuration by using a web browser to navigate to:
1. x.threatx.io/auth/v2/customers/<name>/saml
2. x.threatx.io/auth/v2/channels/<name>/saml
You should be redirected to your SSO Identity Provider to confirm you want to authorize ThreatX Dashboard to act on your behalf.
Follow the prompts in your SSO Identity Provider.
You should be then redirected to the ThreatX Dashboard and authorized to access the system on behalf of your configured user account.
Single-Sign On access is now configured for your tenant.

(optional) You can now update your tenant configuration again using “required: true” to force all your users to use SSO to access the ThreatX Dashboard. This option prevents users from accessing the ThreatX Dashboard directly using the username/password authentication.