Identity Provider [IdP] Integration - SSO [X-Ray]

Note

This page includes:

About integrating FortiMail Workspace Security with an identity provider

You can integrate FortiMail Workspace Security with an external identity provider - such as Microsoft Entra ID, Microsoft Azure AD, Okta, or JumpCloud - to provide SSO [single sign-on] functionality. This integration:

  • Lets admin-users sign-in to FortiMail Workspace Security using their corporate credentials.

  • Uses SAML (Security Assertion Markup Language) to allow identity providers to pass authorization credentials to FortiMail Workspace Security.

Note

  • For each organization, you can configure only a single external identity provider for managing the FortiMail Workspace Security admin-user credentials.

  • The external identity provider must support SAML 2.0.

  • FortiMail Workspace Security supports Single Sign-On (SSO) for standard admin-users via Google Workspace and Microsoft 365 authentication. [This SSO functionality is not available to organizations that are registered with FortiCloud.] For details, see SSO using Google Workspace or Microsoft 365.

  • For details on how to integrate FortiMail Browser Security with an identity provider, see Identity Provider [IdP] Integration - SSO [FortiMail Browser Security].

Types of admin-users

There are two types of admin-users:

  • Standard: Admin users that are added via an invitation from FortiMail Workspace Security.

  • SAML: Admin users that are added by FortiMail Workspace Security when the admin-user first signs-in to FortiMail Workspace Security using the SSO integration.

To see a list of admin-users and the type of each user, go to the Settings > Admin Users page - and look for the Connection Type [Standard or SAML].

Note: You can simultaneously use standard [auth0] and SAML for authorization in your organization. This enables you to initially assign only a single admin user for SAML authorization - while maintaining standard authorization for all other admin users. This in turn, enables you to test that the SAML integration is working as expected, specifically for a single admin user, before rolling-out the SAML integration to all admin users in the organization.

Propagating SSO [IdP] settings

SSO configurations that are set in a parent organization are NOT applied [propagated] to the child organizations. Access to child organizations will not be affected by configuring SSO in the parent organization. If required, SSO must be configured separately for each child organization.

Configuring an IdP integration

Note

The instructions below apply to all identity providers - and not just to one specific provider. The instructions therefore include various non-specific [generic] options and terminology.

To configure an IdP integration, perform the following steps:

Step 1: Generating the SSO parameters

  1. In FortiMail Workspace Security, in the left navigation menu, select Settings > Account.

  2. Scroll down to the SAML Integration section.

  3. Click Configure to edit the settings.

    The SAML Integration Configuration pane will open.

  4. In Connection name, enter a name for the configuration. The name that you enter is currently not used by the system.

  5. From the "Default assigned system role" list, select the admin-role that will be assigned to new admin-users [See Types of admin-users] unless various roles are assigned [see Step 4: Assigning admin-user roles to new admin-users below].

  6. Click Generate SAML metadata.

    FortiMail Workspace Security will display values for the following parameters:

    1. Entity ID

    2. ACS URL

      You'll need to enter these parameters in Step 2 below.

Step 2: Configuring your identity provider

  1. In your identity provider, create a new, simple SAML app.

  2. In your identity provider, for the new app, enter the two parameters that were displayed in Step 1 above - Entity ID and ACS URL.

    Note: You can click the Copy to Clipboard icon [] on the right of each parameter to copy the required values to the clipboard. Hover over the parameter to display the Copy to Clipboard icon [].

    Your identity provider will generate an .xml file that contains the metadata that is required in Step 3 below.

Step 3: Configuring the metadata source

After you have created and configured the simple SAML app, you'll need to provide some metadata about your new SAML app to FortiMail Workspace Security. The required information is contained in the metadata .xml file that is generated by your identity provider.

  1. In the SAML Integration Configuration pane that opened in Step 2, under "Identity provider metadata source" - select either:

    1. File: and then drag the generated .xml file, or locate and upload the file

      - or -

    2. URL: and specify the URL where the generated .xml file is located.

Step 4: Assigning admin-user roles to new admin-users

Note: This step is optional.

In Step 1 above, you configured the default admin-user role that is assigned to admin users.

However, you can configure FortiMail Workspace Security so that when a new admin-user is added to FortiMail Workspace Security via the IdP integration, the new admin-user will be automatically assigned a specified admin-user role - and not necessarily the default role. The admin-user role that is assigned is based on a specified attribute of the user. For example, you could assign the Viewer user role to new users from the "Sales" group, and the Controller user role to new users from the "IT" group. For details on the available admin-user roles, see About admin-user roles.

To enable this automatic assignment of admin-user roles to occur, in your SAML app you'll need to create a new attribute for each user role. Then perform the following:

  1. In the SAML Integration Configuration pane that opened in Step 2, under "Role Mapping", click "Add mapping rule".

  2. Enter the following information for each attribute value:

    1. Attribute name [Group name]

    2. Attribute value [Object ID]

    3. User role in FortiMail Workspace Security

  3. Perform the above 2 steps until you have added all the required mapping rules.

  4. Click Save to save the configuration.

