Security Management

FortiSOAR™ gives you the power to assign levels of accessibility to users with Role-Based Access Control (RBAC) combined with Team membership. You can grant access to specific modules in FortiSOAR™ to users based on their Role Permissions. Users exercise their permissions in conjunction with their Team membership(s). Appliances are governed by the same authorization model.

The security model within FortiSOAR™ achieves the following four essential security goals:

  • Grants users the level of access necessary based on your desired organization structure and policies.
  • Supports sharing of data for collaboration while still respecting your team boundaries.
  • Supports data partitioning and prevents users from accessing data that is not explicitly meant for them.
  • Restricts external applications and scripts (appliances) from using the API beyond the requirements for accomplishing the desired RESTful actions.

The following sections describe several vital concepts you must keep in mind while working with the FortiSOAR™ security model. In-depth discussion and examples might be found in the individual Knowledge Base sections.

Important Concepts

Authentication versus Authorization

The FortiSOAR™ security model consciously treats authentication and authorization separately.

  • Authentication defines your ability to log in and access FortiSOAR™. FortiSOAR™ enforces authentication based on a set of credentials.
  • Authorization governs users' ability to work with data within FortiSOAR™ after authentication is complete. You control authorization by assigning teams and roles to users.

This is an important distinction since when you are setting up user accounts, you must always define both the authentication and desired authorization for a user. Otherwise, once a user logs onto FortiSOAR™, the user might be presented with a blank screen due to lack of authorization.

Users and Appliances

Users represent a discrete individual human who is accessing the system. Users are differentiated from Appliances in that they receive a time-expiring token upon login that determines their ability to authenticate in the system. The Authentication Engine issues the token after users have successfully entered their credentials and potentially a 2-factor authentication. By default, tokens are set to have a lifespan of 30 minutes before being regenerated.

The default 2-Factor authentication consists of a username and password for the primary authentication, and a unique code sent using an SMS or Voice message for the secondary authentication. The secondary authentication method is not mandatory but highly recommended. You can configure the authentication methods on a per-user basis. Use the System Configuration menu to configure the system defaults for the secondary authentication.

Tip

The 2-Factor Authentication can be different for each user, but you can set it at a default preference level across the system. You can also allow a non-admin user to update their own 2-Factor Authentication mechanism. However, this is not recommended.

Appliances represent non-human users. Appliances use Hash Message Authentication Code (HMAC) to authenticate messages sent to the API. HMAC construction information is based on a public / private key pair. Refer to the "API Guide" for instructions for generating the HMAC signature.

Note

For HMAC authentication the timestamp must be in UTC format.

Teams and Roles

Teams and Roles are closely aligned with a data table design. Teams own specific records, which are rows in a table. Roles govern permissions on the columns within that table around Create, Read, Update, and Delete (CRUD) activities.

Teams define ownership of discrete records within the database. A record can have more than one Team owner. Users can belong to multiple teams allowing them to access all records, which are owned by their assigned teams.

Roles define users' ability to act upon data within a CRUD permission set on any module in the system.

Note

You must be assigned a role that has CRUD permissions on the Security module to be able to add, edit and delete teams and roles.

Security Management Menus

The Security Management Administration menu is split into the following seven areas:

Team Hierarchy

Use the Team Hierarchy menu to edit the relationships between teams defined within the system. You can also add and delete teams using the Team Hierarchy page.

Teams

Use the Teams menu to add new teams and edit user membership in bulk within each Team. You can also define membership within teams on an individual basis, using the individual user or appliance profile.

Roles

Use the Roles menu to create and define roles within the system. You assign roles based on CRUD permissions defined across all modules. You can assign roles in the User or Appliance profiles only. Currently, you cannot bulk assign roles.

Version 5.0.0 implements RBAC for playbooks. Prior to version 5.0.0, users who were assigned roles with just Read permission on the Playbooks module could execute playbooks. However, from version 5.0.0 administrators require to assign roles that have the Execute permission on the Playbooks module to users who would be executing playbooks. Execute is a new permission added to the Playbooks and Connector modules.

Note

Users who do not have Execute permissions will not be shown the Execute buttons for the module records, for example alert records. Execute actions include actions such as Escalate, Resolve, or any actions that appear in the Execute drop-down list.

Users

Use the Users menu to create and manage existing users. Each user has a profile with contact information including email and phone numbers plus additional reference information. You can assign teams and roles to users and control a user's state from the user's profile. User states are Active, Unlocked, Inactive, and Locked.

Note

You must be assigned a role that has Create, Read, and Update (CRU) permissions on the People module to be able to add users and edit their user profiles. You cannot delete a user from FortiSOAR™. However, you can make a user "Inactive" to stop that user from using the system. From version 5.0.0 onwards, you can delete users using a script. For more information, see Delete Users.

Appliances

Use the Appliances menu to create and manage Appliances, which use the HMAC authentication model. Appliances are also governed by the same authorization model as users, which means that you must add the appliances to a team, and they must be assigned a role to perform any actions within the system.

Authentication

Use the Authentication menu to configure various authentication settings in FortiSOAR™, including setting session and idle timeouts and settings options for user accounts. You can also setup and manage the LDAP / AD integration and Single Sign-On (SSO) integration within your environment. When you use an external server to perform authentication, you must have an administrative username and password to perform searches to import users.

Note: Version 5.1.0 onwards FreeIPA LDAP authentication is supported.

FortiSOAR™ supports the following methods of authentication: Database users, LDAP users, and SSO.

Note

Even if you configure SSO, you can still provision database and LDAP users.

Secrets

Use the Secrets menu to manage the Secrets store. Use the Secrets store to securely store and manage sensitive data, such as keys and credentials, which might further be used for 3rd party integrations. This feature has been deprecated in version 5.0.0. Use the Password field in the connector configuration instead to securely store and manage sensitive data, such as keys, API Keys, tokens, or credentials.

