The Organizations Feature in Keycloak
A complete, beginner-friendly guide to Keycloak's built-in Organizations support — what it is, why multi-tenant B2B apps need it, and how it changes login, identity, and administration.
Imagine a large office building shared by several different companies. Each company has its own reception desk, its own employee badges, and its own rules about who can enter which floor — yet the building itself has one shared elevator system, one shared security team, and one shared address. Tenants don’t need to know how the building’s plumbing works; they just need their own space to feel separate and self-contained. Keycloak’s Organizations feature brings exactly this kind of “one building, many tenants” structure to identity management, letting a single Keycloak realm serve many separate business customers cleanly.
1What Is the Organizations Feature?
Let’s define it precisely before exploring why it exists.
Organizations is a feature built into Keycloak, the open-source Identity and Access Management (IAM) server from Red Hat, that lets a single realm host multiple distinct business entities — each with its own set of members, its own identity providers, and its own domain-based association — while still sharing the realm’s underlying clients, themes, and administrative infrastructure.
Picture a software-as-a-service company that sells project management software to other businesses. Company A and Company B both use the same application, but Company A’s employees should never see Company B’s projects, and each company might want its own login experience — maybe Company A logs in with its own corporate Microsoft account, while Company B just uses email and password. Without Organizations, the SaaS provider would need a separate realm (essentially a separate mini-Keycloak-instance) for every customer. With Organizations, all of this coexists cleanly inside one realm.
Before Organizations existed, teams building business-to-business (B2B) SaaS products on Keycloak had two common, imperfect options: create a brand-new realm per customer (which becomes an administrative burden at scale — imagine managing a thousand tiny realms), or bolt on custom logic using groups and roles to simulate tenant separation (which was error-prone and did not map naturally onto real B2B needs, like a customer’s employees signing in through the customer’s own identity provider). Organizations was built specifically to close this gap.
Organization
A named entity within a realm representing one tenant or customer business, with its own members and settings.
Member
A user account associated with one or more organizations, distinct from ordinary realm-wide role or group assignment.
Domain
An email domain (like acme.com) linked to an organization, used to automatically route or identify users belonging to that tenant.
Identity Provider Link
A connection between an organization and a specific external identity provider, enabling that organization’s own single sign-on setup.
Organizations turns “multi-tenant B2B identity” from a custom-built, error-prone problem into a first-class, supported Keycloak capability — meaning teams no longer need to reinvent tenant isolation logic from scratch for every SaaS product they build.
2Why Organizations Exists: The B2B Identity Problem
Understanding the pain point makes the feature’s design choices click into place.
Consumer-facing applications usually have a simple identity story: one big pool of individual users, each managing their own account. Business-to-business applications look completely different. A single customer of a B2B product is not one person — it’s an entire company, often with dozens or thousands of employees, its own IT department, its own security policies, and often its own existing corporate identity system (like a company-wide single sign-on setup) that it wants its employees to keep using.
The One-Realm-Per-Customer Approach
- Provides strong isolation, since each customer is a fully separate realm.
- Becomes an operational burden as customer count grows into the hundreds or thousands.
- Requires duplicating clients, themes, and configuration across every realm.
- Makes cross-tenant features (like a shared admin console for the SaaS provider) awkward to build.
The Custom Groups/Roles Approach
- Keeps everything in one realm, avoiding realm sprawl.
- Does not natively support per-tenant identity provider configuration.
- Requires significant custom development to approximate tenant-aware login routing.
- Tends to produce brittle, hard-to-audit logic scattered across application code.
Organizations was introduced to give teams a third option: one realm, natively tenant-aware, with built-in support for the specific patterns B2B applications need most — associating users with a business entity, linking that entity to its own identity provider, and using email domains to automatically recognize which organization a new user belongs to during self-registration or login.
It’s worth noting that Organizations doesn’t replace realms, groups, or roles — it works alongside them. A realm remains the outermost isolation boundary (typically one realm per product or per major business unit of the SaaS provider itself), while Organizations provides tenant-level structure within that realm, and groups/roles continue to express finer-grained permissions within or across organizations as needed.
3Architecture & Components
Let’s map out how Organizations fits into Keycloak’s broader structure.
Realm
The outermost container — still the top-level isolation boundary, holding clients, roles, and now potentially many organizations.
Organization
A tenant entity inside the realm, with its own name, description, domains, and membership list.
Identity Provider
An external login source (corporate SSO, social login, another OIDC/SAML provider) that can be linked specifically to one organization.
Member / User
An individual account that belongs to one or more organizations within the realm, alongside its usual realm-level roles and groups.
When an administrator creates an organization in Keycloak, they typically configure a handful of core settings: a name, an optional description, one or more associated domains, and — critically — links to one or more identity providers that members of this organization should use to sign in. This last part is what enables the classic B2B experience where an employee of “Acme Corp” is automatically directed to Acme’s own corporate login page rather than Keycloak’s generic login form.
Domain-Based Routing
When a user starts a login and enters an email address, Keycloak can inspect the domain portion of that address (the part after the @ symbol) and match it against domains registered to an organization, automatically routing the user toward that organization’s configured identity provider — without the user needing to know which provider to pick manually.
Membership Management
Administrators (or, in self-service setups, organization-level administrators) can add or remove members from an organization, controlling who is recognized as belonging to that tenant, separately from any realm-wide group or role assignment.
graph TD
A[Realm] --> B[Organization: Acme Corp]
A --> C[Organization: Globex Inc]
B --> D[Domain: acme.com]
B --> E[Identity Provider: Acme SSO]
B --> F[Members: Acme Employees]
C --> G[Domain: globex.com]
C --> H[Identity Provider: Globex SSO]
C --> I[Members: Globex Employees]
4The Organization-Aware Login Flow
Let’s trace exactly what happens when a member of an organization logs in.
User Starts Login
The user is redirected to Keycloak’s login page as part of a standard OpenID Connect authentication request from the application.
User Enters Identifier
The user types their email address or username into the login form.
Keycloak Checks Domain Association
If the entered identifier’s domain matches a domain registered to an organization, Keycloak recognizes the user as (potentially) belonging to that organization.
Identity Provider Redirect (If Configured)
If that organization has a linked identity provider, Keycloak can redirect the user onward to that identity provider’s own login page, rather than prompting for a Keycloak-managed password directly.
User Authenticates Externally
The user logs in using their organization’s own credentials — for example, their corporate Microsoft or Google Workspace account.
First-Login Linking or Membership Confirmation
On a first-time login through this path, Keycloak can automatically create the user account and associate it as a member of the matching organization, based on rules configured by the administrator.
Tokens Issued
Keycloak completes the authentication and issues the usual access, ID, and (if configured) refresh tokens back to the requesting application.
Application Reads Organization Context
The application can inspect organization membership information (often available as a claim or via a lookup) to tailor the experience — showing the right tenant’s data, branding, or feature set.
sequenceDiagram
participant User
participant App
participant KC as Keycloak
participant IdP as Acme's Identity Provider
User->>App: Start login
App->>KC: Redirect to login page
User->>KC: Enter email (user@acme.com)
KC->>KC: Match domain to Organization: Acme Corp
KC->>IdP: Redirect to Acme's linked identity provider
User->>IdP: Authenticate with corporate credentials
IdP-->>KC: Confirm identity
KC->>KC: Confirm/create membership in Acme Corp
KC-->>App: Issue tokens with organization context
Not every organization needs a linked identity provider. An organization can exist purely as a grouping and membership construct — using Keycloak’s own login form — with domain-based identity provider routing added later if and when that tenant needs its own corporate SSO.
5Internal Working: Membership, Domains, and Invitations
Let’s look more closely at the mechanics that tie users to organizations.
Membership in an organization is tracked as a distinct relationship, separate from realm roles or groups, though it can certainly be combined with them. A single user can be a member of multiple organizations at once — useful for scenarios like a consultant who works across several client companies that all use the same underlying SaaS platform.
Think of organization membership like being a member of several different gyms that all happen to use the same gym-management software company behind the scenes. Your membership at Gym A doesn’t give you access to Gym B’s equipment or class schedules, even though both gyms run on the same underlying platform. Similarly, being a member of Organization A in Keycloak doesn’t automatically grant visibility into Organization B’s data — that separation still needs to be enforced by the application, informed by the organization membership Keycloak reports.
Domain Verification
Domains associated with an organization can be used both for routing (directing users to the right identity provider) and, in some configurations, as a signal for automatically approving membership for users with matching email addresses.
Invitations
Administrators or organization-level managers can invite specific users to join an organization, sending an invitation that the recipient accepts to formally become a member — useful when domain matching alone isn’t sufficient or appropriate.
Self-Registration Association
When self-registration is enabled, Keycloak can automatically associate a newly registering user with an organization if their email domain matches one already registered to that organization.
Organization-Scoped Roles
Roles can be defined and assigned in a way that is meaningful specifically within the context of one organization, letting the same underlying role name (like “manager”) carry different practical scope per tenant.
Under the hood, Keycloak stores organizations, their domains, their identity provider links, and their membership relationships as part of the realm’s data model, exposed through both the Admin Console (a graphical interface for administrators) and the Admin REST API (for programmatic management, useful when a SaaS provider wants to automate organization creation as part of its own customer onboarding process).
Because organization creation and configuration is available through the Admin REST API, SaaS providers commonly automate the entire “new customer onboarding” process — creating the organization, registering its domain, and linking its identity provider — as a background step triggered the moment a new business customer signs up.
6Data Flow & Lifecycle of an Organization
Let’s trace an organization’s life from creation to ongoing use.
Organization Created
An administrator (manually, or via automated onboarding through the Admin REST API) creates a new organization within the realm, giving it a name and description.
Domains Registered
One or more email domains are associated with the organization, enabling automatic recognition of users belonging to that business.
Identity Provider Linked (Optional)
If the organization wants its own corporate single sign-on, an identity provider is configured and linked specifically to this organization.
Members Join
Users become members through domain matching, explicit invitation, or manual assignment by an administrator.
Ongoing Authentication
Members log in through the organization-aware flow repeatedly over time, with Keycloak continuing to route them appropriately and report their membership to relying applications.
Membership Changes
Members can be removed, new members added, or domains updated over time as the business relationship with that tenant evolves.
Organization Deactivated or Deleted
If the business relationship ends (a customer churns, for example), the organization can be deleted or otherwise deactivated, and its associated configuration cleaned up.
Throughout this lifecycle, the realm itself remains stable — clients, themes, and shared configuration don’t need to be touched as organizations are added, modified, or removed. This is precisely the operational benefit Organizations was designed to deliver: tenant lifecycle events become lightweight, data-level changes within one realm, rather than infrastructure-level changes requiring a whole new realm to be provisioned and maintained.
7Organizations vs. Realms vs. Groups: A Comparison
These three constructs can seem similar at first glance, but they solve different problems.
| Construct | Purpose | Isolation Level | Best Fit |
|---|---|---|---|
| Realm | Top-level administrative and security boundary | Complete — separate users, clients, themes, configuration | Separate products, separate major business units, separate legal entities |
| Organization | Tenant-level grouping within one realm, with domain and identity provider association | Logical — shared infrastructure, separated membership and login routing | B2B customers of a shared SaaS product |
| Group | General-purpose collection of users for role/permission assignment | None on its own — just an assignment mechanism | Departments, teams, or arbitrary categorizations within any scope |
A practical way to decide which construct to reach for: if two sets of users must never share infrastructure or configuration at all, use separate realms. If two sets of users share the same application and infrastructure but represent distinct business customers who may want their own login source, use Organizations. If you simply need to group users for permission purposes within an already-defined scope (realm or organization), use groups.
Many teams combine all three: one realm per product line, Organizations for each B2B customer within that product’s realm, and groups for finer role-based structuring within or across those organizations.
8Advantages, Disadvantages & Trade-offs
Organizations solves real problems, but it’s worth understanding its trade-offs too.
Advantages
- Avoids realm sprawl — hundreds or thousands of B2B customers can be represented within one realm.
- Provides native domain-based routing to per-tenant identity providers, a common and previously hard-to-build B2B requirement.
- Simplifies onboarding automation through the Admin REST API, since creating a new tenant is a lightweight data operation rather than a new realm deployment.
- Keeps shared realm-level configuration (clients, themes, base security settings) consistent and centrally managed across all tenants.
- Coexists cleanly with existing roles and groups rather than requiring a redesign of an existing permission model.
Disadvantages / Trade-offs
- Isolation is logical, not infrastructural — a misconfigured application could theoretically leak data across organizations if it doesn’t properly enforce organization-scoped access itself.
- Adds a new concept for administrators and developers to learn on top of existing realms, groups, and roles.
- Domain-based routing requires careful handling of edge cases, such as personal email addresses or shared corporate domains spanning multiple business relationships.
- Very large numbers of organizations within a single realm still require thoughtful administrative tooling to manage efficiently.
In general, Organizations is the right tool specifically for B2B, multi-tenant SaaS scenarios. For applications with a single, undifferentiated pool of individual consumer users, the added structure of Organizations offers little benefit and simple realm-level user management remains perfectly appropriate.
9Security Considerations
Multi-tenant identity introduces its own specific set of risks to manage carefully.
Application-Level Enforcement
Keycloak reports organization membership, but the application itself is responsible for enforcing that a user only ever sees data belonging to their own organization — Organizations is a foundation, not a full data-isolation guarantee.
Domain Ownership Verification
Automatically associating users with an organization based purely on email domain requires confidence that the domain genuinely belongs to that business, since domain claims can otherwise be a source of confusion or abuse.
Identity Provider Trust Boundaries
Linking an external identity provider to an organization means trusting that provider’s authentication assertions for that tenant’s users — the provider’s own security posture becomes part of the organization’s overall security.
Cross-Organization Accounts
Users who belong to multiple organizations need careful handling in application logic to ensure the correct organization’s context is active for any given session or request.
Problem
Assuming that organization membership alone, as reported by Keycloak, is sufficient to guarantee data isolation between tenants inside the application’s own database or business logic.
Why It’s Harmful
Keycloak’s Organizations feature manages identity and membership — it does not automatically scope every database query or API call an application makes. If the application doesn’t explicitly filter data by organization on every relevant operation, membership information alone provides no real isolation.
Correct Approach
Treat organization membership from Keycloak as an input to the application’s own authorization logic, and explicitly enforce organization-scoped data access at the application and data-layer level, on every relevant request.
Registering overly broad domains (like a generic email provider domain) against an organization, which could inadvertently associate unrelated users with that tenant purely because they happen to share an email domain not actually tied to that specific business.
10Monitoring, Logging & Metrics
Operating Organizations at scale benefits from dedicated visibility into tenant-level activity.
Per-Organization Login Volume
Tracking authentication activity broken down by organization helps spot unusual patterns specific to one tenant, rather than only seeing realm-wide aggregates.
Identity Provider Failure Rates
Since each organization may route to a different external identity provider, monitoring failure rates per linked provider helps catch tenant-specific SSO outages quickly.
Membership Change Events
Logging when members are added to or removed from an organization supports auditing, especially in regulated industries where tenant access history matters.
Domain Matching Anomalies
Unexpected domain-to-organization matches — for example, a user whose email domain doesn’t cleanly correspond to exactly one organization — are worth flagging for administrative review.
Tenant Health Dashboards
SaaS providers running many organizations on Keycloak commonly build dashboards that surface per-tenant login success rates, active member counts, and identity provider status, giving both the platform team and, in some cases, the tenant’s own administrators visibility into their organization’s health.
11Design Patterns & Anti-Patterns
A few patterns recur across mature multi-tenant deployments using Organizations.
Pattern: Self-Service Onboarding
New B2B customers sign up through a dedicated onboarding flow that automatically creates their organization, registers their verified domain, and optionally guides them through connecting their own identity provider — all driven through the Admin REST API rather than manual administrator steps.
Pattern: Organization-Scoped Admin Delegation
Rather than every organization change requiring the SaaS provider’s own administrators, some deployments delegate limited management capabilities (like inviting new members) to a designated administrator within each organization, reducing operational load on the central team.
Pattern: Fallback to Direct Login
Organizations without a linked identity provider simply fall back to Keycloak’s own login form, letting smaller tenants who don’t need corporate SSO still be represented as first-class organizations without extra configuration overhead.
Problem
Creating a new realm per B2B customer instead of using Organizations, simply because that pattern was familiar from before Organizations existed.
Why It’s Harmful
This reintroduces the exact realm-sprawl and administrative overhead problem Organizations was purpose-built to solve — duplicated configuration, harder cross-tenant features, and a much heavier operational burden as the customer base grows.
Correct Approach
Reserve separate realms for genuinely distinct products or security domains, and use Organizations within a single realm for B2B customers of the same underlying application.
12Best Practices & Common Mistakes
A concise checklist for teams adopting Organizations in a real B2B product.
Verify Domain Ownership
Confirm a customer genuinely controls a domain before registering it to their organization, especially for auto-join or auto-routing behavior.
Enforce Isolation in the Application
Always explicitly scope data access by organization membership in application and data-layer logic — never rely on Keycloak configuration alone.
Automate Onboarding
Use the Admin REST API to make organization creation part of a smooth, low-friction customer onboarding flow rather than a manual administrative task.
Plan for Multi-Organization Users
Design the application’s session and context handling to gracefully support users who belong to more than one organization.
Monitor Per-Tenant Identity Providers
Track the health of each linked identity provider individually, since an outage affecting one tenant’s SSO shouldn’t be masked by realm-wide aggregate metrics.
Document Tenant Offboarding
Have a clear, tested process for what happens to an organization’s data, members, and identity provider link when a customer relationship ends.
Forgetting that removing a member from an organization doesn’t automatically delete their user account or revoke every related permission — organization membership, roles, and account existence are related but distinct, and offboarding processes need to address all of them deliberately.
13Real-World & Industry Examples
The Organizations feature maps directly onto patterns common across many B2B products.
B2B Project Management and Collaboration Tools
SaaS platforms serving many client companies use Organizations to keep each company’s projects, teams, and data cleanly associated with the right tenant, while offering each company the option to bring their own corporate SSO.
Vertical Industry SaaS (Legal, Healthcare, Finance)
Industry-specific software serving many separate firms or practices benefits from Organizations’ domain-based routing, letting each firm’s staff log in through their own existing identity systems rather than learning a new one.
Developer Platforms and API Providers
Platforms offering APIs or developer tools to many separate companies use Organizations to group API keys, usage limits, and team members under the correct business entity.
Marketplace and Partner Ecosystems
Platforms connecting many independent partner businesses to a shared marketplace use Organizations to represent each partner as its own tenant, with membership and identity provider configuration tailored to that partner’s needs.
Across these examples, the shared thread is a single application serving many independent businesses at once — exactly the situation where the operational and identity-routing benefits of Organizations become most valuable compared to either a single undifferentiated user pool or a sprawling collection of separate realms.
14Frequently Asked Questions
Common questions teams ask when first evaluating the Organizations feature.
Yes. Organizations is an additive feature — a realm can freely mix users who belong to one or more organizations with users who belong to none at all, depending on the application’s needs.
No. Linking an identity provider to an organization is entirely optional. Organizations without one simply use Keycloak’s own login mechanisms for their members.
Yes, a single user account can be a member of multiple organizations within the same realm, which is useful for scenarios like consultants or contractors working across several client businesses on the same platform.
Organizations manages identity and membership, not application data storage. The application itself is still responsible for structuring and enforcing tenant-scoped access to its own data, using organization membership reported by Keycloak as an input to that logic.
Organizations is a feature of the Keycloak project itself; availability and any packaging specifics can vary by version and distribution, so it’s worth checking the release notes or documentation for the specific Keycloak version being deployed.
This creates ambiguity in domain-based routing and membership matching, since Keycloak needs a domain-to-organization mapping to be unambiguous. Careful domain governance — ensuring each domain is registered to exactly one organization — avoids this situation entirely.
15Summary and Key Takeaways
The Organizations feature gives Keycloak native, first-class support for the business-to-business, multi-tenant identity patterns that used to require either realm sprawl or custom-built workarounds. By letting a single realm host many distinct organizations — each with its own domains, membership, and optional linked identity provider — teams building B2B SaaS products can onboard new business customers as a lightweight configuration step rather than a heavyweight infrastructure change, all while keeping shared realm-level resources like clients and themes centrally managed.
Key Takeaways
- Organizations represents a tenant within a realm — with its own domains, membership, and optional linked identity provider.
- It solves the B2B identity problem without requiring a separate realm per customer or custom-built tenant-routing logic.
- Domain-based routing directs users to the right identity provider automatically, based on their email domain matching an organization’s registered domains.
- Organizations complements realms, groups, and roles — it doesn’t replace any of them, and mature deployments typically combine all four.
- Application-level enforcement is still required — Keycloak reports membership, but the application must enforce actual data isolation between tenants.
- Onboarding automation through the Admin REST API is a common and powerful pattern for scaling B2B customer growth.
- Careful domain governance and offboarding processes keep organization membership accurate and secure over time.