Behind the scenes: How we implement user collaboration within a multi-tenant app

Practices and insights on implementing an invitation and role access management feature like Logto Cloud collaboration in a multi-tenant application.

Background

We introduced the collaboration feature on Logto Cloud last month. If you missed it, take a look! Now, you can invite colleagues and co-workers to your existing Logto tenants, collaborating together on maintaining the identity system for your applications.

In this feature release, we've added two roles to each Logto tenant:

• Admin: Full access to the tenant, including managing identity-related resources, inviting and managing other members, handling billing, and viewing billing history.
• Collaborator: Can manage identity-related resources but does not have access to other admin features.

Consistent with our commitment to using our own tools, we've leveraged our RBAC (Role-Based Access Control) and Organizations feature in building user collaboration. If you're new to RBAC, check out our previous post to get started.

In this blog post, let's take a look at what went into implementing this feature, and how these practices might benefit you if you're developing multi-organization applications.

Logto Cloud's collaboration is built with Logto Organizations

Each Logto Cloud tenant functions as an independent organization in our system, powered by our own Organizations feature. To introduce the tenant admin and collaborator roles, we created two organization roles in the organization template, each assigned with a specific set of organization permissions.

Handle invitations with Logto Management API

We've provided a set of invitation-related Management APIs in the organizations feature. With these APIs, you can, for example:

• POST /api/organization-invitations create and send an organization invitation to an email address
• GET /api/organization-invitations & GET /api/organization-invitations/{id} get your invitations
• PUT /api/organization-invitations/{id}/status accept or reject the invitation by updating the invitation status For more details, refer to the full API documentation.

Connect with your email connector

Since invitations are sent via email, ensure your email connector is properly configured. In this release, we introduced a new email template usage type, OrganizationInvitation, allowing customization of the invitation email template.

This email template will accept a {{link}} variable by default, which is the link to the Logto Console's landing page, where the users can accept the invitation and join a Logto tenant. One of the landing pages in Logto Cloud looks like the screenshot below:

Refer to the API documentation for more details about sending the invitation email through Management API.

Use RBAC to manage user permissions

With the above setups, we can send invitations via email, and invitees can join the organization with the assigned role.

Users with different organization roles will have different scopes (permissions) in their access tokens. Thus, both the client application (Logto Console) and our backend services should check these scopes to determine visible features and permitted actions.

Alright, so far everything seems connected, and what else do we miss?

Handle scope updates in access tokens

Managing scope updates in access tokens involves:

• Revoking existing scopes: For instance, demoting an admin to a non-admin collaborator automatically shrinks scopes in the new access token obtained with the existing refresh token.
• Granting new scopes: Conversely, promoting a user to admin requires triggering a re-login or re-consent process to reflect the change in user access tokens. In Logto Cloud, the Console actively checks user scopes using SWR requests, and we auto-consent whenever a user is promoted to admin.

If you're implementing a similar feature with RBAC, you'll need a mechanism (e.g., WebSocket or server-push events) to notify your application of scope updates, enabling re-consent or issuing new access tokens accordingly. Logto will also provide more webhooks to assist with this in future updates.

In summary

Logto Cloud's multi-tenancy and collaboration features leverage our Organizations feature. If you're developing a similar multi-tenancy app, consider utilizing this feature with similar approaches.

I hope this blog post proves insightful. For questions or discussions, feel free to join our Discord channel.

Try Logto Cloud for free

Comments

[Parker Waiters]

This is quite detailed! Can you dive deeper into how you handle email connector configurations for different environments?

[Charles Zhao]

Thanks for asking. But I don't quite get what you said about "different environments". Do you mean the different email templates (SignIn / Register / OrganizationInvitation) or different product environment (env / prod)?