Configuring Team Hierarchy

Teams represent groups of "owners." If you are a member of a Team that owns a record, then you can apply any Role permissions you have on that record.

There is no direct connection between your Team and Role. If your Team or Teams own a record, you can do whatever you are permitted to do by your Role or Roles. If you are on multiple Teams, you have the permissions provided by your Roles across all those Teams.

Teams only provide ownership of records. Team Relationships extend ownership from one Team's members to another Team's members. Team Relationships are almost a form of "sudo" to borrow from Linux concepts, where you are effectively acting as if you were a member of another Team though you might not be explicitly on the roster of that Team.

Team Relationships do not govern any user permissions. A user's Role or Roles determines their permissions. If you have extended ownership of a record AND sufficient privileges for that record module, then you can exercise those permissions on the extended ownership record.

If your Team has the appropriate relationship, you can work with a record owned by another Team as if you were on that Team, even though your Team may not be identified as an owner.

All user actions in the system are audited, so there is no way for a user to work on a record from another team through a relationship that is not known and recorded.

Relationships

Teams govern record ownership within the FortiSOAR™ Security Model. Team Hierarchy reflects how team ownership relates between discrete teams.

Use the Team Hierarchy editor to define team relationships in accordance with each team's relationships with other teams in the system. The possible team relationships are shown in the following table:

Relationship Type Description
Parent Parent Teams are virtual owners of the records of the Child Team. A Parent team can act on those records as if they were a member of the Child Team.
Sibling Sibling Teams can act on each other's records as if they were each members of the same team.
Child Child Teams are the opposite of Parent Teams. Members of the Parent Teams can act on the records owned by the Child Team, but members of the Child Team cannot act records owned by the Parent teams.

A simple organization chart cannot capture the relationships in this definition. The real structure looks more like a mind map. This was a conscious design decision to support more advanced Team relationship use cases, such as allowing for internal investigations among existing users without alerting the user and providing Legal personas with their own permissions during Incidents.

From version 4.11 onwards, records created by 'nth' level of team hierarchy will be visible to parent teams. For example, records created by grandchildren teams will be visible to the grandparent teams.

There is no inheritance in relationships among Teams or implications from one Team's relationship to another. That means if two teams are Children of a Parent, this does not mean that the Children are Siblings to each other. If you want them to be Siblings, then you must explicitly define them as Siblings.

Using the Editor

The Team Hierarchy Editor is built to centralize around one team at a time and to define how that Team relates to all other teams in the system. The Central Team is referred to as the "Team in Focus" for this document. Click Settings > Team Hierarchy to open Team Hierarchy Editor.

The Team Hierarchy Editor has the All Teams menu and three swim lanes used to define the three relationship types, which are Parent, Sibling, and Child.

Team Hierarchy Editor

To edit the relationships of any team, you must first bring that team in focus. To bring a team in focus, you must drag and drop that team to the Drag team here to edit area or double click that Team's title in the All Teams menu.

Team Hierarchy Editor-Team in focus

Once you have put a Team 'in focus' on the Hierarchy Editor, the relationships that the team in focus has with all other teams is displayed in the respective swim lanes. For example, in the image above, the team in focus is the L1 Team. The L1 Team has SOC Team as the Parent team, L2 Team as its Sibling team and L3 Team as its Child team.

To edit the relationships, drag and drop Team bubbles or the Team titles in All Teams onto the appropriate swim lane. Changes are staged until you click Save. Once you click Save, changes immediately go into effect.

Following is an illustrative example of what is possible in this model:

Example

The SOC Team is the Parent of L1, L2, and L3 so the members of the SOC team can act across all records of the L1, L2, and L3 teams as if they are a member of all teams.

Note you can achieve the same result by adding managers to every team in the organization. However, managers would then never be able to own any records exclusively.

SOC Management Team

The Legal Team is unrelated to all other Teams in this case, which means that the SOC Team team is isolated from all the Legal Team's records and vice versa. If the Legal Team were related to the SOC Managers team, you would have seen the relationship in one of the swim lanes.

The Security Module governs the Role for editing all Teams and Team hierarchies. Anyone with Read access to the Security Module can see all the Teams and Roles within the system.

We recommend you provide Security Module permissions with caution as anyone with the Role can see any relationship in the system and would be alerted if any investigation into their activities were initiated at the Team level.

To summarize the relationships in this view, the SOC Managers:

  1. Effectively own all records of L1, L2, and L3
  2. Own none of Legal

Now let's turn to a different team. If you were to focus L2 Team, you would find a slightly different case. We know that the SOC Team are a Parent Team, so we expect to see that relationship inverted. Beyond the relationship between SOC Team and the L2 Team, no other relationships are implied until you put L2 as the Team in Focus.

L2 Team

When L2 is the Team in Focus, you see that there is another set of relationships governing that Team. The L1 Team is a Sibling of L2, though that is not because the Teams are both Children of the SOC Managers. The Sibling relationship has been explicitly defined between L2 and L3. You also see that the L3 Team is a Child of L2.

To summarize the relationships in this view, the L2 Team can:

  1. Effectively own all records of L1 and L3
  2. Own none of SOC Managers records

The final piece of the example comes from placing L3 as Team in Focus. We know some things already about L3, namely that the SOC Team and L1 Teams are Parent Teams. But we do not know about L2.

L1 Team

When L3 is in focus, we see the expected relationships between the SOC Managers and L2 Teams, but we now see that L1 is also a Parent.

To summarize the relationships in this view, the L1 Team can:

  1. Effectively own only their own records
  2. Own none of SOC Managers, L2, or L3 records

Configuring Teams

Use the Teams page to manage members of a team centrally. You can assign a user to multiple teams; in fact, you can assign a user to be a part of all the teams.

