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

Operations App SSO Migration Procedure

1. Purpose

This document describes the recommended migration procedure for enabling Enterprise SSO in the Operations App, including:

  • steps customers must follow in their Identity Provider (IdP),

  • steps Services / Support must follow in the Operations App,

  • expected user behavior during migration,

  • warnings, risks, and rollback considerations.

The procedure is designed to support progressive, low-risk migration, without service disruption or uncontrolled user creation.

2. Key Principles (Important to Communicate Early)

Before starting, all stakeholders must understand:

  • SSO is enabled progressively, not in bulk.

  • Users are created only when they log in (JIT provisioning).

  • Email is used for discovery, not identity.

  • Identity binding happens only after successful SSO login.

  • Disabling users is explicit and reversible.

  • No billing or licensing logic is changed by this migration.

3. Migration Phases (High-Level)

  1. Preparation

  2. SSO Configuration

  3. Pilot Users

  4. Gradual Rollout

  5. Enforcement

  6. Optional De-Provisioning (SCIM)

Each phase is independent and reversible.

4. Phase 1 — Preparation

Critical: Automatic User Creation via SSO

When SSO is enabled for the Operations App, new users may be created automatically the first time they successfully authenticate via SSO (Just-In-Time provisioning).

This means:

  • Any user who can authenticate via the configured IdP and matches the SSO routing rules may gain access to the Operations App.

  • Users do not need to be manually pre-created in the Operations App.

Customer responsibility

It is the customer’s responsibility to:

  • Control which users in the IdP are eligible to authenticate (e.g. assignments, access policies).

  • Review and disable existing Operations App users who should no longer have access.

  • Monitor newly created users during rollout to ensure access remains appropriate.

Failure to clean up obsolete local users may result in:

  • unintended access,

  • inflated user counts,

  • confusion during audit or support activities.

Critical: depending on the current billing model, make sure to count the ENABLED users (instead of just users).

4.1 Customer Responsibilities (IdP)

Customers must:

  • Identify the IdP to be used (Azure AD, Okta, etc.).

  • Ensure each Operations App user has:

    • a stable IdP identifier (sub / persistent NameID),

    • a valid email address (recommended).

  • Decide whether:

    • all users will migrate at once, or

    • migration will be phased by team or role.

Important

  • Users do not need to be pre-created in the Operations App.

  • IdP group membership alone does not create Operations App users.
    Users are created only after a successful SSO login (Just-In-Time provisioning)

When SSO-related user fields (e.g. auth_mode, account_state) are introduced, existing Operations App users are initialized with safe defaults under the hood at deployment/migration time. This does not change login behavior and does not require any customer or Services action.

4.2 Services Team Responsibilities (Ops App)

Before enabling SSO:

  • Review existing Operations App users:

    • Identify users without email.

    • Identify users that should never use SSO (service accounts, test users).

  • Communicate clearly:

    • users will continue to log in locally until instructed otherwise,

    • no immediate change occurs when SSO config is created.

5. Phase 2 — SSO Configuration

5.1 Services Team — Create SSO Configuration

In the Operations App:

  1. Create a new SSO configuration.

  2. Select target audience:

    • Operator (Operations App).

  3. Select an Operations User template:

    • This defines permissions for future JIT users only.

  4. Configure IdP metadata, certificates, endpoints.

  5. Save the configuration.

✔️ At this stage:

  • No user behavior changes.

  • No users are created.

  • No users are blocked.

5.2 Validation Checklist

Before proceeding:

  • Only one SSO configuration should match a given email domain (or other discovery rule).

  • No ambiguity exists in routing.

  • Services team confirms routing determinism using test identifiers.

6. Phase 3 — Pilot Users

6.1 Services Team — Prepare Pilot Users

For existing users who will pilot SSO:

  1. Ensure the user has an email set (if blank).

  2. Set auth_mode = SSO_PREFERRED.

This allows:

  • SSO attempt first,

  • safe local fallback.

⚠️ Do not set SSO_REQUIRED yet.

6.2 Pilot User Instructions (Client-Facing)

Users are instructed to:

  1. Go to the Operations App login page.

  2. Enter their email (recommended) or username.

  3. If redirected to the IdP:

    • authenticate as usual.

  4. If not redirected:

    • log in with existing username/password.

On first successful SSO login:

  • their account becomes permanently linked to the IdP,

  • no further action is required.

7. Phase 4 — Gradual Rollout

7.1 Services Team

Repeat for additional users or groups:

  • Populate email if missing.

  • Set auth_mode = SSO_PREFERRED.

Monitor:

  • SSO Event Log (runtime observability).

  • Binding success/failure.

  • Provisioning failures (for new users).

7.2 Handling New Users

For users not yet in the Operations App:

  • They are created automatically only when they log in via SSO.

  • Permissions are assigned via the selected Operations User template.

  • No local password is created by default.

This prevents:

  • overnight creation of hundreds of users,

  • uncontrolled billing growth.

8. Phase 5 — Enforcement (Optional)

Once confidence is high:

8.1 Services Team

For selected users or groups:

  • Change auth_mode to SSO_REQUIRED.

Pre-flight validation ensures:

  • routing is deterministic,

  • users are not locked out.

After this:

  • local login is no longer allowed,

  • SSO becomes mandatory.

⚠️ Warning

  • Do not enforce SSO_REQUIRED unless users have already logged in successfully via SSO at least once, or routing is guaranteed.

9. Phase 6 — Optional De-Provisioning (SCIM)

9.1 When to Enable SCIM De-Provisioning

Only after:

  • SSO migration is stable,

  • users are reliably linked,

  • customer understands disable semantics.

9.2 Services Team — Configuration

  1. Enable SCIM integration on the SSO configuration.

  2. Set scim_deprovisioning_enabled = true.

  3. Provide SCIM endpoint and credentials to the customer.

9.3 De-Provisioning Behavior (Important to Explain)

When a user is removed or disabled in the IdP:

  • If the user exists and is SSO-linked:

    • their Operations App account is disabled.

  • If the user:

    • never logged in,

    • or was never SSO-linked:

    • the SCIM request is a no-op.

Disabled users:

  • cannot log in (local or SSO),

  • remain visible,

  • can be re-enabled manually if needed.

10. Warnings and Attention Points

Identity & Matching

  • Email changes in IdP do not affect linkage.

  • Usernames may change without impact.

  • Only (issuer, subject) matters.

Admin Actions

  • Admins cannot “fix” linkage manually.

  • Admins cannot force identity binding.

  • Re-enabling users does not remove linkage.

Observability

  • Audit Trail ≠ Runtime Event Log.

  • Use:

    • Audit Trail for configuration & admin actions.

    • SSO Event Log for login failures, binding issues, provisioning errors.

11. Risks and Mitigations

Risk

Mitigation

User lockout

Use SSO_PREFERRED before SSO_REQUIRED

Ambiguous routing

Blocked deterministically; fix config before rollout

Too many users created

JIT provisioning only

IdP cleanup disables wrong users

SCIM applies only to SSO-linked users

Debugging failures

Always-on runtime SSO Event Log
 

12. Rollback Strategy

At any time:

  • Set users back to LOCAL_ONLY.

  • Disable SSO configuration.

  • Disable SCIM de-provisioning flag.

No user data is lost; no identity linkage is removed.

13. Final Notes for Services Team

  • Never rush enforcement.

  • Always test with pilot users.

  • Check observability before assuming user error.

  • SSO linkage is permanent; treat first login carefully.