Building Scalable Multi-Tenancy Authentication and Authorization using Open Standards and Open-Source Software

Multi-tenancy Mickey Cake

In today’s interconnected digital ecosystem, businesses are increasingly adopting multi-tenancy to serve multiple organizations (or tenants) using a single instance of an Identity and Access Management (IAM) platform. This architecture offers significant benefits, including scalability, cost efficiency, and flexibility, by allowing multiple organizations to coexist within the same infrastructure. However, this approach introduces unique challenges in ensuring that authentication and authorization mechanisms can meet the diverse needs of each tenant.

Let’s start at the beginning. As an IAM Architect, throughout this article, I will address each problem by following open standards and using an open-source software (OSS). This article builds on the principles and ideas detailed in the articles linked below. Feel free to review them to grasp the core concepts.

• Keycloak integration with OpenFGA (based on Zanzibar) for Fine-Grained Authorization at Scale (ReBAC)
• Mastering Access Control: Low-Code Authorization with ReBAC, Decoupling Patterns and Policy as Code

Here is a high-level diagram showing how you can connect all the pieces in IAM landscape with the related standards and open-source solutions. Usually, my approach is standards-first, and then we move to the platform-specific.

Let’s dive explain each bubble adding some references to the multi-tenancy scenario — I will not add to much detail of the point described in the previous articles.

Everything is related to the identity therefore we start from there. Then, we move to the authentication stage, where we implements OpenID Connect standard. Keycloak, acting as an Identity Provider (IdP), will be responsible for handling authentication as well as the identity, organization, and permission model. In relation to the last point, Keycloak offers a new feature called the Organizations feature, which facilitates Business-to-Business (B2B) scenarios. Thanks to this feature, we are now using the Organization model to represent each tenant — more details are described in the next sections.

In the authorization stage, we follow the specifications provided by the OpenID AuthZEN working group. This is why we describe the architecture using “P*P” components and externalize authorization through an API served by the Policy Decision Point (PDP). This component is implemented using OpenFGA, an advanced fine-grained authorization platform that supports Relationship-Based Access Control (ReBAC).

ReBAC enables dynamic access decisions based on relationships, such as “User X is a member of Organization Y” or “User Z has the role Auditor and is a member of Organization B”. With Keycloak’s new organization model, OpenFGA now supports handling the relationship between users and organizations. All event synchronization behind the scenes is managed by the Keycloak OpenFGA Event Publisher extension — how it works was described in previous articles.

Finally, by adopting a decoupled authorization architecture and implementing Policy as Code, we leverage Apache APISIX — a cloud-native, identity-aware API gateway integrated with OpenFGA — to enforce ReBAC policies at the API level using the Authorization OpenFGA plugin.

Based on the points described above, let’s begin by outlining a multi-tenant scenario to apply these concepts, followed by the workshop.

Use Case: Payment Platform PayPlus B2B (Multi-Tenant Scenario)

Business Requirements

Consider a payment platform, PayPlus, which processes transactions for multiple customers (businesses). Each customer has its own set of users (e.g., employees, finance teams, auditor) with distinct authentication and authorization requirements.

In this scenario, each customer is represented as an organization within Keycloak. Within these organizations, users are assigned to global roles, which define their access to platform features.

One of the goals is to explore how to protect multi-tenant APIs by leveraging organizational and permission model relationships in authorization policies. For the sake of this use case, we are going to expose the transaction API (GET /api/orgs/{orgId}/transactions). Access to this endpoint will require that only organization members with the global role Account Manager are allowed to view the information.

The integration of Keycloak and OpenFGA creates a scalable, secure, and flexible authentication and authorization system that adapts to each customer’s needs while ensuring consistent access control. Additionally, the protection based on ReBAC authorization rules by the API Gateway integrated with OpenFGA simplifies the overall authorization process.

Considerations: At the time of writing this article, Keycloak’s Organization feature had just been released. As a result, many features are still on the roadmap for future implementation, such as support for assigning authentication flows per organization and the ability to create a new permission model tied to organizations. Once these features are supported by Keycloak, I plan to further enhance the workshop. For now, my goal is to provide a general overview of the current state and future possibilities.

Workshop Architecture: Payment Platform PayPlus B2B

Workshop Architecture

To review the integration between components, you can refer to the previous articles. Below, I will introduce the new features that support this multi-tenancy scenario.

Keycloak: New Organization Feature

Simplifying the idea here, Keycloak introduce the feature Organization, where a user can be member either by invitation link, through identity brokering (which means you can associate the organization domain to an external IdP) or manually by an administration.

Therefore, the administrator can manage the identity lifecycle and authentication per organization. Another point to keep in mind is that authentication is identity-first, and you can have organization-specific claims.

