Skip to main content

SSO with Keycloak

Requirements

  • FortiGate with at least FortiOS 7.X
  • Keycloak (26.X ideally)

This has been tested with Keycloak 26.X and FortiOS 7.6.6

Realm names in Keycloak are case-sensitive. Ensure all URLs referencing the realm name use the exact same casing (e.g. MyRealm not myrealm).

IfYou youneed wanta separate permissionsKeycloak client for each FortiGate SSO use case. For example: one client for Admin SSO and e.g.one VPNfor User SSO (Regularfirewall User)policy youauthentication). needThis twoallows Clientsseparate foraccess that!restrictions per use case.

Keycloak Setup

The following steps apply to both the Admin SSO client and the User SSO client. Differences between the two are noted where applicable.

Step 1: Create the Keycloak Client Setup (basic)

  1. Log into Keycloak and go to Clients
  2. Create a new Client of Type SAML and set the Client IDID: to
    • Admin SSO: http://<your-fortigate-ip-or-fqdn>/metadata/

    • User SSO: http://<your-fortigate-fqdn>/remote/saml/metadata/

    Note the trailing slash — it must be present. The Client ID must be a byte-for-byte match of the Issuer value sent by FortiGate in its SAMLRequest.

  3. Finish the Create Client wizard with default settings for now

KeycloakStep 2: Client SetupSettings (advanced)

  • General Settings
    • Set a display name for Name
    • Optionally set a Logo URI to display a logo on the account console. For FortiGate clients the official Fortinet logo is available at:
      https://upload.wikimedia.org/wikipedia/commons/6/62/Fortinet_logo.svg

      The Logo URI is only shown in the Keycloak account console, not on the login page itself. To show a logo on the login page, a custom theme is required.

  • Access settings
    • Set your desired accessFortiGate address as Root URL and Home URL
    • Set https://<your-fortigate-ip-or-fqdn>/saml/?acs as Valid Redirect URIs
      • :
      • SetAdmin SSO: https://<your-fortigate-ip-or-fqdn>/saml/?acs
        • as
      • User SSO: https://<your-fortigate-fqdn>/remote/saml/?acs
    • Set Master SAML Processing URL to the same value as Valid Redirect URIs above
  • SAML capabilities
    • Set Name ID Format to username
    • Enable Force POST Binding
  • Signature and Encryption
    • Enable Sign documents
    • Enable Sign assertions
  • Keys tab
    • Set Client Signature Required to Off — FortiGate does not sign AuthnRequests
  • Logout settings (Settings tab)
    • Enable Front channel logout
    • Set Logout service POST binding URL: to
      • Admin SSO: https://<your-fortigate-ip-or-fqdn>/saml/?sls
      • User SSO: https://<your-fortigate-fqdn>/remote/saml/?sls
    • Set Logout service Redirect binding URL to the same value as above
  • Logout settings (Advanced tab)
    • Set Backchannel logout URL:
      • Admin SSO: https://<your-fortigate-ip-or-fqdn>/saml/?sls
      • User SSO: https://<your-fortigate-fqdn>/remote/saml/?sls
    • Enable Backchannel logout session required

KeycloakStep Client3: Add Username Attribute Mapper Setup

Without a username mapper, FortiGate will reject the SAML assertion as it contains no username attribute.

  1. Go to Clients → your FGT client → Client scopes → (client)-dedicated → Add mapper → By configuration
  2. Select User Property and configure:
    • Name: username
    • Property: username
    • SAML Attribute Name: username
    • SAML Attribute NameFormat: Basic
  3. Save

Access Restriction (Optional)

By default, any user in Keycloak can authenticate through the client. To restrict access to a specific group, follow the steps below. Repeat this process for each client with its own role and group.

This works by creating a realm role, assigning it to a group, and then creating a custom authentication flow that denies access to users who do not have that role.

Step 1: Create a Realm Role

  1. Go to Realm roles → Create role
  2. Set a name for the role (e.g. Firewall Admins or Firewall Users)
  3. Save

Step 2: Assign the Role to a Group

  1. Go to Groups → your desired group → Role mapping
  2. Click Assign role
  3. Select the role created in Step 1 and assign it

All members of the group will automatically inherit the role. If you use AD/LDAP federation, make sure group sync is configured so group memberships are reflected in Keycloak.

