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

If you want separate permissions for Admin SSO and e.g. VPN SSO (Regular User) you need two Clients for that!

Keycloak Setup

Keycloak Client Setup (basic)

  1. Log into Keycloak and go to Clients
  2. Create a new Client of Type SAML and set Client ID to http://<your-fortigate-ip-or-fqdn>/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

Keycloak Client Setup (advanced)

  • General Settings
    • Set a display name for Name
  • Access settings
    • Set your desired access address as Root URL and Home URL
    • Set https://<your-fortigate-ip-or-fqdn>/saml/?acs as Valid Redirect URIs
    • Set https://<your-fortigate-ip-or-fqdn>/saml/?acs as Master SAML Processing URL
  • 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
    • Enable Front channel logout
    • Set Logout service POST binding URL to https://<your-fortigate-ip-or-fqdn>/saml/?sls
    • Set Logout service Redirect binding URL to https://<your-fortigate-ip-or-fqdn>/saml/?sls

Keycloak Client 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

FortiGate Setup

Preparation

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

  • Download the X509 Certificate from https://<your-keycloak-uri>/realms/<realm-name>/protocol/saml/descriptor
    1. Look for the value of <ds:X509Certificate>
    2. Paste that content into a file with -----BEGIN CERTIFICATE----- as the first line and -----END CERTIFICATE----- as the last
  1. Log into FortiGate and go to System → Certificates
  2. Click Create/Import and select Remote Certificate
  3. Upload the previously created file
  4. Note the 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 Settings
      • Set IdP type to Custom
      • Set IdP certificate to the name of your previously uploaded certificate (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
Back to top