Skip to content

Commit 5d5cda3

Browse files
bcbogdanbcbogdan
authored
Merge pull request #1047 from supertokens/feat/tenant-management-docs
Feat/tenant management docs
2 parents b747669 + 1079aa0 commit 5d5cda3

File tree

10 files changed

+2075
-56
lines changed

10 files changed

+2075
-56
lines changed

‎docs/authentication/enterprise/manage-tenants.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Manage tenants
2+
title: Tenant actions
33
hide_title: true
44
sidebar_position: 6
55
description: Discover different APIs that can help you work with tenants.

‎docs/authentication/enterprise/tenant-management-plugin.mdx‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
---
2+
title: Tenant management
3+
hide_title: true
4+
sidebar_position: 6
5+
description: Use the tenant management plugin for an out-of-the-box admin experience
6+
page_type: tutorial
7+
---
8+
9+
# Tenant management plugin
10+
11+
## Overview
12+
13+
This tutorial shows you how to add comprehensive tenant management functionality to your SuperTokens authentication flows.
14+
The guide makes use of the plugins functionality which provides complete multi-tenancy management including tenant creation, user roles, invitations, join requests, and seamless tenant switching.
15+
16+
## Before you start
17+
18+
The tenant management plugin supports only the `React` and `NodeJS` SDKs.
19+
Support for other platforms is under active development.
20+
21+
## Steps
22+
23+
### 1. Initialize the backend plugin
24+
25+
#### 1.1 Install the plugin
26+
27+
```bash
28+
npm install @supertokens-plugins/tenants-nodejs
29+
```
30+
31+
#### 1.2 Update your backend SDK configuration
32+
33+
```typescript
34+
import SuperTokens from "supertokens-node";
35+
import TenantsPlugin from "@supertokens-plugins/tenants-nodejs";
36+
37+
SuperTokens.init({
38+
appInfo: {
39+
// your app info
40+
},
41+
recipeList: [
42+
// your recipes
43+
],
44+
experimental: {
45+
plugins: [
46+
TenantsPlugin.init(),
47+
],
48+
},
49+
});
50+
```
51+
52+
##### Configuration options
53+
54+
The plugin supports the following configuration options:
55+
56+
| Option | Type | Default | Description |
57+
|--------|------|---------|-------------|
58+
| `requireNonPublicTenantAssociation` | `boolean` | `false` | Require users to associate with at least one non-public tenant |
59+
| `requireTenantCreationRequestApproval` | `boolean` | `true` | Whether tenant creation requires admin approval |
60+
| `enableTenantListAPI` | `boolean` | `false` | Enable API to list all tenants |
61+
| `createRolesOnInit` | `boolean` | `true` | Auto-create required roles on init |
62+
63+
### 2. Initialize the frontend plugin
64+
65+
#### 2.1 Install the plugin
66+
67+
```bash
68+
npm install @supertokens-plugins/tenants-react
69+
```
70+
71+
#### 2.2 Update your frontend SDK configuration
72+
73+
```typescript
74+
import SuperTokens from "supertokens-auth-react";
75+
import ProfileBasePlugin from "@supertokens-plugins/profile-base-react";
76+
import TenantsPlugin from "@supertokens-plugins/tenants-react";
77+
78+
SuperTokens.init({
79+
appInfo: {
80+
// your app info
81+
},
82+
recipeList: [
83+
// your recipes
84+
],
85+
experimental: {
86+
plugins: [
87+
ProfileBasePlugin.init(),
88+
TenantsPlugin.init(),
89+
],
90+
},
91+
});
92+
```
93+
94+
##### Configuration options
95+
96+
The plugin supports the following configuration options:
97+
98+
| Option | Type | Default | Description |
99+
|--------|------|---------|-------------|
100+
| `requireTenantCreation` | `boolean` | `false` | Whether users must create a tenant before accessing the app |
101+
| `redirectToUrlOnJoiningTenant` | `string` | `/` | The path to which users are redirected after joining a tenant |
102+
103+
### 3. Test the implementation
104+
105+
With this configuration, users can access comprehensive tenant management features through the profile interface.
106+
Make sure that you have a user with the required permissions and then access`/user/tenants/create` to create a new tenant.
107+
108+
## Customization
109+
110+
### Roles and permissions
111+
112+
The plugin automatically creates the following roles and permissions:
113+
114+
#### Default roles
115+
116+
| Role | Description | Permissions |
117+
|------|-------------|-------------|
118+
| `tenant-admin` | Full administrative access within the tenant | All tenant permissions |
119+
| `tenant-member` | Basic member access within the tenant | `tenant-access` |
120+
| `app-admin` | Global application administrator | All permissions across all tenants |
121+
122+
#### Available permissions
123+
124+
| Permission | Description |
125+
|------------|-------------|
126+
| `tenant-access` | Basic access to tenant |
127+
| `list-users` | View list of users in tenant |
128+
| `manage-invitations` | Create and manage tenant invitations |
129+
| `manage-join-requests` | Approve or reject join requests |
130+
| `change-user-roles` | Modify user roles within tenant |
131+
| `remove-users` | Remove users from tenant |
132+
133+
### Email delivery configuration
134+
135+
Configure custom email delivery for tenant-related notifications:
136+
137+
```typescript
138+
import { PluginSMTPService } from "@supertokens-plugins/tenants-nodejs";
139+
import TenantsPlugin from "@supertokens-plugins/tenants-nodejs";
140+
141+
SuperTokens.init({
142+
// ... other config
143+
experimental: {
144+
plugins: [
145+
TenantsPlugin.init({
146+
emailDelivery: {
147+
service: new PluginSMTPService({
148+
smtpSettings: {
149+
host: "smtp.example.com",
150+
port: 587,
151+
from: {
152+
name: "Your App",
153+
email: "[email protected]",
154+
},
155+
secure: false,
156+
authUsername: "username",
157+
password: "password",
158+
},
159+
}),
160+
},
161+
}),
162+
],
163+
},
164+
});
165+
```
166+
167+
### Custom implementation override
168+
169+
You can override default behaviors by providing custom implementations:
170+
171+
```typescript
172+
TenantsPlugin.init({
173+
override: {
174+
functions: (originalImplementation) => ({
175+
...originalImplementation,
176+
isAllowedToCreateTenant: async (session) => {
177+
// Custom logic to determine if user can create tenant
178+
const userId = session.getUserId();
179+
// Add your custom logic here
180+
return true;
181+
},
182+
canApproveJoinRequest: async (targetUser, tenantId, session) => {
183+
// Custom logic for approving join requests
184+
return true;
185+
},
186+
}),
187+
},
188+
});
189+
```
190+
191+
### Custom user interface
192+
193+
To create your own UI you can use the `usePluginContext` hook.
194+
It exposes an interface which you can use to interface with the endpoints exposed by the backend plugin.
195+
196+
```typescript
197+
import { usePluginContext } from "@supertokens-plugins/tenants-react";
198+
199+
function CustomTenantComponent() {
200+
const { api, t } = usePluginContext();
201+
const [tenants, setTenants] = useState([]);
202+
203+
const handleFetchTenants = async () => {
204+
const result = await api.fetchTenants();
205+
if (result.status === "OK") {
206+
setTenants(result.tenants);
207+
}
208+
};
209+
210+
const handleCreateTenant = async (name) => {
211+
const result = await api.createTenant({ name });
212+
if (result.status === "OK") {
213+
console.log("Tenant created successfully");
214+
}
215+
};
216+
217+
const handleSwitchTenant = async (tenantId) => {
218+
const result = await api.switchTenant(tenantId);
219+
if (result.status === "OK") {
220+
console.log("Switched to tenant successfully");
221+
}
222+
};
223+
224+
return (
225+
<div>
226+
<h2>{t("PL_TD_SELECT_TENANT_TITLE")}</h2>
227+
<button onClick={handleFetchTenants}>Load Tenants</button>
228+
{tenants.map((tenant) => (
229+
<div key={tenant.id}>
230+
<span>{tenant.name} ({tenant.role})</span>
231+
<button onClick={() => handleSwitchTenant(tenant.id)}>
232+
Switch
233+
</button>
234+
</div>
235+
))}
236+
</div>
237+
);
238+
}
239+
```
240+
241+
### Custom page components
242+
243+
You can customize the default pages by providing your own components:
244+
245+
```typescript
246+
import TenantsPlugin from "@supertokens-plugins/tenants-react";
247+
import { CustomSelectTenant, CustomTenantManagement } from "./your-custom-components";
248+
249+
SuperTokens.init({
250+
// ... other config
251+
experimental: {
252+
plugins: [
253+
TenantsPlugin.init({
254+
override: (oI) => ({
255+
...oI,
256+
pages: (originalPages) => ({
257+
...originalPages,
258+
selectTenant: CustomSelectTenant,
259+
tenantManagement: CustomTenantManagement,
260+
}),
261+
}),
262+
}),
263+
],
264+
},
265+
});
266+
```
267+
268+
## Next steps
269+
270+
Besides tenant management, you can also explore other enterprise authentication features:
271+
272+
<ReferenceCard.Grid>
273+
<ReferenceCard href="/docs/authentication/enterprise/tenant-discovery" label="Tenant discovery" />
274+
<ReferenceCard href="/docs/authentication/enterprise/initial-setup" label="Initial setup" />
275+
<ReferenceCard href="/docs/authentication/enterprise/manage-tenants" label="Manage tenants" />
276+
<ReferenceCard href="/docs/additional-verification/user-roles/introduction" label="User roles" />
277+
<ReferenceCard href="/docs/references/plugins/introduction" label="Plugins reference" />
278+
</ReferenceCard.Grid>

