Claims Mapping

Configure how JWT claims from your identity provider map to MACAW's internal attributes. Different providers use different claim names—the claims mapper handles the translation.

Quick Start

Edit .claims-config.yaml in your project root to map your identity provider's claims:

.claims-config.yaml

providers:
  your_provider:
    your_org_claim: company
    your_dept_claim: business_unit
    your_team_claim: team
    your_user_claim: user

That's it! MACAW will automatically use these mappings when creating sessions from JWT tokens.

Internal Attributes

MACAW uses 4 core attributes for hierarchical policy resolution:

Attribute	Description	Policy Key
company	Organization or company	company:{value}
business_unit	Department or division	bu:{value}
team	Team or workgroup	team:{value}
user	User identifier	user:{value}

Provider Examples

Keycloak

keycloak:
  organization: company
  business_unit: business_unit
  team: team
  email: user

Okta

okta:
  companyName: company
  department: business_unit
  groups: team    # Uses first group
  email: user

Azure AD

azure_ad:
  companyName: company
  department: business_unit
  jobTitle: team    # Or use groups
  userPrincipalName: user

Google Workspace

google:
  hd: company     # Hosted domain
  ou: business_unit  # Org unit
  groups: team
  email: user

How It Works

JWT Authentication

Your app authenticates users with your IDP and receives a JWT with claims.

Claims Mapping

MACAW's SessionManager uses .claims-config.yaml to map claims to internal attributes.

Policy Resolution

PolicyResolver uses attributes to find applicable policies at each hierarchy level.

JWT Claims → SessionManager → Claims Mapper → Session Context → PolicyResolver

The token's claims are also values your identity provider attests. A policy can require them directly, such as a role or a scope, with a claim-based attestation.

Adding a Custom Provider

1.Identify your provider's claim names from a sample JWT
2.Add a new section under providers in .claims-config.yaml
3.Map each claim to the appropriate internal attribute
4.Test with a sample JWT

Custom Provider Example

providers:
  custom_idp:
    corp_name: company
    division: business_unit
    squad: team
    username: user

Troubleshooting

Claims Not Mapping

• Claim names must match exactly (case-sensitive)
• Provider name must match JWT's iss field
• .claims-config.yaml must be in project root

Enable Debug Logging

import logging
logging.getLogger("macaw.identity").setLevel(logging.DEBUG)

Claims Mapping

Quick Start

Internal Attributes

Provider Examples

How It Works

JWT Authentication

Claims Mapping

Policy Resolution

Adding a Custom Provider

Troubleshooting

Claims Not Mapping

Enable Debug Logging

Related Topics

JWT & Security Context

Enterprise SSO

Delegated Authentication

Policies