Identity Providers & Federation
Summary
Identity Providers and Federation enables Keymate to authenticate users through external identity sources. Keycloak extensions provide custom identity provider implementations that integrate with government identity systems, enterprise directories, and social login providers while maintaining tenant-scoped federation and consistent user attribute mapping.
Why It Exists
Organizations authenticate users through various external systems:
- Government identity portals for citizen authentication
- Enterprise directories (LDAP, Active Directory) for employee access
- Social providers (Google, Microsoft) for consumer applications
- Partner identity systems for B2B scenarios
Each provider has unique authentication flows, attribute schemas, and security requirements. Identity provider extensions standardize these integrations, providing consistent user attribute mapping, authentication level validation, and audit logging across all federation scenarios.
Where It Fits in Keymate
Identity providers operate within Keycloak's authentication infrastructure. When a user authenticates through an external provider, the identity provider extension:
- Redirects to the external authentication endpoint
- Receives and validates the authentication response
- Maps external attributes to Keycloak user attributes
- Creates or links the user account
- Emits audit events for compliance tracking
Boundaries
What it covers:
- Custom identity provider implementations
- OAuth 2.0, OIDC, and SAML federation
- User attribute mapping from external sources
- Authentication level validation
- First broker login flows
What it does not cover:
- Session synchronization with external systems (see Session Sync)
- Keycloak realm configuration (see Keycloak documentation)
- Token claim customization (see Token & Session)
How It Works
Identity Provider Types
Keycloak supports multiple identity provider protocols:
| Protocol | Use Case |
|---|---|
| OAuth 2.0 | Modern web applications, API-based authentication |
| OIDC | Standard identity federation with ID tokens |
| SAML 2.0 | Enterprise SSO, legacy integrations |
Configuration Model
Each identity provider requires configuration for:
| Element | Description |
|---|---|
| Client credentials | Client ID and secret from the external provider |
| Endpoints | Authorization, token, and userinfo URLs |
| Scopes | Requested permissions and data access |
| Attribute mappers | Rules for mapping external attributes to Keycloak |
Attribute Mapping
Identity provider extensions map external attributes to Keycloak user profiles:
| Mapping Type | Behavior |
|---|---|
IMPORT | Map attributes on first login only |
FORCE | Update attributes on every login |
INHERIT | Use default realm attribute mapping |
Authentication Level Validation
For providers that support authentication levels (such as government identity systems), extensions validate that the authentication meets minimum requirements:
| Level | Description |
|---|---|
| Basic | Username and password |
| Enhanced | Multi-factor authentication |
| High assurance | Hardware tokens or biometrics |
First Broker Login Flow
When a user authenticates through an identity provider for the first time:
- User creation — Keycloak creates a new user if no matching account exists
- Account linking — Keycloak links the external identity to the user account
- Profile review — Optional step for users to verify or complete their profile
- Required actions — Keycloak enforces password setup or other required actions
Diagram
Example Scenario
Scenario
An organization configures a government identity provider for citizen authentication. Users authenticate through the external portal and are automatically provisioned in Keycloak with mapped attributes.
Input
- Actor: Platform administrator
- Resource: Identity provider configuration
- Action: Configure external identity provider
- Context: Government OAuth 2.0 provider with multi-factor authentication
Expected Outcome
- Administrator configures identity provider with client credentials and endpoints
- Attribute mappers translate government attributes to Keycloak user profile
- Users authenticate through the external portal
- Keycloak creates user accounts with mapped attributes on first login
- The extension validates authentication level before granting access
- The system records audit events for all authentication activities
Common Misunderstandings
- Identity providers handle authorization — Identity providers only authenticate users. Keymate's policy engine handles authorization decisions.
- All attributes sync automatically — Only attributes with configured mappers synchronize. The system does not import unmapped attributes.
External identity providers must register Keycloak's redirect URI before authentication works. The redirect URI follows the pattern: https://{keycloak-host}/realms/{realm}/broker/{provider-alias}/endpoint
Design Notes / Best Practices
- Configure attribute mappers to import only necessary user data
- Use
IMPORTsync mode to preserve local profile changes - Validate authentication levels for sensitive applications
- Enable audit logging for compliance requirements
- Test federation flows in a non-production environment first
Use Keycloak's first broker login flow to enforce password setup for users who authenticate exclusively through external providers.
Related Use Cases
- Government identity integration for citizen services
- Enterprise SSO with corporate directories
- Partner federation for B2B applications
- Social login for consumer applications