Configuring Claims Mapping

MACAW integrates with any enterprise identity provider (Keycloak, Okta, Azure AD, etc.) by mapping external JWT claims to internal attributes used for policy resolution.

Quick Start

Edit .claims-config.yaml to map your identity provider's claims to MACAW's internal model:

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.

How It Works

1. JWT Authentication

Your application authenticates users with your identity provider (Keycloak, Okta, etc.) and receives a JWT with claims:

{
  "email": "alice@company.com",
  "organization": "FinTech Corp",
  "business_unit": "Analytics",
  "team": "Reporting"
}

2. Claims Mapping

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

organization → company
business_unit → business_unit
team → team
email → user

3. Policy Resolution

The PolicyResolver uses these attributes to find applicable policies:

• company:FinTech Corp - Organization-wide policies
• bu:Analytics - Business unit policies
• team:Reporting - Team policies
• user:alice@company.com - User-specific policies

Internal Attributes

MACAW uses these 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  # Organizational unit
  groups: team
  email: user

Adding a New Provider

1. Identify your provider's claim names
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

Example for a custom provider:

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

Usage in Code

Creating a Session

from macaw.identity.session_manager import SessionManager

# JWT claims from your identity provider
jwt_claims = {
    "sub": "12345",
    "email": "alice@fintech.com",
    "organization": "FinTech Corp",
    "business_unit": "Analytics",
    "team": "Reporting"
}

# Create session (claims are automatically mapped)
session = session_manager.create_session(jwt_claims)

Context Flow

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

The mapped attributes flow automatically through MACAW's security pipeline:

1. SessionManager reads .claims-config.yaml
2. Claims are mapped to internal attributes
3. Attributes are stored in session context
4. PolicyResolver uses them for policy lookup

Troubleshooting

Claims Not Mapping

Check that:

1. Claim names match exactly (case-sensitive)
2. Provider name matches JWT's iss field
3. .claims-config.yaml is in project root

Missing Policies

Verify policies exist for the mapped values:

# Check if policies are loaded for your organization
macaw-cli policy list | grep "company:YourOrg"

Debug Logging

Enable debug logging to see claim mapping:

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

Future Extensions

Currently not supported (planned for future):

• Nested claim extraction (e.g., profile.department)
• Array indexing (e.g., groups[0])
• Claim transformations
• Conditional mappings
• Regular expression patterns

For now, only flat claim mappings are supported.

Security Considerations

• The .claims-config.yaml file should be read-only in production
• Internal model section is documentation only and cannot affect runtime
• Unknown providers pass through claims unchanged (no mapping)
• Missing claims are ignored (no error thrown)

---

Copyright MACAW Security. All rights reserved.