There is no limit to how many Teams you can have in the system. Teams do not necessarily have to represent a specific team within your organization, but instead, Teams represent a group of users who own a set of records. In this way, you can think of Teams as row ownership within a table. The records are rows, and at least one and potentially more than one Team must own that row.

Important

Whenever you add a new team, you must update the Playbook (called WFUSER in previous versions) assignment. Playbook is the default appliance in FortiSOAR™ that gets included in a new team. Only a user with CRUD access to the Appliances module can update the Playbook assignment, to ensure that the appliance has the necessary role to perform data read or write to modules. If the Playbook does not have appropriate permissions, then Playbooks will fail.

Editing Teams

Click Settings > Teams to open the Teams page. Use the Team Editor to create new teams and to assign users in bulk to teams. You can quickly move users between teams by selecting users who are designated to be Team Members. You can use filtering and searching techniques to assign users to teams easily.

You can perform the following operations on the Teams page:

  • Add a team
  • Delete a team
  • Clone a team
  • Edit team details, including editing the name and description of the team and changing the assignment of users within a team

To Delete or Clone a team, on the Teams page, select the team you want to delete or clone, and click Delete or Clone.

To edit a team, on the Teams page, click the team you want to edit. On the Edit Team page, you can change the name and description of the team and edit members. Members of a team are "linked" using the Link button on the Assign Team Members grid.

Team membership page

To add a user and then immediately assign that user to a team click Add.

To add members to a team, click Link, which brings up the Change Relationships modal window. The Change Relationships window displays all the users within the system. Click the checkbox on the user row to add the user to the team. To remove members from a team, click the checkbox on the user row. Click Save Relationship to complete your actions and add or remove members from a team.

Team membership takes effect immediately upon saving across the system.

Team membership editing

Configuring Roles

The Roles menu allows you to define and modify all the roles within the application. Roles are not hardcoded in the system; therefore, Role editing is a sensitive permission and must be carefully governed by system users.

Important

Any user that requires to work with FortiSOAR™ and records within FortiSOAR™ must be assigned a Role with a minimum of Read permission on the Application, Audit Log Activities, and Security modules.

Use the Role Editor to add and edit RBAC permissions within FortiSOAR™. Role permissions are based on the Create, Read, Update, and Delete model (CRUD). Each module within FortiSOAR™ has explicit CRUD permissions that you can modify and save within a single Role. You can also explicitly assign permissions for each field within a module by clicking the Set Field Permissions link for that module.

A user can have more than one role applied to their RBAC model. Each role granted to a user is additive to the users' overall RBAC permission set. Therefore, a users' RBAC permissions is an aggregation of all the CRUD permissions granted to them by each Role they are assigned.

Example 1: If you assign roles of Security Administrator and Application Administrator to User A, then User A will have CRUD permissions on both the Security and Application modules.
Note that the Security Administrator role also has CRUD permissions on the Secure Message Exchange and Tenants modules, so that this role can configure multi-tenanted systems.

Example 2: If you had assigned the role of Application Administrator to User B, then User B gains all the CRUD permissions on the Application module and this user can configure your FortiSOAR™ system.

Example 3: If you want a user to work with Incident records, then you must assign that user with CRUD permissions on the Incident module, apart from that you must also assign the user a Role that has a minimum of Read access on all the related modules. To view the related modules, click Settings > Modules. Select the module whose records you want the user to work on, for example, Incidents from the Select a module to edit or create new module drop-down list. Click the Fields Editor tab to view all the fields and related modules, such as Indicators and Tasks, as shown in the following image. In this case, when you add a user to work in the Incident module, you must also assign the user a Role that has a minimum of Read access on the Indicators and Tasks modules.

Fields Editor - Incident Module

Default Roles

By default, FortiSOAR™ has at least one role in place after installation, the Security Administrator. Apart from the Security Administrator role, FortiSOAR™ generally also has the following default roles defined:

  • Security Administrator - administers Teams and Roles and is responsible for creating the appropriate team structure, building and assigning roles.
  • Application Administrator - given full access to application-wide features, so that they can configure the system and customize FortiSOAR™ as required.
  • Full App Permissions - generally, this role is defined as one that has full permissions across FortiSOAR™, i.e., a root user. You can define this role as per your requirements. Use this role carefully.
  • Playbook Administrator - manages playbooks and connectors and also has permission to the Security module.
  • T1 Analyst - triages alerts, filters false positives, and escalates potentially malicious alerts to incidents for review by T2 Analysts.
  • T2 Analyst - investigates incidents and performs other remediation and containment tasks.

All Roles are "soft" roles, meaning none of the default Roles are hard coded. You can add, modify, reassign permissions, and delete roles at will, but use this power with extreme caution.

Tip

We recommend that you do not modify the default roles and instead add new roles, as per your requirements.

Security Administrator

The Security Administrator role starts by having full CRUD permissions across the Security module. This allows the Security Administrator to add and manage Roles and Teams within the application. The security administrator role also has CRUD permissions on the Secure Message Exchange and Tenants modules, so that this role can configure multi-tenanted systems.

The Security Administrator should be assigned to someone who has been tasked with the responsibility for building and maintaining the role and team structure for your organization.

Do not remove the Security Administrator Role

We recommend you never remove the Security Administrator role. If you remove the Security Administrator role, you must ensure that at least one other role with an assigned user has the Security module enabled if you always want to maintain access to edit teams and roles within the application. You can assign the Security Module to another role, or to another user, as required.

Playbook Administrator

The Playbook Administrator has access to the Orchestration and Playbooks component. Only users who have explicitly been given a minimum of Read access to Playbooks can see this component on the left navigation bar. For users to have full privileges to manage playbooks, you must be given Read, Create, Update, Delete, and Execute permissions.

Note

System-level playbooks are also configured and should remain in place permanently. These are tagged as 'system, dev' and are now in a hidden Collection.

Application Administrator