Step 3: Create a Custom Authentication Flow

  1. Go to Authentication → Flows
  2. Click on Browser → Action → Duplicate
  3. Give it a descriptive name (e.g. Browser - Firewall Admins) and confirm
  4. Open the duplicated flow
  5. Click Add sub-flow at the top level:
    • Name: Role Check
    • Requirement: Conditional
  6. Inside the Role Check sub-flow, click Add condition:
    • Select Condition - User Role
    • Requirement: Condition
    • Click the settings (pencil) icon and set:
      • Role: select the role created in Step 1
      • Negate: On
  7. Inside the Role Check sub-flow, click Add step:
    • Select Deny Access
    • Requirement: Required

The Negate toggle is critical. With Negate On, the condition matches users who do not have the role, causing them to be denied. Without Negate, users with the role would be denied instead.

Step 4: Bind the Flow to the Client

  1. Go to Clients → your client → Advanced tab
  2. Scroll to Authentication flow overrides
  3. Set Browser flow to your newly created flow
  4. Save

FortiGate Setup

Preparation — Import Keycloak Certificate

Make sure to download the certificate from your specific realm's metadata endpoint, not the master realm. Each realm has its own signing key.

    1. Download the X509 Certificate fromOpen https://<your-keycloak-uri>/realms/<realm-name>/protocol/saml/descriptor
        in your browser
      1. Look forFind the value of <ds:X509Certificate> value and copy it
      2. Paste thatthe content into a filetext withfile, wrapping it as follows: 
        -----BEGIN CERTIFICATE-----
as<paste thecertificate firstcontent linehere>
and -----END CERTIFICATE-----
        as
      3. Save the lastfile with a .crt extension
  1. Log into FortiGate and go to System → Certificates
  2. Click Create/Import and→ select Remote Certificate
  3. Upload the previouslyfile createdand file
  4. Notenote the assigned name assigned to the certificate — (usually REMOTE_Cert_X)

Admin SSO Configuration

  1. Log into FortiGate and go to Security Fabric → Fabric Connectors
  2. Right-click on Security Fabric Setup → Edit → Single Sign-On Settings:
    • Set Mode to Service Provider (SP)
    • Click Use current browser address to automatically configure the SP Address value
    • Configure the Default admin profile to your desired settings
    • IdP SettingsSettings:
      • Set IdP type to Custom
      • Set IdP certificate to the name of your previously uploadedimported certificate name (e.g. REMOTE_Cert_X)
      • Set IdP entity ID to https://<your-keycloak-uri>/realms/<realm-name>
      • Set IdP single sign-on URL to https://<your-keycloak-uri>/realms/<realm-name>/protocol/saml
      • Set IdP single logout URL to https://<your-keycloak-uri>/realms/<realm-name>/protocol/saml

User SSO Configuration (Firewall Policy Authentication)

  1. Log into FortiGate and go to User & Authentication → Single Sign-On → Create New
  2. Configure the following:
    • Set Type to Custom
    • Set Address to your FortiGate FQDN or IP — the SP Entity ID, ACS URL, and SLO URL will auto-populate
    • Set Attribute used to identify users to username
    • Set Attribute used to identify groups to group
    • IdP Settings:
      • Set IdP type to Custom
      • Set Certificate to the imported certificate name (e.g. REMOTE_Cert_X)
      • Set IdP entity ID to https://<your-keycloak-uri>/realms/<realm-name>
      • Set IdP single sign-on URL to https://<your-keycloak-uri>/realms/<realm-name>/protocol/saml
      • Set IdP single logout URL to https://<your-keycloak-uri>/realms/<realm-name>/protocol/saml
  3. Save the SSO configuration
  4. Go to User & Authentication → User Definition → Create New:
    • Set User Type to SAML
    • Set Username to a name for this SAML user (e.g. keycloak-users)
    • Set SAML SSO Server to the SSO configuration created above
  5. Go to User & Authentication → User Groups → Create New:
    • Add the SAML user definition as a Member
  6. Apply the user group to a Firewall Policy under Policy & Objects → Firewall Policy → Source

Users matching a firewall policy with this group will be prompted to authenticate via Keycloak SAML before traffic is allowed through.

Back to top