Okta SSO and SCIM

Configure OIDC or SAML single sign-on, dashboard-tile launch, and Okta SCIM provisioning for your organization.

This guide covers the customer-side setup for Headways enterprise identity: verifying your email domain, configuring OIDC or SAML, launching from the Okta dashboard tile, and provisioning users and groups with SCIM. Everything here is configured by an owner or IT admin at Admin > SSO (/o/<orgSlug>/settings/sso).

Prerequisites

• Owner or admin role in the Headways organization
• DNS access to publish a TXT record for your employee email domain
• An Okta administrator who can create an app and assign pilot users

Step 1: Verify your domain

Headways only links a work email to your organization when the email domain is one your organization has proven it controls. Verification never grants membership by itself.

1. In Admin > SSO, add the exact employee email domain (for example acme.com). Subdomains are not implied — mail.acme.com is a separate claim.
2. Publish the supplied _headways-sso.<domain> TXT value in DNS.
3. Click Verify. A stale or mismatched challenge fails; re-issue the challenge to get a fresh value.

If another organization already holds a live claim on the domain, verification is refused rather than stealing the claim.

Step 2: Configure OIDC

1. In Okta, create an OIDC Web Application using Authorization Code with client secret authentication and PKCE.
2. Copy the exact callback/redirect URI from Headways into Okta. Use the issuer Okta shows for this app — do not assume /oauth2/default.
3. Set scopes to openid email profile. Do not request offline_access, directory/Graph, or business-data permissions.
4. Assign pilot users or a group, and apply your normal MFA/sign-on policy.
5. Transfer the client secret through your approved secure channel and enter it into the Headways draft.
6. Save draft, then complete the real sign-in test, then Activate. A failed draft or test leaves the previously active configuration in place.

Saved secrets are never returned to the browser — loaders and network responses expose redacted configuration only.

Step 3: Configure SAML and the dashboard tile

1. Create a separate SAML 2.0 app for the organization's SAML revision.
2. Copy the exact ACS URL and SP Entity ID from Headways into Okta.
3. Map a stable opaque subject separately from work email and display name. The subject is case-sensitive and is never treated as the email.
4. Exchange signing metadata/certificates with Headways.
5. Make the Headways tile visible and assign the pilot group. Leave the optional launch destination empty to open the organization home, or set one within the connected organization.
6. Save draft, complete the real signed-in test, then activate.

A launch from the tile opens the tile's organization without changing unrelated organization authorization. If the browser is already signed in as someone else, Headways asks for explicit confirmation; cancelling leaves the original session unchanged. Rotate signing certificates through a staged, tested overlap and retire the old certificate explicitly.

You may run one active protocol at a time. Switching OIDC↔SAML requires a separately tested revision; account associations are preserved under the verified-ownership rules.

Step 4: Enable SCIM provisioning

Which Okta app to use

Headways tests SCIM with an Okta app that exposes a Provisioning tab — the SAML/custom integration app with provisioning enabled, or the supported SCIM test integration. A custom OIDC app in Okta may not present a Provisioning tab at all; if yours does not, use the SAML/custom integration for SCIM and keep OIDC for sign-in. Do not assume every custom OIDC app can provision.

Configure

1. Copy the SCIM base URL, https://api.headways.ai/scim/v2/<organizationId>, and issue a token from Headways. Tokens are shown once; only a digest is stored.
2. Set userName to the unique mapped work-email attribute and use bearer-token auth.
3. Enable Create Users, Update User Attributes, and Deactivate Users. Leave password sync off.
4. Test connectivity — Headways supports filtered user lookup and paginated discovery.

Issuing a new token before revoking the old one gives you overlap for rotation; revocation is permanent.

Group push grants no roles or content permissions

Pushing Okta groups creates Headways directory groups and rosters only. Group membership is recorded as a directory join and carries no workspace role, no department override, and no content permission (no SpiceDB relation). Group deletion removes the group, never the employees. Reconcile any role changes explicitly in Headways.

Offboarding: what happens and when

When a user is deactivated in Okta (SCIM active=false), Headways permanently invalidates that person's live authorization for the organization:

• All server-side checks deny and live sockets/streams close within 60 seconds; ongoing delivery rechecks authorization at least every 10 seconds.
• A durable cleanup task tears down runs, slots, schedules, and former privileged tuples. A recovery scan picks up dropped cleanup within 10 seconds, without depending on the offboarded person's token.
• Other organizations and organization-owned service pipelines are unaffected.
• Reactivation restores active eligibility but does not restore old credentials, sessions, or delegations. Former privileged roles must be reassigned explicitly, and ordinary access may stay blocked until privileged cleanup is acknowledged.

Already-downloaded files and actions already sent upstream cannot be recalled; Headways terminates server-side authority rather than claiming offline erasure.

Configuration vs. enforcement

The Admin > SSO page separates three independent ideas so a setup change never locks anyone out by accident:

• Sign-in configuration (provider, domains, tests) makes corporate SSO available. Saving, testing or activating a provider never changes enforcement.
• Require SSO for this organization and Enable SCIM provisioning are separate, default-off switches. Requiring SSO needs a tested active provider and a tested recovery owner; enabling SCIM needs a reviewed reconciliation.
• Access revocation protection is a one-way migration. Enabling it (alone, or with the first switch) makes deactivation take effect across old sessions, personal keys, devices and delegated activity. It has no off switch: turning Require SSO or SCIM off never restores old credentials or re-adopts legacy proof.

Turning either switch off is not a rollback. It stops new enforcement actions only: deactivated members stay blocked, revoked credentials stay revoked, and members must complete a fresh corporate sign-in after reactivation before regaining access. If the only usable provider is removed while managed offboarded members exist, provide a tested replacement or use the scoped recovery process — do not silently drop to optional and strand them.

Recovery access

Designate a non-directory-managed recovery owner using a separate passkey or MFA-protected method. If the active provider breaks, that owner can enter recovery, authenticate freshly, and receive configuration-only access to repair the provider or policy. Enabling required SSO is only safe after the provider and the recovery method have both been tested. Recovery never restores previously offboarded credentials, and removing the last valid provider/recovery path requires an explicit policy change.

Troubleshooting

Related

• Workspace Setup — members, roles, and the CLI
• Configuring Protection Rules — role and approval controls