Fortinet black logo

Administration Guide

Security Management

Copy Link
Copy Doc ID d06a3c3b-1178-11ed-9eba-fa163e15d75b:202940
Download PDF

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.

Tooltip

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 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.

FortiSOAR implements RBAC for playbooks; for example, for uses to run playbooks, administrators require to assign roles that have the Execute permission on the Playbooks module to such users.

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 using the FortiSOAR UI, though you can make a user “Inactive” to stop that user from using the system. However, you can delete users using a script, for more information, see the Delete Users section.

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. FortiSOAR supports the FreeIPA LDAP authentication.

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.

Password Vault

Use the Password Vault menu to manage integrations with external vaults such as "Thycotic Secret Server" and "CyberArk" that are used by organizations to securely store their sensitive data and credentials. You can also 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 persona with their own permissions during Incidents.

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.

Honoring RBAC for related records

Teams govern record ownership within FortiSOAR. However, in the case of related records display the RBAC is ignored when viewing records in context of their parent records. For example, if users have access to an alert records that is linked to 5 indicator records, among which the user does not have access to one indicator record, still the user is able to view all 5 indicator records in the context of alert records in alert details page under the relation tab. Note that when users click the related records to which they do not have access, users will see an "Access Denied" message.
However, if you want to honor the RBAC for related records, i.e., display only those related records to which users have access when viewing records in context of their parent records, then do the following:

  1. Open and edit the /opt/cyops-api/config/parameters_prod.yaml file.
  2. Update the ignore_rbac_for_related_record parameter to change its value to 'false' (default is 'true'):
    ignore_rbac_for_related_record: false
  3. Run the following command to complete the change:
    systemctl restart php-fpm && sudo -u nginx php /opt/cyops-api/bin/console cache:clear && systemctl restart php-fpm

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 Team 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 Team:

  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 Team. 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 Team 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 Team and L2 Teams, but we now see that L1 is also a Parent.

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

  1. Effectively own only their own records
  2. Own none of SOC Team, L2, or L1 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.

By default, FortiSOAR has at least one team in place after installation, the SOC Team. We recommend that you do not modify the default teams and instead add new teams, as per your requirements.

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.

Tooltip

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 hard-coded in the system; therefore, Role editing is a sensitive permission and must be carefully governed by system users.

Note

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 Roles page 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 for a particular role.

Release 7.2.1 has enhanced the 'Set Role Permissions' grid on the Roles page to make permission assignment efficient, intuitive, and logical:

  • Automatic logical selection of permissions:
    • Selecting the 'Create' permission for a module leads to the automatic selection of the 'Read' permission for that module.
    • Selecting the 'Update' permission for a module leads to the automatic selection of the 'Read' and 'Create' permissions for that module.
  • Locks the column headers of the 'Set Role Permissions' grid to ensure that is always displayed, which improves the usability of the grid.

You can also explicitly assign permissions for each field within a module by clicking the Set Field Permissions link for that module, changing the permissions for the particular field and then clicking Save:
Roles Page - Set Field Permissions dialog

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-tenant 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 its installation, the Security Administrator. Apart from the Security Administrator role, FortiSOAR generally also has the following default roles defined, after the installation of the SOAR Framework Solution Pack (SP):

  • SOC Manager - manages the investigation of incidents and other containment and remediation tasks.
  • Security Administrator - administers Teams and Roles and is responsible for creating the appropriate team structure and 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.
  • SOC Analyst - triages alerts, filters false positives, investigates incidents, and performs other remediation and containment tasks.

Apart from the default roles, you can also create roles as per your requirements such as a FortiSOAR Agent that contains agent permissions, i.e., agent appliances are auto-assigned to this role. You can add this role directly to users so that they get access to agents. Agent appliances are auto-assigned to this role, and by default have access (CRU permissions) to Files and Attachments.

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

Caution

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

SOC Manager

The SOC Manager role is given complete access to the Alerts and Incident modules and modules associated with the investigation of incidents, such as Approvals, Assets, Communications, Indicators, Tasks, War Rooms, etc, and also Notification Rules, Schedules, Reporting, etc. These users are responsible for investigating incidents and performing remediation and containment activities.

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-tenant 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.

Caution

"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 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, they 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.

Tooltip

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.

SOC Analyst

The SOC Analyst role is given access to the Alerts and Incident modules, and modules associated with alerts, such as Comments, Attachments, Indicators, Tasks, War Rooms, etc, and also Schedules, Reporting, etc. These users are responsible for alert triaging, false-positive filtering, investigating incidents and performing other remediation and containment tasks, and escalating potentially malicious alerts to incidents for review by the SOC team.

Modules in the Roles Page

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.

Note

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.

Note

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.
  • Password Vault - the ability to integrate with external vaults such as "Thycotic Secret Server" and "CyberArk" to securely store their sensitive data and credentials.
  • 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 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).

Tooltip

Users who are assigned roles having permissions to the 'People' module, but who do not have access to the 'User Id' field, i.e., the User Id field is set as 'No Access' in the People Field Permissions dialog, are unable to see 'Locked', 'User Id', and 'Login Status' fields for users listed on the Users page in FortiSOAR. For information on setting field permissions for modules, see the Configuring Roles section

Configuring User and Appliance Profiles

Adding Users

To add a new user, click Settings > Users to open the Users page. The Users page displays details such as name, title, lock status, ID, etc for all the created users in your FortiSOAR system.

Users Page - Login Status

From version 7.0.1 onwards, you can select any active user as a "Super Admin." A Super Admin user has a privilege of being able to log into FortiSOAR even when the system is in violation of the allowed user seats, i.e., the number of named users exceeds the number of seats you have bought for FortiSOAR. By default, this user is set as 'CS Admin'. Prior to version 7.0.1, the csadmin user could log into FortiSOAR, even when there was a license validation failure. However, there could be customer environments where the csadmin user is kept inactive or has been deleted, and therefore ability to choose any active user as a Super Admin is introduced in version 7.0.1. On the Users page, in the Designate Super Admin section, from the Select User drop-down list, which displays only active users, select the user that you want to designate as the Super Admin and click Set As Super Admin.

Note

The user who is chosen as the Super Admin user must have Read and Update permissions on the Security and People modules, so that in case of a license violation the Super Admin is able to update the access type of the users. Also, the Super Admin user cannot be marked as 'Inactive' or deleted.

From version 7.0.1 onwards, the Users page also displays the access type, i.e., named or concurrent, and login status of all the users. For more information on 'Concurrent Users', see the Licensing FortiSOAR chapter in the "Deployment Guide." You can selectively update users' access type, i.e., Concurrent users to Named users, and vice-versa, at any time. You can also bulk update the access type of users from Named to Concurrent by selecting the users in the Grid on the Users page whose access type you want to change from named to concurrent, then click the Switch to Concurrent button, and then click Confirm on the Confirmation dialog.

Bulk change user access from Named to Concurrent

You might need to bulk update the user access from Named to Concurrent, when you have upgraded FortiSOAR, or when you have used the FortiSOAR's wizard-based export and import of user configuration information between environments, where all the users present in FortiSOAR have their access type set as Named. For more information on Export and Import Wizards, see the Application Editor chapter.

You can forcefully log out selective 'Concurrent' users from the system, by clicking the Logout icon in the row of a particular user. For example, if you want to log out Test User2, then click Logout in the Test User2 row. FortiSOAR will display a Confirmation dialog, click Confirm to display a Force Logout User dialog, in which you can add a custom message that will be displayed to the user when the user is being forcefully logged out, and then click Logout User:

Force logout user dialog

Note

A Named user can never be forcefully logged out of any system.

To add a new user, click Add and enter the user details on the New User page and click Save to save the new user profile.

Note

The Username field is mandatory and case sensitive and it cannot be changed once it is set. It is also recommended that all new users should change their password when they first log on to FortiSOAR, irrespective of the complexity of the password assigned to the users.

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.

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, phone numbers, and access type, i.e., Named or Concurrent. 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

You can upload the user's profile picture by clicking Change Image, which opens the Upload a Profile Picture dialog, where you can drag-and-drop the profile image file, or click the Import icon and browse to the image file to import the profile image file to FortiSOAR, and then click Save Profile Image to add the profile image. Once the profile image is added, the same can be removed at anytime by clicking the Remove Image button that appears on the profile image.
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 get temporally locked out of FortiSOAR when they have exceeded the number of authentications tries allowed within a one-hour period. By default, users' can enter incorrect credentials, username and/or password 5 times, while logging into FortiSOAR, before their account gets locked for 30 minutes. From version 7.0.0 onwards, administrators cannot lock a user using the FortiSOAR UI; however, administrators can unlock a locked user using the UI by clicking the Unlock checkbox on that user's profile page and then clicking Save, or locked users can wait for 30 minutes before their account gets unlocked. Security Administrators can also change the default values for the different parameters, such as number of attempts before the user account is locked, etc. For information about these parameters. see the Debugging, Troubleshooting, and Optimizing FortiSOAR chapter.

From version 7.0.1 onwards, you can also forcefully log out selective users from the system, by clicking the Logout icon on the user's profile page:

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.

Tooltip

If you face issues with user preferences such as applying filters on the grid or column formatting within a grid, 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.

In release 7.2.1, FortiSOAR provides administrators — users with a minimum of 'Security' Read permissions — with the ability to view the aggregated list of effective permissions based on different roles assigned to a given user. To view the consolidated permissions list for a specific user, click Settings > Users. On the Users page in the Manage Users section, click the row of the user whose consolidated permissions you want to view. On the user's profile page, in the Roles section, click View Effective Role Permissions:
User Profile - View consolidated permissions

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 chapter for further details.

From release 7.2.0 onwards, a new user type named 'RADIUS' is introduced. In the Authentication Type drop-down list, you can create either a 'Native' user or a 'RADIUS' user. Users with their authentication type set to RADIUS can log in to FortiSOAR using their RADIUS credentials:

Uses whose type is set to 'RADIUS'

Administrators must setup RADIUS configuration before users can perform authentication. The steps for setting up RADIUS are present in the Configuring FortiSOAR authentication with a RADIUS server topic. Also, note that the username of the RADIUS user that you create in FortiSOAR must be the same as the username specified on the RADIUS server since FortiSOAR performs a lookup for the user before making the RADIUS authentication request. You can also import RADIUS users in bulk into your FortiSOAR system, details for which are present in the Importing RADIUS users in bulk topic.
While logging on to FortiSOAR, the user credentials are first authenticated against primary radius server, and if the authentication against primary server succeeds, the user gets logged in to FortiSOAR. If the connection to the primary radius server fails, then the credentials are authenticated against secondary server, and if this authentication succeeds, the user gets logged in to FortiSOAR; else the log in attempt fails with the appropriate error message.

You can configure the users' access type, i.e., whether the user is a Named user or a Concurrent user. A 'Named' user has a FortiSOAR seat permanently reserved, i.e., such a user can always log onto FortiSOAR except in case of a license violation. However, a 'Concurrent' user can log in only when there is a concurrent seat available. You can also selectively change users' access type, i.e., Concurrent users to Named users, and vice-versa, at any time, or you can bulk change users access type from Named to Concurrent. For more information, see the Adding Users section.

Editing user access type

You can also configure whether the user is an Application User or Dashboard User. You can set different re-authentication 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. Security Administrators can 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

You can determine how you want to send notifications. To send system notifications using emails, select the Enable System notification on email checkbox. To send emails when a user is tagged, using @, in comments, select the Enable email notifications for @ mentions in comments checkbox.

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. Audit logs 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.

In release 7.2.1, FortiSOAR provides administrators — users with a minimum of 'Security' Read permissions — with the ability to view the aggregated list of effective permissions based on different roles assigned to a given appliance. To view the consolidated permissions list for a specific appliance, click Settings > Appliances. On the Appliances page, click the row of the appliance whose consolidated permissions you want to view. On the Edit Appliance page, in the Roles section, click View Effective Role Permissions:
Appliance - View consolidated permissions

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.

Caution

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.

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 Team 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 Team. 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 Team 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 Team 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.

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, configuring SAML to enable users to use sign-on (SSO), and configuring authentication with RADIUS server.

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, and recommended value is 30 minutes.
Note: The token refresh time must always be set to less than 120 minutes. This is needed as the maximum token alive time is 120 minutes, before which the token must be refreshed.
Reauthenticate Dashboard User The number of hours after which a dashboard user is forced to be re-authenticated. The default value is 24 hours.
Reauthenticate Application User The number of hours after which an application user is forced to be re-authenticated. 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.

Enabling custom password policies for users configured with Basic Authentication

When a new password is set up it must contain the following:

  • At least 8 characters
  • one lower-case alphabet
  • one upper-case alphabet
  • one digit
  • Any one of the following special characters ~ ! @ # $ % ^ & * | ? _

Apart from the above default rules, you can also set up custom password policies, which enforces the following additional restrictions on the passwords that users can create:

  • Password must not be one of 10 previous passwords.
  • Password must not contain the username of the user.

  • Password must not have been changed in the last 1 day.

By default, the custom password policy is disabled. If you want to enable the custom password policy, you need to do the following on your FortiSOAR instance:

  1. Edit the das.ini file as a root user using an SSH session:
    vi /opt/cyops-auth/utilities/das.ini
  2. Add the[PASSWORD] section at the end of the das.ini file as follows:
    [PASSWORD]
    validator = custom

    This enables the custom password policy for your FortiSOAR instance.
  3. If you want to change any of the parameters for the default or custom password policy, you require to edit the custompwdvalidator.py file located at /opt/cyops-auth/validationutils/custompwdvalidator.py
    For example, if you want to change the default length of the password that users can set from 8 characters to 10 characters, in the custompwdvalidator.py file update the following:
    if len(password) < 8:
    message = "Password must be at least 8 character long"
    logger.error(message)
    return False, message

    To
    if len(password) < 10:
    message = "Password must be at least 10 character long"
    logger.error(message)
    return False, message

    Similarly, you can also update a custom policy. For example, if you do not want to enforce the "Password must not contain the username of the user" policy, you can comment out or remove the following code from the custompwdvalidator.py file:
    if loginid.lower() in password.lower():
    message = "username not allowed in password"
    logger.error(message)
    return False, message

    Important: If you make any changes to the validate() function in the customepwdvalidator.py file, ensure you make the corresponding update in the password_policy() function in the same file.
    Optionally, if you want to update the "Password must not be one of 10 previous passwords" custom policy to "Password must not be one of 12 previous passwords", you can run the following command:
    /opt/cyops/scripts/api_caller.py --method PUT --endpoint https://localhost/api/auth/config --payload '{"option":"history","value": 12}'
    The value of the value parameter in the --payload determines the number of passwords that users cannot use, for example in the above command it is set to '12'.
    Or, if you want to update the "Password change not allowed within 1 day of last password change" custom policy to "Password change not allowed within 2 days of last password change", you can run the following command:
    /opt/cyops/scripts/api_caller.py --method PUT --endpoint https://localhost/api/auth/config --payload '{"option":"min_password_age","value": 2}'
    The value of the min_password_age parameter in the --payload determines how often users can change their passwords, for example in the above command it is set to '2', i.e., users cannot change their password within a two-day time frame.
  4. If you make any changes in the custompwdvalidator.py file, then you must restart the cyops-auth service:
    systemctl restart cyops-auth

Configuring account lockout configurations

Click Settings > Authentication to open the Account Configuration page. In the Failed Authentication Settings section, you can configure the following options for account lockouts:
Settings for managing account lockouts

  • Maximum Failed Login Attempts: Specify the number of times that users can enter an incorrect password while logging into FortiSOAR before their account gets locked. By default, this is set to 5 (times).
  • Account Unlock Time: Specify the duration, in minutes, after which the user accounts get automatically unlocked, in cases where user accounts were locked due to exceeding the number of failed login attempts. By default, this is set to 30 (minutes).

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

