Manage automation users#

Configure and manage dedicated users and groups for automation tasks that interact with external components or systems, such as in Intelligence Center integration implementations.

It is a good idea to have one or more dedicated user, groups, and roles, as necessary, to handle automation tasks that interact with external products or components of your system:

Automation roles group sets of permissions to define and to constrain the actions automation users are allowed to perform.
Automation groups bring together automation users, and they define which Intelligence Center areas, features, and functionality are accessible to automation users.
Automation users handle automation and integration tasks – based on the automation role they are assigned and the automation groups they are members of – such as authentication, data exchange through outgoing and incoming feeds, or automatic entity creation as a follow-up action on a specific event.

Create an automation user group#

An automation group should include all the allowed data sources the automation users in the group need to access.

Intelligence Center data sources can be:

Incoming feeds
Enrichers
Groups

To create a new automation user group:

In the side navigation bar click > User management.
Click the Groups tab, and then click + (Create group) to create a new user group.

The group editor is displayed.

Under Create group,define the following configuration settings:

In the Name field enter a short, clear, and descriptive name to identify the automation user group.

Example: Integration automation group
In the Description field enter a short, free-form description to clarify the purpose and the scope of the automation user group.

Example: Automation group to integrate and exchange data with external systems and services through incoming and/or outgoing feeds

Under Allowed sources, click + Add or + More to define the data sources the automation group can access, and the TLP-based access level.
1. From the Sources drop-down menu, select one or more data sources the automation user group and its members can access to retrieve data from.
  
  Data sources can be existing incoming feeds and enrichers, as well as existing Intelligence Center user groups.
  
  If you do not specify any data source, the current group becomes the default allowed data source.
  Note
  - Role-based permissions define:
    - The type of actions users are allowed to perform.
    - The type of objects users are allowed to interact with.
  - Group-based Allowed sources and TLP define:
    - Specific Intelligence Center data, assets, and resources users are allowed to access.
2. From the TLP drop-down menu, select a Traffic Light Protocol color to filter data accordingly.
  
  Default value: Red
3. Click + Add or + More to add new rows as needed, where you can enter additional criteria.
From the Source reliability drop-down menu, select a reliability value to filter data source by.

The automation user group is granted access only to data whose source reliability matches the filter value you set here.
From the Allowed roles drop-down menu Group admin settings, select one or more roles that group admins can assign to member users of the groups they are admin of.

Alternatively:
- Start typing a role name in the autocomplete text input field.
- Select one or more filtered roles from the matching result list.
To remove a selection, go to the item(s) you want to remove, and click the cross icon X.

To remove all selections at once, click the cross icon X next to the drop-down menu arrow in the input field.

Alternatively, click Unselect all options.

Group admins can assign to the users of the groups they manage only the role subset you define here.

This setting protects from unwanted privilege escalation by limiting the set of role-based permissions group admins can grant to their group members.
To store your changes, click Save; to discard them, click Cancel.

To access additional save options, click the down arrow on the Save button:
- Click Save and new to save the current data or configuration for the item you are working on, and to create a new item of the same type right away.
  
  For example, a new dataset, feed, policy, rule, task, or workspace.
- Click Save and duplicate to save the current data for the item you are working on, and to create a new prepopulated copy of the same item, which you can use as a template or a blueprint to speed up repetitive manual work.

Create an automation role#

To create a new automation role:

In the side navigation bar click > User management.
Click the Roles tab, and then click + (Create role) to create a new role.

The role editor is displayed.

Under Create role, define the following configuration settings:

In the Name field, enter a short, clear, and descriptive name to identify the automation role.

Example: External systems integrator
In the Description field, enter a short, free-form description to clarify the purpose and the scope of the automation role.

Example: Allows implementing data exchange interoperability between EclecticIQ Intelligence Center and an external system.
From the Permissions drop-down menu, select the actions the role is allowed to perform, and EclecticIQ Intelligence Center objects the role can act on.

Alternatively:
- Start typing a permission name in the autocomplete text input field.
- Select one or more filtered permissions from the matching result list.
To remove a selection, go to the item(s) you want to remove, and click the cross icon X.

