Identity Federation Quick Start

Integrate existing identity providers (LDAP, SAML, OIDC) with Keycloak for centralized authentication.

Integrate existing identity providers (LDAP, SAML, OIDC) with Keycloak for centralized authentication.

See ADR-0037 for architecture details.

Identity Federation Protocol Flow

The following diagram shows the detailed protocol flow for federating external identity providers (Azure AD, Okta, Google) through Keycloak, including SAML/OIDC exchanges, token handling, and JWT issuance:

Key Steps in the Federation Flow:

1. External IdP Redirect: User authenticates with their existing identity provider (Azure AD, Okta, Google) using SAML or OIDC
2. Protocol Response: IdP returns SAML assertion (XML) or OIDC authorization code with ID token
3. Signature Validation: Keycloak broker validates signatures and assertions against IdP public keys
4. Claim Extraction: Broker extracts user claims (email, name, roles, groups) from the assertion/token
5. Attribute Mapping: External claims are mapped to Keycloak user attributes using configured mappers
6. Token Exchange: External tokens are exchanged for internal Keycloak user representation
7. Session Creation: Keycloak creates a new user session with federated identity information
8. Session Storage: Session data is persisted to Redis or database for scalability
9. JWT Signing: Keycloak generates and signs a new JWT (access + refresh tokens) using its own keys
10. Client Response: Signed Keycloak JWT is returned to the MCP server for API authentication

Security Considerations:

• Signature Verification: All external tokens/assertions are cryptographically verified
• Token Exchange: External tokens are never passed directly to clients - always exchanged for Keycloak JWTs
• Session Isolation: Federated sessions are isolated from local Keycloak sessions
• Attribute Validation: Mapped attributes are validated against Keycloak schema
• Replay Protection: SAML assertions include timestamp and ID validation to prevent replay attacks

Quick Setup

LDAP/Active Directory

## Set environment variables
export LDAP_CONNECTION_URL='ldap://ad.example.com:389'
export LDAP_BIND_DN='CN=Service Account,OU=Service Accounts,DC=example,DC=com'
export LDAP_BIND_PASSWORD='your-password'
export LDAP_USERS_DN='OU=Users,DC=example,DC=com'
export LDAP_GROUPS_DN='OU=Groups,DC=example,DC=com'

## Run setup script
python scripts/setup/setup_ldap_federation.py

See setup_ldap_federation.py for full documentation.

Google Workspace

## Set credentials
export GOOGLE_CLIENT_ID='your-client-id.apps.googleusercontent.com'
export GOOGLE_CLIENT_SECRET='your-secret'
export GOOGLE_HOSTED_DOMAIN='example.com'  # Optional

## Run setup
python scripts/setup/setup_oidc_idp.py --provider google

See setup_oidc_idp.py for full documentation.

Microsoft 365 / Azure AD

export MICROSOFT_CLIENT_ID='your-app-id'
export MICROSOFT_CLIENT_SECRET='your-secret'
export MICROSOFT_TENANT_ID='common'  # or specific tenant

python scripts/setup/setup_oidc_idp.py --provider microsoft

GitHub

export GITHUB_CLIENT_ID='your-oauth-app-id'
export GITHUB_CLIENT_SECRET='your-secret'

python scripts/setup/setup_oidc_idp.py --provider github

Okta

export OKTA_CLIENT_ID='your-app-id'
export OKTA_CLIENT_SECRET='your-secret'
export OKTA_DOMAIN='example.okta.com'

python scripts/setup/setup_oidc_idp.py --provider okta

ADFS (SAML)

export SAML_ALIAS='adfs'
export SAML_SSO_URL='https://adfs.example.com/adfs/ls/'
export SAML_LOGOUT_URL='https://adfs.example.com/adfs/ls/'

python scripts/setup/setup_saml_idp.py

See setup_saml_idp.py for full documentation.

Authentication Flow

Federated User Login

What Users See

All federated users receive standard Keycloak JWTs:

{
  "iss": "http://keycloak:8180/realms/langgraph-agent",
  "sub": "user:[e-mail]",
  "email": "[e-mail]",
  "given_name": "Alice",
  "family_name": "Smith",
  "realm_access": {
    "roles": ["admin", "premium", "user"]
  }
}

Configuration Details

LDAP Attribute Mapping

Edit config/ldap_mappers.yaml (reference):

attribute_mappers:
  - name: email
    ldap_attribute: mail
    keycloak_attribute: email
  - name: department
    ldap_attribute: department
    keycloak_attribute: department

OIDC Provider Configuration

Edit config/oidc_providers.yaml (reference):

providers:
  google:
    alias: google
    config:
      client_id: ${GOOGLE_CLIENT_ID}
      hosted_domain: ${GOOGLE_HOSTED_DOMAIN}

Testing

Test LDAP Connection

## In Keycloak Admin Console:
## User Federation → ldap → Test connection
## User Federation → ldap → Test authentication
## User Federation → ldap → Synchronize all users

Test OIDC Login

## Visit Keycloak account console
https://keycloak.example.com/realms/langgraph-agent/account

## Click "Sign in with Google" (or other provider)
## Complete OAuth2 flow
## Verify user is created in Keycloak

Verify JWT Issuance

## After federated login, get JWT
curl -X POST http://localhost:8080/auth/login \
  -d '{"username": "[e-mail]", "password": "federated-password"}'

## Should return Keycloak-issued JWT

Troubleshooting

LDAP Connection Failed

Check:

• LDAP URL is accessible from Keycloak pod
• Bind DN and password are correct
• Users DN exists
• Firewall allows LDAP traffic (port 389/636)

SAML Metadata Import Failed

Solutions:

• Download SAML metadata from IdP
• Import manually in Keycloak Admin Console
• Verify SAML signature algorithm matches (RSA-SHA256)

OIDC Provider Not Found

Check:

• Client ID and secret are correct
• Redirect URI is configured in external IdP
• Scopes are correct (openid profile email)

References

• ADR: ADR-0037: Identity Federation
• LDAP Setup: scripts/setup/setup_ldap_federation.py
• SAML Setup: scripts/setup/setup_saml_idp.py
• OIDC Setup: scripts/setup/setup_oidc_idp.py
• Configuration: config/ldap_mappers.yaml, config/oidc_providers.yaml