Xata utilizes Keycloak for authentication and relies on its Organizations feature for multi-tenancy, providing isolated workspaces for customers. After encountering limitations with organization invitation management, we chose to contribute upstream rather than implement a workaround. The effort spanned six months, involving extensive collaboration with maintainers from Red Hat and IBM before merging into the main branch.
What is Keycloak?
Keycloak functions as an open-source Identity and Access Management solution handling authentication, single sign-on, and user federation. Originally developed at Red Hat, it became a CNCF incubating project in 2023. The platform supports OpenID Connect, OAuth 2.0, and SAML 2.0 protocols. For SaaS companies, the Organizations feature enables built-in multi-tenancy without requiring separate isolated environments.
The Problem: Invisible Invitations
The invitation workflow involves an administrator sending an email invite, Keycloak generating a signed action token (JWT), and the invitee registering or logging in to join the organization. However, once sent, invitations become invisible—administrators cannot view pending invitations, verify expiration status, resend invitations, revoke them, or track acceptance. This proves particularly problematic when inviting users without existing accounts, as no user entity exists to track invitation state.
Why Contribute Upstream?
Building an external invitation tracking layer introduces ongoing maintenance burdens with each Keycloak upgrade, potential synchronization problems between systems, and duplicated logic that other users must reimplicate. Contributing upstream places the feature where it belongs, benefits from community testing and maintenance, and creates permanent infrastructure.
Technical Challenge
Keycloak's stateless action tokens are cryptographically verified JWTs designed to avoid database writes at creation and validation checks at redemption. This architecture fails for invitations to non-existent users lacking a user ID to encode.
What Was Built
REST API Enhancements:
- GET endpoints list and retrieve specific invitations
- DELETE removes active invitations
- POST operations enable resending invitations
- The existing invite-user endpoint creates accompanying database records
Admin Console UI:
A new Invitations tab displays invitee email addresses, invitation status (pending/expired), dates, and action options.
Token Lifecycle Integration:
When accepted, the InviteOrgActionTokenHandler validates tokens and marks database records accordingly. Upon revocation, database records are deleted and cached tokens invalidated.
The Review Process
Contributing required architectural discussions about generic PersistentActionEntity implementations, multiple iteration rounds addressing naming, error handling, and test coverage. Core maintainer Pedro Igor provided co-authorship on several commits. The six-month timeline from PR opening in June through November merger reflects typical extended review cycles for identity infrastructure projects.
Release Timeline
Merged November 27, 2025, the feature will ship in version 26.5.0 (expected early 2026), currently available in nightly builds.
Contributing to Large OSS Projects
Success requires features core to product function rather than nice-to-have improvements. Projects with long review cycles demand patience. Collaboration improving code through the process yields better outcomes than unchanged merges.
Future Plans
Xata intends continuing contributions to Keycloak and other foundational open-source projects supporting its platform, improving tools while building its database platform.