Managing SOAR Platform users

You manage users and their roles from the Users tab. From the Users tab you can create new accounts, assign groups, assign workspaces, assign roles, reassign incidents and tasks, deactivate, and delete users. You can also create API key accounts to enable apps or external scripts to access the SOAR Platform through the REST API.

If LDAP is enabled for your organization, the users of authorized LDAP groups are listed and are given the default permissions after they are known to the SOAR Platform. For example, users are known after they are assigned an incident. For LDAP users, you can reassign only incident and tasks in the Users tab. You must use LDAP for the other tasks. For more information, see LDAP authentication for SOAR.

If configuring the SOAR Platform for the first time, it is preferable to define roles in the Roles tab before configuring user accounts.

New user and roles

To set up a new user, click Administrator Settings, then go to the Users tab.

  1. In the Users tab, click Invite User.
  2. Enter the user’s email address.
  3. Add the user to one or more groups by selecting them from the drop-down menu. You can use groups to build up incident response teams that can be assigned to incidents.
  4. Select the appropriate role or roles. If you are assigning multiple roles, the user has the superset of all the permissions that are granted in the roles. If a user is not assigned a role, the user has the default permission to be assigned incidents and manage those incidents when a member or owner of the incident.
    Note: You cannot assign workspace roles to users from this dialog. For more information, see SOAR platform workspaces.
  5. Click Send Invitation.

The user receives an email that contains a link to log in and create a password. New users can go to My Settings from the menu near their name at the upper right and complete their contact information.

By default, the user's password expires in 90 days. For on-premises installations, you can modify the expiration date as described in SOAR Platform password and API key expiration.

SOAR Platform API key accounts

API key accounts are designed to enable external scripts or apps to authenticate to the SOAR Platform through the REST API, with the minimum permissions. A system-generated token is used to authenticate. API key accounts are not linked to LDAP and cannot access the SOAR Platform user interface, own incidents or be members of an incident or group. The API key display name is unique for each organization in the SOAR Platform.

About this task

Apps that are installed using the Apps tab automatically create their own API key account. For apps that are deployed with the Integration Server, manually create an API key account with a set of permissions that are needed for that app to run successfully.

When you create an API key account, you must specify a display name for the account. You can also assign the minimum permissions that are needed for that key account. For example, if the script or app that accesses the SOAR Platform requires only permission to edit incidents, you can assign only these permissions.
Note: To create and manage API key accounts, your global role must have the API Keys permission, which is assigned from the Administration and Customization Permissions. If you upgraded from a previous version of the SOAR Platform, you must assign this permission to one or more roles.

Each API key account contains a server-generated ID and secret, a unique display name, and the permissions assigned. It also contains the user who created or last updated the key account and the created or updated time and date, and if added, a description.

API key accounts ignore two factor authentication. In addition, API key accounts cannot access the SOAR Platform user interface. They cannot own or be members of incidents, own or be members of tasks, or be members of a group.

Incidents that are created by API key accounts are automatically assigned to the default group if an incident owner is not specified during incident creation.

Procedure

  1. Go to Administrator Settings > Users and click the API Keys tab.
  2. Click Create API Key.
  3. From the Create API Key screen, enter the display name for the API key account. It must be unique in the organization. The display name is shown on the Administrator Settings > Users > API Keys tab. You can also enter a description. From the Permissions section, assign the necessary permissions for the API key that you are creating.
  4. Click Create. The API key credentials are displayed.
  5. Make a note of the credentials and store them safely as you cannot retrieve them after you click OK. Then click OK to proceed.

Results

The API Key Account is created.

To change the permissions, display name, or description, go to Administrator Settings > Users > API Keys, select the key to edit, and click Edit. From the editor, change the permissions or display name, as needed.

If you need to regenerate the key, see Regenerating an API key.

To delete the key, click Regenerate API Key Secret > Delete API Key.

By default, the API Key account expires in one year. For on-premises installations, you can modify the expiration date as described in SOAR Platform password and API key expiration.

Important: An API key account is generated automatically whenever an app is installed using the Apps tab. Changing the permissions or regenerating the secret of this account might cause the app to stop working.

Regenerating an API key

You can regenerate the API Key account secret to change the secret as needed. Regenerating the secret does not change the ID.

