Skip to main content

Self-Service Federation Lock

This document explains the architectural concepts behind the Self-Service Federation Lock in Framework M, focusing on why it is enforced, the security validations behind it, and how the flow matches the Single Source of Truth design.

1. Concept: Single Source of Truth​

When an application operates in Federated Mode (Mode B/Mode C, where users authenticate via external corporate providers like Okta, Keycloak, or Azure AD), the external identity provider is the Single Source of Truth (SSoT) for user data.

If users were allowed to update their profile info (such as email, full name, or phone number) directly inside Framework M:

  • It would create data drift: changes would not sync back upstream to the corporate IdP.
  • On the next social login, the JIT provisioning mechanism would see mismatching data, causing identity linking conflicts or reverting the user's edits with fresh upstream token data.

To prevent this drift, Framework M enforces a complete lock on local self-service inputs whenever the user is logged in via a federated strategy.

2. Redirection and UI Context Locks​

Redirection to Upstream​

If an authenticated user has an active federated session (e.g. upstream_profile_url is populated in their context from the active OIDC provider configuration block):

  1. In the frontend Desk shell, the standard profile editing fields are locked and rendered as read-only.
  2. The UI renders a prominent "Edit Profile on [Provider]" button that points to the configured upstream_profile_url.
  3. If the user attempts to directly hit the profile update API endpoints (e.g. PUT /api/v1/auth/me), the web adapter rejects the request immediately with 405 Method Not Allowed or 400 Bad Request.

3. Verification Sequence Diagrams​

Email Verification Loop (Local Mode)​

For local accounts, updating email requires verifying ownership first to prevent hijacking and spam database pollution.

Email Verification Sequence

Phone (OTP) Verification Loop (Local Mode)​

Phone verification uses SMS gateways for verification-driven updates.

Phone Verification Sequence