Docs/Identity/Claims Mapping

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

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