TenantAtlas/specs/137-platform-provider-identity/spec.md

Feature Specification: Platform Provider Identity Standardization

Feature Branch: 137-platform-provider-identity
Created: 2026-03-13
Status: Draft
Input: User description: "Spec 137 — Platform Provider Identity Standardization"

Spec Scope Fields (mandatory)

• Scope: tenant
• Primary Routes:
  • Microsoft provider onboarding wizard and connection setup flows under workspace-admin and tenant-admin surfaces
  • Microsoft admin consent start and callback flow
  • Provider connection detail, verification, and re-consent screens
  • Advanced dedicated-override management screens for authorized operators
• Data Ownership:
  • The canonical platform provider identity is platform-managed and centrally configured; it is not copied into tenant-owned records
  • provider_connections remain tenant-owned operational records describing tenant target, consent state, verification state, and connection type
  • provider_credentials remain tenant-owned only for explicit dedicated connections
  • Legacy tenant credential fields remain legacy inspection and migration inputs only until later cleanup
• RBAC:
  • Workspace membership remains required for all provider connection management flows
  • Tenant entitlement remains required before a tenant-scoped provider connection can be viewed, created, verified, or changed
  • Standard connection creation and consent retry require the normal provider-connection management capability
  • Dedicated override, dedicated credential management, and connection-type changes require a stronger dedicated-management capability and remain unavailable to unauthorized roles

User Scenarios & Testing (mandatory)

User Story 1 - Self-service platform onboarding (Priority: P1)

As a tenant operator, I want the standard Microsoft onboarding flow to use the platform-managed app automatically so that I can connect my tenant by granting consent without entering application credentials.

Why this priority: This is the product-default path and directly removes the current onboarding fragility and support burden.

Independent Test: Can be fully tested by starting a new Microsoft connection from the onboarding wizard, confirming that the flow creates a platform connection, shows the platform app identity read-only, asks only for admin consent, and completes verification without storing per-connection credentials.

Acceptance Scenarios:

1. Given an authorized operator starts a new Microsoft connection in the standard onboarding flow, When the connection is created, Then the connection type is set to platform and no manual credential fields are required.
2. Given a platform connection is awaiting consent, When the operator opens the consent action, Then the generated consent link uses the canonical platform app identity.
3. Given consent succeeds for a platform connection, When the operator runs verification, Then the connection can proceed without any tenant-specific credential record.

---

User Story 2 - Runtime and consent stay on one identity (Priority: P1)

As a platform maintainer, I want consent generation and runtime credential resolution to use the same identity source for platform connections so that the product cannot drift into a hybrid app model.

Why this priority: The core defect is identity drift between consent and runtime. If this is not fixed centrally, onboarding and operations remain unreliable.

Independent Test: Can be fully tested by exercising consent-link generation, callback completion, runtime verification, and provider operations for a platform connection while asserting that the same effective app identity is used end to end and that tenant-local credential fallbacks are rejected.

Acceptance Scenarios:

1. Given a platform connection exists, When any runtime component resolves credentials, Then it uses the centralized platform identity and does not read tenant-local credential sources.
2. Given a platform connection has granted consent, When a provider operation or verification starts, Then the resolved effective app identity matches the identity used for consent.
3. Given legacy tenant-local app fields or dedicated credential rows still exist, When a platform connection resolves identity, Then those legacy values do not become silent fallbacks.

---

User Story 3 - Dedicated stays explicit and protected (Priority: P2)

As a workspace owner or specially authorized admin, I want dedicated customer-specific app registrations to remain possible as an advanced override so that legitimate enterprise exceptions are supported without becoming the normal path.

Why this priority: Dedicated connections are required for some enterprise cases, but they must be intentionally controlled to preserve the SaaS governance model.

Independent Test: Can be fully tested by enabling the dedicated override path for an authorized user, confirming that the UI clearly labels it as an exception, requires explicit selection, accepts dedicated credentials only there, and blocks unauthorized users from accessing the path.

Acceptance Scenarios:

1. Given the dedicated override is not enabled for the current user, When they use the standard onboarding flow, Then they cannot access dedicated credential entry or dedicated connection creation.
2. Given an authorized operator intentionally selects dedicated mode, When they create or edit the connection, Then the connection stores dedicated credential metadata and runtime uses that dedicated identity only.
3. Given a dedicated connection is missing required credentials, When runtime verification or provider operations start, Then the system blocks the action with an explicit dedicated-credential reason.

---

User Story 4 - Existing hybrid tenants are migrated safely (Priority: P2)

As an operator responsible for existing customer tenants, I want legacy and hybrid provider connections to be classified explicitly so that existing environments can be standardized without silent breakage.

Why this priority: Existing connections may already work only because of contradictory sources. Safe migration requires visibility, not implicit rewrites.

