Okta SSO & SCIM Integration for Enterprise Health & Wellness Platform

We implemented Okta SSO via SAML 2.0/OIDC for authentication and SCIM 2.0 for automated user provisioning, deprovisioning, and group synchronization — integrated into the existing multi-tenant backend.

Architecture

• Identity Provider: Okta (customer-managed tenants)
• SSO Protocol: SAML 2.0 (primary) + OIDC (alternative)
• Provisioning: SCIM 2.0 server built into the platform backend
• Backend: NestJS with PostgreSQL and Redis
• Auth Layer: JWT-based sessions with SSO-aware token issuance
• Admin Dashboard: React-based tenant configuration for SSO setup
• Existing Auth: Email/password + Google OAuth preserved alongside SSO

---

SSO Implementation (SAML 2.0 / OIDC)

SAML 2.0 Flow

The SP-initiated SAML flow works as follows: the user visits the login page and selects SSO, enters their company email domain, the platform identifies the tenant's Okta configuration from the domain, sends an AuthnRequest to Okta, the user authenticates, Okta returns a signed SAML assertion, the platform validates the assertion and creates a session with JWT tokens.

Per-Tenant Configuration

Each tenant's SSO is configured with their identity provider's SSO URL, entity ID, X.509 certificate for signature validation, along with the platform's SP entity ID, assertion consumer service URL, and attribute mappings from identity provider profile fields to platform user fields.

OIDC Alternative

For customers preferring OIDC over SAML, the platform supports Authorization Code flow with PKCE, using the same attribute mapping via OIDC claims and ID token validation with JWKS.

Multi-Tenant SSO Routing

The platform routes users to the correct identity provider based on their email domain. When a user enters their email, the platform looks up the domain against tenant SSO configurations. If SSO is configured, the user is redirected to their organization's Okta tenant. If not, they fall back to email/password or Google OAuth. Vanity URLs are also supported for direct SSO access. ---

SCIM 2.0 Implementation

SCIM Server

The platform exposes a SCIM 2.0 compliant API that Okta calls to manage users and groups. The API supports full user lifecycle operations (create, read, update, deactivate, delete), group CRUD with membership management, and standard SCIM discovery endpoints for capabilities, schemas, and resource types.

User Lifecycle via SCIM

Provisioning:

When an admin assigns a user to the platform app in Okta, Okta sends a create request to the SCIM API. The platform creates the user account with tenant association, marks them as active and SSO-provisioned, and the user can immediately log in via SSO.

Profile Updates:

When an admin updates a user's profile in Okta, the changes are pushed to the platform via SCIM. If department changes, group membership is re-evaluated automatically.

Deprovisioning:

When a user is removed from the app in Okta, the platform deactivates the account — revoking all active sessions immediately, preventing further login, retaining data per retention policy, and freeing the license seat.

Reactivation:

Re-assigning a user in Okta reactivates their account with all historical data intact.

Group Synchronization

Okta groups map to platform roles and program tiers — controlling access to different feature levels, admin capabilities, specialized dashboards, and exclusive program enrollments. Group membership changes in Okta are pushed via SCIM and reflected in real-time without requiring re-login. ---

Security & Authentication

Token Issuance After SSO

After SAML assertion validation, the platform issues tenant-scoped JWTs with claims for user identity, organization, roles (derived from SCIM group membership), authentication method, and identity provider — enabling audit differentiation between SSO and other auth methods.

Session Management

• SSO sessions respect Okta's session lifetime
• Single Logout (SLO) supported for session termination when user logs out of Okta
• Back-channel logout webhook for immediate session revocation
• SCIM deactivation revokes all active sessions within 60 seconds

Security Controls

• SAML response signature validation against tenant's X.509 certificate
• Assertion replay prevention via one-time-use tracking
• Clock skew tolerance for assertion timestamp validation
• Audience restriction validation
• Encrypted assertions supported for sensitive deployments
• SCIM endpoint authentication via per-tenant Bearer tokens
• Rate limiting on SCIM endpoints

---

Admin Configuration Dashboard

Tenant SSO Setup

The admin dashboard provides a self-service setup flow:

1. Protocol Selection — Choose SAML 2.0 or OIDC
2. Metadata Upload — Upload IdP metadata XML (auto-populates configuration)
3. Attribute Mapping — Map identity provider profile fields to platform user fields
4. Domain Verification — Verify ownership of email domain(s) for SSO routing
5. Test Connection — Initiate test SSO login before enabling for all users
6. SCIM Setup — Generate Bearer token for SCIM provisioning configuration
7. Group Mapping — Map identity provider groups to platform roles and tiers

The dashboard also provides downloadable SP metadata for easy identity provider app configuration. ---

Key Features

1. SAML 2.0 + OIDC Support — Flexible protocol choice per tenant
2. SCIM 2.0 Provisioning — Automated user creation, updates, and deactivation
3. Group-to-Role Mapping — Identity provider groups control platform access tiers and programs
4. Instant Deprovisioning — SCIM deactivation revokes access within 60 seconds
5. Multi-Tenant SSO Routing — Email domain-based IdP discovery across tenants
6. Coexisting Auth Methods — SSO alongside email/password and Google OAuth
7. Self-Service Setup — Admin dashboard for SSO configuration without engineering support
8. Single Logout — Platform session terminated when user logs out of identity provider
9. Audit Trail — Every SCIM operation and SSO event logged for compliance
10. SCIM Group Sync — Real-time role and program changes from identity provider group membership