[object Object]

Freshworks SAML SSO is well-documented for the happy path. The pitfalls live in user provisioning, the difference between the four login surfaces, and what happens when SSO breaks.

The four login surfaces

Freshworks has four distinct login flows: agent portal, customer portal, mobile app, and API. SSO can be enforced on each independently. Most teams enforce on agent portal but leave customer portal as email/password — which is usually correct.

Just-in-time provisioning vs SCIM

SAML JIT creates an agent on first login. SCIM provisions ahead of time. JIT is faster to set up but creates orphan accounts when an agent leaves and never logs out. SCIM is the right choice for headcount > 50.

SCIM endpoint:
  https://yourcompany.freshdesk.com/scim/v2/Users
Auth: Bearer token from Admin → SCIM
Supports: create, update, deactivate

Group mapping

Map IdP groups to Freshworks roles via SAML attribute statements. Without this, every JIT-provisioned user lands as a default agent with no group membership.

// Okta SAML attribute statement
{
  "name": "groups",
  "value": "user.groups.filter(g => g.name.startsWith('FW_'))"
}
// Then in Freshworks: map FW_Tier1 → Group "Tier 1 Support"

Break-glass account

Always keep one local-auth admin account that bypasses SSO. When your IdP has an outage, this is the only way back in. Document the credentials in your secret store; rotate every 90 days.

Session timeout

The default Freshworks session is 14 days. For agent portal, shorten to 8 hours via Admin → Security. SSO tokens expire faster than the session, leading to mid-shift re-auth otherwise.

SP-initiated vs IdP-initiated

Freshworks supports both. SP-initiated (user goes to Freshworks first) is more common. IdP-initiated (user clicks tile in Okta) requires the relay state to be configured for direct deep-linking to work.

Audit the assertion

Use a SAML tracer browser extension during setup. The most common failure is a malformed nameID format or an attribute with a typo (emailaddress vs email_address).

What to do this week

Confirm SCIM is enabled if you have 50+ agents, set up the IdP group → Freshworks role mapping, create the break-glass local account, and shorten agent session timeout to 8 hours.

[object Object]
Share