Behind the scenes: How we implement user collaboration within a multi-tenant app
Tags: webdev, identity, productivity, usercollaboration
Published: 2024-05-21 00:22:59

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](https://blog.logto.io/releases/2024-apr/) 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](https://blog.logto.io/mastering-rbac/) 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.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yfr1t33411haue5sw6bh.png)![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3m38vjr2gv8i1jnh5dzt.png)
# 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](https://openapi.logto.io/group/endpoint-organization-invitations).

# 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.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w67ikmt8kn2laj34h1i9.png)
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:

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w26por64xnva6fwcvlze.png)
Refer to the [API documentation](https://openapi.logto.io/operation/operation-post-api-organization-invitations-parameter-message) 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](https://swr.vercel.app/) 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](https://discord.com/invite/UEPaF3j5e6).


{% cta https://logto.io/?ref=dev %} Try Logto Cloud for free {% endcta %}