Skip to content
English
Contact us
  • There are no suggestions because the search field is empty.

PRD: Enterprise Single Sign On (SSO) in Operations App (web)

1. Problem Statement

The Operations App currently relies on local authentication (username/password) and lacks:

  • enterprise-grade SSO support,

  • a safe migration path from local auth to SSO,

  • deterministic identity matching,

  • lifecycle management for SSO users,

  • observability into SSO behavior and failures.

Enterprises require:

  • SSO with their Identity Provider (IdP),

  • controlled rollout (not bulk user creation),

  • deterministic login behavior,

  • safe de-provisioning when users leave,

  • auditability and runtime visibility.

The solution must:

  • reuse existing SSO infrastructure (Client Portal),

  • avoid introducing identity ambiguity,

  • protect against accidental user explosion,

  • be robust under partial rollout and migration.

2. Goals

Primary Goals

  • Enable SSO for Operations App users using existing SSO infrastructure.

  • Support progressive migration (local → SSO).

  • Ensure deterministic identity resolution.

  • Support Just-In-Time (JIT) provisioning only.

  • Provide clear audit and runtime observability.

  • Support IdP-driven de-provisioning without provisioning.

Explicit Non-Goals

  • No bulk provisioning from IdP.

  • No SCIM-based user creation or updates.

  • No implementation or modification of billing or licensing logic.

    This initiative introduces an explicit user account state (ENABLED / DISABLED); downstream systems (e.g. billing or licensing) are expected to interpret “active users” based on account state rather than user record existence, but such systems are out of scope for this PRD.

  • No redesign of authentication protocols.

  • No admin-controlled identity linkage.

3. Core Design Principles

3.1 Durable Identity

  • Only (issuer, subject) is a durable identity key.

  • Email and username are mutable discovery attributes, not identity.

3.2 Determinism

At every step:

  • exactly one path is chosen (local, SSO, or blocked),

  • ambiguity is explicitly blocked,

  • no silent fallback in restricted modes.

3.3 Safety by Default

  • JIT provisioning only (no overnight user creation).

  • SCIM is de-provisioning only.

  • Disabled users are blocked before authentication.

  • Templates grant permissions, never identity.

4. Actors and Permissions

Actors

  • Operations App user

  • Privileged Operations App user

  • System / IdP integration

Key Permissions

  • SSO configuration administration (existing)

  • Change user login mode

  • Enable/disable user accounts

No permission exists to:

  • manually create SSO linkage,

  • edit (issuer, subject).

5. High-Level Architecture

Components

  • Shared SSO configuration module

  • Operations App user model

  • Login routing service

  • SSO success handling

  • Audit trail

  • Runtime SSO event log

  • SCIM integration (de-provisioning only)

6. SSO Configuration

6.1 Target Audience

Each SSO configuration selects a target audience:

  • Operator (Operations App)

  • Internet user (Client Portal)

The target audience:

  • determines which application may consume the configuration,

  • determines which user templates may be selected,

  • does not alter protocol or flow.

This PRD applies only to users who authenticate into the Operations App UI; Internet Users that exist solely for API access (e.g. “API Users” used for usage/credit accounting) are out of scope and do not participate in SSO, login routing, or user lifecycle behavior defined here.

6.2 User Templates

  • Templates grant permissions only.

  • Templates are applied only during JIT provisioning.

  • Templates do not participate in identity matching.

7. Operations App User Model

Fields

  • username

  • email (optional, normalized, unique, write-once)

  • auth_mode (LOCAL_ONLY, SSO_PREFERRED, SSO_REQUIRED)

  • account_state (ENABLED, DISABLED)

  • durable SSO linkage: (issuer, subject)

Defaults

  • Existing users:
    auth_mode = LOCAL_ONLY, account_state = ENABLED

  • JIT users:
    account_state = ENABLED, auth_mode = system default

Defaults for existing users are applied once at deployment/migration time when the user model is extended; this is an internal initialization and not a configurable setting.

Defaults for JIT-provisioned users are assigned by the Operations App at provisioning time. The default auth_mode used for JIT provisioning is an application-defined constant and is not configurable per SSO configuration or user template.

8. Login UX