The Application Administrator is granted access to configure application settings, found in the Application Editor section on the Settings screen.

Tip

All users must have Read privileges to the Application module to be able to use the application interface. Non-human users, API users, can be restricted from entering into the application GUI by not giving them any access to the Application module.

Full App Permissions User

Full App Permission user is a "root" user, who has full permissions across FortiSOAR™. However, data partitioning is still in effect depending on the Team to which the Full App Role user belongs. The result of data partitioning is that a user with the Full App Permissions role might not see all the data within the application unless they have made their Team a Parent of all other Teams in the Application.

T1 Analyst

The T1 Analyst role is given access to the Alerts module and modules associated with alerts, such as Comments, Attachments, etc, and also Schedules. These users are responsible for alert Triaging, false positive filtering and escalating potentially malicious alerts to Incidents for review by T2 Analysts.

T2 Analyst

The T2 Analyst role is given access to the Incidents module and modules associated with incidents, such as Alerts, Indicators, etc, and also People, Schedules, and Reporting. These users are responsible for investigating incidents and performing other remediation and containment tasks.

Modules in the Role Editor

Modules are discrete areas or record sets within the application. Some modules represent discrete record tables while some represent areas of modification within the administrator's panel.

Tip

Not all modules present in the Roles menu are available in the interface. Some of the modules are administrative or for particular purposes, such as the Files module.

Table Modules

Table modules are record sets that are editable within the FortiSOAR™ UI from a component level, i.e., these are all the modules that are listed in the Roles Editor, which is used to set module-specific permissions. Components, which include Incident Management, Vulnerability Management, Resources, etc., consist of a logical grouping of modules. For example, the Incident Management component contains modules such as Alerts, Incidents, Tasks, etc., and the Vulnerability Management component contains modules such as Vulnerabilities, Assets, and Scans. Each of these individual modules is accessible within the navigation menus.

Important

Users can access and modify modules if they are given appropriate CRUD permissions to those modules within FortiSOAR™. For example, if a user requires to modify alerts and incidents, that user must be assigned a role that at the minimum has Read and Update permissions on the Alerts and Incidents modules.

Administration Modules

Administration modules refer to specific areas of administration within the application. These are generally accessible in the Settings menu, with discrete tabs for each of the menu options.

Some of the admin modules found in the system, in alphabetical order, are:

  • Appliances - the ability to manage appliances from the Appliances item.
  • Application - the ability to change system defaults used throughout the system from the System Configuration item.
  • People - the ability to manage human users from the Users item.
  • Playbook - the ability to access and manage the Orchestration and Playbooks component in the left navigation menu.
  • Secret - the ability to manage the secrets from the Secrets item.
  • Security - the ability to manage teams and roles from the Team Hierarchy, Teams, and Roles item.

Adding Roles

To add a new role, click Settings > Roles to open the Roles page. Click Add to open the New Role page enter the role name and description in the respective fields. In the Set Role Permissions grid, the Module column displays the name of the various modules to which you can assign permissions. Each of the Create, Read, Update, and Delete columns have checkboxes that allow you to assign specific permissions for each module. The Playbook module has an additional Execute permission that is required for users to execute actions and playbooks.

Note

Whenever you add a new role, then by default the Read permission for Application will be selected.

For example, if you require to create a user who needs to add and modify alerts and their associated tasks, you can create a new role as shown in the following image:

Role Editor Page with Alerts and Incidents modules selected

Assigning Roles to Users and Appliances

You cannot assign roles in bulk to Users or Appliances. You must assign roles directly assigned to users at the time of creating or updating user or appliance profiles.

To assign a role to a user, click Settings > Users to open the Users page. The Users page displays a list of users (active and inactive) for the organization. On the Users page, click the username to whom you want to assign the role. On the Edit User page, select the role(s) from the Roles table in the Team and Role section that you want to assign to the user, and click Save. If there are more than five roles in the system, the Roles table becomes scrollable.

For example, you can assign the Alerts creation and modification role to New User as shown in the following image:

User Profile page with User A assigned the Alerts and Incidents role

Roles can be added or removed at any time from any profile. When permissions to a Role is changed, then enforcement begins immediately. However, as the UI is built upon login, some aspects of the UI for navigation might still be available until the UI is refreshed or logged out. For instance, if Playbook privileges are removed from your user, you will still be able to see the Playbooks navigation button in the UI, but when you navigate to it, you will be notified that you are not authorized to view that page (401 error).

Configuring User and Appliance Profiles

Adding Users

To add a new user, click Settings > Users to open the Users page. Click Add Person and enter the user details on the New User page and click Save to save the new user profile.

Note that the Username field is mandatory and case sensitive and it cannot be changed once it is set.

Important

All new users, including the csadmin user, must change their password when they first log on to FortiSOAR™, irrespective of the complexity of the password assigned to the users. Ensure that you note down your csadmin password since if you forget your initial csadmin password, then you have to request FortiSOAR™ to reset this password. Also, when you are changing your csadmin password, you must ensure that you also update the email ID that is specified for csadmin, which by default is set to soc@fortinet.com (which is not a valid email ID). You can change the email ID by clicking the User Profile icon (User Profile icon) to open the User Profile page and change the email address in the Email field. Once you set a valid email ID in the user profile, then you would be able to reset your password, whenever required, by clicking the Forgot Password link on the login page.

Use the SMTP connector to configure SMTP, which is required to complete the process of adding new users. The SMTP connector is used to send email notifications. If you have not set up the SMTP connector, the user gets created. However, the password reset notification link cannot be sent to the users, and therefore the process remains incomplete. For more information on FortiSOAR™ Built-in connectors, including the SMTP connector, see the "FortiSOAR™ Built-in connectors" article present on the support site. You must log onto the support site to view this information.

User Profiles

All users within the system have a profile. Each user has access to their own profile so that they can update specific information about them by clicking the User Profile icon (User Profile icon).

