The SSO launch post covered what we built. This is the honest follow-up: what broke in production during rollout, and how we fixed it.

Every vendor's SSO announcement reads the same: clean, confident, done. Actual rollouts are messier, and we think the messiness is more useful to another team evaluating this than the polished version. So here's what actually went wrong migrating our first cohort of customers onto SAML.

Clock skew broke assertion validation for one customer in three

SAML assertions carry a validity window, and we were validating it strictly against server time. One customer's IdP server clock was four minutes fast, which meant every login attempt failed with an opaque "assertion not yet valid" error that told nobody anything useful. We added a configurable clock-skew tolerance (default 2 minutes) and, more importantly, a specific error message that names clock skew as the likely cause.

Group claims silently truncate past a certain size

# What we started logging instead of failing silently
WARN: SAML assertion for This email address is being protected from spambots. You need JavaScript enabled to view it. contained 340 group claims,
      exceeding Azure AD's default claim limit (200). Groups may be
      incomplete. Configure group filtering in your IdP app registration.

A customer with deeply nested Azure AD groups hit the IdP's own claim-count limit, not ours — but from their side, it looked like Helix was dropping group memberships randomly. We can't fix another vendor's limit, but we can detect and explain it instead of leaving someone to debug it blind.

The rollout order that worked

What worked well: running SSO in parallel with existing local auth for two weeks before requiring it, with a dashboard showing which users had and hadn't authenticated via SSO yet. That gave admins a concrete list to chase rather than a hard cutover date and hope.

The support ticket we're still getting

Even with all of the above fixed, the single most common SSO support question is still some version of "why does this specific user see a permission they shouldn't." Nearly every instance traces back to a group-role mapping written before someone's group membership changed, and the mapping just never got revisited. We're adding a periodic drift report that flags users whose effective Helix role no longer matches what their current IdP group membership would produce, so this stops being a reactive support conversation.

  • Configurable clock-skew tolerance for SAML assertion validation
  • Explicit detection and warning for IdP-side group claim truncation
  • Parallel-run period with local auth before enforcing SSO-only
  • Per-user SSO adoption dashboard for admins during migration