Session Sync

Summary

Session Sync enables bi-directional session synchronization between Keycloak and external systems through the External Session Provider extension. It implements a hierarchical session model with parent-child relationships, allowing external systems to map their sessions to Keycloak's session lifecycle and enabling coordinated session termination across systems.

Why It Exists

Enterprise environments often have multiple systems that maintain their own session states. When a user authenticates through Keycloak, external systems (legacy applications, microservices, third-party integrations) may create their own sessions. Without synchronization:

• Session lifecycle mismatch: A user logs out of Keycloak, but their session in the external system remains active, creating a security gap.
• No visibility: Administrators cannot see the full session tree across systems.
• Manual coordination: Session revocation requires touching each system individually, leading to inconsistent enforcement and audit gaps.

The External Session Provider solves these problems by maintaining a session mapping table that links external session identifiers to Keycloak sessions, enabling cascade termination and unified session visibility.

Where It Fits in Keymate

Session Sync operates as a Keycloak SPI extension deployed alongside Keycloak. It integrates with:

• Keycloak Session Management: Maps external sessions to Keycloak user sessions and client sessions.
• Keymate Event Manager: Emits audit events for session mapping and destruction operations.
• External Systems: Any system that can call the Session Sync REST API to register and manage its sessions.

Boundaries

What Session Sync covers:

• Mapping external parent sessions to Keycloak user sessions
• Mapping external child sessions to parent sessions
• Cascade termination of session hierarchies
• Session tree retrieval for visibility
• Audit event emission for all session operations

What Session Sync does not cover:

• Authentication flows (handled by Keycloak)
• Session timeout policies (handled by Keycloak session settings)
• Cross-realm session operations (sessions are realm-scoped)

How It Works

Session Model

Session Sync uses a hierarchical model with three session types:

Type	Description
PARENT	Root session mapped to a Keycloak user session. Represents the primary authentication event.
CHILD	Session linked to a parent. Represents a dependent session (e.g., a downstream service session).
FIXED	Standalone session that operates independently without parent-child relationships.

Each session has a status:

Status	Description
ACTIVE	Session is currently valid and active.
DESTROYED	Session has been explicitly terminated.
ORPHANED	Parent session was terminated; child session is orphaned.

Session Lifecycle

Data Storage

Session mappings are stored persistently with the following data model:

Field	Description
External ID	Unique identifier from the external system (primary key)
Parent Session Reference	Link to parent session for child sessions
Session Type	PARENT, CHILD, or FIXED
Realm	Keycloak realm identifier for tenant isolation
Keycloak Session Reference	Link to the corresponding Keycloak user or client session
Status	Current session state: ACTIVE, DESTROYED, or ORPHANED
Attributes	Custom metadata as key-value pairs
Timestamps	Creation and last update times

note

Session records are realm-scoped. The combination of realm and external ID ensures uniqueness across multi-tenant deployments.

API Endpoints

The extension exposes a REST API under /admin/realms/{realm}/external-sessions:

Endpoint	Method	Description
/map-parent	POST	Map an external parent session to a Keycloak user session
/map-child	POST	Map an external child session to a parent session
/destroy-parent	POST	Terminate a parent session and cascade to all children
/destroy-child	POST	Terminate a single child session
/session-tree/{externalId}	GET	Retrieve the full session hierarchy

All endpoints require the users:manage permission (Keymate's fine-grained authorization permission, not to be confused with Keycloak's manage-users realm role).

Diagram

Example Scenario

Scenario

A user authenticates via Keycloak to access an enterprise portal. The portal creates its own session and registers it with Session Sync. The user then accesses two downstream microservices, each registering child sessions. When the user logs out, all sessions are terminated in cascade.

Input

• Actor: External portal system
• Resource: Session mapping API
• Action: Map parent session, then map child sessions
• Context: User has authenticated via Keycloak, Keycloak user session ID is kc-user-123

Expected Outcome

• Result: Sessions are mapped successfully
• Why: The portal registers portal-session-001 as a parent mapped to kc-user-123. Microservice A registers service-a-session-001 as a child. Microservice B registers service-b-session-001 as a child. When the portal calls destroy-parent, all three sessions are marked as DESTROYED and the Keycloak user session is terminated.

Common Misunderstandings

• Session Sync does not handle authentication: It only maps and synchronizes sessions after authentication occurs in Keycloak.
• Child sessions are not automatically created: External systems must explicitly call the API to register child sessions.
• Realm isolation is enforced: Sessions from one realm cannot reference sessions from another realm.

warning

Destroying a parent session cascades to all children. This is intentional for security, but external systems should handle the orphaned state gracefully if they need cleanup logic.

Design Notes / Best Practices

• Use meaningful external IDs: External session IDs should be globally unique and traceable to the source system.
• Store metadata in attributes: Use the attributes field for custom data like source system, user type, or external user ID.
• Handle idempotency: The API returns 409 Conflict if an identical session already exists, allowing safe retries.
• Monitor session trees: Use the /session-tree/{externalId} endpoint to debug session hierarchies.

tip

Integrate Session Sync API calls into your application's session creation and destruction hooks to ensure synchronization happens automatically.

Related Use Cases

• Single logout across federated systems
• Session visibility for compliance audits
• Coordinated session revocation during incident response
• Legacy IAM parallel run with synchronized session termination

Related Docs

Session Governance

Session lifecycle policies and boundaries in Keymate.

Logout Model

Coordinated logout patterns across systems.

FAQ

Does Session Sync require changes to Keycloak's session timeout settings?

No. Session Sync works alongside Keycloak's native session management. Keycloak's timeout policies still apply to the Keycloak user session. Session Sync adds visibility and coordinated termination for external sessions.

What happens if I destroy a child session but not the parent?

Only the specified child session is terminated. The parent and other child sessions remain active. The child session status is updated to DESTROYED.

Can I query sessions by Keycloak session ID instead of external ID?

Yes. The API supports queries by Keycloak user session ID and client session ID in addition to external ID.

How does Session Sync handle concurrent requests?

The API is idempotent. If you send the same mapping request twice, the second request returns 409 Conflict with ALREADY_EXISTS status. Database constraints prevent duplicate external IDs.