Independent Test: Can be fully tested by running the classification path against representative platform-like, dedicated, and hybrid legacy connections and verifying that each receives the correct migration outcome and follow-up behavior.

Acceptance Scenarios:

1. Given an existing connection already behaves like a platform connection, When migration classification runs, Then it is explicitly marked platform.
2. Given an existing connection intentionally depends on customer-specific credentials, When migration classification runs, Then it is explicitly marked dedicated.
3. Given an existing connection mixes consent and runtime identities, When migration classification runs, Then it is flagged for operator review instead of being silently converted.

Edge Cases

• A platform connection may have granted consent but still fail verification because permissions, service principal presence, or tenant reachability are broken.
• A dedicated credential row may exist from legacy history for a connection that should now be platform and must not be auto-consumed.
• A consent callback may arrive for a connection that was created in one state but has stale or contradictory legacy metadata.
• An operator may retry consent after consent was revoked or after verification previously failed, and the UI must keep consent and verification states separate.
• A hybrid legacy tenant may have tenant-local app fields and provider credential rows that disagree on app identity and cannot be auto-classified safely.
• Platform secret rotation must not require tenant-by-tenant rewrites or produce tenant-scoped audit artifacts that imply secrets were copied.

Requirements (mandatory)

Constitution alignment (required): This feature changes Microsoft provider identity resolution for onboarding, consent, verification, and runtime operations. All Microsoft Graph access continues to flow through the canonical Graph client path and existing contract registry entries; this spec does not permit any new direct Graph endpoint shortcuts. Provider connection creation, connection-type changes, consent initiation, dedicated credential lifecycle changes, and migration reclassification are write behaviors and therefore require server-side authorization, audit logging, and focused tests. Verification and preflight flows that already run as operational work must continue to respect tenant isolation, observable run identity, and explicit failure reason handling.

Constitution alignment (OPS-UX): This feature does not require the admin consent callback itself to create a new long-running run record, but any verification, preflight, or provider-operation flows that create or reuse an OperationRun must keep the existing Ops-UX 3-surface contract intact: queued toast only, active progress only in the approved progress surfaces, and one terminal initiator-only DB notification. Any OperationRun.status or OperationRun.outcome transition remains service-owned through OperationRunService. Any updated verification summary metrics must keep using approved numeric summary keys only. System-initiated verification remains auditable through Monitoring without tenant-wide completion notifications. Regression coverage must guard that provider identity changes do not reintroduce direct OperationRun lifecycle writes or ad-hoc completion notifications.

Constitution alignment (RBAC-UX): This feature affects workspace-admin /admin/... and tenant-context /admin/t/{tenant}/... provider connection management flows. Cross-plane access to /system remains deny-as-not-found. Non-members or actors lacking tenant entitlement must receive deny-as-not-found for tenant-scoped provider connection reads, consent retries, verification starts, dedicated override access, and credential mutations. Members lacking the required capability must receive forbidden on execution. Authorization must remain server-side for connection creation, connection-type changes, consent retry, verification start, dedicated credential create or rotate, and migration overrides. Capability checks must use the canonical capability registry only. Global search must remain tenant-safe and must not reveal inaccessible provider connections. Destructive or security-sensitive actions such as deleting dedicated credentials or switching connection type away from dedicated must require confirmation. Tests must include both positive and negative authorization coverage, including stronger gating for dedicated mode.

Constitution alignment (OPS-EX-AUTH-001): The Microsoft admin consent handshake may continue to perform synchronous outbound identity-provider exchanges on auth-oriented callback endpoints without creating an OperationRun. This exception applies only to the consent handshake itself and must not be reused for Monitoring or other operational pages.

Constitution alignment (BADGE-001): This feature introduces or clarifies operator-visible status semantics for connection type, consent status, verification status, and health status. Those labels and badge meanings must stay centralized so the same values render consistently across onboarding, detail views, tables, and verification surfaces. Coverage must confirm that new consent and verification states do not create ad-hoc badge mappings.

Constitution alignment (UI-NAMING-001): Operator-facing copy must consistently use product vocabulary such as Platform connection, Dedicated connection, Grant admin consent, Run verification again, and Managed centrally by platform. The same terms must be preserved across wizard steps, detail headers, action labels, confirmation text, status messaging, notifications, and audit prose. Internal implementation terms such as resolver, fallback, or payload must not become primary operator-facing labels.

Constitution alignment (Filament Action Surfaces): This feature modifies existing Filament resources and pages for provider onboarding and connection management. The Action Surface Contract is satisfied. Provider connection list and detail surfaces keep inspection affordances, visible actions remain limited and grouped, empty states explain the platform-default path, and sensitive credential or connection-type mutations remain confirmation-gated and audited.