User Search

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.

Tooltip

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.

Introduction to SAML

Security Assertion Markup Language (SAML) is an XML-based, open standard data format for exchanging authentication and authorization data between parties, particularly between an identity provider and a service provider. The single most important requirement that SAML addresses are web browser single sign-on (SSO).

By using SAML, FortiSOAR does not require to store user credentials, and FortiSOAR is independent of the underlying authentication mechanism used by a user. Once you complete making all the SAML configurations on both the FortiSOAR and Identity Provider (IdP) side, then the FortiSOAR login page will display a Login with SSO button. Users can then log on to FortiSOAR using the Login with SSO button that is present on the FortiSOAR login page.

FortiSOAR™ login page with Single Sign-On

Once the user clicks the Login with SSO button, the user is redirected to a third-party identity provider login page, where the user must enter their credentials and get themselves authenticated. Once a user successfully logs on to FortiSOAR, the user profile automatically gets created. The User profile is created based on the configurations you have set while Configuring SAML in FortiSOAR. For example, when the user is created, the user is assigned the default team and role based on what the administrator configured during SAML configuration. Users can update their profile by editing their user profile.

You can map the role and team of SSO users in FortiSOAR based on their roles defined in the IdP. Thereby you can set different roles for different SSO users, i.e., you can set the role of an SSO user in FortiSOAR based on the role you have defined in your IdP. For more information, see Support for mapping roles and teams of SSO users in FortiSOAR.

Note

The default access type set for all SSO users is 'Concurrent'. Administrators can change the access type for the user later, if needed. For more information about user access types, see the Licensing FortiSOAR chapter in the "Deployment Guide."

Benefits of SAML

User experience: SAML provides the ability for users to securely access multiple applications with a single set of credentials entered once. This is the foundation of the federation and single sign-on (SSO). Using SAML, users can seamlessly access multiple applications, allowing them to conduct business faster and more efficiently.

Security: SAML is used to provide a single point of authentication at a secure identity provider, meaning that user credentials never leave the firewall boundary, and then SAML is used to assert the identity to others. This means that applications do not need to store or synchronize identities, which in turn ensures that there are fewer places for identities to be breached or stolen.

Standardization: The SAML standardized format is designed to interoperate with any system independent of implementation. This enables a more open approach to architecture and identity federation without the interoperability issues associated with vendor-specific approaches.

SAML Principles
Roles

SAML defines three roles: Principal (generally a user), Identity Provider (IdP), and the Service Provider (SP).

Principal: The principal is generally a user that has an authentic security context with IdP and who requests a service from the SP.

Identity Provider (IdP): IdP is usually a third-party entity outsourced to manage user identities, or in other terms, an IdP is a user management system. The IdP provides user details in the form of assertions. Before delivering the identity assertion to the SP, the IdP might request some information from the principal, such as a username and password, to authenticate the principal. SAML specifies the assertions between the three parties: in particular, the messages that assert identity that is passed from the IdP to the SP. In SAML, one identity provider can provide SAML assertions to many service providers. Similarly, one SP might rely on and trust assertions from many independent IdPs.

Service Provider (SP): The SP maintains a security wrapper over the services. When a user request for a service, the request first goes to the SP, who then identifies whether a security context for the given user exists. If not, the SP requests and obtains an identity assertion from the IdP. Based on this assertion, the service provider makes the access control decision and decides whether to perform some service for the connected principal.

Attribute Mapping

Each IdP has its own way of naming attributes for a user profile. Therefore, to fetch the attribute details for a user from an IdP into the SP, the attributes from the IdP must be mapped to attributes at the SP. This mapping is taken care in a separate part at the SP. If the attribute mapping is not set correctly, the SP sets default values for mandatory attributes like First Name, Last Name, and Email.

Prerequisites to configuring SAML

  • Ensure that you are assigned a security administrator role that at a minimum has Read, Create and Update permissions on the Security module. You also require to have Read permissions for Teams and Roles.
  • Ensure that you have enabled SAML in your FortiSOAR instance. To enable SAML, log on to FortiSOAR, click Settings. In the Security Management section click Authentication to open the Authentication Configuration page. Click the SSO Configuration tab and click the SAML Enabled checkbox.

Configuring SAML in FortiSOAR

Configuring SAML is a two-way process. The SP configuration that is present in the FortiSOAR UI must be made at the IdP. Similarly, the IdP configuration must be added to the FortiSOAR UI.

This section covers configuring SAML with IdPs such as, FortiAuthenticator (FAC) OneLogin, Auth0, Okta, Google, and Active Directory Federation Services. (ADFS), which are the IdPs that have been tested with FortiSOAR. You can use a similar process to configure any other IdP that you use.

  1. Log on to FortiSOAR as an administrator.
  2. Click Settings > Authentication > SSO Configuration.
  3. To enable SAML for FortiSOAR, click the SAML Enabled check box.
  4. In the Identity Provider Configuration section, enter the IdP details.
    Get the details for FortiAuthenticator (FAC) from the Configuring SAML in FortiAuthenticator section.
    Get the details for OneLogin from the Configuring SAML in OneLogin section.
    Get the details for Auth0 from the Configuring SAML in Auth0 section.
    Get the details for Okta from the Configuring SAML in Okta section.
    Get the details for Google from the Configuring SAML in Google section. You must have an administrator account for your G Suite account.
    Get the details for Azure Active Directory (Azure AD) from the Configuring SAML in Azure Active Directory section.
    For information on Configuring SAML in FortiSOAR for Active Directory Federation Services (ADFS) from the Configuring SAML in ADFS section. For specific information about the values, you need to add for the SSO configuration, see Configuring FortiSOAR for ADFS.
  5. From the Provision User drop-down list, select the user creation strategy, i.e., choose either At Sign-in (Default) or Pre-provision. For more information see the Pre-provisioning SAML users section.
  6. Map the user attributes received from the IdP with the corresponding attributes of FortiSOAR.
    Use the User Attribute Map to map the attributes received from the IdP with the corresponding attributes required by FortiSOAR. FortiSOAR requires the firstname, lastname and email attributes to be mapped.
    In the User Attribute Map, under Fields, in the Tree view, click the editable field name (right side field name), to map it to the attribute that will be received from the IdP. The non-editable field name (left-side field name) is the FortiSOAR attribute. For example, in the following image, you map the FortiSOAR attribute firstName to the IdP attribute First Name.
    User Attribute Map - Tree View
    If you want to sync the user attributes and/or SAML roles between FortiSOAR users and their IdP profile, toggle IdP User Attribute Sync to ON and then select one of the following options:
    • Sync All Attributes Except SAML Roles: Selecting this option synchronizes all user attributes except SAML Roles between FortiSOAR users and their IdP profile.
    • Sync SAML Roles Only: Selecting this option synchronizes only the SAML Roles between FortiSOAR users and their IdP profile.
    • Sync All Attributes: Selecting this option synchronizes all user attributes and SAML Roles between FortiSOAR users and their IdP profile.
    You can also change the mapping in the using the Code View:
    User Attribute Map - Code View
  7. To map roles that you have defined in your IdP (see Support for mapping roles and teams of SSO users in FortiSOAR) to teams and roles in FortiSOAR, do the following:
    1. If you want to ensure that roles defined as part of SAML role mapping will be applied to SSO users in FortiSOAR, then select the Enforce SAML Role Mappings checkbox.
      Teams and Role Mapping section to map IdP roles
    2. To map a role in the IdP to a FortiSOAR-role and optionally a team in FortiSOAR, in the Team and Role Mapping section, click Add Role Mapping.
    3. In the Add New Role Mapping dialog, do the following:
      1. In the SAML Role field, add the name of the roles that you have defined in your IdP.
        Note: The name that you have specified in your IdP, and the name that you enter in this field must match exactly, including the matching the case of the name specified.
      2. From the Roles column, select the FortiSOAR role(s) that you want to assign to the role that you have specified in the SAML Role field.
      3. (Optional) From the Teams column, select the FortiSOAR teams(s) that you want to assign to the role that you have specified in the SAML Role field.
        Add New Role Mapping Dialog
        Once you assign the default team and roles to users, all user profiles created contain this team and role assigned to them.
        If you do not assign the default team and roles to users, and you have also not defined a Default (Fall Back Role), details given in a further step in this procedure, then all user profiles are created without team or role information and will have only basic access. In this case, users will require to request the administrator for appropriate access and privileges.
      4. Click Add Role Mapping.
        This adds the mapped role in the SAML Roles drop-down list in the Team and Role Mapping section as shown in the following image:
        Mapped SAML role
        As shown in the above image, the oneLoginSAMLRole, i.e., the role defined in the IdP has been mapped to the Application Administrator role and the SOC Team in FortiSOAR.
    4. To define a default role (and optionally teams) that will be assigned to the SSO user if you have not set up mapped roles of SSO users in FortiSOAR, or if FortiSOAR receives a response from the IdP that does not contain any roles, or receives a response that does not map to any of the FortiSOAR roles, do the following:
      1. From the SAML Roles drop-down list, select Default (Fall Back Role) and click Edit.
      2. In the Update Role Mapping dialog, from the Roles column select the role(s) that you want to assign to the default role. You can also optionally select the team(s) that you want to assign to the default role from the Teams column and click Update Mapping.
    5. (Optional) To delete or update an existing role do the following:
      1. To update an existing role, select the role from the SAML Roles drop-down list and click Edit and in the Update Role Mapping dialog, you can update the name of the mapped SAML role, and the mapped FortiSOAR roles and teams.
        Once you have completed modifying the existing role as per your requirement, click Update Mapping.
      2. To delete an existing role, select the role from the SAML Roles drop-down list and click Delete.
        FortiSOAR displays a confirmation dialog, click Confirm to delete the role.
  8. Add the information provided in the Service Provider section to Configuration section your IdP.
    This information is pre-configured. However, you can edit the fields, such as Entity ID (hostname) within this section. This is especially useful if you are using an alias to access FortiSOAR. You can also edit the certificate information and the private and public keys of your service provider, which is useful in cases where you want to use your own certificates.
    Service Provider configuration
    For OneLogin, enter this information in the Configure IdP step. See the Configuring SAML in OneLogin section for more details.
    For Auth0, enter this information in the Configure IdP step. See the Configuring SAML in Auth0 section for more details.
    For Okta, enter this information in the Configure IdP step. See the Configuring SAML in Okta section for more details.
  9. (Optional) Configure advanced settings for SAML.
    Prior to version 7.0.0, users were required to click the Use Single Sign On (SSO) link to get redirected to the SSO login page or login using SSO active session. However, there are some organizations that have policies, which require direct redirection to the SSO login page, if SSO is configured. Therefore, in version 7.0.0 an Auto Redirect checkbox is introduced. Select the Auto Redirect checkbox to redirect users directly to the SSO login page or automatically log the user into FortiSOAR in case the SSO session is active. If you leave the Auto Redirect checkbox cleared, then FortiSOAR directs users to the FortiSOAR login page, where users can click the Use Single Sign On (SSO) link to get redirected to the SSO login page or login using SSO active session.
    If you have selected the Auto Redirect checkbox, i.e., enabled SSO auto-redirect, administrator can yet access the FortiSOAR login page to configure or troubleshoot issues with the portal, by adding auto_redirect=false to the URL. For example, https://<hostname>/login/?auto_redirect=false
    Select the Auth Request Signed checkbox if your IdP requires FortiSOAR to send signed authentication requests.
    Select the Logout Request Signed checkbox if your IdP requires FortiSOAR to send signed logout requests.
    Select the Messages Signed checkbox if you want messages coming from your IdP to be signed.
    Select the Assertion Encrypted checkbox if you want assertions within the SAMLResponse to be encrypted.
    SAML Advanced Properties
  10. Click Save to complete the SAML configuration in FortiSOAR.
Note

Changing the hostname using the csadm command does not change hostname part in 'Service Provider' details in SAML configurations. Therefore, if you have changed the hostname, you must manually update the hostname in 'Service Provider' details in the SAML Configuration page.

Pre-provisioning SAML users

From version 7.0.2 onwards, you can choose the strategy to create SSO users between At Sign-in (Default) or Pre-provision. The At Sign-in (Default) strategy creates users at login, i.e., user accounts are created automatically on the first SSO login of the user login. The Pre-provision strategy requires the user account to be created prior to login. Pre-provisioning users enables you to limit the SSO authentication only for pre-created users, which enables you to:

  • Pre-decide roles mapping for SSO users. Now you can create users and then you can manually intervene to map the user to the correct role.
  • Minimize the issues administrators can face due to incorrect or partial configuration mapping at the IdP's end.
  • Control creation of users by mistake.

The process of pre-provisoning users is as follows:

  1. Ensure that you have selected the Pre-provision option from the Provision User drop-down list on the SSO Configuration page (Settings > Authentication > SSO Configuration).
  2. To pre-provision users you need to provide user details in a CSV file as follows:
    1. From the left menu, click Users, and on the Users page, click the Import Users button.
      Note: The Import Users button will be visible only if SSO or RADIUS is enabled.
    2. In the Import Users dialog, do the following:
      1. From the User Type To Import drop-down list, select SSO User.
      2. Click the Download CSV File Sample link to download the sample CSV file (SSO User_Template.csv).
        Import Users dialog
        The sample CSV file contains an example of the user details you need to provide. You need to provide the following user details in the CSV file:
        • username: Name of the SSO user.
        • email: Email address of the SSO user
        • firstname: (Optional) First name of the SSO user.
        • lastname: (Optional) Last name of the SSO user.
        • phonemobile: (Optional) Mobile number of the SSO user.
        • roles: (Optional) Role (s) that you want to assign to the SSO user. To assign a role to the user you need to provide the UUID of that role. To get the UUID of a role, click Settings > Security Management > Roles, and then click the role that you want to assign to the user. For example, click T1 Analyst, which opens the Edit Role page, and then from the address bar, copy the UUID (as shown in the following image) and paste it in the roles column in the CSV file.

          Note: You can assign multiple roles to the user by using the pipe symbol (|) to separate the UUID of each role.
        • teams: (Optional) Team (s) that you want to assign to the SSO user. To assign a team to the user you need to provide the UUID of that team. To get the UUID of a team, click Settings > Security Management > Teams, and then click the team that you want to assign to the user, and then from the address bar copy the UUID of the team, similar to the process described for roles.
          Note: You can assign multiple teams to the user by using the pipe symbol (|) to separate the UUID of each team.
        • accessType: Access type (Named or Concurrent) that you want to assign to the SSO user. If you do not specify any access type for the user, then the user will be assigned as a 'Concurrent' user.
    3. Once you complete filling the user details in the CSV file, click the Import User button, and in the Import Users dialog, drag and drop the csv file or click the import icon to import the CSV file, and then click the Import Users button.
      If there are no issues in the import, then all the SSO users get created and they can log into FortiSOAR.
      If there are any issues in the CSV files, such as not providing all the information required to create SSO users, then such users are not created. To get information about the users not created, download the status report.
      Importing SSO Users - Download Status Report