Identifier-First Flow

  1. Identifier step (username or email)

  2. Routing decision (backend)

  3. Authentication step (local or SSO)

If the user is DISABLED:

  • login is blocked immediately,

  • no password prompt,

  • no SSO redirect.

SSO Authentication UX Clarification

When SSO is selected by login routing, the Operations App delegates authentication entirely to the customer’s Identity Provider using standard SSO protocols (OIDC or SAML).

The Operations App does not collect, process, or transmit IdP credentials.
All authentication steps, including any MFA challenges or step-up verification, are rendered and enforced by the Identity Provider.

9. Login Routing Rules

Existing User

  1. If DISABLED → block.

  2. LOCAL_ONLY → local auth.

  3. SSO_PREFERRED / SSO_REQUIRED:

    • if deterministic SSO config exists → SSO,

    • else:

      • SSO_REQUIRED → block,

      • SSO_PREFERRED → local fallback.

No Existing User

  • If deterministic SSO config selected → allow SSO (JIT later).

  • Else → invalid credentials behavior.

Ambiguity is always blocked.

10. SSO Success Flows

10.1 Existing Linked User

  • Resolve by (issuer, subject)

  • Establish session

  • No profile changes

10.2 Existing Unlinked User (First-Time Bind)

  • Only after successful SSO

  • Persist (issuer, subject)

  • Collision → fail

  • Disabled → fail

10.3 No Existing User (JIT Provisioning)

  • Create user with template permissions

  • No local credentials

  • Bind (issuer, subject)

  • Set auth_mode to system default

  • Email stored if provided (write-once)

Failures leave no partial state.

10.4 Post-Login User Experience and Identity Management

After successful login (local or SSO), the Operations App session behavior is identical regardless of authentication method.

Identity ownership and mutability rules are as follows:

  • Durable identity is based exclusively on the stored SSO linkage (issuer, subject).

  • Username and email are not used to re-resolve or switch identities after login.

  • Email is used only for initial discovery and routing and is not editable after being set.

  • Username may be modified by a privileged Operations App user and does not affect SSO linkage or identity resolution.

Changing mutable attributes (e.g. username) does not and cannot “move” a user to a different SSO identity.
If a user’s SSO-linked identity no longer matches expectations, administrative correction requires explicit user management actions (e.g. disablement and re-provisioning), not attribute edits.

Password management behavior:

  • For SSO-authenticated users, password reset and credential management are handled exclusively by the Identity Provider.

  • The Operations App does not provide password reset flows for SSO-required users.

  • Local password reset remains available only for users permitted to authenticate locally.

Visibility:

  • Privileged Operations App users can view SSO enablement and linkage status per user via the user management UI.

  • No UI exists to modify or repair SSO linkage manually.

11. Failure Handling

  • Governed strictly by auth_mode

  • No silent downgrade

  • No partial linkage or provisioning

  • Disabled users never fall back

12. User Management Guardrails

  • Email:

    • write-once,

    • does not affect linkage.

  • SSO_REQUIRED cannot be enabled unless routing is deterministic.

  • No admin-initiated linkage.

  • No implicit re-enablement.

13. Visibility and Audit

13.1 SSO Status (Per User)

  • Local only

  • SSO enabled (not linked)

  • SSO linked

  • Account state shown alongside

13.2 Audit Trail

Captures:

  • SSO config changes

  • auth_mode changes

  • account_state changes

  • first-time binding

  • JIT provisioning

Audit is administrative, not runtime.

14. Runtime SSO Observability

An always-on SSO Event Log:

  • captures successes and failures,

  • includes routing, binding, provisioning stages,

  • stores identifiers as non-reversible fingerprints,

  • searchable per SSO configuration.

This is not the audit trail.

15. Account State

  • DISABLED blocks all authentication paths.

  • Disable/enable is permission-gated and audited.

  • Identity and linkage remain intact.

16. SCIM De-Provisioning

Scope

  • Disable only

  • No provisioning, no updates.

Rules

  • Operates only on SSO-linked users.

  • Identity resolution uses (issuer, subject) only.

  • Non-existent or unlinked users → no-op.

  • Gated by per-SSO-config flag:
    scim_deprovisioning_enabled.

Safety

  • Idempotent

  • Audited

  • Observable

  • Cannot re-enable users