Multi-Tenancy and Delegated Access Management with Organizations

1. Organization vs. Instance
2. Organizations
   1. User Management
   2. Managing Roles and Applications
   3. Login and Access Policies
3. Delegated Access Management
   1. Project Grants
   2. Delegate Self-Service to Customers
4. Authorize Users Outside of Your Organization
5. Conclusion

The most distinct feature of ZITADEL is how you can structure your identity architecture around Users and Organizations. Whether you're building a customer-facing app and looking for a CIAM solution to handle authentication for you, or trying to offer hundreds of business customers and partners the ability to use their identities and delegate permission management to your customer, it's worth understanding how you can build your solution scenarios with ZITADEL.

This article aims to give you an overview of the overall concepts used and explain the most important points, so you can get started with enough knowledge at hand.

Organization vs. Instance

The highest level of separation in ZITADEL is an instance. ZITADEL allows you to operate multiple virtual instances on the same system with the same database.

Access across instances is not possible. Instances can be managed with the System API as described in this Guide.

It's important to note that some settings can only be set per instance, specifically:

• SMTP Service: All emails within the instance will be sent from this service
• Custom Domain: You can define under which domains (eg, login.demo-vendor.com) the ZITADEL service can be accessed

Note:
At the time of writing, token lifetimes can only be configured on instance level. There is no technical limitation, but it is an outstanding feature.

Instances provide one form of multi-tenancy in ZITADEL, where each tenant is completely isolated. However, most scenarios might involve some form of self-service or fluidity between the different tenants to reduce administrative overhead. These cases most often leverage our organization model within a single instance.

Organizations

Think of an organization as a way to group users and set shared policies (our term for "settings") such as login, security, branding. Organizations also allow you to manage applications centrally and grant other organizations to them.

User Management

In the following diagram, you can see two organizations. One for a service provider, for example a software vendor or project like you, and one for a customer organization. Each organization has its own users.

Users will always belong to one organization. You have a high degree of flexibility when it comes to how you structure your identities. You can put all your users in one organization and use ZITADEL like any other CIAM. Just as well, you might want to split users in different groups. For example, you may want to separate your customers from your team members or employee identities. Alternatively, you may want to keep each of your customers' identities in its own organization.

Managing Roles and Applications

Each organization can have multiple projects, and each project can contain multiple applications with a shared set of roles. Think of a project like a "shared security context" for applications that logically belong together. For example, a web app and mobile app, or a front-end and back-end of the same service.

In the example below, you can see that the service provider has the two projects Portal and Data Cube. Portal would serve as customer portal for all customers to access their services and contains roles like reader, admin, support:read, support:write to grant users a different set of permissions.

The service Data Cube may require different roles, such as analyst, engineer, manager, and could be granted to customer organizations based on a subscription option.

Login and Access Policies

For each organization, you can define individual policies around login, access, branding, and domains.

With the security settings per organization, it is possible, for example, to configure different external identity providers per customer organization. You could configure one organization to allow login with a customers' AzureAD tenant, while configuring another customer organization to login with a local password and 2FA.

At this point, you might ask yourself: How to redirect users to the correct domain?

One way would be to setup domain discovery on your instance to route users according to their login name or email address. Another option is to send a reserved scope with your auth request to enforce the organization's policies on the login.

Delegated Access Management

Broken Authorization is a Major Risk to Web Applications
The highest-ranking risk for web-applications is Broken Access Control, according to the OWASP Top 10. Providing a secure way of authorization in a multi-tenancy setup, while allowing for self-service, is difficult to achieve. We built ZITADEL, based on our experience, from the ground up with this particular challenge in mind, so you don't have to worry about it.

Now we get to the more interesting part of the setup.

How can you give other organizations access to a project and its applications? And once the organization has access, how can they give permissions to their users?

That is where the unique delegated access management feature of ZITADEL comes into play.

Instead of copying over all projects or applications to each customer organization, which would result in quite some overhead to manage at scale, you can grant projects to other organizations.

Project Grants

With a project grant, you can select a subset of roles that the receiving organization can assign to their users.

As an example you could keep certain administrative roles for support or developers in your own organization. Or you might want to only grant a role once the customer has subscribed to a feature in your application.

Think of a project grant as creating a link to the project. You don't need to manage the applications within each organization, but only grant them to other organizations. The receiving organization will see an incoming projects as a "Granted Project" and cannot change the project and that project's applications directly, but only use the roles to authorize their own users.

