Central Identity Broker Architecture

Identity Federation

QueryTek Tapestry acts as a neutral identity broker between enterprise Identity Providers (IdPs) and partner platforms. Inbound enterprise protocols use managed upstream federation (Keycloak). Tapestry normalizes identity into a canonical claims model, then routes users to partner applications through registered outbound adapters — with strict multi-tenant isolation.

Hybrid broker posture (ADR-068 Option B): cross-protocol journeys are composition (upstream inbound + Tapestry session + outbound adapter), not a single in-process protocol codec.

Identity Brokering Model

Tapestry implements a central identity broker pattern to simplify partner integrations and ensure consistent identity handling across platform boundaries.

Inbound Federation

Enterprise → Tapestry

  • Accepts SAML 2.0 and OIDC enterprise IdPs via tenant federation connections
  • Managed upstream federation (Keycloak) — enterprise SAML wire terminates upstream
  • Tapestry receives OIDC authorization-code callbacks only (no edge ACS)
  • Multi-tenant IdP configuration per tenant

Canonical Claims

Internal Representation

  • Vendor-neutral identity normalization at the Identity Broker boundary
  • Minimized attribute surface area
  • Tenant-scoped subject identifiers
  • Role and permission mapping

Outbound Federation

Tapestry → Partner

  • Partner-specific outbound handoffs (OIDC SSO JWT, SAML Response) via registered adapters
  • Partner-specific claim mapping
  • Short-lived signed tokens or assertions where adapters ship
  • Fail-closed routing on identity errors

Shipped Cross-Protocol Journeys

These journeys combine mismatched inbound and outbound protocols without a second interactive login at the partner when adapters are configured. Evidence: P7-086 journey matrix.

Journey Inbound Outbound Pilot partner Status
J1 Enterprise SAML IdP (Keycloak broker) OIDC SSO JWT Textmetrics Shipped
J2 Enterprise OIDC IdP SAML Response (HTTP-POST) Trusaic PayParity Shipped

Deferred Journeys

The following cross-protocol journey is on the roadmap but not yet evidenced in staging E2E. This page does not claim it as shipped.

  • J3 (Deferred): Enterprise SAML IdP inbound → Trusaic SAML outbound — composition of shipped legs; staging browser evidence pending

Supported Protocols

Tapestry supports both major enterprise SSO protocols at the federation boundary:

  • SAML 2.0: Enterprise standard — inbound via upstream Keycloak broker
  • OIDC: Modern OAuth 2.0-based identity layer — inbound callback and outbound adapters
  • Cross-protocol journeys: See Shipped Cross-Protocol Journeys table above (J1, J2)

Identity Normalization

All inbound identity is normalized into a canonical claims model at the Identity Broker boundary:

  • tenant_id: Multi-tenant isolation scope
  • subject_id: Stable per-tenant user identifier
  • email: Primary contact and audit trail
  • display_name: User-friendly representation
  • roles: Tenant-scoped authorization

Security Properties

Identity handling enforces strict security and privacy controls:

  • Short-lived tokens with expiration enforcement
  • Signed outbound assertions where partner adapters ship (e.g. Trusaic SAML pilot)
  • OIDC token validation at the Tapestry callback boundary
  • No cross-tenant credential exposure

Canonical Claims Model

The Canonical Claims Envelope defines the internal identity representation used for routing, policy enforcement, and audit logging throughout Tapestry.

Claim Required Description
tenant_id ✓ Stable identifier for the customer tenant (Tapestry tenant)
subject_id ✓ Stable per-tenant user identifier (canonical subject)
email ✓ Primary user email (normalized to lowercase)
display_name Human-readable name
given_name First name component
family_name Last name component
roles Array of role strings (tenant-scoped)

Identity Federation Flow

Step 1: Enterprise Authentication

User initiates authentication through their enterprise IdP:

  • User accesses launch URL for partner application
  • Tapestry redirects to tenant's configured federation connection
  • Enterprise IdP authenticates user (SAML or OIDC flow)
  • For enterprise SAML: authentication terminates at the upstream Keycloak broker; Tapestry receives an OIDC authorization-code callback
  • For enterprise OIDC: Tapestry receives an OIDC callback directly from the federation provider

Step 2: Claims Normalization

Tapestry Identity Broker normalizes inbound claims:

  • Validates OIDC token from the federation callback; upstream broker validates enterprise SAML
  • Extracts identity attributes from the normalized callback payload
  • Maps to canonical claims model
  • Applies tenant-specific attribute mappings
  • Creates Tapestry session with normalized identity

Step 3: Partner Routing

Routing Orchestrator evaluates partner launch request:

  • Retrieves partner configuration from registry
  • Validates tenant-partner enablement
  • Applies routing policy and context rules
  • For Textmetrics OIDC launch, mints a short-lived signed SSO token via the partner adapter
  • Redirects the user to Textmetrics with the SSO token for seamless entry
  • For Trusaic SAML launch (pilot), builds a signed SAML Response and HTTP-POST handoff via the partner adapter
  • Other partners may still receive registry redirect URLs until their outbound adapters ship

Multi-Tenant Isolation

Identity federation enforces strict tenant boundaries to prevent data leakage:

  • Tenant-scoped subject identifiers
  • Isolated IdP configurations per tenant
  • No cross-tenant identity correlation
  • Tenant boundary validation in all APIs

Partner Adapters

Each partner integration uses an adapter pattern for protocol-specific handling:

  • Canonical claims → partner claim mapping
  • Protocol selection per partner registry (OIDC SSO JWT, SAML Response)
  • Partner-specific signing where adapters ship
  • Context channel metadata injection

Observability

Comprehensive logging and monitoring for identity operations:

  • Authentication success and failure events
  • Partner adapter handoffs and claim mapping events
  • Partner routing decisions and outcomes
  • Token lifecycle (issuance, refresh, expiration)

Architectural Decisions

Our identity federation architecture reflects deliberate design choices optimized for enterprise interoperability, security, and operational reliability.

Protocol Strategy

  • Multi-protocol federation support (SAML and OIDC)
  • Hybrid broker posture (ADR-068): composition of upstream inbound + session + outbound adapters
  • Vendor-neutral canonical claims model
  • Standards-based authentication

Identity Model

  • Centralized claim normalization
  • Minimized attribute surface
  • Tenant isolation enforcement
  • Auditable identity lifecycle

Federation Architecture

  • Managed provider integration
  • Consistent routing semantics
  • Short-lived credential patterns
  • Continuous compliance alignment

Related Integrations

Integration Patterns

Enterprise IdP Onboarding

  • SAML metadata exchange
  • OIDC client registration
  • Custom attribute mapping configuration
  • Multi-IdP support per tenant

Partner Integration

  • Protocol capability declaration
  • Claim requirement specification
  • Certificate and key exchange
  • Sandbox testing and certification

Operational Roadmap

Not yet shipped — tracked separately from current federation pilots:

  • Automated SAML certificate rotation and metadata refresh
  • Platform-operated JWKS lifecycle automation
  • Partner configuration versioning tooling

Last reviewed: 2026-07-21 (P7-086). Identity federation architecture maintained by Engineering and Security teams. Public claims on this page are gated by automated checks (QDR-023) against shipped runtime posture.