Docs/Identity/Identity Bridge

Identity Bridge

The Identity Bridge is a universal translator for enterprise identities. It converts JWT tokens from any identity provider into MACAW's canonical internal model, enabling consistent policy enforcement regardless of which IdP your organization uses.

The Problem

Enterprises use different identity providers — Keycloak, Okta, Azure AD, Auth0, Google Workspace. Each has its own JWT structure and claim names. Without a translation layer:

Every app needs IdP expertise

10 apps × 5 providers = 50 integration points to maintain

Inconsistent claim names

Keycloak: organization, Okta: companyName, Azure: tid

Policy fragmentation

Different claim names mean different policy rules per provider

The Canonical Internal Model

MACAW defines a canonical internal model — a standard set of attributes that all identity providers map to. This enables consistent policy enforcement regardless of which IdP issued the JWT.

┌─────────────────────────────────────────────────────────────────┐
│                   ANY IDENTITY PROVIDER                          │
│  Keycloak     │    Okta      │   Azure AD   │   Auth0   │ Google │
│  organization │  org         │   tid        │   org_id  │   hd   │
│  business_unit│  department  │   department │   dept    │   ou   │
│  team         │  division    │   jobTitle   │   team    │ groups │
│  email        │  email       │   upn        │   email   │  email │
│  realm_access │  groups      │   roles      │   roles   │  roles │
│     .roles    │              │              │           │        │
└───────────────────────────┬─────────────────────────────────────┘
                            │ Claims Mapper
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│               MACAW CANONICAL INTERNAL MODEL                     │
│                                                                  │
│   company        → Policy key: company:{value}                   │
│   business_unit  → Policy key: bu:{value}                        │
│   team           → Policy key: team:{value}                      │
│   user           → Policy key: user:{value}                      │
│   roles          → Role-based policy matching                    │
└─────────────────────────────────────────────────────────────────┘

Internal Attribute	Policy Key	Description
company	company:{value}	Organization or company name for top-level policies
business_unit	bu:{value}	Department or division for business unit policies
team	team:{value}	Team or workgroup for team-level policies
user	user:{value}	User identifier (email or subject) for individual policies
roles	—	List of roles for role-based access control

Key Insight

Write your policies once using the canonical model. The Claims Mapper handles the translation from each provider's specific claim names. Your policies work with any IdP.

Claims Mapping

The Claims Mapper translates provider-specific JWT claims to MACAW's canonical model. Each provider has different claim names for the same concepts:

MACAW Attribute	Keycloak	Okta	Azure AD	Auth0
company	organization	org	tid	org_id
business_unit	business_unit	department	department	app_metadata.dept
team	team	division	jobTitle	user_metadata.team
user	email	email	upn	email
roles	realm_access.roles	groups	roles	permissions

Auto-Detection

The Claims Mapper auto-detects the identity provider from the JWT's iss (issuer) claim and applies the correct mapping automatically.

Role Filtering

Configure which roles are allowed and how provider-specific role names map to MACAW role names (e.g., analysts → analyst).

Authentication Flow

User identity flows through the entire system, from your application to AI execution:

┌─────────────────────────────────────────────────────┐
│ YOUR APPLICATION                                     │
│ analyzer.analyze_report("Q4")                        │
│ └── jwt_token from your SSO (Okta, Azure AD, etc.)   │
└───────────────────────────┬─────────────────────────┘
                            │ JWT Token
                            ▼
┌─────────────────────────────────────────────────────┐
│ MACAW ADAPTER (SecureOpenAI, SecureAnthropic, etc.) │
│ Passes JWT to MACAW Client                          │
└───────────────────────────┬─────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────┐
│ IDENTITY BRIDGE                                      │
│ • Validates JWT signature with your IdP             │
│ • Auto-detects provider from issuer                 │
│ • Maps claims → canonical internal model            │
│ • Creates security_context                          │
└───────────────────────────┬─────────────────────────┘
                            │ security_context
                            ▼
┌─────────────────────────────────────────────────────┐
│ POLICY RESOLVER                                      │
│ • Looks up policies for company, bu, team, user     │
│ • Applies monotonic restriction                     │
│ • Returns computed policy for this request          │
└───────────────────────────┬─────────────────────────┘
                            │ User's policies applied
                            ▼
