Enterprise SSO
Setup guides for integrating MACAW with enterprise identity providers. MACAW works with any OIDC/JWT provider—Keycloak, Okta, Azure AD, and more.
Two-Layer Identity Architecture
MACAW uses a two-layer identity model: service identity for MACAW itself, and user identity for runtime requests.
Layer 1: Service Identity (Setup)
Configured via Console. Establishes trust with your identity provider.
Go to Console → Settings → Identity to configure:
- • Provider type (Keycloak, Okta, Azure AD)
- • OAuth/OIDC endpoints
- • Client credentials
- • Claims mapping rules
Layer 2: User Identity (Runtime)
Dynamic per-request identity. Applications pass user JWTs for user-specific policy enforcement.
# Application code
client = SecureOpenAI()
response = client.chat.completions.create(
model="gpt-4",
messages=[...],
jwt_token=user_jwt
)Keycloak Setup
Create MACAW Client
In Keycloak Admin Console, create a new client for MACAW:
Client ID: macaw-service Client Protocol: openid-connect Access Type: confidential Valid Redirect URIs: https://your-app/*
Add Custom Claims
Add mappers for organization attributes:
Mapper Type: User Attribute User Attribute: organization Token Claim Name: organization Claim JSON Type: String Add to ID token: ON Add to access token: ON
Configure Claims Mapping
# .claims-config.yaml
providers:
keycloak:
organization: company
business_unit: business_unit
team: team
email: userOkta Setup
Create Application
In Okta Admin, create a new OIDC application:
Application type: Web Application Sign-in method: OIDC Grant type: Authorization Code Redirect URIs: https://your-app/callback
Add Custom Claims
In Authorization Server → Claims:
Name: companyName Include in: ID Token, Access Token Value type: Expression Value: user.organization
Configure Claims Mapping
# .claims-config.yaml
providers:
okta:
companyName: company
department: business_unit
groups: team
email: userAzure AD Setup
Register Application
In Azure Portal → App registrations:
Name: MACAW Service Supported account types: Single tenant Redirect URI: Web - https://your-app/callback
Configure Token
In Token configuration, add optional claims:
Optional claims → ID token: - companyname - department - jobtitle - upn
Configure Claims Mapping
# .claims-config.yaml
providers:
azure_ad:
companyName: company
department: business_unit
jobTitle: team
userPrincipalName: userTesting Your Integration
1. Test Authentication in Code
Use RemoteIdentityProvider to verify your IDP connection:
from macaw_client.identity import RemoteIdentityProvider
idp = RemoteIdentityProvider()
# Test login
result = idp.login("alice@fintech.com", "password")
print("✓ Login successful")
print(f" Token expires in: {result['expires_in']}s")
# Validate the token
validation = idp.validate(result["access_token"])
print(f"✓ Token valid: {validation['valid']}")
print(f" Claims: {validation['claims']}")2. Test Policy Resolution
Make a real request to verify policy is applied:
from macaw_adapters.openai import SecureOpenAI
client = SecureOpenAI(app_name="sso-test")
# Make a request with user identity
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "Hello"}],
jwt_token=result["access_token"]
)
print("✓ Request succeeded with caller's policy")3. Verify in Console
- Go to Console → Logs
- Find your test request
- Verify the Principal shows the correct user identity
- Check the Policy Applied matches expected policy chain
- Confirm claims were mapped correctly in the request details