‎docs/references/plugins/opentelemetry-nodejs.mdx‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,8 @@ Defined in: [supertokens-plugins/packages/opentelemetry-nodejs/src/index.ts:5](h
115115

116116
#### Type Declaration
117117

118-
| Name | Type | Description | Defined in |
119-
| ------ | ------ | ------ | ------ |
118+
| Name | Type | Defined in |
119+
| ------ | ------ | ------ |
120120
| <a id="init"></a> `init` | `any` | [supertokens-plugins/packages/opentelemetry-nodejs/src/index.ts:5](https://github.com/supertokens/supertokens-plugins/blob/main/packages/opentelemetry-nodejs/src/index.ts#L5) |
121121

122122
***
@@ -127,8 +127,7 @@ Defined in: [supertokens-plugins/packages/opentelemetry-nodejs/src/index.ts:5](h
127127
const init: any;
128128
```
129129

130-
Defined in: [supertokens-plugins/packages/opentelemetry-nodejs/src/plugin.ts:11](https://github.com/supertokens/supertokens-plugins/blob/main/packages/opentelemetry-nodejs/src/plugin.ts#L11)
131-
130+
Defined in: [supertokens-plugins/packages/opentelemetry-nodejs/src/plugin.ts:8](https://github.com/supertokens/supertokens-plugins/blob/main/packages/opentelemetry-nodejs/src/plugin.ts#L8)
132131

133132
***
134133

0 commit comments

Comments
 (0)