Case study: Build multi-tenancy with Logto Organizations

Nowadays, multi-tenancy becomes an essential part of an app, or SaaS. It often involves the complex relationship between users, organizations, roles, and permissions. For example, a user can be a member of multiple organizations, and vice versa; a user can also have different roles in different organizations.

The problem

This can lead to headaches for not only the beginning, but also the long-term maintenance of an app. The traditional role-based access control (RBAC) model can partially solve this problem, but quickly becomes a nightmare when the number of users and organizations grows.

For example, at the beginning, you may only have two roles in each organization: admin and member. When you have 10 organizations, you will manage 20 roles; when you have 1,000 organizations, you will manage 2,000 roles.

As the business grows, you may need to add more roles, such as guest, developer, etc. The complexity of the RBAC model will grow exponentially.

There was the same problem we had when we built Logto Cloud. We soon realized that it is a common problem for the industry, and we need to solve it. And Logto Organizations is here to rescue.

Organization template

A quick question: Why SaaS apps are SaaS? We believe scalability is one of the most important reasons. In other words, what works for one client should work for all clients.

This leads to the concept of "organization template". An organization template is a blueprint of the access control model for every organization: it defines the roles and permissions that apply to all organizations.

Let's say we have two roles for each organization:

• admin: can manage the organization, including adding / removing members, changing roles, etc.
• member: can access the organization's resources and invite new members.

We can create an organization template with the following configuration:

Add users to organizations

Since we set up the organization template, managing users becomes easy and natural. You can add a user to an organization by Logto Console (the web UI) or via Logto Management API

See Configure organizations to learn more.

We added two organizations with the following setup:

• Organization A: Both Alice and Bob are members. Alice has the admin role, and Bob has the member role.
• Organization B: Only Alice is a member, and she has the member role.

Request organization tokens in your app

In your customer app, now you can request an organization access token (organization token) from Logto. The organization token is a JWT token that contains necessary information for your service to verify if the user has the permission in the organization.

The detail steps of requesting an organization token are described in Integrate Organizations with your app.

Assume Alice is signed in to your app, and she wants to remove a user in Organization A. You app can request an organization token for "Organization A" with the remove:member permission (scope). Logto will verify if Alice has the permission in the organization, and return an organization token since she has the admin role:

{
  "sub": "alice-user-id",
  "iss": "https://your-logto-endpoint",
  "aud": "urn:logto:organization:{organization-a-id}",
  // ...
  "scope": "remove:member"
}

Here are some examples of error cases:

• If Bob wants to remove a user in Organization A, Logto would return an error since he doesn't have the admin role in Organization A.
• If Alice wants to remove a user in Organization B, Logto would also return an error since she doesn't have the admin role in Organization B.
• If Bob wants to fetch organization token with any permission in Organization B, Logto would return an error since he doesn't have the membership in Organization B.

After your app receives the organization token, it can call your service with the organization token by adding it to the Authorization header.

Verify organization tokens in your service

In your service, you can verify the organization token by the standard JWT verification process. See Verify organization tokens for more details.

Update organization template

When you need to update the organization template, for example, add a new role called developer, you can do it in Logto Console or via Logto Management API. The change will automatically apply to all organizations without any downtime.

Conclusion

With Logto Organizations, managing and scaling multi-tenancy becomes standard and comfortable. You can focus on your business logic and leave the identity and access control to Logto.