In the following screen, you can see that the project Portal, which is owned by the organization Demo-Vendor, has two active grants to Demo-Customer and Demo-Customer2 respectively.

The organization Demo-Customer2 sees the granted project under the tab "Granted Projects". When clicking on it, you can't edit the project itself, like how Managers of Demo-Vendor could, but only assign the granted roles to your users, given you have the permissions. We will discuss Managers in the next section.

You can always get an overview of all authorizations under the Authorizations tab in the ZITADEL console. Here you can also see that the user Eric Employee has the role reader in the granted Project Portal.

When Demo-Vendor removes the project grant to an organization, then all authorizations will be removed as well.

Delegate Self-Service to Customers

Managers allow you to let organizations self-assign roles to users, thus authorizing them to access the granted Project. Managers are an internal role and permission concept of ZITADEL. The concept offers many use cases for delegating self-service to users in other organizations.

For example, in a SaaS application, you might assign a manager role to the first user in a new organization. With that, this user could, for example, configure SSO and assign roles to their team members.

Integrate self-service features for managers into your application by using our APIs, or start your POC by letting users configure their organization via the branded console. The console will always be scoped to the manager permissions of a user.

Authorize Users Outside of Your Organization

But wait... there is more 🤯! We've already learned that you can isolate tenants with instances. We also saw how create a multi-tenancy setup with organizations that allow for grouping users, individual security policies (such as configurations of external identity providers), and delegating access management using managers.

So, how about a situation where one of your customers wants to invite users from another of your partners/customers and give them access to their organization's resources?

Here are a few of use cases for this:

• Accounting: You offer an accounting platform for SMEs. Your customers are the SMEs but also fiduciaries and accounting firms as partners that manage the finances of the SMEs. Each SME and partner would have their own organization with their own users and either log in with their business account or with a local account on your platform. The SMEs can grant access to their organization by inviting users of partners and authorize them with specific roles as part of your organization, so that they get access to the data they need.
• Education: You are an EdTech provider for different schools. You have an organization per school with teachers and students as users. Some teachers are, however, also responsible for conducting classes at another school. You can create a user grant for these teachers to the secondary placement. Note: in case the accounts would not be managed by one primary school, you would anyway set up two accounts and manage the logic to select an account in your application.
• Healthcare: A university hospital is sponsoring a platform for cross-hospital knowledge and case exchange (e.g., scientific boards). Instead of creating separate accounts for each participant in your organization, you could create an organization for each participating organization. Then let users sign in with their existing accounts from their hospital and create a user grant, such that they get access to your project where you assign roles for the digital collaboration workspace.

Technically this would look similar as indicated in the next diagram. As service provider, for example for a time-keeping app, ACME organization owns a project with the roles Accountant and Developer. The project is granted to both Alpha and Beta where Beta has assigned Bob already the role Developer.

Alice from Alpha is the accountant of Beta and requires regular access to the time-keeping app to do her job. Beta can create a User Grant for Alice and assign her the role Accountant in self-service. Alice can now access the Project as external user of Beta with her role.

ACME must implement the application permissions for such cases within their application.

This feature goes beyond a traditional multi-tenancy approach by also allowing delegated access management tenant-to-tenant via user grants. You can integrate such external user management with ease in your application using our APIs.

Here is how you can set up a user grant via the ZITADEL console:

1. Go to Authorizations and press N (or click the button) to create a new authorization.
2. Under the text field Loginname there is a hint "If you want to grant a user of another organization click here".
3. Click on click here to switch to external users.
4. Enter the loginname of the external user and select a granted or owned project.
5. Go to the next screen and add the roles to the user.

The user will be now visible under Authorizations. You can't view or edit the user's details, since it is being managed by another organization. But you can change the associated roles like for internal users.

Conclusion

We went through several aspects of multi-tenancy of ZITADEL:

• Use instances to completely separate tenants
• Use organizations to group users, security policies, and other settings
• Manage your project centrally in one organization and grant the project to other organizations
• By assigning a Manager, a receiving organization can give permissions to their users via the incoming project
• You can also invite external users from another organization to your organization and give them permission to your owned or granted projects

In conclusion, ZITADEL has a high degree of flexibility to fit your use case. ZITADEL's multi-tenancy features provide a comprehensive solution for managing users, projects, and security policies across multiple tenants, ensuring a secure and efficient environment for your applications and services. Check out our Solution Scenarios and try out the Sample B2B application for more hands-on learning.