Organization template

An organization template is an access control design for multi-tenant apps. It builds on the basics of RBAC (Role-Based Access Control) but is adapted for multi-tenant environments, where organizations represent businesses, groups, or users.

At the organization level, access control is needed to manage permissions for resources.

Here’s an example using Notion, a popular collaboration tool, and a typical multi-tenant app. It supports various features for authentication and authorization:

• You can create and join multiple workspaces with one account, instead of needing separate accounts for each workspace.
• Notion uses the same set of access levels, like "Workspace owner" and "Member," across all workspaces, even though you might expect different access levels for each one.

In this chapter, we’ll focus on the organization template, which refers to the authorization design at the organization level.

To set it up properly, you need to understand [how organizations work] and the different entities involved. If you haven’t reviewed that yet, be sure to read those chapters.

Understand organization template

Organization permission

Organization permission refers to the authorization to perform an action in the context of organization. An organization permission should be represented as a meaningful string, also serving as the name and unique identifier.

For example, edit:resource.

Organization permissions are not meaningful without the context of an organization. For example, edit:resource in the context of organization org1 is different from edit:resource in the context of organization org2 because they’re pointing to different resources (org 1 vs org 2).

Organization role

An organization role is a collection of organization or API permissions (permissions directly defined in API resources in Logto Cloud) that can be assigned to users.

Organization roles are not meaningful without the context of an organization. For example, admin in the context of organization org1 is different from admin in the context of organization org2.

note

Can I assign permissions defined at the API resource level to organization roles?

Yes, you can assign API permissions to organization roles, not just organization-level permissions.

API resources in Logto Cloud mainly protect user/system-level resources, but when systems and organizations share endpoints, Logto lets you assign API permissions to organization roles for flexibility.

Organization template

Organization template refers to a collection of organization permissions and roles that apply to every organization. It is considered as organization-level Role-based access control.

Think of a typical collaboration app, and they naturally share the same access control “template” that defines access levels and what users can do in the organization. We call it "organization template” in Logto.

Let’s take an example to understand how everything connects:

John, Sarah are in different organizations with different roles in the context of different organizations.

From this diagram, here are some info you need to know:

1. John is affiliated with two organizations, using the email [email protected] as his unique identifier. He holds the position of admin in Organization A and is a guest in Organization B.
2. Sarah is associated with a single organization and uses the email [email protected] as her unique identifier. She is the admin of Organization B.
3. The roles of Admin, Member, and Guest are designated within organizations and these roles are consistent across various organizations.
4. Additional roles can be created within the organization template settings. These newly created roles will be applied and shared across all organizations.

note

In Logto, the organization template is an access control model designed specifically for organizations. While it’s based on Role-Based Access Control (RBAC), it’s meant for different scenarios.

Use the organization template when you need to set up roles and permissions for an organization.

For a simple B2C app without an organization level, use user/system-level RBAC instead.

You can use both organization template and user/system-level RBAC in Logto, allowing a more robust approach to meet your specific business and product requirements. To understand RBAC, refer to this section.