You might need to regenerate the key secret if the API Key Account is locked due to too many failed login attempts. Any locked API key accounts have a True status in the Locked column.

API key accounts are often used by one or more apps for authentication. Regenerating an API key account secret might cause a running app that uses the API key account to lock up.

For apps configured to use an App Host , you can prevent the app from locking.
  1. Determine which app or apps authenticate with the API key account. Typically, the API key account name includes the app name. If it does not, you can also use one of the following methods.
    • Use the API Key account name, which is listed with API Key account itself and in the Configuration tab of an app under App Secrets.
    • Use the API Key ID, which is listed with API Key account itself and in the app's app.config file as api_key_id.
  2. Go to the Apps tab, click the app that uses the API key account then click Undeploy. For more information, see Managing SOAR apps.
  3. Regenerate the API key.
    1. Go to the Users tab then click API Keys.
    2. Click the API key that you want to regenerate. Scroll down to see the API Key Details of the account.
    3. Click Regenerate API Key Secret then click Regenerate API Key Secret in the drop-down menu. The ID remains the same but a new secret is generated.
    4. In the API Key Credentials, click Copy to Clipboard. You can paste the ID and secret into a text file temporarily so you can easily paste just the secret when you update the app.
  4. Update the app's secret.
    1. Click the app on the Apps tab then click its Configuration tab.
    2. In the App Secrets section, click the name of the API key account.
    3. Paste the new secret in the Secret Value field then click Update.
  5. Click the Details tab then click Deploy to reactivate the app with the new secret.

For apps deployed by an integration server, you need to add the new secret to the app's app.config file. For more information, see Editing the configuration file.

You cannot pause a single app that was deployed with the integration server. You can pause all running apps by stopping the Resilient® Circuits service then restarting the service after you update the secret.

Change groups or roles

To view or edit the details of any user, click the username then scroll to the end of the page to see the details. Click Edit to change the assigned groups and roles.

Screen shot of User Details

As defined in Managing SOAR Platform roles, global roles define a set of permissions that apply across the organization and workspace roles are a set of permissions for specific workspaces only. Permissions that are assigned through global roles are aggregated with workspace permissions that are granted through workspace roles. Therefore, if a user has an assigned global role that includes permissions to create incidents, the user can create incidents in any workspace.

You can assign a workspace role then restrict the user’s permissions to just that workspace by removing the user's organization level permissions in global roles.

Reassign incidents and tasks

You can reassign open incidents and incomplete tasks from active and deactivated users to another active user as follows. If you are using LDAP, you can also reassign a deleted LDAP user’s open incidents and incomplete tasks.

  1. Click the drop-down arrow near your username then click Administrator Settings.
  2. In the Users tab, click the user's username then scroll to the end of the page to see the details.
  3. In the User Details section, click Reassign Incidents/Tasks.
  4. Choose to reassign all the user's incidents, tasks, or both by selecting a specific user or group to become the new owner. If the list is long, click […] to filter the user list.
  5. Click Confirm Reassignment to implement your change.

Managing user accounts and passwords

An administrator can deactivate, delete, or reset a user's password.

You deactivate a user to suspend the user's account temporarily, where you can reactivate the user at any time. Deleting a user removes the account permanently.

The following behavior occurs when you deactivate a user.

  • The user remains the owner of any incidents and tasks unless you reassign them.
  • The user cannot be assigned new tasks or incidents.
  • The user appears as deactivated in the Groups tab. An administrator can change group membership for deactivated users.
  • Any saved incident filters containing the deactivated user are not affected.

The system does not send notifications to deactivated or deleted users.

You can deactivate or delete a user.

  1. Click the drop-down arrow near your username then click Administrator Settings.
  2. In the Users tab, select the user's username then scroll to the end of the page to see the details.
  3. In the User Details section, click the Deactivate User drop-down then choose to deactivate or delete the user.
  4. With either selection, choose to reassign any open tasks and incidents to another user. If the user is to be deactivated for a considerable amount of time, you can reassign the incidents and tasks.
  5. Implement your change.

You can reactivate the user by selecting the username and choosing to reactivate.

To reset a user's password, select a user to open User Details, click Deactivate User then select Reset Password.