Enterprise SSO with WorkOS AuthKit

Why WorkOS for Agent Infrastructure Auth

Enterprise authentication is a solved problem — but only if you use the right building blocks. Rolling your own SAML implementation, OIDC flow, or directory sync is a multi-month endeavor that yields a brittle result. Enterprise customers expect SSO that works with Okta, Azure AD, Google Workspace, and OneLogin on day one, not after a custom integration project.

WorkOS provides a unified API for enterprise identity features: SSO (SAML and OIDC), directory sync (SCIM), organization management, and session handling. HatiData uses WorkOS AuthKit as the authentication layer for its control plane, giving every customer enterprise-grade identity management without custom integration work.

The key advantage for agent infrastructure specifically is organization-level isolation. In HatiData, an organization is the top-level tenant — it owns agents, data, quotas, and billing. WorkOS maps naturally to this model: each WorkOS organization corresponds to a HatiData organization, and users are members of organizations with defined roles.

SSO Setup: SAML and OIDC

SAML Integration

SAML (Security Assertion Markup Language) is the dominant SSO protocol in enterprise environments. When a customer's IT team configures SAML SSO for HatiData, the flow works as follows:

1. 1User navigates to HatiData dashboard and enters their email
2. 2HatiData identifies the user's organization and redirects to their IdP (e.g., Okta)
3. 3The user authenticates with their corporate credentials (password, MFA, etc.)
4. 4The IdP sends a SAML assertion back to HatiData via WorkOS
5. 5WorkOS validates the assertion and creates a session
6. 6The user is logged into the HatiData dashboard with their organization context

The entire SAML exchange happens through WorkOS — HatiData never handles SAML XML directly. WorkOS normalizes the assertion into a standard user profile regardless of which IdP the customer uses.

Configuration is done through the HatiData dashboard:

1. 1Organization admin enables SSO in settings
2. 2HatiData provides the ACS URL and Entity ID (from WorkOS)
3. 3Admin enters these in their IdP and provides the IdP metadata URL
4. 4WorkOS validates the connection with a test login

OIDC Integration

For customers using modern identity providers that support OpenID Connect, the flow is simpler:

1. 1Admin provides the OIDC discovery URL, client ID, and client secret
2. 2WorkOS handles the authorization code flow
3. 3Users are redirected to their IdP, authenticate, and return with tokens
4. 4WorkOS exchanges the authorization code for identity tokens

OIDC is common with Google Workspace, Azure AD, and Auth0 deployments. The setup requires fewer configuration steps than SAML, and the token-based flow is more straightforward to debug.

SCIM Directory Sync

SSO handles authentication — verifying who a user is. But enterprises also need provisioning — automatically creating and removing user accounts when employees join or leave the company. SCIM (System for Cross-domain Identity Management) is the standard protocol for this.

When SCIM is enabled, HatiData stays in sync with the customer's user directory:

• User provisioned — When a new employee is added to the relevant group in the IdP, a user account is automatically created in HatiData with the appropriate organization and role
• User deprovisioned — When an employee leaves or is removed from the group, their HatiData access is immediately revoked
• User updated — Changes to name, email, or role in the IdP are automatically reflected in HatiData
• Group sync — IdP groups can be mapped to HatiData roles, so group membership changes automatically update permissions

SCIM sync happens in near-real-time through webhook events from WorkOS. When an employee is terminated in Okta at 3:00 PM, their HatiData access is revoked within seconds — not on the next nightly sync.

Corporate IdP (Okta/Azure AD)
    |
    | SCIM Events (create/update/delete)
    v
WorkOS Directory Sync
    |
    | Webhook notifications
    v
HatiData Control Plane
    |
    +── Create/update/revoke user accounts
    +── Map group memberships to roles
    +── Audit log all provisioning events

Organization-Level Auth

HatiData's multi-tenant model maps one WorkOS organization to one HatiData organization. This provides clean isolation:

• Each organization has its own SSO configuration (different IdPs for different customers)
• Each organization has its own user directory and role assignments
• Each organization has its own billing, quotas, and data isolation
• Users can be members of multiple organizations (common for consultants and managed service providers)

When a user authenticates, the session includes their organization context. All API calls, dashboard views, and agent operations are scoped to that organization. Switching between organizations requires re-authentication or explicit organization selection.

Session Management

WorkOS AuthKit handles session lifecycle:

• Session creation — After successful SSO, WorkOS creates a session with configurable expiration (default 24 hours for active sessions, 7 days for remembered sessions)
• Session refresh — Active sessions are automatically refreshed on each request, extending the expiration window
• Session revocation — Admins can revoke specific sessions or all sessions for a user (useful when an account is compromised)
• Session introspection — Each API request validates the session token with WorkOS, ensuring revoked sessions are immediately rejected

The HatiData control plane caches session validation results for a short TTL (default 5 minutes) to reduce latency on API calls. This means there is at most a 5-minute window between session revocation and effective access removal — acceptable for most security requirements, and configurable for stricter environments.

AuthKit Integration Patterns

Dashboard Authentication

The HatiData dashboard uses WorkOS AuthKit's hosted login flow. Users are redirected to a WorkOS-hosted page that handles email-based organization detection, SSO redirect, and fallback to email/password for organizations without SSO configured.

This hosted approach means HatiData never handles credentials directly — passwords, SAML assertions, and OIDC tokens are all processed by WorkOS. HatiData only receives a session token after successful authentication.

API Authentication

API access uses two authentication methods:

1. 1API keys — For agent-to-HatiData communication (the hd_live_ keys described in the agent identity guide). These are long-lived and do not involve WorkOS.
2. 2Session tokens — For human-to-dashboard communication. These are issued by WorkOS after SSO and have a limited lifetime.

The control plane distinguishes between the two by inspecting the Authorization header format. API keys and session tokens are validated through different code paths but result in the same internal identity model.

Webhook Verification

WorkOS sends webhook events for directory sync, organization updates, and authentication events. HatiData verifies these webhooks using the WorkOS webhook secret, ensuring that only legitimate events are processed.

All webhook events are idempotent — processing the same event twice has no additional effect. This protects against retry storms from WorkOS and ensures consistency.

Security Properties

The WorkOS integration provides several security properties that would be difficult to achieve with a custom auth implementation:

• Zero credential storage — HatiData never stores passwords, SAML assertions, or OIDC tokens. All credential handling is delegated to WorkOS.
• Immediate access revocation — SCIM deprovisioning and session revocation take effect within seconds, not on the next login attempt.
• MFA delegation — Multi-factor authentication is configured at the IdP level. HatiData does not need to implement its own MFA — it inherits whatever MFA the customer's IdP requires.
• Audit trail — Every authentication event, provisioning change, and session operation is logged with timestamps and source information.

Next Steps

Enterprise SSO is a prerequisite for production deployments in regulated industries. See the WorkOS SSO documentation for step-by-step setup guides for Okta, Azure AD, Google Workspace, and other IdPs. For agent authentication (API keys rather than SSO), see the agent identity guide.