Configuring SAML in FortiAuthenticator
  1. Log on to FortiAuthenticator (FAC) as an administrator.
  2. Configure IdP. To configure general SAML IdP portal settings, navigate to Authentication > SAML IdP > General, and then select Enable SAML Identity Provider portal.
    FAC - Enable SAML Identity Provider portal
  3. In the Edit SAML Identity Provider Settings section, enter the following details:
    • Device FQDN: To configure this setting, you must enter a Device FQDN in the System Information widget in the Dashboard.
    • Server address: Enter the IP address, or FQDN, of the FAC device.
    • Username input format: Select one of the following three username input formats:
      • username@realm
      • realm\username
      • realm/username
    • Realms: Select Add a realm to add the default local realm with which the users will be associated.
      Use Groups and Filters to add specific user groups.
    • Login session timeout: Set the user's login session timeout limit between 5 - 1440 minutes (one day). The default is 480 minutes (eight hours).
    • IDP certificate: Select a certificate from the dropdown menu.
  4. Configure a Service Provider. Navigate to Authentication > SAML IdP > Service Providers, and then click Create New.
    FAC - Create New SAML Service Provider section
    In the Create New SAML Service Provider section, enter the following information:
    • SP name: Enter the name of the Service Provider (SP).
    • IDP prefix: Enter a prefix for the IDP that will be appended to the end of the IDP URLs.
      Alternatively, you can select Generate unique prefix to generate a random 16 digit alphanumeric string.
    • IDP address: To configure the IDP address (and IDP settings below), you must have already configured the server's address in Authentication > SAML IdP > General.
    • SP entity id: Enter the entity ID of the SP. Retrieve the SP entity id, SP ACS URL, and SP SLS URL from FortiSOAR by navigating to Settings > Authentication > SSO Configuration. Then click the Service Provider Configuration section to get these details.
      Alternatively, you can download the metadata of the SP from FortiSOAR and import the same here.
    • SP ACS (login) URL: Enter the Assertion Consumer Service (ACS) login URL of the SP.
    • SP SLS (logout) URL: Enter the Single Logout Service (SLS) logout URL of the SP.
    • SAML Attributes: Map the User attributes to SAML attributes. This is needed so that users created in FortiSOAR have the correct details.
      SAML attributes must be configured as shown in the following image:
      FAC - Map SAML Attributes
      Important: You must not change the SAML Attribute names as these are the attribute names expected by FortiSOAR. You can change the User Attribute names as per your requirement.
      The remaining fields can be left unmodified, or can be modified as per your requirement.
      You must download the IdP metadata.
  5. In FortiSOAR, navigate to Settings > Authentication > SSO Configuration, and then enter the following details in the Identity Provider Configuration section:
    FAC IDP details
    • Entity ID: Enter the IDP entity id from the Create New SAML Service Provider section mentioned in step 4.
    • Single Sign On URL: Enter the IDP single sign-on URL from the Create New SAML Service Provider section mentioned in step 4.
    • Single Logout Request URL: Enter the IDP single logout URL from the Create New SAML Service Provider section mentioned in step 4.
    • X509 Certificate: Retrieve the signing certificate from IDP metadata that you have downloaded in step 4 and enter it in this field. The signing certificate is located under the <md:KeyDescriptor use="signing"> key in the metadata xml file.
    • Advanced Properties: In the Security configuration section, ensure that the Auth Request Signed checkbox is enabled:
      FAC Advanced Properties
    • For Team and Role Mapping, the Role name can be given as the 'User Group' name from FortiAuthenticator that is present in Authentication > User Management > User Groups. You can utilize an existing Group or create a new one as per your requirement. The login user should be from the same group as mentioned in 'Team and Role' mapping.
  6. Click Save in FortiSOAR to save the changes to the IdP configuration.
Configuring SAML in OneLogin
  1. Log on to OneLogin as an administrator.
  2. Create a new application in OneLogin. Navigate to APPS > Company Apps > ADD APP. In the Find Applications section, search for saml and select SAML Test Connector (IDP w/attr w/sign response). Save the application.
    SAML Test Connector (IDP w/attr w/sign response application)
  3. Configure IdP. On the SAML Test Connector (IDP w/attr w/sign response), click the Configuration tab and enter your SP details as shown in the following image:
    SAML Test Connector - Configuration tab
  4. Get SSO details. On the SAML Test Connector (IDP w/attr w/sign response), click the SSO tab and you will see the SSO details of OneLogin (IdP) as shown in the following image:
    SAML Test Connector - SSO tab
  5. Add the SSO details shown in step 4 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, enter the IdP details as shown in the following image:
    Configure IdP in FortiSOAR™
  6. Add the default user attribute mapping for OneLogin in FortiSOAR by updating the User Attribute Map as shown in the following image:
    Default user attribute mapping for OneLogin in FortiSOAR
    Note: You can change the default user attribute mapping if required.
  7. Click Save in FortiSOAR to save the changes to the IdP configuration and user attribute mapping.
  8. Create a new user in OneLogin. Log on to OneLogin as an administrator and navigate to the USERS main menu and create a new user by clicking on NEW USER and entering relevant details. Once the user is created, open the user details, click the Applications tab and select the application created in step 2.
    Note: While attaching the application to the user, the ‘SAVE’ button might be disabled. To enable the Save button, click any field and then press space or any key and then clear the space or character using backspace.
    OneLogin - Create New User
    Once the user is created, you must assign the user a password by clicking MORE ACTIONS.
Configuring SAML in Auth0
  1. Log on to Auth0 as an administrator.
  2. Create a new application in Auth0. In the Clients section, create a new client by selecting Regular Web Applications.
  3. Configure IdP (Auth0). In Auth0, go to the Addon tab of the application you have created in step 1 and select SAML2 WEB APP. On the Settings page that appears, in the Application Callback URL field enter the ACS URL from your SP configuration. In the Settings field, uncomment the logout portion and set the callback field to the value that is present in the Logout POST URL field that is present in the Service Provider section on the FortiSOAR SSO Configuration page, as shown in the following image:
    Auth0 Application - Addon Settings tab
  4. Get SSO details. Download Identity Provider Metadata, by navigating to App configuration > Addons > SAML2 > Usage > Identity Provider Metadata. Click Download. The Identity Provider Metadata appears as shown in the following image:
    Identity Provider Metadata
  5. Add the SSO details shown in step 4 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, use the Identity Provider Metadata to fill in the Entity ID, Single Sign On URL, X509 Certificate, and Single Logout Request URL details.
    Based on Identity Provider Metadata screenshot in step 4, you would fill in the SSO details in FortiSOAR as follows:
    • In the Entity ID field enter the following value that you get from the Identity Provider Metadata:
      Entity ID field from the Identity Provider Metadata
    • In the Single Sign On URL field enter the following value that you get from the Identity Provider Metadata:
      Single Sign On URL field from the Identity Provider Metadata
    • In the Single Logout Request URL field enter the following value that you get from the Identity Provider Metadata:
      Single Logout Request URL field from the Identity Provider Metadata
    • In the X509 Certificate field enter the following value that you get from the Identity Provider Metadata:
      X509 Certificate field from the Identity Provider Metadata
    • Click Save in FortiSOAR to save the changes to the IdP configuration and user attribute mapping.
Configuring SAML in Okta
  1. Log on to Okta as an administrator.
    If you don’t have an Okta organization, you can create a free Okta Developer Edition organization.
  2. Create a new application in Okta and configure IdP in the application.
    • In Okta, click the blue Admin button.
    • On the Applications tab, click Add Applications > Create New App.
    • On the Create a New Application Integration dialog, select SAML 2.0 and click Create.
      Creating a New Application in Okta
  3. Configure IdP.
    • In the newly created application, on the General Settings dialog, in the App name field, enter the application name and click Next.
      General Settings dialog - Adding an application name
    • On the Configure SAML dialog, in the SAML Settings section, in the Single Sign On URL field, enter or paste the SP ACS URL and in the Audience URI field, enter or paste the SP Entity ID.
      SAML Settings dialog
    • Click Show Advanced Settings.
    • Select the Enable Single Logout checkbox.
      In the Single Logout URL field, enter or paste the SP Logout POST URL.
      In the SP Issuer field, enter or paste the SP Entity ID.
      In the Signature Certificate field, browse to where you have downloaded the SP X509 certificate and click Upload Certificate.
      Advanced Settings dialog
    • In the ATTRIBUTE STATEMENTS (OPTIONAL) section, set the mapping as shown in the following image:
      Attribute Statement mapping
      Note: You must remember the attribute names specified in the above image. You will require to map these user attribute names while configuring the User Attribute Map on the SSO Configuration page in FortiSOAR.
    • Click Next.
    • On the Help Okta Support understand how you configured this application dialog, select I’m an Okta customer adding an internal app, and This is an internal app that we have created.
      Okta Feedback dialog
    • Click Finish.
      The Sign On tab of your newly created SAML application gets displayed. Keep this page open in a separate tab or browser window as you will require the information present on this page to complete the Identity Provider Configuration section in FortiSOAR.
      Sign On tab of the newly created SAML application
  4. Get SSO details. Click View Setup Instructions and information as shown in the following image:
    View Setup Instructions of the newly created SAML application
  5. Add the SSO details shown in step 4 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, enter the IdP details as shown in the following image:
    FortiSOAR™ UI - Identity Provider Configuration Details
    Note: The LogoutRequest message for Okta must be signed for Single Logout (SLO). Therefore, you must select the Logout Request Signed checkbox that is present in the Advanced Properties SAML Advanced Settings pane in the Security Configuration section.
    FortiSOAR™ UI - Security Configuration section
  6. Add the default user attribute mapping for Okta in FortiSOAR by updating the User Attribute Map as shown in the following image:
    Default user attribute mapping for Okta in FortiSOAR™
    Note: The IdP keys, the keys on the right side, are obtained from the ATTRIBUTE STATEMENTS (OPTIONAL) section in Okta, as specified in step 3. You can change the default user attribute mapping later if required.
  7. Click Save to complete the SSO configuration in FortiSOAR.
  8. Create a new user in Okta. Log on to Okta as an administrator and navigate Directory > People > Add Person and enter all the user details.
    Okta - Add User
    Once the user is created and activated successfully, you can assign this user to the SAML application that you have created. Click on a user to get the user details, and then assign the user to an application using the Assign Applications dialog as shown in the following image:
    Okta - Assign Application to user
Configuring SAML in Google
  1. Ensure that you have Administrator access for your G Suite account and log on to G Suite using the admin account.
  2. Configure IdP.
    • On your Admin console, click Apps.
      GSuites Admin Console
    • Click SAML apps. On the SAML page, click + on the right bottom corner, to add a new SAML Application.
      SAML page - New SAML Application
    • On the Enable SSO for SAML Application page, click SETUP MY OWN CUSTOM APP.
      Enable SSO for SAML Application page
    • Click Next to display the Google IdP information. Save the Google IdP information and download the Certificate.
      You will require the IdP information for Google to configure SSO within FortiSOAR.
      Google IdP information
    • Click Next and add basic information about the App, such as Name and Description and then click Next.
    • On the Service Provider Details page, enter the Entity ID and ACS URL from the Service Provider section in FortiSOAR. Log on to FortiSOAR and navigate to Settings > Authentication > SSO Configuration, go to the Service Provider section to get the details. See Configuring SAML in FortiSOAR.
      Service Provider Details page
    • Click Next and add more attribute mapping as required.
      Attribute Mapping page
    • Save the app configuration and click Exit.
    • Set up user access for the Google SAML App, see Set up your own custom SAML application.
  3. Add the SSO details saved in step 2 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, enter the Google IdP details and certificate as shown in the following image:
    Gmail - Configuring IdP details in FortiSOAR™
    Note: Google SAML app does not provide a Logout URL. Therefore, users remain logged into their Google account even if they log off from FortiSOAR.
    In FortiSOAR the Single Logout Request URL field is optional and can be left blank.
  4. Add the default user attribute mapping for Google in FortiSOAR by updating the User Attribute Map, based on what you have set in the attribute mapping in the Google SAML app, as shown in the following image:
    Default user attribute mapping for Google in FortiSOAR™
  5. Click Save in FortiSOAR to save the changes to the IdP configuration.
Configuring SAML in Azure Active Directory
  1. Open the Azure Active Directory (Azure AD) portal: https://aad.portal.azure.com/.
  2. From the left menu, click Enterprise Applications.
    Azure AD - Enterprise Applications menu
  3. On the Enterprise Applications page, click New Application.
    Add Enterprise Applications in Azure AD
  4. Click Create Your Own Application.
  5. Enter FortiSOAR in the Name field and and click Integrate any other application you don't find in the gallery (Non-gallery), and then click Create.
  6. Follow the steps mentioned in the Getting Started section such as adding users/groups, creating custom roles for SAML Role mapping, etc.
    Creating the FortiSOAR application in Azure AD
  7. Click Single sign-on, and then SAML.
    Creating FortiSOAR SSO in Azure AD
  8. Create a unique Identifier (Entity ID) in Azure AD.
    Creating a unique FortiSOAR ID in Azure AD
  9. Modify user attributes in Azure AD as shown in the following image:

    Modifying user attributes in Azure ADImportant: For the Azure AD attributes and claims, it's recommended that you delete the namespace section for each attribute, else it generates a URL. The following image is an example of the Email attribute whose namespace is blank:
    Azuare AD - Manage Claim dialog
  10. In FortiSOAR, navigate to Settings > Authentication > SSO Configuration, and then enter the IdP details in the Identity Provider Configuration section as shown in the following image:
    Details of the IdP Configuration section in FortiSOAR
    Enter the details such as the Entity ID, Single Sign On URL, Single Logout Request URL, etc as set up in Azure AD.
    In the X509 Certificate field, paste the text that you copied from the downloaded Azure AD certificate.
  11. Add the user attribute mapping for Azure AD in FortiSOAR by updating the User Attribute Map as shown in the following image:
    Mapping user attributes in FortiSOAR
  12. In the Team and Role Mapping section map the teams and roles of SSO users to the teams and roles created in Azure AD IdP:
    1. To create roles in Azure AD, open the Azure Active Directory (Azure AD) portal.
    2. From the left menu, click Azure Active Directory and then click App registrations. In the All applications section, search for the name of your FortiSOAR application:
      Application Registrations page on Azure AD
    3. Click App Roles and then click Create app role. for example, create the FSR_T2 Analyst in Azure AD, as shown in the following image:
      Creating an new app role in Azure AD
      Then enter the values in the Create app role dialog, and click Apply.
      Adding values for the FSR_T2 role in Azure AD
      This creates the FSR_T2 Analyst role in Azure AD. You need to perform this step for each role that you want to map in FortiSOAR.
    4. Log on to FortiSOAR and on the SSO Configuration page, and map the roles that you have created in Azure AD to FortiSOAR roles. For example, FSR_T2 Analyst role can be mapped to the T2 Analyst role in FortiSOAR:
      Update Role Mapping in FortiSOAR for the FSR_T2 role created in Azure AD
  13. The Service Provider details are auto-populated, as shown in the following image:
    Service Provider configuration section
    Note: These settings can be kept as is and only need to be updated for DNS name change if you want to keep a different DNS name for FortiSOAR than the one set in FortiSOAR (as hostname).
  14. Click Save in FortiSOAR to save the changes to the IdP configuration.
Configuring SAML in ADFS
Note

If you change the hostname for your FortiSOAR system, you will require to delete the old ADFS configuration and re-configure ADFS.

General ADFS Setup

This procedure uses ADFS 3.0 and uses samlportal.example.com as the ADFS website. The values you use in your setup will be based on your ADFS website address. See ADFS integration with SAML 2.0 for more information.

  1. Log on to the ADFS server and open the management console.
  2. Right-click Service and click Edit Federation Service Properties.
    ADFS configuration: Edit Federation Service Properties option
  3. On the Federation Service Properties dialog, in the General Settings tab, confirm that the DNS entries and certificate names are correct. Note the Federation Service Identifier, since you will use as the Entity ID in the Identity Provider Configuration in the FortiSOAR UI.
    ADFS configuration: Federation Service Properties dialog
  4. In the Services panel, browse to Certificates and export the Token-Signing certificate using the following steps.
    1. Right-click the certificate and select View Certificate.
    2. Select the Details tab and click Copy to File, which opens the Certificate Export wizard.
    3. On the Certificate Export Wizard, click Next.
    4. Select Base-64 encoded binary X.509 (.cer), and then click Next.
    5. Select where you want to save the Token-Signing certificate and provide a name to the certificate, and then click Next.
    6. Click Finish.
    7. Copy the contents of the Token-Signing certificate and paste the contents in the X509 Certificate area in the Identity Provider Configuration in the FortiSOAR UI.
