Runtime Sync
Summary
Runtime Sync enables real-time synchronization of user data, credentials, and events between Keycloak and external systems. Through Keycloak SPI extensions, Runtime Sync propagates changes to external systems when users update their passwords, modify their profiles, or perform authentication actions — maintaining consistency across integrated platforms.
Why It Exists
Enterprise environments often maintain user data in multiple systems:
- Legacy identity systems that predate Keycloak adoption
- External workforce management platforms
- Partner systems requiring credential synchronization
- Compliance systems requiring real-time event feeds
Without runtime synchronization:
- Password drift — Users update passwords in Keycloak, but external systems retain old credentials
- Attribute inconsistency — Profile changes in Keycloak are not reflected elsewhere
- Audit gaps — Authentication events are not captured by external compliance systems
Runtime Sync addresses these challenges through event-driven synchronization that propagates changes in real time.
Where It Fits in Keymate
Runtime Sync operates through Keycloak's Service Provider Interface (SPI) mechanism. Extensions register as event listeners and sync providers, receiving callbacks when relevant events occur.
Boundaries
What it covers:
- Password synchronization to external systems
- User attribute synchronization
- Authentication event propagation
- Non-blocking sync with graceful failure handling
What it does not cover:
- Session lifecycle synchronization (see Session Sync)
- Batch user migration (see Legacy IAM Parallel Run)
- Identity provider federation (see Identity Providers & Federation)
How It Works
Sync Provider Model
Sync providers implement a standard interface for credential synchronization:
| Method | Trigger | Purpose |
|---|---|---|
| Password Sync | Password update | Propagate new credentials to external systems |
| Attribute Sync | Profile update | Propagate attribute changes |
| Event Notify | Any Keycloak event | Forward events to external listeners |
Non-Blocking Design
Runtime Sync operates in a non-blocking manner:
- User performs an action in Keycloak (e.g., password update)
- Keycloak completes the action locally
- Sync providers receive callbacks asynchronously
- External sync failures do not block the original operation
- The system logs failures for monitoring and manual intervention
This design ensures that external system availability does not affect Keycloak operations.
User Targeting
Sync providers support selective synchronization based on user attributes:
| Attribute | Purpose |
|---|---|
| Sync enabled | Flag indicating whether sync is active for this user |
| User type | Classification determining sync behavior |
| External ID | Identifier in the external system |
Configuration
Sync providers use environment variables for configuration:
| Parameter | Description |
|---|---|
| Sync enabled | Global toggle for sync functionality |
| External API URL | Endpoint for external system API |
| Default user type | Default classification for new users |
Event Types
The following events trigger sync provider callbacks:
| Event | Sync Action |
|---|---|
| Password update | Credential sync |
| Profile update | Attribute sync |
| Login success | Event notification |
| Login failure | Event notification |
| Logout | Event notification |
Diagram
Example Scenario
Scenario
A user updates their password in Keycloak. The password sync provider propagates the new credential to an external workforce system.
Input
- Actor: End user updating password
- Resource: Password sync provider
- Action: Password change
- Context: User has sync enabled attribute set to true
Expected Outcome
- Password updates successfully in Keycloak
- Sync provider receives password change callback
- Provider checks user eligibility (sync enabled, correct user type)
- Provider sends credential update to external system API
- The system logs success or failure
- User can log in with new password regardless of sync result
Common Misunderstandings
- Sync failure blocks user actions — Sync operations are non-blocking. Users can continue even if external sync fails.
- All users sync automatically — Only users with sync enabled attributes participate in synchronization.
- Sync is bidirectional — Runtime Sync is typically unidirectional (Keycloak → external). Reverse sync requires separate mechanisms.
External system failures do not prevent Keycloak operations, but they create credential drift. Monitor sync failure logs and implement alerting for prompt intervention.
Design Notes / Best Practices
- Mark users for sync explicitly using user attributes
- Monitor sync failure rates and response times
- Implement retry logic in external system integrations
- Use meaningful user type classifications
- Log all sync operations for audit trails
Configure alerting on sync failure patterns to detect external system outages before they cause widespread credential drift.
Related Use Cases
- Password synchronization with legacy identity systems
- Real-time event feeds to compliance platforms
- Attribute propagation to HR systems
- Credential sync for partner access management