Constitution alignment (UX-001 — Layout & Information Architecture): In-scope Filament create and edit flows must present platform-default onboarding in structured sections, with the platform app identity displayed read-only and no manual credential fields in the standard path. Detail views must separate connection type, consent, verification, health, and effective app identity in sectioned presentation. Empty states must explain why no provider connection exists yet and offer a single primary CTA to start standard onboarding. Tables and detail pages must expose the core dimensions needed for support and operations without collapsing consent, verification, and health into one field.

Functional Requirements

• FR-137-01 Platform default: The system must default every newly created standard Microsoft provider connection to connection type platform.
• FR-137-02 Required connection type: Every provider connection must store a non-null connection type with allowed values platform or dedicated.
• FR-137-03 Central platform identity source: The system must resolve the platform Microsoft app identity from one canonical centrally managed source and must not duplicate the platform secret or app identity into tenant-owned connection or credential rows.
• FR-137-04 Canonical identity resolver: The system must expose one canonical provider-identity resolution path that selects the effective identity strictly from connection type.
• FR-137-05 No platform fallback: For platform connections, the resolver must not silently fall back to tenant-local app fields, provider credential payloads, or other legacy per-tenant identity sources.
• FR-137-06 Dedicated-only credential usage: Dedicated credentials must be required and used only when the connection type is dedicated.
• FR-137-07 Canonical consent builder: All Microsoft admin consent links must be generated from one canonical builder so that every surface uses the same app identity source for the same connection.
• FR-137-08 Platform consent identity: For platform connections, consent links must always use the central platform app identity.
• FR-137-09 Dedicated consent identity: For dedicated connections, consent links must use the explicitly associated dedicated app identity.
• FR-137-10 Standard onboarding UX: The standard onboarding wizard must not ask operators to enter application credentials and must instead show the platform app identity as read-only along with consent and verification guidance.
• FR-137-11 Dedicated override UX: Dedicated mode must appear only in an explicitly labeled advanced or enterprise override path and only for authorized users.
• FR-137-12 Callback state integrity: A successful admin consent callback must create or update the provider connection with an explicit connection type and must not leave the connection appearing operational when the required identity source is missing or incomplete.
• FR-137-13 Separate state model: The connection model must represent consent status separately from verification or health status so that granted consent does not automatically imply operational readiness.
• FR-137-14 Runtime identity parity: Runtime verification, preflight, and provider operations must resolve the same effective app identity that the connection type implies.
• FR-137-15 Platform operational readiness: A platform connection must be able to reach operational readiness without any per-connection credential row.
• FR-137-16 Dedicated operational readiness: A dedicated connection must be blocked from operational readiness until its dedicated credential requirements are satisfied.
• FR-137-17 Legacy read restriction: Legacy tenant-local app identity fields may be read only for migration analysis, operator review, or explicit dedicated reclassification and must not remain the standard source for new provider flows.
• FR-137-18 No implicit mode switch: The system must never silently switch a connection from platform to dedicated or from one effective app identity to another as an error fallback.
• FR-137-19 Migration classification: Existing connections must be explicitly classified into platform, dedicated, or review-required migration outcomes before final legacy cleanup.
• FR-137-20 Review-required protection: Hybrid or contradictory legacy connections must surface a review-required outcome that blocks silent automatic conversion.
• FR-137-21 Audit coverage: The system must audit provider connection creation, connection-type changes, consent start and result, consent revocation detection, verification result, dedicated credential lifecycle events, and migration classification outcomes.
• FR-137-22 Audit payload minimums: Audit events for this feature must include workspace, tenant, provider, connection identifier, connection type, actor or system actor, prior and new state where applicable, and the triggering source or reason.
• FR-137-23 Dedicated authorization: Dedicated mode enablement, dedicated credential management, and connection-type changes to or from dedicated must require a distinct dedicated-management capability that is stronger than standard platform connection management and is not implicitly granted wherever basic provider-management access exists.
• FR-137-24 Connection detail clarity: Provider connection detail views must clearly display connection type, consent status, verification status, health status, effective app identity, and credential source.
• FR-137-25 Platform detail redaction: Platform connection detail views must present the effective platform app identity as centrally managed and must never show a secret value.
• FR-137-26 Dedicated detail metadata: Dedicated connection detail views must show dedicated credential source and relevant lifecycle metadata such as rotation timing or expiry when available.
• FR-137-27 Guard coverage: Regression guards must fail if platform consent or runtime paths begin reading tenant-local app fields or dedicated credential payloads as silent fallbacks.
• FR-137-28 End-to-end parity tests: The test suite must cover standard platform onboarding, dedicated override, callback behavior, runtime identity resolution, migration classification, and explicit negative cases for missing consent or missing dedicated credentials.

Non-Goals

