Identity Provider Configuration

Deployments integrate enterprise identity providers using standard patterns: OAuth 2.0 / OIDC, SAML SSO, directories (SCIM optionally), and session-backed browsers aligned to your security posture. Cascades does not require a specific commercial IdP—you choose OIDC-compliant services (Azure AD Entra ID, Google Workspace OIDC), SAML gateways, Okta, Keycloak, or similar stacks as your organization adopts them.

Reference builds of Cascades ship with libraries suitable for OIDC-hosted login flows (Auth0’s Next.js SDK is one workable pattern in the codebase today—you can substitute other OIDC gateways as integrations mature).

Canonical Auth0 identifiers (reference)

When using Auth0 as the OIDC provider, align dashboards and APIs with:

• API audience: https://cascades.work/api — set AUTH0_AUDIENCE to this Auth0 API identifier in production (NODE_ENV=production). In development, AUTH0_AUDIENCE is optional; omitting it skips the OAuth audience parameter (relaxed local login).
• Custom claim namespace: https://cascades.work — use /roles (array or string) and optional /org_id for organization scoping. The application resolves ADMIN vs USER from these claims.

Architectural expectations

• External identity — Assertions map to Cascades tenant users (subject, tenant/organization scopes, MFA upstream).
• Session layer — HttpOnly cookie sessions anchored to issuer metadata; refresh/revoke follows your IdP TTL.
• Role claims — Map provider groups or entitlement claims onto Cascades dashboards (ADMIN, entitlement-sensitive routes).
• Logout — End sessions at Cascades and coordinate IdP SAML/OIDC logout when required.

Compatibility notes for common stacks:

Concrete env variable names appearing in Cascades deployments often mirror AUTH0_*-style placeholders derived from OIDC issuer metadata—they should be generalized to your chosen issuer (Auth0-compatible deployments today should not imply mandatory Auth0 SKU selection).

Example reference surfaces (today’s codebase)

Certain builds wire session middleware (middleware.ts), server auth clients (lib/auth0.ts-style wrappers), /api/auth0/session JSON for SPA hydration—not because “Auth0” is fixed, but because they demonstrate verifiable integrations you can refactor toward your issuer.

Validation checklist (before GA)

1. Login redirects traverse your IdP and return with expected claims.
2. Logout terminates Cascades cookie sessions (+ IdP where applicable).
3. Refreshing dashboards preserves authenticated principals.
4. Protected routes bounce unauthenticated callers to login.
5. Admin operators require uplifted entitlement claims—not default fallthrough.

Additional IdPs beyond the shipped adapters remain an integration exercise—map claims to Cascades roles accordingly.