To remove all selections at once, click the cross icon X next to the drop-down menu arrow in the input field.

Alternatively, click Unselect all options.
To store your changes, click Save; to discard them, click Cancel.

About permissions#

Permission purpose

Permissions provide granular user access control to Intelligence Center functionality, assets, and resources.

Permission names

Permission names are descriptive:

A verb describes the type of action the permission grants
A noun or noun phrase describes EclecticIQ Intelligence Center object that the action can be carried out on.
Format: ${type of action} ${object of the action}
Example: modify entities

Permission organization

Permissions are grouped in roles.

Roles act as containers for sets of permissions.
They define the set of capabilities and actions users can carry out in EclecticIQ Intelligence Center.
Users can be granted one or more roles.

Permission usage

Permissions are predefined in EclecticIQ Intelligence Center. They are not editable or configurable.
You can either grant permissions to, or revoke them from roles.

Permission actions

Permissions allow two types of action:

Modify: a modification permission that allows to read, create, update, and delete Intelligence Center data.
Read: a read-only permission that grants access to Intelligence Center data, without allowing any modifications.

View permissions

To display a list of the available Intelligence Center permissions:

In the side navigation bar click > User management > Permissions.
To sort items by column header:
- Click the header of the column whose content you want to sort.
- Click or to sort the content in either ascending or descending order, respectively.

Note

Role-based permissions define:
- The type of actions users are allowed to perform.
- The type of objects users are allowed to interact with.
Group-based Allowed sources and TLP define:
- Specific Intelligence Center data, assets, and resources users are allowed to access.

When you assign permissions to a role, either to modify an existing role or to define a new role, make sure you understand what permissions are and how they work in EclecticIQ Intelligence Center.

For more information, see:

Create an automation user#

To create a new automation user:

In the side navigation bar click > User management.

Click the Users tab, and then click + (Create user) to create a new automation user.

The user editor is displayed.

Under Create user, define the following configuration settings:

In the First name field, enter a name that provides a short description of the automation user and its purpose.

Example: taxii-sync.
In the Last name field, enter a name that provides a short description of the automation user and its purpose.

Example: between-platforms.
In the Username field, enter the designated user name to identify the automation user when it is signed in to EclecticIQ Intelligence Center.

Choose a name that helps understand what the automation user does.

Example: platform-to-platform-connector; platform-splunk-connector.
In the Email field, enter an email address associated with the automation user.

This is the email address the user activation email is sent to, with further details about setting a password for the user and completing the activation process.

Active users can sign in to EclecticIQ Intelligence Center and carry out actions, based on their permissions.

You can use this address to send and to receive automated notifications.
You can ignore the Contact info field.
Optionally, in the PGP public key field enter the user’s PGP public key, if available.
From the Locale drop-down menu, select a locale.

Tip

Selecting a Locale allows user to select a timezone from the Preferred timezone drop-down menu.
Select the Use system timezone to use the timezone set in Settings () > System settings > General > Timezone.

When not selected, the Preferred timezone menu appears allowing you to select a specific timezone for selected Locale.
In the Groups section, you can add the user to groups, and you can designate them as members or admins of the groups you assign them to.

Group membership controls user
access to Intelligence Center data, assets, and resources.

Note

Users must belong to at least one user group to be able to access EclecticIQ Intelligence Center data, assets, and resources.
1. From the Group drop-down menu, select the group you want to add the user to.
2. From the User type drop-down menu, select whether you want the user to be a Member or a Group admin of the groups they belong to.
  
  To remove a selection, go to the item(s) you want to remove, and click the cross icon X.
3. Click + Add or + More to insert new rows or input fields, as necessary, where you can enter additional group membership and user type details.
In the Assigned roles section, click the Roles field, and then select one or more available roles from the drop-down menu.
- Start typing a role name in the autocomplete text input field.
- Select one or more filtered roles from the matching result list.
To remove a selection, go to the item(s) you want to remove, and click the cross icon X.

To remove all selections at once, click the cross icon X next to the drop-down menu arrow in the input field.