The user profile includes users' name, email, username, password, and phone numbers. Users can also view the team and roles they belong to as well as update their theme. Users can also view their own audit logs, which display a chronological list of all the actions that you have performed across all the modules of FortiSOAR™.

You must change your password when you log on to FortiSOAR™ for the first time. To change your password, click the User Profile icon and then select the Change password option. You can also change your password at any time using this option.

Note

The Username field is mandatory that cannot be edited once it is set.

To edit user profiles, you must be assigned a role that has a minimum of Read, Create and Update permission on the People module. Click Settings > Users to open the Users page and click the user whose profile you want to edit. This opens the Edit User page, where you can edit the user's profile, including the user's email ID, name, phone and fax numbers, users' teams, roles, 2-factor authentication settings, notification settings, and theme settings. You can also see their login history.

User Profile Page

A user is one whose People record is Active. If you have Read and Update permissions on both the Security and People modules, you can edit a user's Active or Inactive status on their profile page. If you change a user's status to Inactive, you stop that user from using the system upon expiration of their issued token.

Locked users are those who have exceeded the number of authentications tries allowed within a one-hour period. You can define the maximum number of attempts allowed before the user is locked. The User can only be unlocked by an administrator who has CRUD permissions on the People module and Read and Update permission on the Security module.

By default, users' can enter an incorrect password 5 times, while logging into FortiSOAR™, before their account gets locked for 30 minutes. A Security Administrator can change these default values, see the Debugging, Troubleshooting, and optimizing FortiSOAR™ section for further details.

If a Security Administrator has enforced 2FA across all FortiSOAR™ users, then the Work Phone becomes a mandatory field and you must enter the work phone number for all FortiSOAR™ users. For more information see, Configuring User Accounts.

Note

You might face issues with user preferences such as applying filters on the grid or column formatting within a grid after you have upgraded FortiSOAR™ between major releases such as 5.x.x to 6.x.x. To resolve these issues, click the More Options icon (More Options icon) and click on the Reset Columns To Default option.

Teams and Roles

If you are editing your own profile and you have no access to the People module, then you can only view to which teams and roles you belong.

If you are assigned a role with Read, Create, and Update permissions on the People module then:

  • You can assign roles to users by selecting the roles from the Roles table in the Team and Role section on the Edit User page. If there are more than five roles in the system, the Roles table becomes scrollable.
  • You can assign teams to users by selecting the teams from the Teams table in the Team and Role section on the Edit User page. If there are more than five teams in the system, the Teams table becomes scrollable.

Authentication

An administrator who is assigned a role with Read, Create and Update permissions on the People module and Read and Update permission on the Security module can reset passwords for users on the User Profile page. To reset passwords, open the profile page of the user whose password you want to reset and go to the Authentication section.

User Profile Page: Authentication Section

Click the Reset Password button to reset the password for a user. Clicking Reset Password displays the Reset Password dialog, in which you must enter the new password in the New Password field and re-enter the same password in the Confirm Password field.

Reset Password Dialog

Select the Send Email to User check box to send an email notification to the user whose password you have reset. The email notification tells the user that the administration has changed their password and the user must contact their administrator for the new password or reset their password using the Forgot Password option on the FortiSOAR™ login page. For more information on the Forgot Password option, see the Regenerating your password topic in the "User Guide." Click Submit to reset the users' password.

By default, users' can click the Reset Password link 10 times before actually resetting their password, after which users' will not get a new link to reset their password for 12 hours. A Security Administrator can change these default values, see the Debugging, Troubleshooting, and optimizing FortiSOAR™ section for further details.

You can also configure whether the user is an Application User or Dashboard User. You can set different reauthentication times for an Application user and a Dashboard user.

2-Factor

The 2-Factor authentication menu displays the current user preference for the 2-factor method. Currently, FortiSOAR™ supports only TeleSign for 2-Factor authentication. You require to have a TeleSign account to configure 2-Factor Authentication (2FA) to send the one-time password (OTP) code to the users' mobile devices and log onto FortiSOAR™.

The options for 2FA are: - No 2-Factor authentication.
Version 5.1.0 has provided Security Administrators with the ability to enforce 2FA across all FortiSOAR™ users. Therefore, this option will be displayed only if you have not enforced 2FA across all FortiSOAR™ users. For more information see, Configuring User Accounts.

  • 2FA Voice, which sends a voice message to the user's work phone.

  • 2FA SMS, which sends a text message to the user's work phone.

Note

Once you enable 2FA in a user's profile, then the work phone field becomes mandatory.

Notifications

Currently, notification preferences are limited to email. In the future, in-app notifications and SMS notifications will enable additional notification mechanisms.

Theme Settings

You can update your FortiSOAR™ theme, if you have appropriate rights, using the Theme Settings menu on the Edit User page. There are currently three theme options, Dark, Light, and Space, with Space being the default. Click Preview Theme to see the Theme as it would look and save the profile to apply the theme. To go back to the original theme, after previewing the theme, click Revert Theme.

History

The History menu contains the authentication history for the user and displays the ten most recent authentication attempts and their outcome.

Audit Logs

The User Specific Audit Logs panel displays a chronological list of all the actions that a user has performed across all the modules of FortiSOAR™. Click the Audit Logs panel to view the list of actions. The audit log displays users' login success or failures and logout events. The login event includes all three supported login types, which are DB Login, LDAP Login, and SSO Login. From version 5.1.0 onwards, the audit log also contains user-specific terminate and resume playbook events.

Appliances

Appliance users have a few essential differentiators versus Users (People). The most important one is that API access for appliances uses HMAC verification as opposed to issuing a token from the Authentication Engine. The Authentication Engine uses the HMAC signature to validate the Public and Private key pair, which is issued at the time of Appliance creation. Appliance users also do not have a login ID and do not add to your license count.

