From Legacy to Keycloak—No Re-Authentication Required

Keymate's Legacy Token Exchange extension enables you to convert existing IAM tokens into Keycloak-compliant access tokens—supporting smooth, parallel migrations without breaking user sessions.

Seamless Token Conversion for Parallel IAM Migration

Why It Matters

During IAM migrations, users may still authenticate against a legacy identity provider for a period of time. Forcing users to reauthenticate or reimplement SSO is risky, costly, and can degrade user experience.

This extension allows you to:

Accept tokens issued by external or legacy IAM platforms
Validate those tokens securely via introspection or signed assertions
Issue a valid Keycloak token with enriched attributes and scopes
Allow seamless transition to Keycloak, with no app-side changes required

Parallel Login. Unified Tokens.

Here's how the flow works:

Legacy Token Exchange Flow

This enables zero-downtime migration from legacy IAM systems.

Example: An external legacy token is securely exchanged for a Keycloak token.

Key Components:

User authenticates via your existing IAM provider

Your application receives a legacy token (JWT, opaque, etc.)

The app calls Keycloak's custom token exchange endpoint

Keymate validates the token via external API or cryptographic verification

A Keycloak session is created (if not already), and a new token is issued

The token contains standard and enriched claims (e.g., org, role, risk)

Extension Highlights — What Makes It Unique

Multi-Format Token Support

Accepts JWT, opaque, SAML-like or custom token formats

Custom Verification Logic

Supports external API validation, introspection, or signature checks

Session Creation + Enrichment

Creates or reuses session and populates session notes

Seamless Integration

Works with any legacy IAM provider (e.g., internal SSO, CAS, OAuth1, etc.)

Backward-Compatible Login Flow

Existing apps don't need to be updated

Full Observability

All token exchange requests are logged and traceable via OTEL

Frequently Asked Questions

Yes. You can plug in a validator that verifies tokens using your existing system's API or signing key.

You can configure the extension to auto-create users or link them via federation.

Tokens are only accepted if they pass configured validation checks, including signature, issuer, and expiry.

Exactly. This is ideal for parallel run periods where both legacy and Keycloak systems coexist.

How to Use This Extension

Implementation Steps

Deploy the token exchange extension JAR into your Keycloak instance

Define a custom grant type for token exchange

Implement and register a validator for your legacy tokens

Configure enrichment logic (e.g., map legacy roles to Keycloak roles)

Log exchange results to your audit platform via OTEL

Start accepting legacy tokens across apps—with no disruption

ELEVATE YOUR IAM STRATEGY

Ready to Transform Your Keycloak Experience?

Implement fine-grained authorization, multi-tenant infrastructure, and comprehensive security policies with Keymate — built on the Keycloak foundation you already trust.