kc-validators

A collection of custom validators for Keycloak, packaged as a single SPI plugin. Currently includes phone number validation powered by Google's libphonenumber, Russian INN (Taxpayer Identification Number) and Kazakhstan IIN validation with checksum verification.

Features

• Phone number validation (any, mobile-only, fixed-line-only) via libphonenumber
• Russian INN validation (any, personal 12-digit, legal 10-digit) with checksum verification
• Kazakhstan IIN validation (12-digit) with two-pass modulo-11 checksum
• Configurable per-validator i18n error message keys
• Custom validation logic separated from SPI wiring (Layer 3 utilities)
• Input trimming and masking utilities

Requirements

• Keycloak 26.x
• Java 17+

Quick Start

Build the shadow JAR, drop it into Keycloak's providers/ directory, and rebuild:

./gradlew clean test shadowJar
cp build/libs/kc-validators-*.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build

Or, in a Dockerfile:

COPY --from=builder /app/build/libs/kc-validators-*.jar /opt/keycloak/providers/

After restarting Keycloak, the current validators can be assigned to user profile attributes in the Admin Console under Realm Settings > User Profile.

For full installation steps and verification, see Getting Started.

Validators

Phone validators

All phone validators require E.164 format (e.g. +12025551234).

Validator ID	Accepts
phone-validator	Any valid phone number
phone-mobile-validator	Mobile numbers (including fixed-line-or-mobile)
phone-fixed-line-validator	Fixed-line numbers (including fixed-line-or-mobile)

INN validators

Validator ID	Accepts
inn-validator	Any valid INN (10 or 12 digits)
inn-personal-validator	Personal INN for individuals (12 digits)
inn-legal-validator	Legal entity INN (10 digits)

IIN validator

Validator ID	Accepts
iin-validator	Kazakhstan IIN for individuals (12 digits, checksum)

Configuration

Every validator supports an error-message property overriding the default i18n error key; phone validators additionally support an allowed-regions country whitelist. For all configurable properties, default error messages, and theme localization, see Configuration.

Example: Phone attribute

• Attribute: phoneNumber
• Validator: phone-mobile-validator
• Config: error-message = error-invalid-mobile

Example: INN attribute

• Attribute: inn
• Validator: inn-personal-validator
• Config: error-message = error-invalid-inn-personal

Documentation

Guide	Description
Getting Started	Installation, setup, verification
Architecture	Layered design, package structure, dependency rules
Configuration	All properties and error messages

Contributing

Issues and pull requests are welcome. Please make sure tests pass and the project builds (./gradlew clean test shadowJar) before submitting a PR.

Commit messages must follow Conventional Commits (type(scope): description); valid scopes are listed in commit_scopes.txt. Enable the local validation hook once after cloning:

git config core.hooksPath .githooks

Commit messages and PR titles are also validated in CI.

License

This project is licensed under the MIT License.

Copyright 2026 ALTESSA SOLUTIONS INC.