Configuring ADFS Relying Party Trust
  1. Log on to FortiSOAR as an administrator.
  2. Click Settings > Authentication > SSO Configuration and download the SAML metadata file by clicking Download in the Service Provider Configuration section.
  3. Log on to the ADFS server and open the ADFS management console.
    ADFS Management Console
  4. Expand Trust Relationships and right-click Relying Party Trust and select Add.
  5. On the Add Relying Party Trust Wizard click Start.
  6. In the Select Data Source panel, select the Import data about the relying party from a file option and click Browse to navigate to the SAML metadata file that you have saved in Step 2 and then click Next.
    ADFS configuration: Add Relying Party Trust Wizard
  7. In the Specify Display Name panel set the display name and then click Next.
  8. (Optional) In the Configure Multi-factor Authentication Now? panel configure MFA and then click Next.
  9. In the Choose Issuance Authorization Rules panel, select the Permit all users to access this relying party option and then click Next.
  10. In the Ready to Add Trust panel, click Next.
  11. In the Finish panel, ensure that the Open the Edit Claim Rules dialog statement is selected and then click Close. This opens the Edit Claim Rules Wizard in which you can immediately add and configure rules as mentioned in the next section, or if you have closed Edit Claims Rules then use the steps mentioned in the next section to open Edit Claim Rules and add and configure rules.
Configuring ADFS Relying Party Claim Rules

You must edit the claim rules to enable communication with FortiSOAR SAML

  1. Log on to the ADFS server and open the management console.
  2. Right-click the relying party trust (as configured in the previous section) and select Edit Claim Rules.
  3. Click the Issuance Transform Rules tab and select Add Rules.
  4. Select Send LDAP Attribute as Claims as the claim rule template to use and then click Next.
  5. On the Configure Claim Rule dialog, in Claim rule name, enter a name to the claim rule. For example, name the claim rule as Get LDAP Attributes.
  6. From the Attribute store drop-down list, select Active Directory.
  7. In the Mapping of LDAP attributes to outgoing claim types section, map the following values:
    1. Select SAM-Account-Name from the LDAP Attribute column and map that to E-Mail Address in the Outgoing Claim Type column.
    2. Select E-Mail-Addresses from the LDAP Attribute column and map that to Email in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column.
    3. Select Surname from the LDAP Attribute column and map that to Last Name in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column.
    4. Select Given-Name from the LDAP Attribute column and map that to First Name in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column and the values that you specify in the Outgoing Claim Type column must match the what you enter in the right-side field in the User Attribute Map in the Identity Provider Configuration in the FortiSOAR UI.
    5. Select Token-Groups - Unqualified Names from the LDAP Attribute column and map that to Roles in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column.
      ADFS configuration: Edit Rule - Get LDAP Values
  8. Click Finish and select Add Rules.
  9. Select Transform an Incoming Claim as the claim rule template to use and then click Next.
  10. On the Add Transform Claim Rule Wizard, in Claim rule name, enter a name to the claim rule. For example, name the claim rule as Email to Name ID.
  11. From the Incoming claim type drop-down list, select E-Mail Address, from the Outgoing claim type drop-down list, select Name ID and select the Pass through all claim values option and click Finish and then click OK.
    ADFS configuration: Add Transform Claim Rule Wizard
Configuring FortiSOAR for ADFS
  1. Log on to FortiSOAR as an administrator.
  2. Click Settings > Authentication > SSO Configuration.
  3. To enable SAML for FortiSOAR, click the SAML Enabled check box.
  4. In the Identity Provider Configuration section, enter the IdP details.
    Enter the Entity ID as the one that you had noted in Step 3 of the General ADFS Setup procedure. For example, https://samlportal.example.com/adfs/services/trust
    Enter the Single Sign On URL as <server_address>/adfs/ls. For example, https://samlportal.example.com/adfs/ls
    Enter the Single Logout Request URL as <server_address>/adfs/ls?wa=wsignout1.0. For example, https://samlportal.example.com/adfs/ls?wa=wsignout1.0
    In the X509 Certificate area, paste the contents of the certificate you exported in Step 8 of the General ADFS Setup procedure. Following is an image of sample inputs in the FortiSOAR UI:
    Identity Provider Configuration Section: ADFS Configuration
  5. Map the user attributes received from the ADFS (IdP) with the corresponding attributes of FortiSOAR.
    Use the User Attribute Map to map the attributes received from the ADFS with the corresponding attributes required by FortiSOAR. FortiSOAR requires the firstname, lastname and email attributes to be mapped. The ADFS attributes that you need to map are the names that you specify as values in the Outgoing Claim Type column in the management console of ADFS. For more information, see Configuring ADFS Relying Party Claim Rules.
    In the User Attribute Map, under Fields, click the editable field name (right side field name), to map it to the attribute that will be received from the IdP. The non-editable field name (left-side field name) is the FortiSOAR attribute. For example, in the following image, you map the FortiSOAR attribute firstName to the IdP attribute First Name.
    User Attribute Map
    If you want to set any of the optional configurations, see Configuring SAML in FortiSOAR.
  6. Click Save to complete the SAML configuration in FortiSOAR.
Support for mapping roles and teams of SSO users in FortiSOAR

You can map the role and team of SSO users in FortiSOAR based on their roles defined in the IdP. Thereby you can set the role of an SSO user in FortiSOAR based on the role you have defined in your IdP.

To achieve this FortiSOAR has added a new configuration in the SSO Configuration page where you can map the role that you have specified in the IdP to a FortiSOAR role and team. The relationship between the IdP role and the FortiSOAR role is one to many, i.e., one IdP role can map to multiple FortiSOAR roles.

SAML supports attribute-based authorization. Therefore, you should configure attribute roles in your IdP that will contain roles of your SSO users on the IdP.

If you have not set up mapped roles of SSO users in FortiSOAR, or if FortiSOAR receives a response from the IdP that does not contain any roles, or receives a response that does not map to any of the FortiSOAR roles, then the SSO user will be assigned the default roles.

Configuring IdPs to send the SSO user role information to FortiSOAR

The following sections define how you can configure IdPs, i.e., OneLogin, Okta, or Auth0 to send the SSO user role information to FortiSOAR when the user is logging on to FortiSOAR (SSO login).

For mapping of roles in ADFS, see the Configuring ADFS Relying Party Claim Rules section.

For any other IdP, configure roles as per the IdP requirements and contact the IdP support personnel if you face any issues.

OneLogin

  1. Log on to OneLogin as an administrator.
  2. Navigate to the SAML app that you have created by clicking APPS in the administration panel. Open the SAML app and in the App Configuration screen, go to the Parameters section and click Add Field, which displays the New Field dialog.
  3. In the New Field dialog, in the Field name type Roles, ensure that you check Include in SAML assertion checkbox in the Flags section, and then click Save.
    OneLogin SAML application: New Field Dialog
  4. In the next dialog, i.e., the Edit Field Roles dialog, from the Value drop-down list, select User Roles and click Save.
    OneLogin SAML application: Edit Field Dialog

Okta

  1. Log on to Okta as an administrator.
  2. Navigate to the SAML app that you have created and edit the SAML settings.
  3. In the GROUP ATTRIBUTE STATEMENTS (OPTIONAL) section set the following:
    Name: Set as Roles.
    Filter: Set as Matches regex*.*
    Okta application: SAML Settings
  4. Click Next and complete the setup.

Auth0

  1. Log on to Auth0 as an administrator and in the left menu click Authorization.
  2. On the Authorization Extension page, create a new group and associate required members (users) and roles with this group.
    Auth0: Authorization Extension page with the details of the new group
  3. Navigate back to the main menu (Dashboards page) and click Applications.
  4. Create a new application, or click on the Settings icon of the application whose settings you want to edit:
    Auth0: Editing the settings of an application
    This opens the Setting page for the application:
    Auth0: Settings Page of an Application
  5. Click the Addons tab and click SAML2 and enter the required details on the Settings tab for the application you have created:
    Auth0: Addons SAML2 Web App
  6. Click Save to save the settings of the application.

Troubleshooting SAML issues

Unable to login to FortiSOAR when ADFS SAML is configured

If you are unable to login to FortiSOAR when ADFS SAML is configured and the default certificates are failing, and if you find the "The revocation function was unable to check revocation for the certificate." error in the ADFS logs, then you must turn off the certificate revocation check using the following steps:

  1. Enter Powershell in the "Administrator" mode of the ADFS system.
  2. Run the following commands: (RelyingPartyTrustName should be in double quotes):
    Set-AdfsRelyingPartyTrust -TargetName "<RelyingPartyTrustName>" -SigningCertificateRevocationCheck None
    Set-AdfsRelyingPartyTrust -TargetName "<RelyingPartyTrustName>" -EncryptionCertificateRevocationCheck None
    This turns off the certificate revocation check and now you should be able to login to FortiSOAR.
SAML users face issues while trying to login to FortiSOAR when the certificate gets expired or replaced on ADFS IDP

When the certificate gets expired or replaced on ADFS IDP, then the SAML users get the following errors which trying to log into FortiSOAR:

Fri Oct 22 06:46:26 AST 2021
			There was an unexpected error (type=Internal Server Error, status=500).
			Processing samlservice sso response failed with error: Signature validation failed. SAML Response rejected

			[root@lincon ~]# tail /var/log/cyops/cyops-gateway/saml.log
			22-10-2021 05:09:38.351 [http-nio-8080-exec-110] ERROR c.onelogin.saml2.authn.SamlResponse.isValid - Signature validation failed. SAML Response rejected
			22-10-2021 05:16:34.567 [http-nio-8080-exec-114] ERROR c.onelogin.saml2.authn.SamlResponse.isValid - Signature validation failed. SAML Response rejected
		

Resolution

To resolve this issue, get the newly deployed certificate and log in to FortiSOAR. Navigate to Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, replace the contents of the x509 Certificate field with the contents of the new certificate.

Configuring FortiSOAR authentication with a RADIUS server

From release 7.2.0 onwards, FortiSOAR enables you to authenticate users using a RADIUS server, i.e., users can enter their RADIUS credentials to log into FortiSOAR.

Use the Authentication menu to setup, modify, and turn on or off authentication with a RADIUS server.

Note

To create or update a RADIUS configuration, administrators must have 'Security Update' permissions.

Click Settings > Authentication to open the Account Configuration page. Click the RADIUS Configuration tab and click the RADIUS Enabled checkbox, if you want to authenticate users using a RADIUS server.

Security Management - Radius Configuration

Once you click the RADIUS Enabled checkbox, configure your primary and optionally a secondary RADIUS server as follows:

  1. In the Primary Server Configuration section, enter the following details for your primary RADIUS server:
    1. In the Host field, enter the IP address of the primary RADIUS server that you will use to authenticate users.
    2. In the Port field, enter the port number where the primary RADIUS server listens for authentication requests. Defaults to 1812.
    3. In the Shared Secret field, enter the secret code that is known to only the client (FortiSOAR in this case) and the primary server.
      To check the RADIUS configuration of the primary server, click the Test Connectivity button. Clicking Test Connectivity opens the Enter Test Credentials dialog in which you can enter the username and password used to connect to the primary server. If the connection succeeds, then a success message gets displayed, and if the connection fails, then an appropriate error message gets displayed.
  2. In the Secondary Server Configuration section, enter the following details for your secondary RADIUS server:
    1. In the Host field, enter the IP address of the secondary RADIUS server that you will use to authenticate users.
    2. In the Port field, enter the port number where the secondary RADIUS server listens for authentication requests. Defaults to 1812.
    3. In the Shared Secret field, enter the secret code that is known to only the client (FortiSOAR in this case) and the secondary server.
      To check the RADIUS configuration of the secondary server, click the Test Connectivity button. Clicking Test Connectivity opens the Enter Test Credentials dialog in which you can enter the username and password used to connect to the secondary server. If the connection succeeds, then a success message gets displayed, and if the connection fails, then an appropriate error message gets displayed.
  3. To save the configurations for your primary and secondary RADIUS servers, click Save.

You can use the Export and Import Wizards to export and import your Radius configurations across instances. For more information on export and import wizards, see the 'Export and Import Wizards' topic in the Application Editor chapter.

Importing RADIUS users in bulk

You can import RADIUS users in bulk into your FortiSOAR system. To import users, you must enable RADIUS authentication on the RADIUS Configuration page (Settings > Authentication > RADIUS Configuration). Once you have enabled RADIUS authentication, do the following to import users:

  1. From the left menu, click Users, and on the Users page, click the Import Users button.
    Note: The Import Users button will be visible only if RADIUS or SSO is enabled.
  2. In the Import Users dialog, do the following:
    1. From the User Type To Import drop-down list, select RADIUS User.
    2. Click the Download CSV File Sample link to download the sample CSV file (RADIUS User_Template.csv).
      Import User dialog
      The sample CSV file contains an example of the user details you need to provide. You need to provide the following user details in the CSV file:
      • username: Name of the RADIUS user.
      • email: Email address of the RADIUS user
      • firstname: (Optional) First name of the RADIUS user.
      • lastname: (Optional) Last name of the RADIUS user.
      • phonemobile: (Optional) Mobile number of the RADIUS user.
      • roles: (Optional) Role (s) that you want to assign to the RADIUS user. To assign a role to the user you need to provide the UUID of that role. To get the UUID of a role, click Settings > Security Management > Roles, and then click the role that you want to assign to the user. For example, click T1 Analyst, which opens the Edit Role page, and then from the address bar, copy the UUID (as shown in the following image) and paste it in the roles column in the CSV file.
        Copying UUID of Roles
        Note: You can assign multiple roles to the user by using the pipe symbol (|) to separate the UUID of each role.
      • teams: (Optional) Team (s) that you want to assign to the RADIUS user. To assign a team to the user you need to provide the UUID of that team. To get the UUID of a team, click Settings > Security Management > Teams, and then click the team that you want to assign to the user, and then from the address bar copy the UUID of the team, similar to the process described for roles.
        Note: You can assign multiple teams to the user by using the pipe symbol (|) to separate the UUID of each team.

      • accessType: Access type (Named or Concurrent) that you want to assign to the RADIUS user. If you do not specify any access type for the user, then the user will be assigned as a 'Concurrent' user.

  3. Once you complete filling the user details in the CSV file, click the Import User button, and in the Import Users dialog, drag and drop the CSV file or click the import icon to import the CSV file, and then click the Import Users button.
    If there are no issues in the import, then all the RADIUS users get created and they can log into FortiSOAR.
    If there are any issues in the CSV file, such as not providing all the information required to create RADIUS users, then such users are not created. To get information about the users not created, download the status report.
    Importing RADIUS users using the CSV file

Configuring the Password Vault Manager

FortiSOAR integrates 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 have 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. FortiSOAR has integrated with Thycotic Secret Server and CyberArk, and therefore we have a Thycotic Secret Server and CyberArk connectors in the Content Hub.

To use a vault in FortiSOAR, you must first install the connector from the Content Hub. 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 a 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 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 integrated 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.

Delete Users

Apart from the above functions that an administrator can perform on the FortiSOAR UI, administrators can also delete users using a script.

Caution

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 userId of the user(s) that you want to delete in the usersToDelete.txt file, which is located at /opt/cyops/scripts/. The UserID of the users are displayed in the User Id column on the Users page in the FortiSOAR UI as shown in the following image:
    Users page in FortiSOAR UI
    To copy the UserID, right-click the 'User Id' cell and from the context menu, select the Copy Cell Value To Clipboard option.
    The usersToDelete.txt file is an empty text file in which you can enter the ID of users.
  2. SSH to your FortiSOAR VM and login as a root user.
  3. Run the following command: # /opt/cyops/scripts/userDelete
    Important: The User Delete script deletes users in the local database and does not work for externalized databases.

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.

Tooltip

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 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.

