Integrating WatchGuard Access Portal with Keycloak via SAML 2.0

by | Oct 8, 2025 | Uncategorized

identity provider. Keycloak is a great choice, but the SAML handshake can be tricky:
subtle differences around certificates, encryption, and attributes often lead to 501 or
redirect loops. This post documents a working, anonymized configuration and the reasoning behind it,
so you can get from “almost there” to “rock-solid” quickly.

 

 

 

 

Table of Contents

Architecture Overview

The Firebox acts as the SAML Service Provider (SP); Keycloak is the SAML Identity Provider (IdP) backed by Active Directory.

Step 1 — Configure WatchGuard (SP)

On the Firebox Web UI, go to Authentication → SAML and enable Access Portal (and optionally SSL VPN).

Firebox SP Settings (example)
Entity ID:
  https://saml.company.tld:4433/auth/saml

Assertion Consumer Service (ACS):
  https://saml.company.tld:4433/auth/saml/acs

NameID Format:
  email   (or: unspecified)

After saving, open the generated instructions page:

SP Instructions Page
https://saml.company.tld:4433/auth/saml

From “Option 2 (Manual Configuration)” copy the SP certificate (Base64/PEM) — you will import it into Keycloak as the encryption key.

Step 2 — Create Keycloak SAML Client

  • Realm: DMZ → Clients → Create
  • Client ID: https://saml.company.tld:4433/auth/saml (must equal Firebox Entity ID)
  • Client Protocol: SAML, Enabled: On

Recommended Security Options

  • Force POST Binding: On
  • Sign Assertions & Documents: On (RSA_SHA256)
  • Encrypt Assertions: On
  • Encryption Algorithm: RSA1_5
  • Key Transport Algorithm: AES128_CBC
  • NameID Format: email
  • Include AuthnStatement: On

Why RSA1_5 + AES128_CBC?

These values are broadly compatible with Firebox SAML processing and avoid common decrypt issues.

Step 3 — Import Firebox Certificate (Encryption Key)

In Keycloak Client → Keys → Encryption → Import, upload the certificate copied from the Firebox
instructions page. This ensures Keycloak encrypts assertions with the Firebox public key, so the SP can decrypt them.

Step 4 — Configure Firebox IdP Settings

Point the Firebox at the Keycloak Realm metadata (used to verify Keycloak’s signatures):

Firebox IdP Settings
IdP Metadata URL:
  https://keycloak.company.tld/realms/dmz/protocol/saml/descriptor

Group Attribute Name:
  groups

Step 5 — Define Keycloak Mappers (No Duplicates)

Create just the mappers you need (avoid overlapping SAML client scopes like role_list or saml_organization to prevent duplicate attributes):

Minimal Mapper Set
NameID:
  Type: User Property
  Property: email
  SAML Attribute Name: NameID
  NameID Format: email

username:
  Type: User Property
  Property: username
  SAML Attribute Name: username
  NameFormat: unspecified

email:
  Type: User Property
  Property: email
  SAML Attribute Name: email
  NameFormat: unspecified

groups:
  Type: Group list
  SAML Attribute Name: groups
  Full group path: Off   ← important for WatchGuard
  NameFormat: unspecified

With Full group path: Off, Keycloak sends plain group names (e.g., VPN-User) instead of full LDAP DNs.

Step 6 — Test the End-to-End Flow

  1. Open https://saml.company.tld:4433/ and click Login with SAML.
  2. Authenticate in Keycloak (backed by AD).
  3. Success logs on Firebox should include:

    Expected Log Lines
    samld ACS: user user@company.com groups=["VPN-User","Admins"]
samld Login: existing user from access_portal

Troubleshooting Playbook

“failed to decrypt” after redirect
  • Keycloak is not encrypting with the Firebox SP certificate — re-import the current SP cert into Client → Keys → Encryption.
  • Set Encrypt Assertions = On, Encryption Algorithm = RSA1_5, Key Transport = AES128_CBC, and Force POST Binding = On.
“The assertion is not encrypted and the SP require it”
  • Firebox enforces encrypted assertions; enable Encrypt Assertions in Keycloak and ensure the Firebox SP certificate is imported.
“Found an Attribute element with duplicated Name”
  • Remove overlapping SAML client scopes (e.g., role_list, saml_organization), or rename conflicting mappers.
Redirect loop back to the login page
  • NameID mismatch: use NameID = email if Firebox expects email-style usernames.
  • Group mapping: with Full group path off, ensure Firebox groups match the short names (e.g., VPN-User).
  • Clock drift: sync NTP on both systems; SAML assertions are time-bound.
  • Cookies: ensure the browser allows the session cookies from the portal domain.

Lessons Learned

  • Match the Firebox Entity ID exactly with the Keycloak Client ID.
  • Use RSA1_5 + AES128_CBC to avoid decryption incompatibilities.
  • Send groups as short names; avoid full LDAP DNs unless Firebox groups are created with the exact DN strings.
  • Keep Realm metadata URL on Firebox; import the SP certificate into Keycloak for encryption.