Skip to main content
authenticationfederationoidcsamlidentitynamespacesecurity
Status: DraftAuthor: Jacob ReppCreated: Apr 13, 2026Updated: Apr 13, 2026

RFC-064: Federation Profile for Namespace-Aware Identity

Summary​

This RFC defines how Prism supports external identity federation without weakening the proxy and namespace contract established in RFC-063: Normative Proxy Auth Contract and Namespace Security Model.

It covers:

  • OIDC as the preferred federation profile
  • SAML as a supported enterprise federation profile
  • stable subject construction across providers
  • namespace-aware IdP selection
  • session bridging from external identity assertions into Prism-native backend tokens

This RFC does not redefine Prism into a general identity platform. It defines the safe federation boundary for a namespace-oriented data access gateway.

Motivation​

Prism needs to support more than Dex and local OIDC development flows. Enterprise adoption requires:

  • multiple OIDC providers
  • SAML support for enterprise IdPs
  • clear tenant and namespace mapping rules
  • predictable subject identity semantics across providers

The previous RFC-063 draft attempted to combine this with SCIM provisioning and service vendoring. That made the trust model unclear. Federation needs its own RFC because identity mapping mistakes propagate directly into authorization.

Goals​

  1. Make OIDC the default external federation path.
  2. Support SAML where enterprise constraints require it.
  3. Define a stable canonical subject format for all external providers.
  4. Define namespace-aware provider selection without relying on email equality.
  5. Define how external assertions become Prism sessions and backend tokens.

Non-Goals​

  • Building a custom IdP
  • Defining SCIM provisioning
  • Defining arbitrary cross-tenant account linking
  • Replacing the RFC-063 backend token model

Decision​

1. OIDC Is Preferred, SAML Is Supported​

Prism SHOULD prefer OIDC providers for new integrations because OIDC aligns better with JWT-based proxy validation and session establishment.

Prism MUST support SAML for enterprise environments that require it, but SAML assertions are an input to session establishment, not a durable Prism identity format by themselves.

2. Canonical Subjects Are Issuer-Scoped​

Prism MUST derive a stable subject identifier from provider identity plus issuer context.

Examples:

  • oidc:auth0|abc123
  • oidc:okta|00u123abc
  • saml:corp-okta|a94d...

Email MAY be stored as an attribute, but MUST NOT be used as the canonical identity key for linking or authorization.

3. Namespace Configuration Chooses Allowed Providers​

Each namespace MAY declare one or more allowed federation providers. The namespace policy determines:

  • which providers are allowed
  • provider priority
  • whether the namespace permits human identities, service identities, or both
  • whether fallback across providers is allowed

Provider fallback is a login-routing mechanism, not an identity-equivalence mechanism.

If the same human authenticates through two providers and no explicit link exists, Prism MUST treat those as two distinct subjects for authorization.

Example:

namespace: digital-twin-prod

auth:
  providers:
    - name: corporate-okta
      type: oidc
      priority: 1
    - name: vendor-saml
      type: saml
      priority: 2
  subject_policy:
    link_mode: explicit
    canonical_format: issuer_scoped

4. Session Bridging Produces Prism-Native Tokens​

External federation does not flow directly to backends.

The required flow is:

  1. Prism validates the OIDC token or SAML assertion.
  2. Prism resolves the issuer-scoped subject.
  3. Prism evaluates namespace authorization via Topaz.
  4. Prism creates a Prism-native session.
  5. Prism mints backend tokens per RFC-063.

This keeps backend trust anchored in Prism-native proof rather than arbitrary external token formats.

Architecture​

Federation Flow​

External IdP
   │
   │ OIDC token or SAML assertion
   ▼
Prism Proxy
   │
   ├─ Validate issuer-specific rules
   ├─ Resolve canonical subject
   ├─ Map namespace-allowed provider
   ├─ Authorize via Topaz
   └─ Mint Prism-native session + backend token

Provider Rules​

OIDC providers MUST define:

  • issuer URL
  • JWKS source
  • audience rules
  • required claims
  • clock skew tolerance

SAML providers MUST define:

  • metadata source
  • signing requirements
  • attribute mapping
  • audience and recipient validation rules
  • replay and expiry controls

Identity Linking Rules​

Identity linking is a privileged administrative operation, not an automatic side effect of login.

Prism MUST support the following modes:

  1. disabled
  2. explicit-admin-link
  3. explicit-user-link with policy approval

Prism MUST NOT support automatic account linking based only on:

  • email address equality
  • display name equality
  • group name equality

Namespace Authorization Semantics​

Federation does not grant access by itself. A successful login only identifies the subject.

Authorization still requires:

  • namespace membership or relationship in Topaz
  • requested operation mapping
  • any additional policy checks

This means the same user may authenticate successfully but still be denied for a namespace.

If a namespace enables multiple providers, it MUST choose one of these authorization models:

  1. bind each provider subject independently
  2. require explicit subject linking before equivalent access is granted across providers

Prism MUST NOT infer equivalent access merely because provider fallback is enabled.

Security Considerations​

Subject Confusion​

If two providers can mint identities with the same email address, automatic linking creates privilege escalation risk. Issuer-scoped subjects avoid this.

Provider Drift​

Per-namespace provider configuration can drift over time. Audit logs MUST record which external provider produced each Prism session.

SAML Complexity​

SAML support increases validation complexity and configuration risk. For that reason, OIDC remains the preferred profile.

Implementation Plan​

Phase 1​

  1. Add issuer-scoped canonical subject resolution in the proxy.
  2. Refactor Dex/local OIDC support to fit the provider model.
  3. Add namespace-level allowed-provider configuration.

Phase 2​

  1. Add production OIDC providers such as Auth0, Okta, and Azure AD.
  2. Add provider-specific validation tests and negative tests.
  3. Add audit fields for provider, issuer, and subject source.

Phase 3​

  1. Add SAML provider support.
  2. Add session bridging from SAML assertions to Prism-native sessions.
  3. Add explicit identity linking workflows if still required.

Phase 4​

  1. Add subject-provider mapping to backplane for identity tracking.
  2. Add check_link_mode and record_subject_provider to InMemoryBackplane.
  3. Wire federation policy enforcement into connection handler.
  4. Add x-prism-auth-method header extraction for SAML hinting.
  5. Update authorization policies to use issuer-scoped subjects.
  6. Add 12 end-to-end federation integration tests.

Status: DONE

Test Results:

  • backplane: 3 new tests (federation policy, link mode, subject provider)
  • oidc: 7 tests (slug generation, registry, SAML interop)
  • saml: 12 tests (validation, replay, recipient, JSON parsing)
  • main: 8 tests (header stripping, injection, normative headers)
  • auth: 2 tests (namespace policy, authorization with issuer-scoped IDs)
  • federation_integration: 12 end-to-end tests

What Remains: All Phase 4 items complete.

Revision History​

  • 2026-04-13: Initial draft split from RFC-063 foundation work