diff --git a/website/integrations/security/fortimail/index.mdx b/website/integrations/security/fortimail/index.mdx index 4efe22e7ec..5f12a910f8 100644 --- a/website/integrations/security/fortimail/index.mdx +++ b/website/integrations/security/fortimail/index.mdx @@ -19,22 +19,26 @@ import TabItem from "@theme/TabItem"; The following placeholders are used in this guide: - `authentik.company` is the FQDN of the authentik installation. -- `fortimailadmin.company` is the FQDN (or IP) of your FortiMail admin interface. -- `fortimailuser.company` is the WAN-facing FQDN of your FortiMail user/webmail portal. +- `fortimailadmin.company` is the FQDN or IP address of your FortiMail admin interface. +- `fortimailuser.company` is the FQDN or IP address of your FortiMail user/webmail portal. :::info -This documentation lists only the settings that you need to change from their default values. Changing settings not mentioned in this guide can prevent single sign-on from working correctly. +This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. ::: -:::info -FortiMail 7.6.4 and later allows you to configure separate service providers for the admin and user/webmail portals. If you plan to use the user/webmail portal, avoid importing FortiMail’s auto-generated metadata directly, as you will need to edit the ACS URL in that XML to replace the host with your user-facing FQDN. +:::info FortiMail Cloud +FortiMail Cloud supports SSO for webmail users. The Admin Portal SSO steps apply to FortiMail Appliance and VM. +::: + +:::info Webmail limitations +When SSO is enabled for FortiMail webmail users, CalDAV and WebDAV authentication do not use SSO and continue to require local password authentication. If your FortiMail system is deployed in server mode, configure an LDAP profile for the domain users before enabling webmail SSO. ::: ## authentik configuration -To support the integration of the FortiMail with authentik, you need to create an application/provider pair in authentik. +To support the integration of FortiMail with authentik, you need to create an application/provider pair in authentik. -You can configure either Admin Portal SSO or User Portal SSO (or both), depending on the intended user and the desired scope of authentication. +You can configure either Admin Portal SSO or User Portal SSO, or both, depending on the intended users and the desired scope of authentication. 1. Log in to authentik as an administrator and open the authentik Admin interface. -2. Navigate to **Applications** > **Applications** and click **New Application** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) - - **Application**: provide a descriptive name (e.g. `FortiMail Admin`), an optional group for the type of application, the policy engine mode, and optional UI settings. Take note of the **slug** as it will be required later. +2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard. + - **Application**: provide a descriptive name (for example, `FortiMail Admin`), an optional group for the type of application, the policy engine mode, and optional UI settings. Take note of the **slug** value because it will be required later. - **Choose a Provider type**: select **SAML Provider** as the provider type. - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - - Set the **ACS URL** to `https://fortimailadmin.company/sso/SAML2/POST`. - - Set the **Audience** to `https://fortimailadmin.company/sp`. - - Under **Advanced protocol settings**: - - Select any available certificate as the **Signing Certificate** and enable **Sign Assertions**. - - Ensure that `authentik default SAML Mapping: Username` is selected as a **Selected User Property Mappings**; other mappings are optional and can be removed if not needed. - - **Configure Bindings** _(optional)_: create a [binding](/docs/add-secure-apps/bindings-overview/) (policy, group, or user) to control which administrators see the FortiMail Admin application on the **Application Dashboard** page. - -3. Click **Submit** to save the application and provider. + - Temporarily set the **ACS URL** to `https://temp.temp`. + - Temporarily set the **Audience** to `https://temp.temp`. + - Under **Advanced protocol settings**, select any available certificate as the **Signing Certificate**. + - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (policy, group, or user) to manage the listing and access to applications on a user's **Application Dashboard** page. +3. Click **Create Application** to save the new application and provider. ### Download metadata file 1. Log in to authentik as an administrator and open the authentik Admin interface. -2. Navigate to **Applications** > **Providers** and click on the name of the provider that you created in the previous section (e.g. `Provider for FortiMail Admin`). -3. Under **Related objects** > **Metadata**, click on **Download**. This downloaded file is your metadata file and it will be required in the next section. +2. Navigate to **Applications** > **Providers** and click the name of the provider that you created in the previous section (for example, `Provider for FortiMail Admin`). +3. Under **Related objects** > **Metadata**, click **Download**. This file is required in the next section. ## FortiMail configuration 1. Sign in to the FortiMail admin interface. -2. Navigate to **System** > **Single Sign On** and select the **Setting** tab. -3. Enable **Single sign-on** and note the values that FortiMail displays (the ACS field is read-only): +2. Navigate to **System** > **Single Sign On** and open the **Profile** tab. +3. Create a new SSO profile and configure the following settings: + - **Profile name**: enter a descriptive name (for example, `authentik-admin`). + - **Metadata**: upload the authentik metadata file that you downloaded in the previous section. + - **Attribute used to identify email address**: `http://schemas.goauthentik.io/2021/02/saml/username` +4. Click **Create** or **OK** to save the SSO profile. +5. Open the **Setting** tab and enable **Single sign-on**. +6. If FortiMail displays **Use different service provider for admin and webmail access**, select **Admin** as the service provider metadata target. +7. In the **Service Provider Metadata** section, configure the following values: - **Entity ID**: `https://fortimailadmin.company/sp` - - **Assertion consumer service (ACS) URL**: `https://fortimailadmin.company/sso/SAML2/POST` + - **Host name**: `fortimailadmin.company` +8. Click **Apply**. +9. Copy the following FortiMail service provider values: + - **Entity ID** + - **ACS URL** -Ensure that these values match those configured in authentik. If not, update the values in authentik and re-download the [authentik metadata file](#download-metadata-file). +### Reconfigure the authentik provider -4. Upload the authentik SAML metadata file that you downloaded in the previous step. -5. Switch to the **Profile** tab and configure the attribute mapping: - - Set **Attribute used to identify email address** to `http://schemas.goauthentik.io/2021/02/saml/username`. +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers** and click the provider that you created for FortiMail Admin. +3. Click **Edit**. +4. Under **Protocol settings**, set the following values: + - **ACS URL**: paste the **ACS URL** value from FortiMail. + - **Audience**: paste the **Entity ID** value from FortiMail. +5. Click **Update**. -:::info User Provisioning -FortiMail does not auto-provision administrator accounts via SSO. +### Configure administrator accounts -You must manually create admin users and, for each account, configure the **Authentication type** as `Single Sign On` to enable authentication through the SAML provider. -::: +FortiMail does not automatically provision administrator accounts through SSO. Create or edit each administrator that should use SSO: + +1. In the FortiMail admin interface, navigate to **System** > **Administrator** > **Administrator**. +2. For each SSO-enabled administrator, set **Authentication type** to **Single Sign On** and set **Single sign on profile** to the SSO profile that you created for authentik. ### Enforce SSO-only access (optional) -To require SSO for FortiMail Admin Portal logins: +To show only SSO on the administrator login page, run the following commands in the FortiMail CLI: -1. Sign in to the FortiMail admin interface. -2. Navigate to **System** > **Customization** > **Appearance** > **Webmail Portal** and set **Login page** to `Single Sign On only`. +```shell +config system appearance +set admin-sso-login-option sso-only +end +``` + +:::warning Administrator recovery +When administrator SSO-only login is enabled, the built-in `admin` account cannot sign in to the GUI. Keep SSH or local console access available before enabling this option. +::: -## authentik configuration - -To support the integration of the FortiMail User Portal with authentik, you need to create an application/provider pair in authentik. - ### Create an application and provider in authentik 1. Log in to authentik as an administrator and open the authentik Admin interface. -2. Navigate to **Applications** > **Applications** and click **New Application** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) - - **Application**: provide a descriptive name (e.g. `FortiMail User Portal`), an optional group for the type of application, the policy engine mode, and optional UI settings. Take note of the **slug** as it will be required later. +2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard. + - **Application**: provide a descriptive name (for example, `FortiMail User Portal`), an optional group for the type of application, the policy engine mode, and optional UI settings. Take note of the **slug** value because it will be required later. - **Choose a Provider type**: select **SAML Provider** as the provider type. - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. - - Set the **ACS URL** to `https://fortimailuser.company/sp2/sso/SAML2/POST`. - - Set the **Audience** to `https://fortimailuser.company/sp`. - - Under **Advanced protocol settings**, choose any available certificate as the **Signing Certificate** and enable **Sign Assertions**. Ensure `authentik default SAML Mapping: Email` is selected as a **Selected User Property Mapping**; other mappings are optional and can be removed if not needed. - - **Configure Bindings** _(optional)_: create a [binding](/docs/add-secure-apps/bindings-overview/) to control which end users see the FortiMail webmail application on the **Application Dashboard** page. - -3. Click **Submit** to save the application and provider. + - Temporarily set the **ACS URL** to `https://temp.temp`. + - Temporarily set the **Audience** to `https://temp.temp`. + - Under **Advanced protocol settings**, select any available certificate as the **Signing Certificate**. + - **Configure Bindings** _(optional)_: you can create a [binding](/docs/add-secure-apps/bindings-overview/) (policy, group, or user) to manage the listing and access to applications on a user's **Application Dashboard** page. +3. Click **Create Application** to save the new application and provider. ### Download metadata file 1. Log in to authentik as an administrator and open the authentik Admin interface. -2. Navigate to **Applications** > **Providers** and click on the name of the provider that you created in the previous section (e.g. `Provider for FortiMail User Portal`). -3. Under **Related objects** > **Metadata**, click on **Download**. This downloaded file is your metadata file and it will be required in the next section. +2. Navigate to **Applications** > **Providers** and click the name of the provider that you created in the previous section (for example, `Provider for FortiMail User Portal`). +3. Under **Related objects** > **Metadata**, click **Download**. This file is required in the next section. ## FortiMail configuration 1. Sign in to the FortiMail admin interface. -2. Navigate to **System** > **Single Sign On** and select the **Setting** tab. -3. Enable **Use different service provider for admin and webmail access**, and select the **Webmail** service provider. -4. For the user/webmail service provider, note the values that FortiMail displays (the ACS field is read-only): - - **Entity ID**: `https://fortimailuser.company/sp` - - **Assertion consumer service (ACS) URL**: replace the host portion with `fortimailuser.company` (for example, `https://fortimailuser.company/sp2/sso/SAML2/POST`) +2. Navigate to **System** > **Single Sign On** and open the **Profile** tab. +3. Create a new SSO profile and configure the following settings: + - **Profile name**: enter a descriptive name (for example, `authentik-webmail`). + - **Metadata**: upload the authentik metadata file that you downloaded in the previous section. + - **Attribute used to identify email address**: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` +4. Click **Create** or **OK** to save the SSO profile. +5. Open the **Setting** tab and enable **Single sign-on**. +6. Enable **Use different service provider for admin and webmail access**, and then select **Webmail** as the service provider metadata target. +7. In the **Service Provider Metadata** section, configure the following values: + - **Entity ID**: `https://fortimailuser.company/sp2` + - **Host name**: `fortimailuser.company` +8. Click **Apply**. +9. Copy the following FortiMail service provider values: + - **Entity ID** + - **ACS URL** -Ensure that these values match those configured in authentik. If not, update the values in authentik and re-download the [authentik metadata file](#download-metadata-file). +### Reconfigure the authentik provider -5. Upload the authentik SAML metadata file you downloaded in the previous step. -6. On the **Profile** tab for the user/webmail provider, set **Attribute used to identify email address** to `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`. +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers** and click the provider that you created for the FortiMail User Portal. +3. Click **Edit**. +4. Under **Protocol settings**, set the following values: + - **ACS URL**: paste the **ACS URL** value from FortiMail. + - **Audience**: paste the **Entity ID** value from FortiMail. +5. Click **Update**. + +### Configure webmail access + +1. In the FortiMail admin interface, navigate to **Domain & Users** > **Domain** and edit the domain that should use SSO. +2. Open **Advanced Setting** > **Other** and set **Webmail single sign on** to the SSO profile that you created for authentik. ### Enforce SSO-only access (optional) -To require SSO for FortiMail User Portal logins: +To show only SSO on the webmail login page, run the following commands in the FortiMail CLI: -1. Sign in to the FortiMail admin interface. -2. Navigate to **Domain & Users** > **Domain**, edit the domain entry, then open **Advanced Setting** > **Other** and set **Webmail single sign on** to the SSO profile you created for end users. +```shell +config system appearance +set webmail-sso-login-option sso-only +end +``` ## Configuration verification -1. Open a new browser session (or private window) and navigate to the relevant FortiMail portal (admin or user). -2. Initiate the SSO login flow (this happens automatically if you enabled the SSO-only options) and confirm that you are redirected to authentik for authentication. Sign in with an account permitted to use that portal. -3. After successful authentication, verify that you return to the FortiMail portal without being prompted for additional credentials. +To confirm that authentik is properly configured with FortiMail, open the FortiMail portal that you configured and start the SSO login flow. After authenticating with authentik, verify that you return to FortiMail without being prompted for additional credentials. + +## Resources + +- [Fortinet - FortiMail](https://www.fortinet.com/products/email-security) +- [Fortinet Docs - Configuring single sign-on (SSO)](https://docs.fortinet.com/document/fortimail/8.0.0/administration-guide/73231/configuring-single-sign-on-sso) +- [Fortinet Docs - FortiMail Cloud Configuring single sign-on (SSO)](https://docs.fortinet.com/document/fortimail-cloud/1.0.0/fortimail-cloud-administration-guide/73231/configuring-single-sign-on-sso) +- [Fortinet Docs - system saml](https://docs.fortinet.com/document/fortimail/8.0.0/cli-reference/856423/system-saml) +- [Fortinet Docs - system appearance](https://docs.fortinet.com/document/fortimail/7.4.3/cli-reference/523895/system-appearance)