Appliance users are generally used for authenticating to FortiSOAR™ while calling Custom API Endpoint triggers. Mostly while configuring auto-forwarding of events and alerts from a SIEM to FortiSOAR™, you can use an appliance user, otherwise you might require to add a user password, in plain text, in the configuration files.

Like Users, you must assign appropriate roles to appliances and also add the appliances as a member of the teams who would be running playbooks, so that appliances can access or modify any data within the system. Team hierarchy and such is restrictions that apply to Users also apply to Appliance Users.

Note

We recommend that you scope the role and team of an Appliance to give it only the bare minimum level of privilege needed to do the job as a good security practice.

Creating a New Appliance

Click Settings > Appliances > Add to create a new appliance. On the New Appliance page enter a name with which to identify that Appliance and select the Team(s) and Role(s) that apply to that Appliance.

Creating a New Appliance

Generating Appliance Keys

Once you save the new Appliance record, FortiSOAR™ displays a pair of Public / Private cryptographic keys in a modal window.

Important

When the Public / Private key pair are generated, the Private key is shown only once. You must ensure to copy this key and keep it somewhere safe for future reference. If you lose this key, it cannot be retrieved. You can always regenerate these keys when required, and a new Private Key gets displayed. However, you must then update the keys as the old keys will be invalidated.

Cryptographic Keys

Appliance Profile

You can modify details of the Appliance user after the Appliance has been created. Click Settings > Appliances to open the Appliances page and click the appliance user whose profile you want to edit. On the Edit Appliance page, you can modify the name, teams, and roles for the appliance user. You can also use Edit Appliance page to access and copy the Public API Key for the appliance at any time.

Appliance Profile

Playbook Appliance

By default, an appliance user is created as Playbook who belongs to the SOC Managers team. This appliance is used by the FortiSOAR™ workflow service to authenticate to the API service when a workflow step is run that reads, creates, updates, or deletes records. Hence, it should have all necessary permissions on the modules that are accessed using playbooks. Also, as a consequence, when a record is inserted by a workflow such as a Playbook or a Rule that uses the appliance, then the inserted record is owned by the appliance user, which by default is Playbook.

For example, If a new incident record is inserted by a playbook or workflow, then the Created By field of this newly inserted record displays the name of appliance user who has executed the playbook, which by default is Playbook. The owner of this newly inserted record will be the team that is assigned to the appliance that has executed the playbook, which by default is SOC Manager. If multiple teams have been assigned to the appliance, then this newly inserted record would have all those teams as 'owners.' Example to explain this is, if you have created a different appliance named QA, which has been assigned SOC Manager and Team A as its teams. Now if a playbook that inserts an alert record is executed using the QA appliance, then the Created By field of this newly inserted alert record will display QA and its owners will be SOC Manager and Team A.

Note

We recommend that you scope the role and team of a Playbook Appliance to give it only the bare minimum level of privilege needed to do the job as a good security practice.

Appliances Overview Screen

You must however assign the new playbook appliance with a minimum of Read permission on the Playbook module so that the new appliance user can run playbooks without getting permission denied errors. You must also assign appropriate permissions on the other modules such as Alerts, based on the playbooks that you intend to run using the appliance.

Regenerating playbook appliance keys

You can regenerate your playbook appliance keys using the process mentioned in the Generating Appliance Keys topic.

If you regenerate the key pair for the playbook appliance, replace the content of the APPLIANCE_PUBLIC_KEY and APPLIANCE_PRIVATE_KEY files at the following locations with the public and private keys that you have regenerated:

  • /opt/cyops-workflow/sealab/.envdir
  • /opt/cyops-integrations/integrations/configs

After you have replaced the playbook appliance keys, you must restart all the FortiSOAR™ services.

You must take care of the following:

  • Ensure that there are no extra files or folders in the sealab/ .envdir directory.
  • Do Not change the SEALAB_PUBLIC_KEYS or the SEALAB_PRIVATE_KEYS.

Troubleshooting

Getting an HMAC failure

Resolution: If HMAC fails, ensure that the server time for the application server is synced with that of the FortiSOAR™ server. You can synchronize both servers to a common NTP server, for example, time.apple.com, to synchronize the time.

Configuring Authentication

Click Settings > Authentication to configure various authentication settings in FortiSOAR™, including setting session and idle timeouts, settings options for user accounts, configuring LDAP / AD, and configuring SAML to enable users to use sign-on (SSO).

FortiSOAR™ supports the following methods of authentication: Database users, LDAP users, and SSO.

Note

Even if you configure SSO, you can still provision database and LDAP users.

To configure authentication settings, you must be assigned a role that at a minimum has Read and Update permissions on the Security module.

Configuring Accounts

Configuring Session and Idle timeouts

Click Settings > Authentication to open the Account Configuration tab. On the Account Configuration page, in the Session & Idle Timeout section, you can configure the following settings for session and idle timeouts:

Setting Description
Idle Timeout The number of minutes a user can be idle on FortiSOAR™ after which the Idle Warning dialog is displayed. The default value is 30 minutes.
Idle Timeout Grace Period The number of seconds a user is given to view the Idle Warning dialog after which FortiSOAR™ logs the user out. The default value is 60 seconds.
Token Refresh The number of minutes after which the session token is refreshed. The default value is 60 minutes.
Reauthenticate Dashboard User The number of hours after which a dashboard user is forced to be reauthenticated. The default value is 24 hours.
Reauthenticate Application User The number of hours after which an application user is forced to be reauthenticated. The default value is 24 hours.

Notes:
In the case of a non-admin user the Token Refresh, Reauthenticate Dashboard User, and Reauthenticate Application User settings do not work. In the case of Token Refresh, the user gets logged off from the FortiSOAR™ UI once the session token refresh time is reached. In the case of Reauthenticate Dashboard User and Reauthenticate Application User, users are not forcefully logged off from the FortiSOAR™ UI, and they do not need to reauthenticate themselves.

Configuring User Accounts

Click Settings > Authentication to open the Account Configuration page. On the Account Configuration page, you can configure the following option for user accounts:

Enforce 2FA: Globally enforces 2FA across FortiSOAR™ users. Before you enforce 2FA across all FortiSOAR™ users, you must ensure that all users have enabled 2FA in their user profiles. For more information, see 2-Factor.

Currently, FortiSOAR™ supports only TeleSign for 2-Factor authentication. You require to have a TeleSign account to configure 2-Factor Authentication (2FA) to send the one-time password (OTP) code to the users' mobile devices and log onto FortiSOAR™.

To configure 2FA, do the following:

  1. On the Account Configuration page, click the Enforce 2FA checkbox.
    In Choose SMS Vendor, TeleSign will be displayed, since currently only TeleSign is supported for 2-Factor authentication in FortiSOAR™.
    2FA Configuration
  2. In the Customer ID field, enter the customer ID that has been provided to you for using TeleSign.
  3. In the Set API Key field, enter the API Key that has been provided to you for using TeleSign.

Configuring LDAP / AD

Use the Authentication menu to setup, modify, and turn on or off your LDAP / AD authentication provider. Click Settings > Authentication to open the Account Configuration page. Click the LDAP Configuration tab and click the LDAP Enabled checkbox, if you want to enable LDAP authentication for FortiSOAR™.

Enter the hostname and port of your LDAP / AD authentication server. Click Use TLS/SSL and then provide a user search the directory and import users. You can add users either by mapping users using the User Attribute Map, or search for users in the directory and then import users.

Authentication Administration Menu

User Attribute Map

To map users, configure the User Attribute Map. FortiSOAR™ provides you a default user attribute map array that contains the most common combination of field mappings. You can modify the mappings based on your own LDAP container fields by editing the map.

In the User Attribute Map, under Fields, click the editable field name (right-side field name), to map it to your LDAP fields. The non-editable field name (left-side field name) is the FortiSOAR™ attribute.

User Attribute Map

You must have valid administrative username and password to search the LDAP / AD resource for user information. You do not have to use admin credentials, but at a minimum, you must have user credentials to access and import all desired user containers.

User Search

Search User: Searches LDAP / AD for a user in the format CN=UserName,CN=Users,DC=XXXX,DC=XXX.

Base DN: Base DN for user search in the format CN=Users,DC=XXX,DC=XXX.

Search Attribute (s): Attribute for searching a user, for example, sAMAccountName.
Check the Recursive checkbox for recursively searching for users.

Search Criteria: Criteria for searching a user, for example, SOCMembers.

Once you have added the credentials in the User Search section, click Allow User Import to configure your environment to look in the LDAP / AD resource for all new users.

Tip

If you want to add local users, you must clear the Allow User Import checkbox to revert your system to the local user import in the Users administration menu.

Configuring SSO

Use the Authentication menu to setup, modify, and turn on or off your SSO configuration. Click Settings > Authentication to open the Account Configuration page. Click the SSO Configuration tab and click the SAML Enabled check box if you want to enable SAML for FortiSOAR™.

You must configure SAML in FortiSOAR™ to enable users to use single sign-on. See the SAML Configuration chapter for more information on how to setup SAML and user profiles for your organization.

Configuring the Password Vault Manager

FortiSOAR™ 6.0.0 introduces integration with external vaults such as "Thycotic Secret Server" and "CyberArk" that are used by organizations to securely store their sensitive data and credentials. Integration with external vaults also enables users to periodically change system credentials in their central vaults, and automatically having the configurations fetch those passwords using the vault.

Note

To configure the Password Vault, you must be assigned a role that has Read permissions on the Connector module, Read permissions on the Security module, and Update permission on the Application module. To install and configure the connector for using the vault, you must be assigned a role that has Create, Read, Update and Execute permissions on the Connector module and Read permission on the Application module.

FortiSOAR™ must have a connector created for a vault for you to be able to use an external vault in FortiSOAR™. In FortiSOAR™ 6.0.0, we have integrated with Thycotic Secret Server and CyberArk, and therefore we have a Thycotic Secret Server and CyberArk connectors in the Connector Store.

To use a vault in FortiSOAR™, you must first install the connector from the Connector Store. For more information on installing a connector, see the Introduction to connectors chapter in the "Connectors Guide."

Once you have installed the connector, you must configure the connector.

Note

To install and configure the connector for using the vault, you must be assigned a role that has Create, Read, Update (CRU) permissions on the Connector module and Read and Update permissions on the Security module, Read and Update permission on the Application module.

This section describes configuring the "Thycotic Secret Server" connector. You can configure "CyberArk", or any other vault connector that gets integrated with FortiSOAR™ in the future in the similar manner.

Important: You cannot configure a connector that is integrated with an external vault on the Connector Configuration dialog as is the case with other connectors. Once you installed the connector and if you have appropriate permissions, the following the Connector Configuration dialog is displayed in the case of Thycotic Secret Server:

Connector Configuration dialog in case of connectors that integrate with external vaults

You can open the Password Vault Manager by either clicking the Password Vault Manager link on the connector configuration dialog or by clicking Settings > Password Vault.

On the Password Vault page, click the Disabled button to enable integration with external vaults and configure the selected vault. From the Selected Vault Manager drop-down list select the vault that you want to use.

Password Vault Manager - Enabling the integration

In our example, select Thycotic Secret Server, configure the connector, and then click Save.

Password Vault - Configure the vault connector

Note: You can add multiple configurations for a vault; however, you must select a particular configuration for integration with FortiSOAR™. Similarly, you might have multiple vaults, but you can only have one vault integrate with FortiSOAR™.

