$ show playa-ru/keycloak-russian-providers
This repository provides a set of Keycloak identity provider plugins for Russian social networks: Yandex, VK (legacy API), VK ID (new OAuth 2.0 with PKCE), Mail.Ru, and Odnoklassniki. It extends Keycloak's OAuth2 identity provider framework with custom endpoints, token exchange logic, user profile mapping, and admin UI themes. The architecture follows Keycloak's SPI pattern: each provider has a factory, config, identity provider class, and optional custom callback endpoint. Notable engineering includes PKCE support for VK ID, signature-based API authentication for Odnoklassniki, Basic Auth token exchange for Mail.Ru, and Infinispan-based state caching for VK ID's custom OAuth flow. The code is well-structured, uses modern Java 17 and Jakarta EE, and includes CI/CD pipelines for building and publishing to Maven Central. However, the repository lacks unit tests, which is a significant gap for a production-grade library.
The LLM identified 5 files worth highlighting for reuse:
Base class for OAuth callback endpoints that overrides Keycloak's standard endpoint to provide human-readable error messages (e.g., missing email, hosted domain mismatch) and implements PKCE code verifier reconstruction. It encapsulates the token exchange flow and error handling, making it reusable for any OAuth2 identity provider that needs custom error messaging or PKCE support.
Base class for user attribute mappers that uses JsonPath to extract values from the user profile JSON and map them to Keycloak user attributes. It handles JSON arrays and single values, and validates that the attribute name and path are configured. This pattern is reusable for any identity provider that returns user data in JSON format and needs flexible attribute mapping.
Utility for managing a dedicated Infinispan cache to store OAuth state and PKCE code verifiers. It lazily initializes a cache named 'russianProvidersSessions' using Keycloak's Infinispan connection provider. This pattern solves the problem of sharing state across distributed Keycloak nodes for custom OAuth flows (e.g., VK ID) and can be extracted for any Keycloak provider needing distributed state storage.
OAuth2 identity provider for Odnoklassniki that implements a custom signature-based API call to fetch user profile. It generates an MD5 hash of concatenated parameters (access token, client secret, method, etc.) to authenticate the request. This demonstrates a non-trivial authentication pattern required by OK's API and can serve as a reference for integrating other APIs that use request signing.
Custom callback endpoint for VK ID that overrides the standard auth response and token request. It uses Infinispan to map the incoming state parameter to the original Keycloak state, and includes device_id and code_verifier in the token request. This pattern is essential for VK ID's OAuth 2.0 with PKCE and demonstrates how to handle custom state management and token exchange parameters.