┌─────────────────────────────────────────────────────┐
│ AI EXECUTION (with user's permissions)              │
│                                                     │
│ Alice (Junior): GPT-3.5, 500 tokens, public data   │
│ Bob (Senior):   GPT-4, 2000 tokens, dept data      │
│ Carol (Exec):   Any model, unlimited, full access  │
└─────────────────────────────────────────────────────┘

Identity Preservation

The user's identity flows through the entire workflow. Alice remains "Alice" throughout — no shared service accounts, no identity bleed between users. Every operation is audited with the correct user attribution.

Multi-User Safety

The Identity Bridge uses a stateless, per-request design. Each request creates a fresh security context from the JWT, preventing any possibility of identity bleed.

Concurrent Users on Shared Orchestrator:

Time T1: Alice's Request
┌─────────────┐  alice_jwt  ┌─────────────────┐  security_context  ┌─────────────────┐
│ Alice       │────────────▶│ Shared          │───────────────────▶│ Alice's policies│
│ Request     │             │ Orchestrator    │  {company: "FC",   │ applied         │
└─────────────┘             │                 │   user: "alice"}   └─────────────────┘
                            │ Each request    │
Time T2: Bob's Request      │ creates fresh   │
┌─────────────┐  bob_jwt    │ security_context│  security_context  ┌─────────────────┐
│ Bob         │────────────▶│                 │───────────────────▶│ Bob's policies  │
│ Request     │             │ NO STORED STATE │  {company: "FC",   │ applied         │
└─────────────┘             └─────────────────┘   user: "bob"}     └─────────────────┘

NO identity bleed possible - each request is isolated

Stateful (Dangerous)

- Identity stored on instance
- Later requests could use wrong identity
- Concurrent users interfere

Stateless (MACAW)

- Fresh context per request
- JWT → security_context on every call
- Impossible for interference

Tenant Isolation

Identity Bridge configurations are tenant-specific. Each workspace has its own independent configuration that is not shared with other workspaces.

┌─────────────────────────────────────────────────────────────────┐
│                    MACAW CONTROL PLANE                           │
│                                                                  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │ Workspace A     │  │ Workspace B     │  │ Workspace C     │  │
│  │ ─────────────── │  │ ─────────────── │  │ ─────────────── │  │
│  │ IdP: Keycloak   │  │ IdP: Okta       │  │ IdP: Azure AD   │  │
│  │ Claims: config A│  │ Claims: config B│  │ Claims: config C│  │
│  │ Policies: set A │  │ Policies: set B │  │ Policies: set C │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
│         ▲                    ▲                    ▲              │
│         │                    │                    │              │
│    Admin: alice         Admin: bob          Admin: carol        │
│                                                                  │
│  Each workspace admin configures ONLY their workspace           │
│  No cross-tenant access or configuration sharing                │
└─────────────────────────────────────────────────────────────────┘

What's Isolated

- Identity Provider configuration
- Claims Mapper settings
- Policies and attestations
- Audit logs and activity
- API keys and team members

Admin Scope

- Workspace admins configure their workspace only
- Cannot view or modify other workspaces
- Changes affect only their workspace users
- Complete data isolation between tenants

Console Configuration

Configure the Identity Bridge through the Console at Settings → Identity Bridge. Two sub-tabs handle different aspects of configuration:

Identity Provider

Configure your IdP connection. Use the wizard to select your provider and enter credentials.

- Pick provider: Keycloak, Okta, Azure AD, Auth0
- Enter: server URL, client ID, client secret
- Credentials stored securely server-side

Claims Mapper

Configure how your IdP's claims map to MACAW's canonical model.

- Map claim paths to internal attributes
- Configure role filtering and mapping
- Set up multiple providers if needed

Admin Only

Identity Bridge configuration requires admin access. Non-admin users can view the configuration but cannot modify it. Changes to identity configuration affect all users in the workspace.

Supported Providers

Provider	Protocol	Wizard Support
Keycloak	OIDC	Full wizard
Okta	OIDC	Full wizard
Auth0	OIDC	Full wizard
Azure AD	OIDC	Full wizard
Google Workspace	OIDC	Manual config
Custom OIDC	OIDC	Manual config

SDK Integration

Two approaches for passing user identity to MACAW:

RemoteIdentityProvider (Convenience)

For apps that need to authenticate users directly. Handles login, token refresh, and validation.

python

from macaw_client import RemoteIdentityProvider

idp = RemoteIdentityProvider()
result = idp.login(username, password)
token = result["access_token"]

JWT Token (Direct)

For apps that already have a JWT from your IdP. Pass it directly to adapters.