# 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:

```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.

## How It Works

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

```json
{
  "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
```yaml
keycloak:
  organization: company
  business_unit: business_unit
  team: team
  email: user
```

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

### Azure AD
```yaml
azure_ad:
  companyName: company
  department: business_unit
  jobTitle: team  # Or use groups
  userPrincipalName: user
```

### Google Workspace
```yaml
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:
```yaml
providers:
  custom_idp:
    corp_name: company
    division: business_unit
    squad: team
    username: user
```

## Usage in Code

### Creating a Session

```python
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:
```bash
# Check if policies are loaded for your organization
macaw-cli policy list | grep "company:YourOrg"
```

### Debug Logging

Enable debug logging to see claim mapping:
```python
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.