Alternatively, click Unselect all options.

The Roles field works like Groups, the only difference being that instead of adding the user to one or more groups, this option assigns one or more roles to the user.

Roles enable controlling what actions users are authorized to carry out in the Intelligence Center, and which Intelligence Center objects they can act on.
To access additional save options, click the down arrow on the Save button:
- Click Save and new to save the current data or configuration for the item you are working on, and to create a new item of the same type right away.
  
  For example, a new dataset, feed, policy, rule, task, or workspace.
- Click Save and duplicate to save the current data for the item you are working on, and to create a new prepopulated copy of the same item, which you can use as a template or a blueprint to speed up repetitive manual work.

Get the automation group source ID#

Intelligence Center entities include a source field. It is a key/value pair to uniquely identify EclecticIQ Intelligence Center group as a data source.

If you want to programmatically create entities in the Intelligence Center, pass a group source ID value when you send the corresponding requests to EclecticIQ Intelligence Center API.

Likewise, if you want to identify EclecticIQ Intelligence Center source group as a data source when EclecticIQ Intelligence Center transmits data to an external product or system, you can retrieve, and then pass, the source ID value.

To retrieve the correct source ID value identifying a group as a data source:

Retrieve the automation group ID.
Pass the automation group ID in an API request to obtain the corresponding source ID.

Step 1 of 2: retrieve the group ID#

To retrieve the group ID value, so that you can then obtain the source ID to pass in subsequent requests to the Intelligence Center API:

In the side navigation bar click > User management.
Click the Groups tab.
In EclecticIQ Intelligence Center group overview, click anywhere in the row corresponding to the group whose data source ID you want to use as input.

The action returns a URL with the following format:

https://${platform_host}/user-management/groups?detail=${group_id}

# Example
https://cti.platform.org/user-management/groups?detail=30

In the example, the detail value is 30.

This is the ID that uniquely identifies the group.

Pass this value in a request to the /private/groups/${group_id} Intelligence Center API endpoint to retrieve the source ID value.

Step 2 of 2: get the group source ID#

To send API requests to API endpoints you must have a valid API token.

You pass the API token as a Bearer token with any requests you send to EclecticIQ Intelligence Center API.

To obtain an API token to programmatically authenticate through API requests:

Sign in to EclecticIQ Intelligence Center through the web-based GUI.
Create an API token.
Pass it as a Bearer token in an Authorization HTTP header with any requests you send to EclecticIQ Intelligence Center API.

The Authorization HTTP header has the following format:

Authorization: Bearer ${token}

To retrieve the source ID to send requests to EclecticIQ Intelligence Center API to programmatically create entities:

Obtain an API Bearer token.
Send a request to the /private/groups/${group_ID} endpoint:
Pass the Bearer token in a Bearer HTTP header with the request.
Include the group ID you previously retrieved as a trailing element in the URL.

Example:
```
https://${platform_host}/private/groups/30
```
In the JSON response, look for the group object with the "id" : ${int} key/value pair matching the group ID you previously retrieved.

Example:
```
"id" : 30,
```
In the same group object, look for the "source" : "${UUID_string}" key/value pair.

This is the group source ID to pass in API requests to programmatically create entities.

Example#

The following example assumes that authentication has succeeded, and that you have a valid Bearer token.

It uses cURL to:

Send a request to the /private/groups API endpoint to obtain all available data about the group whose ID value is 30.
Obtain a response with a JSON object containing the requests group data, including the source value that identifies the group as a data source in EclecticIQ Intelligence Center.

cURL API request — fetches the group object data#

$ curl -X GET \
      -v \
      --insecure \
      -i \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${token}" \
      --url https://${platform_host}/private/groups/30

API response — returns the group data, including source#