Credentials (passwords, keys, tokens, etc) that you have stored in the vault are not visible to the users. However, once you have configured your vault, then users can use the credentials stored in the vault in connector configurations. For example, if you have a user who is creating a playbook that requires access to VirusTotal, a 3rd party integration, and you do not want to provide the VirusTotal API key to users, you can store the credentials in an external vault. Users can then select the vault credentials in the connector configuration steps by clicking the Password or Set API Key field, which then displays the Dynamic Values dialog from which you can select the required credentials,as shown in the following image:

Connector Configuration - Vault Option

For more information on Dynamic Values, see the Dynamic Values chapter in the "Playbooks Guide."

You can also continue to use the Set Password field in the connector configuration to securely store and manage sensitive data, such as keys, API Keys, tokens, or credentials.

If you have upgraded to FortiSOAR™ 6.0.0 and if you had used the Secrets Store (which has been deprecated since version 5.0.0) to securely store and manage sensitive data, then the credentials that you had stored within the Secrets Store will yet be available as Secret Variables in the Dynamic Values dialog. You can open the Secrets Store by clicking Settings > Password Vault and on the Password Vault Manager click the link (here) available in the Note, as shown in the following image:

Password Vault -  Link to Secrets Store

Clicking here opens the Secrets Store page. However, it is highly recommended to move your sensitive data to your external vault or use passwords to securely store and manage data since the Secrets Store will not be available from the next major release.

Configuring the Secrets Store (Deprecated)

You can use the Secrets store to securely store and manage sensitive data, such as keys or credentials. You can also use the "secrets" API to perform all the operations, such as adding, editing, and deleting secrets.

Warning "Important"
This feature has been deprecated in version 5.0.0 and will not be available in the next major release after version 6.0.0. Use the Password field in the connector configuration or use an external vault to securely store and manage sensitive data, such as keys, API Keys, tokens, or credentials.

To open the connector configuration, in the FortiSOAR™ left navigation, click Automation > Connector. Then select the connector whose data you want to store, which opens the connector configuration pane. In the connector configuration pane, click Set Password and type the secret that you want to save.

In FortiSOAR™ 6.0.0, open the Secrets Store page as explained in the earlier section:

Deprecated Secrets Store page

When you store data in the Secrets store, users cannot see that data. However, they can use this data when required. FortiSOAR™ stores the Secret store data in an encrypted format providing strong security for sensitive information.

Important

To add or update secrets, you must be assigned a role that has Read, Create, and Update permissions on the Secrets module, as well as, a minimum of Read permission on the Application module. To delete secrets, you must also be assigned the Delete permission on the Secrets module.

Example

If you have a user who is creating a playbook that requires access to JIRA, a 3rd party integration, and you do not want to provide the JIRA credentials (username-password pair) to users, you can add a secret to store the credentials. FortiSOAR™ stores the secret fields' variable reference in a jinja format. You can provide this jinja format to users, who can add them to the playbooks where the JIRA credentials are required. The process of adding this secret is mentioned in the following section.

Adding a secret

Note: The following procedure details the method of adding a secret in version 5.0.0 and later, though this is not recommended.

To add a new secret:

  1. Open the Secrets Store page.
    Secrets Store page
  2. Click Add (+) and in the New Secret page, in the Name field, add the name of the secret.
    Note: Secret names must be unique within the system. The Name field can have upper-or-lower case alphabets or numbers. However, it must not contain spaces or special characters, except _ and $.
    For example, adding JIRA credentials (username-password pair) to the secret store.
  3. In the Field Name field, add the field name that you want to store as a secret and reference at a later stage.
    Note: The restrictions that apply to the Name field also apply to the Field Name field.
    For our example, add JIRAUserName in this field.
  4. In the Field Value field, add the value of the field.
    For our example add the username used to access your JIRA instance.
  5. Click Save.
    To revert the changes that you have made, click Revert.
    To delete the secret field click Remove. To delete secrets, you must also be assigned the Delete permission on the Secrets module.
    For our example, you can add another secret for the JIRA password, i.e., add JIRAPassword in the Field Name field, and in the Field Value field add the password used to access your JIRA instance and click Save.
    Secrets Store page
    Note: To edit a secret, in case of the Field Name, you can just edit its value and click Save. To change the value that you have set in the Field Value field, click Set Secret Value and add the new value. You will not be able to see the older value that you had set in the Field Value field, however you can update its value.

Once you save your JIRAUsername and JIRAPassword secrets, you can provide the Jinja template of these secrets to users to add to their playbooks that require JIRA credentials, so that the credentials are fetched from the secret store and used for referencing purpose. The Jinja value of these fields are {{secret_store.JIRAUserName}} and {{secret_store.JIRAPassword}} respectively. Click the Copying a field's variable reference in jinja format icon that is present beside the Field Name field to copy a field's variable reference in jinja format:

Secrets - Copy Variable Reference icon

You can use the Dynamic Values in the Playbook Designer to add Secrets that are in the jinja format to your playbook. For more information, see the Dynamic Values section in the "Playbooks Guide."

Delete Users

Apart from the above functions that an administrator can perform on the FortiSOAR™ UI, administrators can also delete users in version 5.0.0 and later using a script.

Warning

It is highly recommended that you use this script to delete or cleanup users during the initial stages of setting up your FortiSOAR™ system. If you delete users who have been using FortiSOAR™ for a while, then the records for which the deleted user was the only owner, will also be lost forever.

To delete users, perform the following steps:

  1. Enter the UUID of the user(s) that you want to delete in the usersToDelete.txt file, which is located at /opt/cyops/configs/scripts/.
    The usersToDelete.txt file is an empty text file in which you can enter the users UUIDs.
  2. SSH to your FortiSOAR™ VM and login as a root user.
  3. Run the following command: # /opt/cyops/configs/scripts/userDelete
    Important: The User Delete script deletes users in the local database and does not work for externalized databases.