Fortinet black logo

Version:

Version:

Version:

Version:

Version:


Table of Contents

Administration Guide

SAML Configuration

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 Use Single Sign On (SSO) link. Users can then log on to FortiSOAR using the Use Single Sign On (SSO) link that is present on the FortiSOAR login page.

FortiSOAR™ login page with Single Sign-On

Once the user clicks the Use Single Sign On (SSO) link, 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.

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 five IdPs, namely, OneLogin, Auth0, Okta, Google, Active Directory Federation Services (ADFS) which are the five 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.
    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. 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
    You can also go to the change the view to Code view and change the mapping:
    User Attribute Map - Code View
  6. 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.
  7. 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.
  8. (Optional) Configure advanced settings for SAML.
    Prior to version 7.0.0, users 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
  9. Click Save to complete the SAML configuration in FortiSOAR.

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

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 Use Single Sign On (SSO) link. Users can then log on to FortiSOAR using the Use Single Sign On (SSO) link that is present on the FortiSOAR login page.

FortiSOAR™ login page with Single Sign-On

Once the user clicks the Use Single Sign On (SSO) link, 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.

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 five IdPs, namely, OneLogin, Auth0, Okta, Google, Active Directory Federation Services (ADFS) which are the five 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.
    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. 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
    You can also go to the change the view to Code view and change the mapping:
    User Attribute Map - Code View
  6. 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.
  7. 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.
  8. (Optional) Configure advanced settings for SAML.
    Prior to version 7.0.0, users 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
  9. Click Save to complete the SAML configuration in FortiSOAR.

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