• Removing all legacy tenant credential columns immediately
• Migrating the platform identity from client secret to certificate in this spec
• Designing a full sovereign or government-cloud provider model
• Generalizing the provider identity model beyond Microsoft in this spec
• Redesigning all customer self-service permission flows beyond what is needed for platform-default onboarding and dedicated override protection

Assumptions

• The product continues to operate as an enterprise SaaS platform with one canonical Microsoft platform app as the normal tenant-connection model.
• Existing verification and provider-operation flows already exist and will be aligned to the new identity rules rather than replaced wholesale.
• Some legacy tenant records may contain contradictory app identity data and therefore require operator review rather than automatic migration.
• Platform secret storage may remain config-backed initially, with future movement to a central secret store without changing the tenant-facing model.

Dependencies

• Existing provider connection onboarding, consent callback, verification, and provider-operation flows
• Existing canonical Microsoft Graph client and contract registry path
• Existing workspace and tenant authorization enforcement for provider connections
• Existing audit logging infrastructure for connection and credential events
• Existing operation observability for verification or preflight jobs where those flows already run asynchronously

Contract Interpretation

• The OpenAPI artifact for this feature defines a logical internal action contract for provider-connection create, consent, verification, connection-type, and dedicated-credential mutations.
• These contract operations may be satisfied by existing Filament or Livewire action handlers and existing controller endpoints; the spec does not require new standalone public web routes where an existing authorized surface already fulfills the contract semantics.
• Destructive dedicated-credential deletion remains in scope as a first-class contract operation even when it is triggered from a Filament action rather than a new controller-only route.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Microsoft onboarding wizard	Workspace-admin and tenant-admin onboarding flow	Start connection	Step-based wizard flow	None	None	Start Microsoft connection	Re-enter wizard only where already supported	Continue and Cancel	Yes	Standard path shows platform app identity read-only and no credential inputs.
Provider connection list	Provider connection resource list surfaces	New connection	Record click-through to detail	View, More	Existing grouped bulk actions only if already supported	Connect Microsoft tenant	View, Retry consent, Run verification, More	Edit only when allowed; standard path has no manual credential entry	Yes	Dedicated-only actions stay grouped and authorization-gated.
Provider connection detail	Provider connection detail surface	Retry consent, Run verification	Detail sections	Edit, More	None	Not applicable	Retry consent, Run verification, Manage dedicated override where allowed	Save and Cancel on edit screens	Yes	Detail view must separate connection type, consent, verification, health, effective app ID, and credential source.
Dedicated override management	Advanced or enterprise-only provider connection settings	Enable dedicated mode where allowed	Detail view and explicit entry point only	Manage credentials, More	None	Not applicable	Rotate credential, Delete credential, Revert connection type where allowed	Save and Cancel	Yes	Sensitive actions require confirmation and stronger dedicated-management authorization.

Key Entities (include if feature involves data)

• Platform Provider Identity: The centrally managed Microsoft application identity that supplies the effective app ID, authority context, redirect configuration, and secret reference for standard platform connections.
• Provider Connection: The tenant-owned record that represents a tenant’s Microsoft connection state, including connection type, consent status, verification status, and operational health.
• Provider Credential: The tenant-owned credential record used only for explicit dedicated connections and never for the standard platform path.
• Connection Type: The explicit mode selector that determines whether a connection uses the central platform identity or an approved dedicated customer-specific identity.
• Consent State: The record of whether the customer tenant has granted, revoked, failed, or still requires admin consent.
• Verification State: The record of whether technical validation and operational readiness checks have succeeded independently of consent.
• Migration Classification Outcome: The explicit migration result that identifies an existing connection as platform, dedicated, or requiring operator review because of contradictory legacy identity sources.

Success Criteria (mandatory)

Measurable Outcomes

• SC-137-01 Standard onboarding simplification: In focused onboarding coverage, 100% of new standard Microsoft connection flows complete without asking the operator for application credentials.
• SC-137-02 Identity parity: In focused consent and runtime regression coverage, 100% of covered platform scenarios use the same effective app identity for consent generation and runtime resolution.
• SC-137-03 No silent fallback: In focused negative coverage, 100% of covered platform scenarios reject tenant-local or dedicated credential fallback sources instead of silently using them.
• SC-137-04 Dedicated containment: In focused authorization and UX coverage, 100% of covered dedicated scenarios require explicit opt-in and stronger authorization before dedicated credentials can be created or used.
• SC-137-05 State clarity: In covered onboarding and detail-view scenarios, operators can distinguish consent status from verification or health status without relying on a single mixed status field.
• SC-137-06 Migration safety: In focused migration coverage, 100% of representative existing connections are classified into platform, dedicated, or review-required outcomes without silent hybrid conversion.
• SC-137-07 Audit completeness: In focused mutation coverage, every covered connection-type, consent, verification, credential, and migration change produces an auditable event with the required tenancy and actor context.