Well, let’s jump into our example scenario: we created two organizations to represent each tenant — Org A and Org B — and assigned demo users as members in the PayPlus realm.

Keycloak Organization Model

Here is the organization member visualization of the the demo user called paula.smith.

Org A members

We created a global role for the account manager that is related to the permission view:transaction:any resulting in this model.

Workshop Model

The authorization model is synchronized in real-time from Keycloak to the OpenFGA ReBAC model.

Keycloak OpenFGA Extension: New Support for Synchronizing the Organization Model

To support the Keycloak Organization model, we extended the Keycloak OpenFGA Event Publisher to handle organization events. Therefore, when you assign an organization to a user in Keycloak, this event is synchronized to the new OpenFGA model.

New OpenFGA Model with Support for Organizations Introduced

Apache APISIX Authorization OpenFGA plugin: New support for multiples policies with condition

We added a feature to support multiple authorization requests with conditional criteria, such as AND or OR. As a result, we can expose APIs with more complex authorization policies, such as a user having a relation to a role and being a member of an organization.

In this case, the transaction API implements the authorization policy declared in the business requirements — no further explanation is needed, as it is super easy to understand.

API Gateway with ReBAC Policies

Demo App: New PayPlus Multi-tenant app

This is another lovely ❤️ web application showcasing the use cases. It is integrated with OIDC via the Keycloak platform and displays both identity information and organization details. Additionally, it consumes the transaction API exposed by the API gateway to support multi-tenancy scenarios.

Hands-on Workshop: Payment Platform PayPlus B2B

The demo is available in the GitHub repo, which deploys all the components with just one click.

• https://github.com/embesozzi/keycloak-openfga-multitenancy-workshop

Use Case: Access PayPlus as Account Manager for Organization A

1. Access the Pay Plus platform with Paula (paula.smith@orga.com) into the Pay Plus platform and click in the login button.

PayPlus demo app

2. Login in using credentials for paula.smith in Keycloak in identity-first experience.

3. Pay plus demo shows the transaction information for the organization A.

PayPlus Transactions

Let’s dive into what happened behind the scenes

• In the step 1 , the application integrated with OIDC and requested the organization scope to retrieve the organization information.
• In the step 3, here are several points to consider. First, the application displayed the user’s organization based on the organization claim within the identity token.

• Next, the application made a request to list transactions for Organization A (GET /api/orgs/org-a/transactions). The authorization policy enforced by the API Gateway, as defined below, validated the access token and checked that the user belongs to org-a and has the view:transaction:any permission using the OpenFGA platform.

Authorization Policy

As you can see, the user is allowed because, in the OpenFGA authorization model detailed in the workshop below, Paula (sub claim value) is assigned to the account-manager role, which has the parent relation with the view:transaction:any permission, and she is a member of the Organization org-a. All of this model was synchronized from Keycloak to OpenFGA thanks to the custom extension ❤️.

OpenFGA Workshop model

Conclusions

Everything becomes easier when you follow open standards. You’ll achieve interoperability, avoid vendor lock-in, and, most importantly, not reinvent the wheel.

By leveraging open-source software (OSS) such as Keycloak, OpenFGA, and Apache APISIX, along with the Keycloak OpenFGA Event Publisher extension and Authorization OpenFGA plugin we’ve developed and maintained, you gain several benefits:

• Transparency and flexibility: You can inspect the code and ensure it meets your security and business requirements.
• Community support: Active communities contribute improvements, fixes, and new features.
• Cost efficiency: Avoid expensive vendor licenses and reduce the total cost of ownership.

Lastly, as an Identity and Access Management Architect, I believe this is a straightforward approach for addressing a complex scenario like multi-tenancy, guided by a standards-first mindset, open-source software (OSS), and the KISS (Keep It Simple, Stupid) principle.

By using modern standards and technologies described in this article, we can achieve:

• Delegation of authentication to the Identity Provider: Keycloak.
• Delegation of fine-grained authorization to the OpenFGA platform.
• Decoupling of authorization logic through the API Gateway: Apache APISIX).

This makes the IAM and authorization landscape more flexible, scalable, and maintainable.

Stay connected.

That’s all for this post!

Thank you for reading. If you like it, then share it!

Reference

• Github Multi-tenancy Workshop: https://github.com/embesozzi/keycloak-openfga-multitenancy-workshop
• Keycloak Extension: Keycloak OpenFGA Event Publisher — new version soon.
• Apache APISIX plugin: Authorization OpenFGA — new version soon.
• Previous Article: Keycloak integration with OpenFGA (based on Zanzibar) for Fine-Grained Authorization at Scale (ReBAC)
• Previous Article: Mastering Access Control: Low-Code Authorization with ReBAC, Decoupling Patterns and Policy as Code