{
  "data": {
    "admin_users": [
      3
    ],

    "allowed_roles": [],

    "allowed_sources": [
    // Lists all allowed data sources configured in the group editor
    {
        "allowed_tlp": "WHITE",
        "source": "e29ae1x8-1234-5bhg-675k-46d5a420hash"
      }
    ],

    // ...

    // Group id
    "id": 30,
    "last_updated_at": "2019-07-02T12:42:37.597748+00:00",

    // Group name
    "name": "Los pollos hermanos",

    // Group source ID to identify the group as a data source
    "source": "e29ae1x8-1234-5bhg-675k-46d5a420hash",

    "source_reliability": null,
    "type": "groups",
    "users": [
      7,
      6,
      10,
      9,
      2,
      8,
      1
    ],
    "users_count": 8
  }
}

Authentication#

EclecticIQ Intelligence Center authentication mechanism is based on JSON Web Token (JWT).

The token header contains an issued-at timestamp, which is used to check token validity.

By default, the token expires 30 minutes after successfully signing in to a Intelligence Center user session.

Before expiring, a pop-up dialog notifies users that their session is about to be terminated.

Users can choose to continue the current session, or to let it expire.

When the token expires the corresponding session is terminated, and users are automatically logged out.

They need to sign back in to EclecticIQ Intelligence Center if they want to resume working.

When users sign out of EclecticIQ Intelligence Center, the JSON web token related to the web session they just terminated is revoked, and it is no longer valid.

This prevents reusing the token for unauthorized access.

When human interaction is detected — for example, keystrokes or mouse activity — the token is automatically refreshed every 60 seconds.

This prevents the system from signing out users who may be working or saving data at that time.

Therefore, the default maximum amount of idle time without any human interaction before being automatically signed out equals to session token validity - 1 minute.

Authenticate#

To authenticate and to access EclecticIQ Intelligence Center with user name and password credentials:

Make a POST request to the /auth API endpoint.
In the request, pass valid username and password authentication credentials as a JSON object to the /auth endpoint.

The validated credential data is used to generate a Bearer token that is returned with the response.
Include the Bearer token value in any subsequent API requests.
Pass the token by including an Authorization HTTP header in the API request.

The Authorization HTTP header has the following format:

Authorization: Bearer ${token}

Auth endpoint#

API endpoint	`/auth`
Auth method	`POST`
HTTP headers	`"Content-Type: application/json"` `"Accept: application/json"`
API request	`POST + "Content-Type: application/json" + "Accept: application/json" + { "username": "${username}", "password": "${password}" } + https://${platform_host}/api/auth`
API response	`{ "expires_at": "${expiration_timestamp}", "token": "${token}" }`

Auth request#

The following example authenticates with a cURL request:

# Authenticate with username and password
curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"username": "[email protected]", "password": "bug#1"}' \
    --url https://${platform_host}/auth

Auth response#

If the user name and password credentials are valid, the POST request returns a JSON web token:

# Response: Bearer token for the web session
{
  "expires_at": "2019-07-14T12:41:10.063375+00:00",
  "token": "eyJhbGciOiJU ... wiZ1oxNTEwaTIyNDcwfQ.eyJ1c2VyX2lk1jo3fQ.3o65E263hSGf4od5o4eoME2GRF-CnYJvaVg69YTq9HU"
}

Example#

# Example: request a complete list of content blocks belonging to the selected feed
curl -X GET \
    -v \
    --insecure \
    -i \
    -H "Content-Type: application/json" \
    -H "Authorization:Bearer eyJhbGciOiJU ... wiZ1oxNTEwaTIyNDcwfQ.eyJ1c2VyX2lk1jo3fQ.3o65E263hSGf4od5o4eoME2GRF-CnYJvaVg69YTq9HU" \
    --url https://${platform_host}/feeds/downloads/200

Note

About cURL calls

If you make HTTPs cURL calls to the API, and if you have a self-signed or an invalid certificate, include the -k or the --insecure parameter in the cURL call to skip the SSL connection CA certificate check.
Always append a / forward trailing slash at the end of an API URL endpoint.

The only exception is /auth, which does not take a forward trailing slash.
In the cURL call, the -d data payload with the entity information must be flat JSON, not hierarchical JSON.

To pass a hierarchical JSON object, include the --data-binary parameter, followed by the path to the JSON file, for example @/path/to/entity_file.json

Example: --data-binary @/path/to/entity_file.json