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.

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

2. Assign users to their corresponding AIR role groups.

---

Step 2: Configure FortiAuthenticator as SAML IdP

1. Navigate to Authentication → SAML IdP → General.

   
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.

---

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.

---

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

   
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	❌

   
5. Click Save.

---

Step 6: Export IdP Metadata

1. Open the newly created SP entry.

2. Click Download IdP Metadata.

   

---

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.

   

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

   
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.

    
• 📧 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