Keymate Logo

Log In with What You Know—National ID, Passport, Email, or Custom Keys

Enable frictionless user login with multiple identifier types. Whether it's a national ID, corporate ID, email, or passport number—Keymate's extension empowers users to authenticate with the identifier most natural to them, without altering Keycloak's core behavior.

Flexible Login with National ID, Email, Passport, or Custom Identifiers

Why It Matters

Most IAM systems assume "username or email" as login keys. But in public sector, finance, healthcare, and multinational organizations, users often expect to log in with:

  • National ID numbers (e.g., SSN, TCKN, Aadhar, NIN)
  • Passport numbers
  • Employee or customer reference IDs
  • Custom business identifiers (e.g., citizen code, patient ID)

This extension solves that by enabling flexible login matching against any configured user attribute—securely and consistently.

One Login Form, Multiple Identity Keys

At login time, the system checks the submitted identifier across a configurable list of user attributes:

Flexible Identifier Matching

Once a match is found, authentication proceeds seamlessly through the standard Keycloak flow. The original identifier used is also stored in session context for audit or personalization.

Example: A single input can be matched against multiple user attributes in a defined order.

Key Components:

preferred_username (default)
email
attributes.national_id
attributes.passport_number
attributes.custom_id

Extension Highlights — What Makes It Unique

Flexible Identifier Matching

Match user input against multiple fields (email, passport, ID, etc.)

Configurable Priority Order

Define attribute matching precedence via configuration

Audit-Friendly Session Notes

Stores the identifier type and value used at login time

No DB Customization Needed

Works with standard Keycloak schema and user attributes

Multi-Realm Compatible

Supports unique identifier sets per realm or tenant

Security-First Matching

Stops on first match, prevents ambiguous user resolution

Frequently Asked Questions

Any standard or custom user attribute—including email, username, national ID, passport number, employee ID, etc.
Yes. Each realm can have its own identifier priority configuration.
Yes, the matched identifier and type can be injected into session notes or token claims.
No. It only enhances the user resolution step before authentication begins.
Yes, it's recommended to enforce uniqueness for high-sensitivity identifiers via admin logic or external validation.

How to Use This Extension

Follow these steps to enable the Multi-Identifier Login Extension.

Implementation Steps

1

Install the extension JAR into Keycloak and enable it in your login flow

2

Configure the identifier matching priority in the realm settings

3

Ensure relevant user attributes (e.g., national_id, passport_number) are populated

4

Optionally map matched identifier to token or session notes

5

Test login with different identifier types from a single login form

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.