FortiSOAR implements RBAC for playbooks; for example, for uses to run playbooks, administrators require to assign roles that have the Execute permission on the Playbooks module to such users.

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 using the FortiSOAR UI, though you can make a user “Inactive” to stop that user from using the system. However, you can delete users using a script, for more information, see the Delete Users section.

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. FortiSOAR supports the FreeIPA LDAP authentication.

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.

Password Vault

Use the Password Vault menu to manage integrations with external vaults such as "Thycotic Secret Server" and "CyberArk" that are used by organizations to securely store their sensitive data and credentials. You can also 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 persona with their own permissions during Incidents.

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.

Honoring RBAC for related records

Teams govern record ownership within FortiSOAR. However, in the case of related records display the RBAC is ignored when viewing records in context of their parent records. For example, if users have access to an alert records that is linked to 5 indicator records, among which the user does not have access to one indicator record, still the user is able to view all 5 indicator records in the context of alert records in alert details page under the relation tab. Note that when users click the related records to which they do not have access, users will see an "Access Denied" message.
However, if you want to honor the RBAC for related records, i.e., display only those related records to which users have access when viewing records in context of their parent records, then do the following:

  1. Open and edit the /opt/cyops-api/config/parameters_prod.yaml file.
  2. Update the ignore_rbac_for_related_record parameter to change its value to 'false' (default is 'true'):
    ignore_rbac_for_related_record: false
  3. Run the following command to complete the change:
    systemctl restart php-fpm && sudo -u nginx php /opt/cyops-api/bin/console cache:clear && systemctl restart php-fpm

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 Team 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 Team:

  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 Team. 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 Team 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 Team and L2 Teams, but we now see that L1 is also a Parent.

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

  1. Effectively own only their own records
  2. Own none of SOC Team, L2, or L1 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.

By default, FortiSOAR has at least one team in place after installation, the SOC Team. We recommend that you do not modify the default teams and instead add new teams, as per your requirements.

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.

Tooltip

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 hard-coded in the system; therefore, Role editing is a sensitive permission and must be carefully governed by system users.

Note

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 Roles page 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 for a particular role.

Release 7.2.1 has enhanced the 'Set Role Permissions' grid on the Roles page to make permission assignment efficient, intuitive, and logical:

  • Automatic logical selection of permissions:
    • Selecting the 'Create' permission for a module leads to the automatic selection of the 'Read' permission for that module.
    • Selecting the 'Update' permission for a module leads to the automatic selection of the 'Read' and 'Create' permissions for that module.
  • Locks the column headers of the 'Set Role Permissions' grid to ensure that is always displayed, which improves the usability of the grid.

You can also explicitly assign permissions for each field within a module by clicking the Set Field Permissions link for that module, changing the permissions for the particular field and then clicking Save:
Roles Page - Set Field Permissions dialog

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-tenant 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 its installation, the Security Administrator. Apart from the Security Administrator role, FortiSOAR generally also has the following default roles defined, after the installation of the SOAR Framework Solution Pack (SP):

  • SOC Manager - manages the investigation of incidents and other containment and remediation tasks.
  • Security Administrator - administers Teams and Roles and is responsible for creating the appropriate team structure and 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.
  • SOC Analyst - triages alerts, filters false positives, investigates incidents, and performs other remediation and containment tasks.

Apart from the default roles, you can also create roles as per your requirements such as a FortiSOAR Agent that contains agent permissions, i.e., agent appliances are auto-assigned to this role. You can add this role directly to users so that they get access to agents. Agent appliances are auto-assigned to this role, and by default have access (CRU permissions) to Files and Attachments.

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

Caution

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

SOC Manager

The SOC Manager role is given complete access to the Alerts and Incident modules and modules associated with the investigation of incidents, such as Approvals, Assets, Communications, Indicators, Tasks, War Rooms, etc, and also Notification Rules, Schedules, Reporting, etc. These users are responsible for investigating incidents and performing remediation and containment activities.

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-tenant 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.

Caution

"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 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, they 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.

Tooltip

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.

SOC Analyst

The SOC Analyst role is given access to the Alerts and Incident modules, and modules associated with alerts, such as Comments, Attachments, Indicators, Tasks, War Rooms, etc, and also Schedules, Reporting, etc. These users are responsible for alert triaging, false-positive filtering, investigating incidents and performing other remediation and containment tasks, and escalating potentially malicious alerts to incidents for review by the SOC team.

Modules in the Roles Page

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.

Note

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.

Note

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.
  • Password Vault - the ability to integrate with external vaults such as "Thycotic Secret Server" and "CyberArk" to securely store their sensitive data and credentials.
  • 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 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).

Tooltip

Users who are assigned roles having permissions to the 'People' module, but who do not have access to the 'User Id' field, i.e., the User Id field is set as 'No Access' in the People Field Permissions dialog, are unable to see 'Locked', 'User Id', and 'Login Status' fields for users listed on the Users page in FortiSOAR. For information on setting field permissions for modules, see the Configuring Roles section

Configuring User and Appliance Profiles

Adding Users

To add a new user, click Settings > Users to open the Users page. The Users page displays details such as name, title, lock status, ID, etc for all the created users in your FortiSOAR system.

Users Page - Login Status

From version 7.0.1 onwards, you can select any active user as a "Super Admin." A Super Admin user has a privilege of being able to log into FortiSOAR even when the system is in violation of the allowed user seats, i.e., the number of named users exceeds the number of seats you have bought for FortiSOAR. By default, this user is set as 'CS Admin'. Prior to version 7.0.1, the csadmin user could log into FortiSOAR, even when there was a license validation failure. However, there could be customer environments where the csadmin user is kept inactive or has been deleted, and therefore ability to choose any active user as a Super Admin is introduced in version 7.0.1. On the Users page, in the Designate Super Admin section, from the Select User drop-down list, which displays only active users, select the user that you want to designate as the Super Admin and click Set As Super Admin.

Note

The user who is chosen as the Super Admin user must have Read and Update permissions on the Security and People modules, so that in case of a license violation the Super Admin is able to update the access type of the users. Also, the Super Admin user cannot be marked as 'Inactive' or deleted.

From version 7.0.1 onwards, the Users page also displays the access type, i.e., named or concurrent, and login status of all the users. For more information on 'Concurrent Users', see the Licensing FortiSOAR chapter in the "Deployment Guide." You can selectively update users' access type, i.e., Concurrent users to Named users, and vice-versa, at any time. You can also bulk update the access type of users from Named to Concurrent by selecting the users in the Grid on the Users page whose access type you want to change from named to concurrent, then click the Switch to Concurrent button, and then click Confirm on the Confirmation dialog.

Bulk change user access from Named to Concurrent

You might need to bulk update the user access from Named to Concurrent, when you have upgraded FortiSOAR, or when you have used the FortiSOAR's wizard-based export and import of user configuration information between environments, where all the users present in FortiSOAR have their access type set as Named. For more information on Export and Import Wizards, see the Application Editor chapter.

You can forcefully log out selective 'Concurrent' users from the system, by clicking the Logout icon in the row of a particular user. For example, if you want to log out Test User2, then click Logout in the Test User2 row. FortiSOAR will display a Confirmation dialog, click Confirm to display a Force Logout User dialog, in which you can add a custom message that will be displayed to the user when the user is being forcefully logged out, and then click Logout User:

Force logout user dialog

Note

A Named user can never be forcefully logged out of any system.

To add a new user, click Add and enter the user details on the New User page and click Save to save the new user profile.

Note

The Username field is mandatory and case sensitive and it cannot be changed once it is set. It is also recommended that all new users should change their password when they first log on to FortiSOAR, irrespective of the complexity of the password assigned to the users.

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.

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, phone numbers, and access type, i.e., Named or Concurrent. 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

You can upload the user's profile picture by clicking Change Image, which opens the Upload a Profile Picture dialog, where you can drag-and-drop the profile image file, or click the Import icon and browse to the image file to import the profile image file to FortiSOAR, and then click Save Profile Image to add the profile image. Once the profile image is added, the same can be removed at anytime by clicking the Remove Image button that appears on the profile image.
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 get temporally locked out of FortiSOAR when they have exceeded the number of authentications tries allowed within a one-hour period. By default, users' can enter incorrect credentials, username and/or password 5 times, while logging into FortiSOAR, before their account gets locked for 30 minutes. From version 7.0.0 onwards, administrators cannot lock a user using the FortiSOAR UI; however, administrators can unlock a locked user using the UI by clicking the Unlock checkbox on that user's profile page and then clicking Save, or locked users can wait for 30 minutes before their account gets unlocked. Security Administrators can also change the default values for the different parameters, such as number of attempts before the user account is locked, etc. For information about these parameters. see the Debugging, Troubleshooting, and Optimizing FortiSOAR chapter.

From version 7.0.1 onwards, you can also forcefully log out selective users from the system, by clicking the Logout icon on the user's profile page:

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.

Tooltip

If you face issues with user preferences such as applying filters on the grid or column formatting within a grid, 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.

In release 7.2.1, FortiSOAR provides administrators — users with a minimum of 'Security' Read permissions — with the ability to view the aggregated list of effective permissions based on different roles assigned to a given user. To view the consolidated permissions list for a specific user, click Settings > Users. On the Users page in the Manage Users section, click the row of the user whose consolidated permissions you want to view. On the user's profile page, in the Roles section, click View Effective Role Permissions:
User Profile - View consolidated permissions

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 chapter for further details.

From release 7.2.0 onwards, a new user type named 'RADIUS' is introduced. In the Authentication Type drop-down list, you can create either a 'Native' user or a 'RADIUS' user. Users with their authentication type set to RADIUS can log in to FortiSOAR using their RADIUS credentials:

Uses whose type is set to 'RADIUS'

Administrators must setup RADIUS configuration before users can perform authentication. The steps for setting up RADIUS are present in the Configuring FortiSOAR authentication with a RADIUS server topic. Also, note that the username of the RADIUS user that you create in FortiSOAR must be the same as the username specified on the RADIUS server since FortiSOAR performs a lookup for the user before making the RADIUS authentication request. You can also import RADIUS users in bulk into your FortiSOAR system, details for which are present in the Importing RADIUS users in bulk topic.
While logging on to FortiSOAR, the user credentials are first authenticated against primary radius server, and if the authentication against primary server succeeds, the user gets logged in to FortiSOAR. If the connection to the primary radius server fails, then the credentials are authenticated against secondary server, and if this authentication succeeds, the user gets logged in to FortiSOAR; else the log in attempt fails with the appropriate error message.

You can configure the users' access type, i.e., whether the user is a Named user or a Concurrent user. A 'Named' user has a FortiSOAR seat permanently reserved, i.e., such a user can always log onto FortiSOAR except in case of a license violation. However, a 'Concurrent' user can log in only when there is a concurrent seat available. You can also selectively change users' access type, i.e., Concurrent users to Named users, and vice-versa, at any time, or you can bulk change users access type from Named to Concurrent. For more information, see the Adding Users section.

Editing user access type

You can also configure whether the user is an Application User or Dashboard User. You can set different re-authentication 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. Security Administrators can 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

You can determine how you want to send notifications. To send system notifications using emails, select the Enable System notification on email checkbox. To send emails when a user is tagged, using @, in comments, select the Enable email notifications for @ mentions in comments checkbox.

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. Audit logs 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.

In release 7.2.1, FortiSOAR provides administrators — users with a minimum of 'Security' Read permissions — with the ability to view the aggregated list of effective permissions based on different roles assigned to a given appliance. To view the consolidated permissions list for a specific appliance, click Settings > Appliances. On the Appliances page, click the row of the appliance whose consolidated permissions you want to view. On the Edit Appliance page, in the Roles section, click View Effective Role Permissions:
Appliance - View consolidated permissions

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.

Caution

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.

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 Team 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 Team. 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 Team 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 Team 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.

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, configuring SAML to enable users to use sign-on (SSO), and configuring authentication with RADIUS server.

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, and recommended value is 30 minutes.
Note: The token refresh time must always be set to less than 120 minutes. This is needed as the maximum token alive time is 120 minutes, before which the token must be refreshed.
Reauthenticate Dashboard User The number of hours after which a dashboard user is forced to be re-authenticated. The default value is 24 hours.
Reauthenticate Application User The number of hours after which an application user is forced to be re-authenticated. 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.

Enabling custom password policies for users configured with Basic Authentication

When a new password is set up it must contain the following:

  • At least 8 characters
  • one lower-case alphabet
  • one upper-case alphabet
  • one digit
  • Any one of the following special characters ~ ! @ # $ % ^ & * | ? _

Apart from the above default rules, you can also set up custom password policies, which enforces the following additional restrictions on the passwords that users can create:

  • Password must not be one of 10 previous passwords.
  • Password must not contain the username of the user.

  • Password must not have been changed in the last 1 day.

By default, the custom password policy is disabled. If you want to enable the custom password policy, you need to do the following on your FortiSOAR instance:

  1. Edit the das.ini file as a root user using an SSH session:
    vi /opt/cyops-auth/utilities/das.ini
  2. Add the[PASSWORD] section at the end of the das.ini file as follows:
    [PASSWORD]
    validator = custom

    This enables the custom password policy for your FortiSOAR instance.
  3. If you want to change any of the parameters for the default or custom password policy, you require to edit the custompwdvalidator.py file located at /opt/cyops-auth/validationutils/custompwdvalidator.py
    For example, if you want to change the default length of the password that users can set from 8 characters to 10 characters, in the custompwdvalidator.py file update the following:
    if len(password) < 8:
    message = "Password must be at least 8 character long"
    logger.error(message)
    return False, message

    To
    if len(password) < 10:
    message = "Password must be at least 10 character long"
    logger.error(message)
    return False, message

    Similarly, you can also update a custom policy. For example, if you do not want to enforce the "Password must not contain the username of the user" policy, you can comment out or remove the following code from the custompwdvalidator.py file:
    if loginid.lower() in password.lower():
    message = "username not allowed in password"
    logger.error(message)
    return False, message

    Important: If you make any changes to the validate() function in the customepwdvalidator.py file, ensure you make the corresponding update in the password_policy() function in the same file.
    Optionally, if you want to update the "Password must not be one of 10 previous passwords" custom policy to "Password must not be one of 12 previous passwords", you can run the following command:
    /opt/cyops/scripts/api_caller.py --method PUT --endpoint https://localhost/api/auth/config --payload '{"option":"history","value": 12}'
    The value of the value parameter in the --payload determines the number of passwords that users cannot use, for example in the above command it is set to '12'.
    Or, if you want to update the "Password change not allowed within 1 day of last password change" custom policy to "Password change not allowed within 2 days of last password change", you can run the following command:
    /opt/cyops/scripts/api_caller.py --method PUT --endpoint https://localhost/api/auth/config --payload '{"option":"min_password_age","value": 2}'
    The value of the min_password_age parameter in the --payload determines how often users can change their passwords, for example in the above command it is set to '2', i.e., users cannot change their password within a two-day time frame.
  4. If you make any changes in the custompwdvalidator.py file, then you must restart the cyops-auth service:
    systemctl restart cyops-auth

Configuring account lockout configurations

Click Settings > Authentication to open the Account Configuration page. In the Failed Authentication Settings section, you can configure the following options for account lockouts:
Settings for managing account lockouts

  • Maximum Failed Login Attempts: Specify the number of times that users can enter an incorrect password while logging into FortiSOAR before their account gets locked. By default, this is set to 5 (times).
  • Account Unlock Time: Specify the duration, in minutes, after which the user accounts get automatically unlocked, in cases where user accounts were locked due to exceeding the number of failed login attempts. By default, this is set to 30 (minutes).

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

User Search

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.

Tooltip

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.

Introduction to SAML

Security Assertion Markup Language (SAML) is an XML-based, open standard data format for exchanging authentication and authorization data between parties, particularly between an identity provider and a service provider. The single most important requirement that SAML addresses are web browser single sign-on (SSO).

By using SAML, FortiSOAR does not require to store user credentials, and FortiSOAR is independent of the underlying authentication mechanism used by a user. Once you complete making all the SAML configurations on both the FortiSOAR and Identity Provider (IdP) side, then the FortiSOAR login page will display a Login with SSO button. Users can then log on to FortiSOAR using the Login with SSO button that is present on the FortiSOAR login page.

FortiSOAR™ login page with Single Sign-On

Once the user clicks the Login with SSO button, the user is redirected to a third-party identity provider login page, where the user must enter their credentials and get themselves authenticated. Once a user successfully logs on to FortiSOAR, the user profile automatically gets created. The User profile is created based on the configurations you have set while Configuring SAML in FortiSOAR. For example, when the user is created, the user is assigned the default team and role based on what the administrator configured during SAML configuration. Users can update their profile by editing their user profile.

You can map the role and team of SSO users in FortiSOAR based on their roles defined in the IdP. Thereby you can set different roles for different SSO users, i.e., you can set the role of an SSO user in FortiSOAR based on the role you have defined in your IdP. For more information, see Support for mapping roles and teams of SSO users in FortiSOAR.

Note

The default access type set for all SSO users is 'Concurrent'. Administrators can change the access type for the user later, if needed. For more information about user access types, see the Licensing FortiSOAR chapter in the "Deployment Guide."

Benefits of SAML

User experience: SAML provides the ability for users to securely access multiple applications with a single set of credentials entered once. This is the foundation of the federation and single sign-on (SSO). Using SAML, users can seamlessly access multiple applications, allowing them to conduct business faster and more efficiently.

Security: SAML is used to provide a single point of authentication at a secure identity provider, meaning that user credentials never leave the firewall boundary, and then SAML is used to assert the identity to others. This means that applications do not need to store or synchronize identities, which in turn ensures that there are fewer places for identities to be breached or stolen.

Standardization: The SAML standardized format is designed to interoperate with any system independent of implementation. This enables a more open approach to architecture and identity federation without the interoperability issues associated with vendor-specific approaches.

SAML Principles
Roles

SAML defines three roles: Principal (generally a user), Identity Provider (IdP), and the Service Provider (SP).

Principal: The principal is generally a user that has an authentic security context with IdP and who requests a service from the SP.

Identity Provider (IdP): IdP is usually a third-party entity outsourced to manage user identities, or in other terms, an IdP is a user management system. The IdP provides user details in the form of assertions. Before delivering the identity assertion to the SP, the IdP might request some information from the principal, such as a username and password, to authenticate the principal. SAML specifies the assertions between the three parties: in particular, the messages that assert identity that is passed from the IdP to the SP. In SAML, one identity provider can provide SAML assertions to many service providers. Similarly, one SP might rely on and trust assertions from many independent IdPs.

Service Provider (SP): The SP maintains a security wrapper over the services. When a user request for a service, the request first goes to the SP, who then identifies whether a security context for the given user exists. If not, the SP requests and obtains an identity assertion from the IdP. Based on this assertion, the service provider makes the access control decision and decides whether to perform some service for the connected principal.

Attribute Mapping

Each IdP has its own way of naming attributes for a user profile. Therefore, to fetch the attribute details for a user from an IdP into the SP, the attributes from the IdP must be mapped to attributes at the SP. This mapping is taken care in a separate part at the SP. If the attribute mapping is not set correctly, the SP sets default values for mandatory attributes like First Name, Last Name, and Email.

Prerequisites to configuring SAML

  • Ensure that you are assigned a security administrator role that at a minimum has Read, Create and Update permissions on the Security module. You also require to have Read permissions for Teams and Roles.
  • Ensure that you have enabled SAML in your FortiSOAR instance. To enable SAML, log on to FortiSOAR, click Settings. In the Security Management section click Authentication to open the Authentication Configuration page. Click the SSO Configuration tab and click the SAML Enabled checkbox.

Configuring SAML in FortiSOAR

Configuring SAML is a two-way process. The SP configuration that is present in the FortiSOAR UI must be made at the IdP. Similarly, the IdP configuration must be added to the FortiSOAR UI.

This section covers configuring SAML with IdPs such as, FortiAuthenticator (FAC) OneLogin, Auth0, Okta, Google, and Active Directory Federation Services. (ADFS), which are the IdPs that have been tested with FortiSOAR. You can use a similar process to configure any other IdP that you use.

  1. Log on to FortiSOAR as an administrator.
  2. Click Settings > Authentication > SSO Configuration.
  3. To enable SAML for FortiSOAR, click the SAML Enabled check box.
  4. In the Identity Provider Configuration section, enter the IdP details.
    Get the details for FortiAuthenticator (FAC) from the Configuring SAML in FortiAuthenticator section.
    Get the details for OneLogin from the Configuring SAML in OneLogin section.
    Get the details for Auth0 from the Configuring SAML in Auth0 section.
    Get the details for Okta from the Configuring SAML in Okta section.
    Get the details for Google from the Configuring SAML in Google section. You must have an administrator account for your G Suite account.
    Get the details for Azure Active Directory (Azure AD) from the Configuring SAML in Azure Active Directory section.
    For information on Configuring SAML in FortiSOAR for Active Directory Federation Services (ADFS) from the Configuring SAML in ADFS section. For specific information about the values, you need to add for the SSO configuration, see Configuring FortiSOAR for ADFS.
  5. From the Provision User drop-down list, select the user creation strategy, i.e., choose either At Sign-in (Default) or Pre-provision. For more information see the Pre-provisioning SAML users section.
  6. Map the user attributes received from the IdP with the corresponding attributes of FortiSOAR.
    Use the User Attribute Map to map the attributes received from the IdP with the corresponding attributes required by FortiSOAR. FortiSOAR requires the firstname, lastname and email attributes to be mapped.
    In the User Attribute Map, under Fields, in the Tree view, click the editable field name (right side field name), to map it to the attribute that will be received from the IdP. The non-editable field name (left-side field name) is the FortiSOAR attribute. For example, in the following image, you map the FortiSOAR attribute firstName to the IdP attribute First Name.
    User Attribute Map - Tree View
    If you want to sync the user attributes and/or SAML roles between FortiSOAR users and their IdP profile, toggle IdP User Attribute Sync to ON and then select one of the following options:
    • Sync All Attributes Except SAML Roles: Selecting this option synchronizes all user attributes except SAML Roles between FortiSOAR users and their IdP profile.
    • Sync SAML Roles Only: Selecting this option synchronizes only the SAML Roles between FortiSOAR users and their IdP profile.
    • Sync All Attributes: Selecting this option synchronizes all user attributes and SAML Roles between FortiSOAR users and their IdP profile.
    You can also change the mapping in the using the Code View:
    User Attribute Map - Code View
  7. To map roles that you have defined in your IdP (see Support for mapping roles and teams of SSO users in FortiSOAR) to teams and roles in FortiSOAR, do the following:
    1. If you want to ensure that roles defined as part of SAML role mapping will be applied to SSO users in FortiSOAR, then select the Enforce SAML Role Mappings checkbox.
      Teams and Role Mapping section to map IdP roles
    2. To map a role in the IdP to a FortiSOAR-role and optionally a team in FortiSOAR, in the Team and Role Mapping section, click Add Role Mapping.
    3. In the Add New Role Mapping dialog, do the following:
      1. In the SAML Role field, add the name of the roles that you have defined in your IdP.
        Note: The name that you have specified in your IdP, and the name that you enter in this field must match exactly, including the matching the case of the name specified.
      2. From the Roles column, select the FortiSOAR role(s) that you want to assign to the role that you have specified in the SAML Role field.
      3. (Optional) From the Teams column, select the FortiSOAR teams(s) that you want to assign to the role that you have specified in the SAML Role field.
        Add New Role Mapping Dialog
        Once you assign the default team and roles to users, all user profiles created contain this team and role assigned to them.
        If you do not assign the default team and roles to users, and you have also not defined a Default (Fall Back Role), details given in a further step in this procedure, then all user profiles are created without team or role information and will have only basic access. In this case, users will require to request the administrator for appropriate access and privileges.
      4. Click Add Role Mapping.
        This adds the mapped role in the SAML Roles drop-down list in the Team and Role Mapping section as shown in the following image:
        Mapped SAML role
        As shown in the above image, the oneLoginSAMLRole, i.e., the role defined in the IdP has been mapped to the Application Administrator role and the SOC Team in FortiSOAR.
    4. To define a default role (and optionally teams) that will be assigned to the SSO user if you have not set up mapped roles of SSO users in FortiSOAR, or if FortiSOAR receives a response from the IdP that does not contain any roles, or receives a response that does not map to any of the FortiSOAR roles, do the following:
      1. From the SAML Roles drop-down list, select Default (Fall Back Role) and click Edit.
      2. In the Update Role Mapping dialog, from the Roles column select the role(s) that you want to assign to the default role. You can also optionally select the team(s) that you want to assign to the default role from the Teams column and click Update Mapping.
    5. (Optional) To delete or update an existing role do the following:
      1. To update an existing role, select the role from the SAML Roles drop-down list and click Edit and in the Update Role Mapping dialog, you can update the name of the mapped SAML role, and the mapped FortiSOAR roles and teams.
        Once you have completed modifying the existing role as per your requirement, click Update Mapping.
      2. To delete an existing role, select the role from the SAML Roles drop-down list and click Delete.
        FortiSOAR displays a confirmation dialog, click Confirm to delete the role.
  8. Add the information provided in the Service Provider section to Configuration section your IdP.
    This information is pre-configured. However, you can edit the fields, such as Entity ID (hostname) within this section. This is especially useful if you are using an alias to access FortiSOAR. You can also edit the certificate information and the private and public keys of your service provider, which is useful in cases where you want to use your own certificates.
    Service Provider configuration
    For OneLogin, enter this information in the Configure IdP step. See the Configuring SAML in OneLogin section for more details.
    For Auth0, enter this information in the Configure IdP step. See the Configuring SAML in Auth0 section for more details.
    For Okta, enter this information in the Configure IdP step. See the Configuring SAML in Okta section for more details.
  9. (Optional) Configure advanced settings for SAML.
    Prior to version 7.0.0, users were required to click the Use Single Sign On (SSO) link to get redirected to the SSO login page or login using SSO active session. However, there are some organizations that have policies, which require direct redirection to the SSO login page, if SSO is configured. Therefore, in version 7.0.0 an Auto Redirect checkbox is introduced. Select the Auto Redirect checkbox to redirect users directly to the SSO login page or automatically log the user into FortiSOAR in case the SSO session is active. If you leave the Auto Redirect checkbox cleared, then FortiSOAR directs users to the FortiSOAR login page, where users can click the Use Single Sign On (SSO) link to get redirected to the SSO login page or login using SSO active session.
    If you have selected the Auto Redirect checkbox, i.e., enabled SSO auto-redirect, administrator can yet access the FortiSOAR login page to configure or troubleshoot issues with the portal, by adding auto_redirect=false to the URL. For example, https://<hostname>/login/?auto_redirect=false
    Select the Auth Request Signed checkbox if your IdP requires FortiSOAR to send signed authentication requests.
    Select the Logout Request Signed checkbox if your IdP requires FortiSOAR to send signed logout requests.
    Select the Messages Signed checkbox if you want messages coming from your IdP to be signed.
    Select the Assertion Encrypted checkbox if you want assertions within the SAMLResponse to be encrypted.
    SAML Advanced Properties
  10. Click Save to complete the SAML configuration in FortiSOAR.
Note

Changing the hostname using the csadm command does not change hostname part in 'Service Provider' details in SAML configurations. Therefore, if you have changed the hostname, you must manually update the hostname in 'Service Provider' details in the SAML Configuration page.

Pre-provisioning SAML users

From version 7.0.2 onwards, you can choose the strategy to create SSO users between At Sign-in (Default) or Pre-provision. The At Sign-in (Default) strategy creates users at login, i.e., user accounts are created automatically on the first SSO login of the user login. The Pre-provision strategy requires the user account to be created prior to login. Pre-provisioning users enables you to limit the SSO authentication only for pre-created users, which enables you to:

  • Pre-decide roles mapping for SSO users. Now you can create users and then you can manually intervene to map the user to the correct role.
  • Minimize the issues administrators can face due to incorrect or partial configuration mapping at the IdP's end.
  • Control creation of users by mistake.

The process of pre-provisoning users is as follows:

  1. Ensure that you have selected the Pre-provision option from the Provision User drop-down list on the SSO Configuration page (Settings > Authentication > SSO Configuration).
  2. To pre-provision users you need to provide user details in a CSV file as follows:
    1. From the left menu, click Users, and on the Users page, click the Import Users button.
      Note: The Import Users button will be visible only if SSO or RADIUS is enabled.
    2. In the Import Users dialog, do the following:
      1. From the User Type To Import drop-down list, select SSO User.
      2. Click the Download CSV File Sample link to download the sample CSV file (SSO User_Template.csv).
        Import Users dialog
        The sample CSV file contains an example of the user details you need to provide. You need to provide the following user details in the CSV file:
        • username: Name of the SSO user.
        • email: Email address of the SSO user
        • firstname: (Optional) First name of the SSO user.
        • lastname: (Optional) Last name of the SSO user.
        • phonemobile: (Optional) Mobile number of the SSO user.
        • roles: (Optional) Role (s) that you want to assign to the SSO user. To assign a role to the user you need to provide the UUID of that role. To get the UUID of a role, click Settings > Security Management > Roles, and then click the role that you want to assign to the user. For example, click T1 Analyst, which opens the Edit Role page, and then from the address bar, copy the UUID (as shown in the following image) and paste it in the roles column in the CSV file.

          Note: You can assign multiple roles to the user by using the pipe symbol (|) to separate the UUID of each role.
        • teams: (Optional) Team (s) that you want to assign to the SSO user. To assign a team to the user you need to provide the UUID of that team. To get the UUID of a team, click Settings > Security Management > Teams, and then click the team that you want to assign to the user, and then from the address bar copy the UUID of the team, similar to the process described for roles.
          Note: You can assign multiple teams to the user by using the pipe symbol (|) to separate the UUID of each team.
        • accessType: Access type (Named or Concurrent) that you want to assign to the SSO user. If you do not specify any access type for the user, then the user will be assigned as a 'Concurrent' user.
    3. Once you complete filling the user details in the CSV file, click the Import User button, and in the Import Users dialog, drag and drop the csv file or click the import icon to import the CSV file, and then click the Import Users button.
      If there are no issues in the import, then all the SSO users get created and they can log into FortiSOAR.
      If there are any issues in the CSV files, such as not providing all the information required to create SSO users, then such users are not created. To get information about the users not created, download the status report.
      Importing SSO Users - Download Status Report