Note: The "user-role assigning functionality" described above affects new admin-users only - it doesn't affect existing admin-users. To change the role of an existing admin-user, see Changing the role assigned to an admin-user.

Step 5: Validating the SAML integration

Note: You can simultaneously use standard [auth0] and SAML for authorization in your organization. This enables you to initially assign only a single admin user for SAML authorization - while maintaining standard authorization for all other admin users. This in turn, enables you to test that the SAML integration is working as expected, specifically for a single admin user, before rolling-out the SAML integration to all admin users in the organization.

After you have saved the integration configuration, you'll need to test the integration. This will perform a "handshake validation" - thereby enabling the SSO functionality for your users.

If your IdP provides a "Test" button

[For example, Microsoft Entra ID]
 

  1. In your IdP, locate and then click the "Test" button for your new SSO configuration.

  2. After the test succeeds, users will be able to use the following URL to access FortiMail Workspace Security:

    https://xray.perception-point.io/

    Important: Admin users should click "Continue with SAML" to access FortiMail Workspace Security using the new SSO functionality.

If your IdP doesn't have a "Test" button

[For example, Okta or Google Workspace]
 

Perform a manual validation by opening the following URL in an Incognito window and then attempting to log in via your SSO account.

https://xray.perception-point.io/

After the test succeeds, admin users will be able to use the URL above to access FortiMail Workspace Security.

Important: Admin users should click "Continue with SAML" to access FortiMail Workspace Security using the new SSO functionality.

SAML integration status

The SAML configuration can have any of the following statuses:

Not configured

Step 1 above has not yet been completed.

Pending IdP metadata upload

Step 1 above has been completed.

Active

The integration is now active.

Forcing SAML sign-in

It is possible to configure FortiMail Workspace Security so that all admin-users will be forced to use SAML to sign-in to FortiMail Workspace Security. The standard [non-SAML] sign-in procedures won't be available, and non-SAML admin-users won't be able to sign-in to FortiMail Workspace Security.

To force SAML sign-in to FortiMail Workspace Security, you'll need to create a group of admin-users in your identity provider, and give these users the ability to access FortiMail Workspace Security. FortiMail Workspace Security Support will then need to enable forced-SAML-sign-in for your organization.

For implementation details and assistance, contact FortiMail Workspace Security Support [support@perception-point.io].

Note

If your organization is configured to force users to sign-in to FortiMail Workspace Security using SAML, then it is not possible to add [invite] new admin-users via FortiMail Workspace Security. [The Add User button won't appear - see Adding or inviting new standard admin-users.] Instead, a new admin-user needs to sign-in to FortiMail Workspace Security using the "Continue with SAML" option, or via the SAML app. The first time a new admin-user successfully signs-in to FortiMail Workspace Security, a corresponding new admin-user will be created in FortiMail Workspace Security.

Creating admin-users after SAML integration

After setting up SAML integration for SSO, new admin-users are automatically created in FortiMail Workspace Security when the admin-users first sign-in to FortiMail Workspace Security. Each new admin-user will have the "SAML" connection type - that is visible in the Settings > Admin Users page.

  • If SAML sign-in is forced in your organization, it will not be possible to add new admin-users via the FortiMail Workspace Security interface.

  • If SAML sign-in is not forced in your organization, it will still be possible [if necessary] to add new admin-users via the FortiMail Workspace Security interface. Each new admin-user that is created in this manner will have the "Standard" connection type - that is visible in the Settings > Admin Users page.

Deleting duplicate admin-users

After setting up SAML integration for SSO, new admin-users are automatically created in FortiMail Workspace Security when the admin-user first signs-in to FortiMail Workspace Security. Each new admin-user will have the "SAML" connection type - that is visible in the Settings > Admin Users page.

If the admin-user existed in FortiMail Workspace Security before SAML integration was set-up, then there will be duplicate entries for the admin-user:

  • The new entry will have the "SAML" connection type

  • The old entry will have the "Standard" connection type

It is recommended that you delete the old "Standard" connection type admin-user.

Updating or renewing a SAML/SSO certificate

When a SAML/SSO certificate needs to be updated, you'll need to use your identity provider to first generate a new certificate, and then regenerate [renew] the .xml metadata file that contains the new certificate. Then perform the procedure below:

To update a certificate:

  1. In FortiMail Workspace Security, in the left navigation menu, select Settings > Account.

  2. Scroll down to the SAML Integration section.

  3. Click Configure to edit the settings.

    The SAML Integration Configuration pane will open.

  4. Under "Identity provider metadata source" - select either:

    1. File: and then drag the newly generated .xml file, or locate and upload the file

      - or -

    2. URL: and specify the URL where the newly generated .xml file is located.

    3. Click Save.

See also: