# FortiAuthenticator SAML 2.0 SSO Integration

This guide explains how to integrate **FortiAuthenticator** as a SAML 2.0 Identity Provider (IdP) for **AIR**.

> ✅ This method supports **IdP-initiated SAML SSO**. Role mapping is handled via FortiAuthenticator Groups and AIR `roleTags`.

***

## Prerequisites

* Access to FortiAuthenticator with admin privileges
* Access to AIR as an administrator
* Users to be authenticated must have their **email field populated**
* Ensure network connectivity between AIR and FortiAuthenticator (via server address used in configuration)

***

## Step 1: Prepare FortiAuthenticator

1. Log in to FortiAuthenticator with an admin account.
2. Go to **Authentication → User Management → User Groups**.

<figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-602e41a0fcba57e39f472a0380d8bb667411e6fe%2Fuser-groups.png?alt=media" alt=""><figcaption></figcaption></figure>

3. Create user groups that will act as AIR role mappings:
   * Use the prefix `air_role.` followed by the role tag used in AIR.\
     Example: `air_role.global_admin`
   * Only roles that will be actively used for login need to be created.
4. Assign users to their corresponding AIR role groups.

***

## Step 2: Configure FortiAuthenticator as SAML IdP

1. Navigate to **Authentication → SAML IdP → General**.

   <figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-b4bb47aa4cd91dc93f727de8177a78614e7972fb%2Fsaml-general.png?alt=media" alt=""><figcaption></figcaption></figure>
2. Enable "Enable SAML Identity Provider portal" setting.
3. In the **Server Address** field, enter the address AIR will use to reach FortiAuthenticator.\
   Make sure AIR can access this URL over the network.
4. (Optional) Select a **default IdP certificate**.\
   This is recommended for metadata download compatibility.
5. Click **Save** to store your settings.

***

## Step 3: Create Service Provider in FortiAuthenticator

1. Go to **Authentication → SAML IdP → Service Providers**.
2. Click **Create New** to register the AIR as a new SP (Service Provider).
3. Fill in:
   * **SP Name**: Choose a meaningful name (e.g., `AIR-Instance-X`)
   * **IdP Prefix**: Auto-generate or enter manually
   * **Server Certificate**: Select one, or **Use default setting in SAML IdP General page** if using the default certificate
4. Click **Save** to create the SP.

<figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-96a94b38b98e3351acdc10654db97d4d232e912f%2Fcreate-sp.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Step 4: Configure SSO in AIR

1. In a new tab, log in to **AIR** with an admin user.
2. Go to **Settings → Security**, scroll to the **SSO** section.
3. Enable **FortiAuthenticator** and copy the **ACS URL** at the bottom.

<figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-99e53748db746404439bfc85cc90e28c0f0da081%2Facs-url.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Step 5: Complete SP Configuration in FortiAuthenticator

1. Go back to your created SP in FortiAuthenticator.
2. Under **SP Metadata**, fill in:

   * **SP Entity ID** → Paste the ACS URL from AIR
   * **SP ACS (Login) URL** → Paste the ACS URL again

   <figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-07a0eb1ff91618df4d675b4a14f29e47c2d26369%2Ffortiauthenticator-sp-metadata.png?alt=media" alt=""><figcaption></figcaption></figure>
3. Under **Assertion Attributes**, configure:
   * **Subject Name ID** → Set to `email`
   * **Format** → `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
4. Add the following SAML assertions:

   | SAML Attribute | User Attribute | Required |
   | -------------- | -------------- | -------- |
   | `groups`       | Group          | ✅        |
   | `firstName`    | First Name     | ❌        |
   | `lastName`     | Last Name      | ❌        |

   <figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-8f1b2387750fceef3ed9ac0aa28523a799747e98%2Fassertion-attributes.png?alt=media" alt=""><figcaption></figcaption></figure>
5. Click **Save**.

***

## Step 6: Export IdP Metadata

1. Open the newly created SP entry.
2. Click **Download IdP Metadata**.

   <figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-c2d50f9708dbb2c0fa3a745ca374fc5c58f5cc30%2Fdownload-idp-metadata.png?alt=media" alt=""><figcaption></figcaption></figure>

***

## Step 7: Upload Metadata to AIR

1. Return to **AIR → Settings → Security → SSO** section.
2. Use the **Upload IdP Metadata** option to upload the file.

   <figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-b7de3cbd81b71a2f506e26f18d7756dd6ac70cc5%2Fsso-config.png?alt=media" alt=""><figcaption></figcaption></figure>

   > 🔄 Alternatively, you can copy values from Forti and paste them into AIR manually.
3. Click **Save**.

***

## Step 8: Test the Integration

1. Log out of AIR.
2. Click **Login with FortiAuthenticator** on the login screen.

   <figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-7c6462782fa7eae48f0c48f0ac8c73d7c850d766%2Fsign-in.jpeg?alt=media" alt=""><figcaption></figcaption></figure>
3. You’ll be redirected to FortiAuthenticator. After successful authentication, you’ll be redirected back to AIR.

***

## Troubleshooting

If login fails, check the following:

* 🔌 **Network Issues**: Make sure AIR can reach FortiAuthenticator’s Server Address.
* 👥 **Role Mapping**: Ensure the user is assigned to at least one Forti group named `air_role.X` where `X` matches a role tag in AIR.
  * View AIR role tags via **Settings → User Management → User Roles**.

    <figure><img src="https://1662683669-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FnA8kGzryHKp7UhDaLtzW%2Fuploads%2Fgit-blob-5a7d341abbc22221914282f90d942df32a997b85%2Ffortiauthenticator-role-tags.png?alt=media" alt=""><figcaption></figcaption></figure>
* 📧 **Email Field**: Users without an email field in Forti cannot log in.
* 📄 **Logs**: If the issue persists, collect SAML logs from both AIR and Forti and contact support.

***

## Example Group Mapping for Predefined Roles

| AIR Role Name        | AIR Role Tag           | Forti Group Name                |
| -------------------- | ---------------------- | ------------------------------- |
| Global Admin         | `global_admin`         | `air_role.global_admin`         |
| Organization Admin   | `organization_admin`   | `air_role.organization_admin`   |
| L1 & L2 Analyst      | `l1_l2_analyst`        | `air_role.l1_l2_analyst`        |
| Maintenance Engineer | `maintenance_engineer` | `air_role.maintenance_engineer` |
| L3 & L4 Analyst      | `l3_l4_analyst`        | `air_role.l3_l4_analyst`        |
| Responder            | `responder`            | `air_role.responder`            |