Configuring SAML in FortiAuthenticator
  1. Log on to FortiAuthenticator (FAC) as an administrator.
  2. Configure IdP. To configure general SAML IdP portal settings, navigate to Authentication > SAML IdP > General, and then select Enable SAML Identity Provider portal.
    FAC - Enable SAML Identity Provider portal
  3. In the Edit SAML Identity Provider Settings section, enter the following details:
    • Device FQDN: To configure this setting, you must enter a Device FQDN in the System Information widget in the Dashboard.
    • Server address: Enter the IP address, or FQDN, of the FAC device.
    • Username input format: Select one of the following three username input formats:
      • username@realm
      • realm\username
      • realm/username
    • Realms: Select Add a realm to add the default local realm with which the users will be associated.
      Use Groups and Filters to add specific user groups.
    • Login session timeout: Set the user's login session timeout limit between 5 - 1440 minutes (one day). The default is 480 minutes (eight hours).
    • IDP certificate: Select a certificate from the dropdown menu.
  4. Configure a Service Provider. Navigate to Authentication > SAML IdP > Service Providers, and then click Create New.
    FAC - Create New SAML Service Provider section
    In the Create New SAML Service Provider section, enter the following information:
    • SP name: Enter the name of the Service Provider (SP).
    • IDP prefix: Enter a prefix for the IDP that will be appended to the end of the IDP URLs.
      Alternatively, you can select Generate unique prefix to generate a random 16 digit alphanumeric string.
    • IDP address: To configure the IDP address (and IDP settings below), you must have already configured the server's address in Authentication > SAML IdP > General.
    • SP entity id: Enter the entity ID of the SP. Retrieve the SP entity id, SP ACS URL, and SP SLS URL from FortiSOAR by navigating to Settings > Authentication > SSO Configuration. Then click the Service Provider Configuration section to get these details.
      Alternatively, you can download the metadata of the SP from FortiSOAR and import the same here.
    • SP ACS (login) URL: Enter the Assertion Consumer Service (ACS) login URL of the SP.
    • SP SLS (logout) URL: Enter the Single Logout Service (SLS) logout URL of the SP.
    • SAML Attributes: Map the User attributes to SAML attributes. This is needed so that users created in FortiSOAR have the correct details.
      SAML attributes must be configured as shown in the following image:
      FAC - Map SAML Attributes
      Important: You must not change the SAML Attribute names as these are the attribute names expected by FortiSOAR. You can change the User Attribute names as per your requirement.
      The remaining fields can be left unmodified, or can be modified as per your requirement.
      You must download the IdP metadata.
  5. In FortiSOAR, navigate to Settings > Authentication > SSO Configuration, and then enter the following details in the Identity Provider Configuration section:
    FAC IDP details
    • Entity ID: Enter the IDP entity id from the Create New SAML Service Provider section mentioned in step 4.
    • Single Sign On URL: Enter the IDP single sign-on URL from the Create New SAML Service Provider section mentioned in step 4.
    • Single Logout Request URL: Enter the IDP single logout URL from the Create New SAML Service Provider section mentioned in step 4.
    • X509 Certificate: Retrieve the signing certificate from IDP metadata that you have downloaded in step 4 and enter it in this field. The signing certificate is located under the <md:KeyDescriptor use="signing"> key in the metadata xml file.
    • Advanced Properties: In the Security configuration section, ensure that the Auth Request Signed checkbox is enabled:
      FAC Advanced Properties
    • For Team and Role Mapping, the Role name can be given as the 'User Group' name from FortiAuthenticator that is present in Authentication > User Management > User Groups. You can utilize an existing Group or create a new one as per your requirement. The login user should be from the same group as mentioned in 'Team and Role' mapping.
  6. Click Save in FortiSOAR to save the changes to the IdP configuration.
Configuring SAML in OneLogin
  1. Log on to OneLogin as an administrator.
  2. Create a new application in OneLogin. Navigate to APPS > Company Apps > ADD APP. In the Find Applications section, search for saml and select SAML Test Connector (IDP w/attr w/sign response). Save the application.
    SAML Test Connector (IDP w/attr w/sign response application)
  3. Configure IdP. On the SAML Test Connector (IDP w/attr w/sign response), click the Configuration tab and enter your SP details as shown in the following image:
    SAML Test Connector - Configuration tab
  4. Get SSO details. On the SAML Test Connector (IDP w/attr w/sign response), click the SSO tab and you will see the SSO details of OneLogin (IdP) as shown in the following image:
    SAML Test Connector - SSO tab
  5. Add the SSO details shown in step 4 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, enter the IdP details as shown in the following image:
    Configure IdP in FortiSOAR™
  6. Add the default user attribute mapping for OneLogin in FortiSOAR by updating the User Attribute Map as shown in the following image:
    Default user attribute mapping for OneLogin in FortiSOAR
    Note: You can change the default user attribute mapping if required.
  7. Click Save in FortiSOAR to save the changes to the IdP configuration and user attribute mapping.
  8. Create a new user in OneLogin. Log on to OneLogin as an administrator and navigate to the USERS main menu and create a new user by clicking on NEW USER and entering relevant details. Once the user is created, open the user details, click the Applications tab and select the application created in step 2.
    Note: While attaching the application to the user, the ‘SAVE’ button might be disabled. To enable the Save button, click any field and then press space or any key and then clear the space or character using backspace.
    OneLogin - Create New User
    Once the user is created, you must assign the user a password by clicking MORE ACTIONS.
Configuring SAML in Auth0
  1. Log on to Auth0 as an administrator.
  2. Create a new application in Auth0. In the Clients section, create a new client by selecting Regular Web Applications.
  3. Configure IdP (Auth0). In Auth0, go to the Addon tab of the application you have created in step 1 and select SAML2 WEB APP. On the Settings page that appears, in the Application Callback URL field enter the ACS URL from your SP configuration. In the Settings field, uncomment the logout portion and set the callback field to the value that is present in the Logout POST URL field that is present in the Service Provider section on the FortiSOAR SSO Configuration page, as shown in the following image:
    Auth0 Application - Addon Settings tab
  4. Get SSO details. Download Identity Provider Metadata, by navigating to App configuration > Addons > SAML2 > Usage > Identity Provider Metadata. Click Download. The Identity Provider Metadata appears as shown in the following image:
    Identity Provider Metadata
  5. Add the SSO details shown in step 4 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, use the Identity Provider Metadata to fill in the Entity ID, Single Sign On URL, X509 Certificate, and Single Logout Request URL details.
    Based on Identity Provider Metadata screenshot in step 4, you would fill in the SSO details in FortiSOAR as follows:
    • In the Entity ID field enter the following value that you get from the Identity Provider Metadata:
      Entity ID field from the Identity Provider Metadata
    • In the Single Sign On URL field enter the following value that you get from the Identity Provider Metadata:
      Single Sign On URL field from the Identity Provider Metadata
    • In the Single Logout Request URL field enter the following value that you get from the Identity Provider Metadata:
      Single Logout Request URL field from the Identity Provider Metadata
    • In the X509 Certificate field enter the following value that you get from the Identity Provider Metadata:
      X509 Certificate field from the Identity Provider Metadata
    • Click Save in FortiSOAR to save the changes to the IdP configuration and user attribute mapping.
Configuring SAML in Okta
  1. Log on to Okta as an administrator.
    If you don’t have an Okta organization, you can create a free Okta Developer Edition organization.
  2. Create a new application in Okta and configure IdP in the application.
    • In Okta, click the blue Admin button.
    • On the Applications tab, click Add Applications > Create New App.
    • On the Create a New Application Integration dialog, select SAML 2.0 and click Create.
      Creating a New Application in Okta
  3. Configure IdP.
    • In the newly created application, on the General Settings dialog, in the App name field, enter the application name and click Next.
      General Settings dialog - Adding an application name
    • On the Configure SAML dialog, in the SAML Settings section, in the Single Sign On URL field, enter or paste the SP ACS URL and in the Audience URI field, enter or paste the SP Entity ID.
      SAML Settings dialog
    • Click Show Advanced Settings.
    • Select the Enable Single Logout checkbox.
      In the Single Logout URL field, enter or paste the SP Logout POST URL.
      In the SP Issuer field, enter or paste the SP Entity ID.
      In the Signature Certificate field, browse to where you have downloaded the SP X509 certificate and click Upload Certificate.
      Advanced Settings dialog
    • In the ATTRIBUTE STATEMENTS (OPTIONAL) section, set the mapping as shown in the following image:
      Attribute Statement mapping
      Note: You must remember the attribute names specified in the above image. You will require to map these user attribute names while configuring the User Attribute Map on the SSO Configuration page in FortiSOAR.
    • Click Next.
    • On the Help Okta Support understand how you configured this application dialog, select I’m an Okta customer adding an internal app, and This is an internal app that we have created.
      Okta Feedback dialog
    • Click Finish.
      The Sign On tab of your newly created SAML application gets displayed. Keep this page open in a separate tab or browser window as you will require the information present on this page to complete the Identity Provider Configuration section in FortiSOAR.
      Sign On tab of the newly created SAML application
  4. Get SSO details. Click View Setup Instructions and information as shown in the following image:
    View Setup Instructions of the newly created SAML application
  5. Add the SSO details shown in step 4 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, enter the IdP details as shown in the following image:
    FortiSOAR™ UI - Identity Provider Configuration Details
    Note: The LogoutRequest message for Okta must be signed for Single Logout (SLO). Therefore, you must select the Logout Request Signed checkbox that is present in the Advanced Properties SAML Advanced Settings pane in the Security Configuration section.
    FortiSOAR™ UI - Security Configuration section
  6. Add the default user attribute mapping for Okta in FortiSOAR by updating the User Attribute Map as shown in the following image:
    Default user attribute mapping for Okta in FortiSOAR™
    Note: The IdP keys, the keys on the right side, are obtained from the ATTRIBUTE STATEMENTS (OPTIONAL) section in Okta, as specified in step 3. You can change the default user attribute mapping later if required.
  7. Click Save to complete the SSO configuration in FortiSOAR.
  8. Create a new user in Okta. Log on to Okta as an administrator and navigate Directory > People > Add Person and enter all the user details.
    Okta - Add User
    Once the user is created and activated successfully, you can assign this user to the SAML application that you have created. Click on a user to get the user details, and then assign the user to an application using the Assign Applications dialog as shown in the following image:
    Okta - Assign Application to user
Configuring SAML in Google
  1. Ensure that you have Administrator access for your G Suite account and log on to G Suite using the admin account.
  2. Configure IdP.
    • On your Admin console, click Apps.
      GSuites Admin Console
    • Click SAML apps. On the SAML page, click + on the right bottom corner, to add a new SAML Application.
      SAML page - New SAML Application
    • On the Enable SSO for SAML Application page, click SETUP MY OWN CUSTOM APP.
      Enable SSO for SAML Application page
    • Click Next to display the Google IdP information. Save the Google IdP information and download the Certificate.
      You will require the IdP information for Google to configure SSO within FortiSOAR.
      Google IdP information
    • Click Next and add basic information about the App, such as Name and Description and then click Next.
    • On the Service Provider Details page, enter the Entity ID and ACS URL from the Service Provider section in FortiSOAR. Log on to FortiSOAR and navigate to Settings > Authentication > SSO Configuration, go to the Service Provider section to get the details. See Configuring SAML in FortiSOAR.
      Service Provider Details page
    • Click Next and add more attribute mapping as required.
      Attribute Mapping page
    • Save the app configuration and click Exit.
    • Set up user access for the Google SAML App, see Set up your own custom SAML application.
  3. Add the SSO details saved in step 2 in FortiSOAR. To add the SSO details, log on to FortiSOAR, click Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, enter the Google IdP details and certificate as shown in the following image:
    Gmail - Configuring IdP details in FortiSOAR™
    Note: Google SAML app does not provide a Logout URL. Therefore, users remain logged into their Google account even if they log off from FortiSOAR.
    In FortiSOAR the Single Logout Request URL field is optional and can be left blank.
  4. Add the default user attribute mapping for Google in FortiSOAR by updating the User Attribute Map, based on what you have set in the attribute mapping in the Google SAML app, as shown in the following image:
    Default user attribute mapping for Google in FortiSOAR™
  5. Click Save in FortiSOAR to save the changes to the IdP configuration.
Configuring SAML in Azure Active Directory
  1. Open the Azure Active Directory (Azure AD) portal: https://aad.portal.azure.com/.
  2. From the left menu, click Enterprise Applications.
    Azure AD - Enterprise Applications menu
  3. On the Enterprise Applications page, click New Application.
    Add Enterprise Applications in Azure AD
  4. Click Create Your Own Application.
  5. Enter FortiSOAR in the Name field and and click Integrate any other application you don't find in the gallery (Non-gallery), and then click Create.
  6. Follow the steps mentioned in the Getting Started section such as adding users/groups, creating custom roles for SAML Role mapping, etc.
    Creating the FortiSOAR application in Azure AD
  7. Click Single sign-on, and then SAML.
    Creating FortiSOAR SSO in Azure AD
  8. Create a unique Identifier (Entity ID) in Azure AD.
    Creating a unique FortiSOAR ID in Azure AD
  9. Modify user attributes in Azure AD as shown in the following image:

    Modifying user attributes in Azure ADImportant: For the Azure AD attributes and claims, it's recommended that you delete the namespace section for each attribute, else it generates a URL. The following image is an example of the Email attribute whose namespace is blank:
    Azuare AD - Manage Claim dialog
  10. In FortiSOAR, navigate to Settings > Authentication > SSO Configuration, and then enter the IdP details in the Identity Provider Configuration section as shown in the following image:
    Details of the IdP Configuration section in FortiSOAR
    Enter the details such as the Entity ID, Single Sign On URL, Single Logout Request URL, etc as set up in Azure AD.
    In the X509 Certificate field, paste the text that you copied from the downloaded Azure AD certificate.
  11. Add the user attribute mapping for Azure AD in FortiSOAR by updating the User Attribute Map as shown in the following image:
    Mapping user attributes in FortiSOAR
  12. In the Team and Role Mapping section map the teams and roles of SSO users to the teams and roles created in Azure AD IdP:
    1. To create roles in Azure AD, open the Azure Active Directory (Azure AD) portal.
    2. From the left menu, click Azure Active Directory and then click App registrations. In the All applications section, search for the name of your FortiSOAR application:
      Application Registrations page on Azure AD
    3. Click App Roles and then click Create app role. for example, create the FSR_T2 Analyst in Azure AD, as shown in the following image:
      Creating an new app role in Azure AD
      Then enter the values in the Create app role dialog, and click Apply.
      Adding values for the FSR_T2 role in Azure AD
      This creates the FSR_T2 Analyst role in Azure AD. You need to perform this step for each role that you want to map in FortiSOAR.
    4. Log on to FortiSOAR and on the SSO Configuration page, and map the roles that you have created in Azure AD to FortiSOAR roles. For example, FSR_T2 Analyst role can be mapped to the T2 Analyst role in FortiSOAR:
      Update Role Mapping in FortiSOAR for the FSR_T2 role created in Azure AD
  13. The Service Provider details are auto-populated, as shown in the following image:
    Service Provider configuration section
    Note: These settings can be kept as is and only need to be updated for DNS name change if you want to keep a different DNS name for FortiSOAR than the one set in FortiSOAR (as hostname).
  14. Click Save in FortiSOAR to save the changes to the IdP configuration.
Configuring SAML in ADFS
Note

If you change the hostname for your FortiSOAR system, you will require to delete the old ADFS configuration and re-configure ADFS.

General ADFS Setup

This procedure uses ADFS 3.0 and uses samlportal.example.com as the ADFS website. The values you use in your setup will be based on your ADFS website address. See ADFS integration with SAML 2.0 for more information.

  1. Log on to the ADFS server and open the management console.
  2. Right-click Service and click Edit Federation Service Properties.
    ADFS configuration: Edit Federation Service Properties option
  3. On the Federation Service Properties dialog, in the General Settings tab, confirm that the DNS entries and certificate names are correct. Note the Federation Service Identifier, since you will use as the Entity ID in the Identity Provider Configuration in the FortiSOAR UI.
    ADFS configuration: Federation Service Properties dialog
  4. In the Services panel, browse to Certificates and export the Token-Signing certificate using the following steps.
    1. Right-click the certificate and select View Certificate.
    2. Select the Details tab and click Copy to File, which opens the Certificate Export wizard.
    3. On the Certificate Export Wizard, click Next.
    4. Select Base-64 encoded binary X.509 (.cer), and then click Next.
    5. Select where you want to save the Token-Signing certificate and provide a name to the certificate, and then click Next.
    6. Click Finish.
    7. Copy the contents of the Token-Signing certificate and paste the contents in the X509 Certificate area in the Identity Provider Configuration in the FortiSOAR UI.
Configuring ADFS Relying Party Trust
  1. Log on to FortiSOAR as an administrator.
  2. Click Settings > Authentication > SSO Configuration and download the SAML metadata file by clicking Download in the Service Provider Configuration section.
  3. Log on to the ADFS server and open the ADFS management console.
    ADFS Management Console
  4. Expand Trust Relationships and right-click Relying Party Trust and select Add.
  5. On the Add Relying Party Trust Wizard click Start.
  6. In the Select Data Source panel, select the Import data about the relying party from a file option and click Browse to navigate to the SAML metadata file that you have saved in Step 2 and then click Next.
    ADFS configuration: Add Relying Party Trust Wizard
  7. In the Specify Display Name panel set the display name and then click Next.
  8. (Optional) In the Configure Multi-factor Authentication Now? panel configure MFA and then click Next.
  9. In the Choose Issuance Authorization Rules panel, select the Permit all users to access this relying party option and then click Next.
  10. In the Ready to Add Trust panel, click Next.
  11. In the Finish panel, ensure that the Open the Edit Claim Rules dialog statement is selected and then click Close. This opens the Edit Claim Rules Wizard in which you can immediately add and configure rules as mentioned in the next section, or if you have closed Edit Claims Rules then use the steps mentioned in the next section to open Edit Claim Rules and add and configure rules.
Configuring ADFS Relying Party Claim Rules

You must edit the claim rules to enable communication with FortiSOAR SAML

  1. Log on to the ADFS server and open the management console.
  2. Right-click the relying party trust (as configured in the previous section) and select Edit Claim Rules.
  3. Click the Issuance Transform Rules tab and select Add Rules.
  4. Select Send LDAP Attribute as Claims as the claim rule template to use and then click Next.
  5. On the Configure Claim Rule dialog, in Claim rule name, enter a name to the claim rule. For example, name the claim rule as Get LDAP Attributes.
  6. From the Attribute store drop-down list, select Active Directory.
  7. In the Mapping of LDAP attributes to outgoing claim types section, map the following values:
    1. Select SAM-Account-Name from the LDAP Attribute column and map that to E-Mail Address in the Outgoing Claim Type column.
    2. Select E-Mail-Addresses from the LDAP Attribute column and map that to Email in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column.
    3. Select Surname from the LDAP Attribute column and map that to Last Name in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column.
    4. Select Given-Name from the LDAP Attribute column and map that to First Name in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column and the values that you specify in the Outgoing Claim Type column must match the what you enter in the right-side field in the User Attribute Map in the Identity Provider Configuration in the FortiSOAR UI.
    5. Select Token-Groups - Unqualified Names from the LDAP Attribute column and map that to Roles in the Outgoing Claim Type column.
      Note: You must manually type the values in the Outgoing Claim Type column.
      ADFS configuration: Edit Rule - Get LDAP Values
  8. Click Finish and select Add Rules.
  9. Select Transform an Incoming Claim as the claim rule template to use and then click Next.
  10. On the Add Transform Claim Rule Wizard, in Claim rule name, enter a name to the claim rule. For example, name the claim rule as Email to Name ID.
  11. From the Incoming claim type drop-down list, select E-Mail Address, from the Outgoing claim type drop-down list, select Name ID and select the Pass through all claim values option and click Finish and then click OK.
    ADFS configuration: Add Transform Claim Rule Wizard
Configuring FortiSOAR for ADFS
  1. Log on to FortiSOAR as an administrator.
  2. Click Settings > Authentication > SSO Configuration.
  3. To enable SAML for FortiSOAR, click the SAML Enabled check box.
  4. In the Identity Provider Configuration section, enter the IdP details.
    Enter the Entity ID as the one that you had noted in Step 3 of the General ADFS Setup procedure. For example, https://samlportal.example.com/adfs/services/trust
    Enter the Single Sign On URL as <server_address>/adfs/ls. For example, https://samlportal.example.com/adfs/ls
    Enter the Single Logout Request URL as <server_address>/adfs/ls?wa=wsignout1.0. For example, https://samlportal.example.com/adfs/ls?wa=wsignout1.0
    In the X509 Certificate area, paste the contents of the certificate you exported in Step 8 of the General ADFS Setup procedure. Following is an image of sample inputs in the FortiSOAR UI:
    Identity Provider Configuration Section: ADFS Configuration
  5. Map the user attributes received from the ADFS (IdP) with the corresponding attributes of FortiSOAR.
    Use the User Attribute Map to map the attributes received from the ADFS with the corresponding attributes required by FortiSOAR. FortiSOAR requires the firstname, lastname and email attributes to be mapped. The ADFS attributes that you need to map are the names that you specify as values in the Outgoing Claim Type column in the management console of ADFS. For more information, see Configuring ADFS Relying Party Claim Rules.
    In the User Attribute Map, under Fields, click the editable field name (right side field name), to map it to the attribute that will be received from the IdP. The non-editable field name (left-side field name) is the FortiSOAR attribute. For example, in the following image, you map the FortiSOAR attribute firstName to the IdP attribute First Name.
    User Attribute Map
    If you want to set any of the optional configurations, see Configuring SAML in FortiSOAR.
  6. Click Save to complete the SAML configuration in FortiSOAR.
Support for mapping roles and teams of SSO users in FortiSOAR

You can map the role and team of SSO users in FortiSOAR based on their roles defined in the IdP. Thereby you can set the role of an SSO user in FortiSOAR based on the role you have defined in your IdP.

To achieve this FortiSOAR has added a new configuration in the SSO Configuration page where you can map the role that you have specified in the IdP to a FortiSOAR role and team. The relationship between the IdP role and the FortiSOAR role is one to many, i.e., one IdP role can map to multiple FortiSOAR roles.

SAML supports attribute-based authorization. Therefore, you should configure attribute roles in your IdP that will contain roles of your SSO users on the IdP.

If you have not set up mapped roles of SSO users in FortiSOAR, or if FortiSOAR receives a response from the IdP that does not contain any roles, or receives a response that does not map to any of the FortiSOAR roles, then the SSO user will be assigned the default roles.

Configuring IdPs to send the SSO user role information to FortiSOAR

The following sections define how you can configure IdPs, i.e., OneLogin, Okta, or Auth0 to send the SSO user role information to FortiSOAR when the user is logging on to FortiSOAR (SSO login).

For mapping of roles in ADFS, see the Configuring ADFS Relying Party Claim Rules section.

For any other IdP, configure roles as per the IdP requirements and contact the IdP support personnel if you face any issues.

OneLogin

  1. Log on to OneLogin as an administrator.
  2. Navigate to the SAML app that you have created by clicking APPS in the administration panel. Open the SAML app and in the App Configuration screen, go to the Parameters section and click Add Field, which displays the New Field dialog.
  3. In the New Field dialog, in the Field name type Roles, ensure that you check Include in SAML assertion checkbox in the Flags section, and then click Save.
    OneLogin SAML application: New Field Dialog
  4. In the next dialog, i.e., the Edit Field Roles dialog, from the Value drop-down list, select User Roles and click Save.
    OneLogin SAML application: Edit Field Dialog

Okta

  1. Log on to Okta as an administrator.
  2. Navigate to the SAML app that you have created and edit the SAML settings.
  3. In the GROUP ATTRIBUTE STATEMENTS (OPTIONAL) section set the following:
    Name: Set as Roles.
    Filter: Set as Matches regex*.*
    Okta application: SAML Settings
  4. Click Next and complete the setup.

Auth0

  1. Log on to Auth0 as an administrator and in the left menu click Authorization.
  2. On the Authorization Extension page, create a new group and associate required members (users) and roles with this group.
    Auth0: Authorization Extension page with the details of the new group
  3. Navigate back to the main menu (Dashboards page) and click Applications.
  4. Create a new application, or click on the Settings icon of the application whose settings you want to edit:
    Auth0: Editing the settings of an application
    This opens the Setting page for the application:
    Auth0: Settings Page of an Application
  5. Click the Addons tab and click SAML2 and enter the required details on the Settings tab for the application you have created:
    Auth0: Addons SAML2 Web App
  6. Click Save to save the settings of the application.

Troubleshooting SAML issues

Unable to login to FortiSOAR when ADFS SAML is configured

If you are unable to login to FortiSOAR when ADFS SAML is configured and the default certificates are failing, and if you find the "The revocation function was unable to check revocation for the certificate." error in the ADFS logs, then you must turn off the certificate revocation check using the following steps:

  1. Enter Powershell in the "Administrator" mode of the ADFS system.
  2. Run the following commands: (RelyingPartyTrustName should be in double quotes):
    Set-AdfsRelyingPartyTrust -TargetName "<RelyingPartyTrustName>" -SigningCertificateRevocationCheck None
    Set-AdfsRelyingPartyTrust -TargetName "<RelyingPartyTrustName>" -EncryptionCertificateRevocationCheck None
    This turns off the certificate revocation check and now you should be able to login to FortiSOAR.
SAML users face issues while trying to login to FortiSOAR when the certificate gets expired or replaced on ADFS IDP

When the certificate gets expired or replaced on ADFS IDP, then the SAML users get the following errors which trying to log into FortiSOAR:

Fri Oct 22 06:46:26 AST 2021
			There was an unexpected error (type=Internal Server Error, status=500).
			Processing samlservice sso response failed with error: Signature validation failed. SAML Response rejected

			[root@lincon ~]# tail /var/log/cyops/cyops-gateway/saml.log
			22-10-2021 05:09:38.351 [http-nio-8080-exec-110] ERROR c.onelogin.saml2.authn.SamlResponse.isValid - Signature validation failed. SAML Response rejected
			22-10-2021 05:16:34.567 [http-nio-8080-exec-114] ERROR c.onelogin.saml2.authn.SamlResponse.isValid - Signature validation failed. SAML Response rejected
		

Resolution

To resolve this issue, get the newly deployed certificate and log in to FortiSOAR. Navigate to Settings > Authentication > SSO Configuration. In the Identity Provider Configuration section, replace the contents of the x509 Certificate field with the contents of the new certificate.

Configuring FortiSOAR authentication with a RADIUS server

From release 7.2.0 onwards, FortiSOAR enables you to authenticate users using a RADIUS server, i.e., users can enter their RADIUS credentials to log into FortiSOAR.

Use the Authentication menu to setup, modify, and turn on or off authentication with a RADIUS server.

Note

To create or update a RADIUS configuration, administrators must have 'Security Update' permissions.

Click Settings > Authentication to open the Account Configuration page. Click the RADIUS Configuration tab and click the RADIUS Enabled checkbox, if you want to authenticate users using a RADIUS server.

Security Management - Radius Configuration

Once you click the RADIUS Enabled checkbox, configure your primary and optionally a secondary RADIUS server as follows:

  1. In the Primary Server Configuration section, enter the following details for your primary RADIUS server:
    1. In the Host field, enter the IP address of the primary RADIUS server that you will use to authenticate users.
    2. In the Port field, enter the port number where the primary RADIUS server listens for authentication requests. Defaults to 1812.
    3. In the Shared Secret field, enter the secret code that is known to only the client (FortiSOAR in this case) and the primary server.
      To check the RADIUS configuration of the primary server, click the Test Connectivity button. Clicking Test Connectivity opens the Enter Test Credentials dialog in which you can enter the username and password used to connect to the primary server. If the connection succeeds, then a success message gets displayed, and if the connection fails, then an appropriate error message gets displayed.
  2. In the Secondary Server Configuration section, enter the following details for your secondary RADIUS server:
    1. In the Host field, enter the IP address of the secondary RADIUS server that you will use to authenticate users.
    2. In the Port field, enter the port number where the secondary RADIUS server listens for authentication requests. Defaults to 1812.
    3. In the Shared Secret field, enter the secret code that is known to only the client (FortiSOAR in this case) and the secondary server.
      To check the RADIUS configuration of the secondary server, click the Test Connectivity button. Clicking Test Connectivity opens the Enter Test Credentials dialog in which you can enter the username and password used to connect to the secondary server. If the connection succeeds, then a success message gets displayed, and if the connection fails, then an appropriate error message gets displayed.
  3. To save the configurations for your primary and secondary RADIUS servers, click Save.

You can use the Export and Import Wizards to export and import your Radius configurations across instances. For more information on export and import wizards, see the 'Export and Import Wizards' topic in the Application Editor chapter.

Importing RADIUS users in bulk

You can import RADIUS users in bulk into your FortiSOAR system. To import users, you must enable RADIUS authentication on the RADIUS Configuration page (Settings > Authentication > RADIUS Configuration). Once you have enabled RADIUS authentication, do the following to import users:

  1. From the left menu, click Users, and on the Users page, click the Import Users button.
    Note: The Import Users button will be visible only if RADIUS or SSO is enabled.
  2. In the Import Users dialog, do the following:
    1. From the User Type To Import drop-down list, select RADIUS User.
    2. Click the Download CSV File Sample link to download the sample CSV file (RADIUS User_Template.csv).
      Import User dialog
      The sample CSV file contains an example of the user details you need to provide. You need to provide the following user details in the CSV file:
      • username: Name of the RADIUS user.
      • email: Email address of the RADIUS user
      • firstname: (Optional) First name of the RADIUS user.
      • lastname: (Optional) Last name of the RADIUS user.
      • phonemobile: (Optional) Mobile number of the RADIUS user.
      • roles: (Optional) Role (s) that you want to assign to the RADIUS user. To assign a role to the user you need to provide the UUID of that role. To get the UUID of a role, click Settings > Security Management > Roles, and then click the role that you want to assign to the user. For example, click T1 Analyst, which opens the Edit Role page, and then from the address bar, copy the UUID (as shown in the following image) and paste it in the roles column in the CSV file.
        Copying UUID of Roles
        Note: You can assign multiple roles to the user by using the pipe symbol (|) to separate the UUID of each role.
      • teams: (Optional) Team (s) that you want to assign to the RADIUS user. To assign a team to the user you need to provide the UUID of that team. To get the UUID of a team, click Settings > Security Management > Teams, and then click the team that you want to assign to the user, and then from the address bar copy the UUID of the team, similar to the process described for roles.
        Note: You can assign multiple teams to the user by using the pipe symbol (|) to separate the UUID of each team.

      • accessType: Access type (Named or Concurrent) that you want to assign to the RADIUS user. If you do not specify any access type for the user, then the user will be assigned as a 'Concurrent' user.

  3. Once you complete filling the user details in the CSV file, click the Import User button, and in the Import Users dialog, drag and drop the CSV file or click the import icon to import the CSV file, and then click the Import Users button.
    If there are no issues in the import, then all the RADIUS users get created and they can log into FortiSOAR.
    If there are any issues in the CSV file, such as not providing all the information required to create RADIUS users, then such users are not created. To get information about the users not created, download the status report.
    Importing RADIUS users using the CSV file

Configuring the Password Vault Manager

FortiSOAR integrates 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 have 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. FortiSOAR has integrated with Thycotic Secret Server and CyberArk, and therefore we have a Thycotic Secret Server and CyberArk connectors in the Content Hub.

To use a vault in FortiSOAR, you must first install the connector from the Content Hub. 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 a 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 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 integrated 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.

Delete Users

Apart from the above functions that an administrator can perform on the FortiSOAR UI, administrators can also delete users using a script.

Caution

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 userId of the user(s) that you want to delete in the usersToDelete.txt file, which is located at /opt/cyops/scripts/. The UserID of the users are displayed in the User Id column on the Users page in the FortiSOAR UI as shown in the following image:
    Users page in FortiSOAR UI
    To copy the UserID, right-click the 'User Id' cell and from the context menu, select the Copy Cell Value To Clipboard option.
    The usersToDelete.txt file is an empty text file in which you can enter the ID of users.
  2. SSH to your FortiSOAR VM and login as a root user.
  3. Run the following command: # /opt/cyops/scripts/userDelete
    Important: The User Delete script deletes users in the local database and does not work for externalized databases.