Paid Feature
This is a paid feature. Email us to get a license key to start a SuperTokens subscription.
If you want to try this feature without contacting us, you can:
- Sign up for our managed service, and use this feature in our development environment for free; OR
- You can self host the SuperTokens core and run it with the in memory db, by not connecting it to a database when running it. All paid features are enabled for free when using the in memory db.
Creating and configuring a tenant
#
Step 1: Create a tenant and enable third party login for themThe first step in setting up a multi tenant login system is to create a tenant in the SuperTokens core. Each tenant has a unique tenantId
(a string data type) mapped to that tenant's configuation. The tenantId
could be that tenant's sub domain, or a workspace URL, or anything else using which you can uniquely identify them.
The configuration mapped to each tenant contains information about which login methods are enabled for them. You can create a tenant via our backend SDK or via a cURL command to the core. This also allows you to dynamically create tenants without manual intervention:
- NodeJS
- GoLang
- Python
- cURL
Important
import Multiteancy from "supertokens-node/recipe/multitenancy";
async function createTenant() {
let resp = await Multiteancy.createOrUpdateTenant("customer1", {
thirdPartyEnabled: true,
});
if (resp.createdNew) {
// new tenant was created
} else {
// existing tenant's config was modified.
}
}
import (
"github.com/supertokens/supertokens-golang/recipe/multitenancy"
"github.com/supertokens/supertokens-golang/recipe/multitenancy/multitenancymodels"
)
func main() {
tenantId := "customer1"
thirdPartyEnabled := true
resp, err := multitenancy.CreateOrUpdateTenant(&tenantId, multitenancymodels.TenantConfig{
thirdPartyEnabled: &thirdPartyEnabled,
})
if err != nil {
// handle error
}
if resp.OK.CreatedNew {
// new tenant was created
} else {
// existing tenant's config was modified.
}
}
- Asyncio
- Syncio
TODO
TODO
- Single app setup
- Multi app setup
curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"tenantId": "customer1",
"thirdPartyEnabled": true
}'
curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"tenantId": "customer1",
"thirdPartyEnabled": true
}'
#
Step 2: Configure the third party providers for the tenantOnce you have created a tenant with third party enabled, you need to configure which third party providers to enable for the tenant. We have several in built providers, but you can also configure a custom provider.
Once again, you can add / modify this config dynamically using our backend SDK or using a cURL command.
- NodeJS
- GoLang
- Python
- cURL
Important
import Multiteancy from "supertokens-node/recipe/multitenancy";
async function createTenant() {
let resp = await Multiteancy.createOrUpdateThirdPartyConfig("customer1", {
thirdPartyId: "active-directory",
name: "Active Directory",
clients: [{
clientId: "...",
clientSecret: "...",
}],
oidcDiscoveryEndpoint: "https://login.microsoftonline.com/<directoryId>/v2.0",
});
if (resp.createdNew) {
// Active Directory added to customer1
} else {
// Existing active directory config overwritten for customer1
}
}
import (
"github.com/supertokens/supertokens-golang/recipe/multitenancy"
"github.com/supertokens/supertokens-golang/recipe/thirdparty/tpmodels"
)
func main() {
tenantId := "customer1"
resp, err := multitenancy.CreateOrUpdateThirdPartyConfig(tpmodels.ProviderConfig{
TenantId: &tenantId,
ThirdPartyId: "active-directory",
Name: "Active Directory",
Clients: []tpmodels.ProviderClientConfig{
{
ClientID: "...",
ClientSecret: "...",
},
},
OIDCDiscoveryEndpoint: "https://login.microsoftonline.com/<directoryId>/v2.0",
})
if err != nil {
// handle error
}
if resp.OK.CreatedNew {
// Active Directory added to customer1
} else {
// Existing active directory config overwritten for customer1
}
}
- Asyncio
- Syncio
TODO
TODO
- Single tenant / app setup
- Multi tenant / app setup
curl --location --request PUT '/recipe/multitenancy/config/thirdparty' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"config": {
"thirdPartyId": "active-directory",
"name": "Active Directory",
"clients": [
{
"clientId": "...",
"clientSecret": "...",
}
],
"oidcDiscoveryEndpoint": "https://login.microsoftonline.com/<directoryId>/v2.0"
}
}'
curl --location --request PUT '/recipe/multitenancy/config/thirdparty' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"config": {
"thirdPartyId": "active-directory",
"name": "Active Directory",
"clients": [
{
"clientId": "...",
"clientSecret": "...",
}
],
"oidcDiscoveryEndpoint": "https://login.microsoftonline.com/<directoryId>/v2.0"
}
}'
- The above code snippet shows how you can add an Active directory login to your tenant. The
clientId
,clientSecret
anddirectoryId
will be provided to you by your tenant. - You can see the required information for other providers on this page.
Next steps
You have now successfully configured a new tenant in SuperTokens. The next step is to wire up the frontend SDK to show the right login UI for this tenant. The specifics of this step depend on the UX that you want to provide to your users, but we have two common UX flows documented in the next section.
#
Providing additional configuration per tenantYou can also configure a tenant to have different configurations as per the core's config.yaml
(or docker env) variabls. Below is how you can specify the config, when creating or modifying a tenant:
- NodeJS
- GoLang
- Python
- cURL
Important
import Multitenancy from "supertokens-node/recipe/multitenancy";
async function createNewTenant() {
let resp = await Multitenancy.createOrUpdateTenant("customer1", {
coreConfig: {
"email_verification_token_lifetime": 7200000,
"password_reset_token_lifetime": 3600000,
"postgresql_connection_uri": "postgresql://localhost:5432/db2",
}
});
if (resp.createdNew) {
// new tenant was created
} else {
// existing tenant's config was modified.
}
}
import (
"github.com/supertokens/supertokens-golang/recipe/multitenancy"
"github.com/supertokens/supertokens-golang/recipe/multitenancy/multitenancymodels"
)
func main() {
tenantId := "customer1"
thirdPartyEnabled := true
resp, err := multitenancy.CreateOrUpdateTenant(&tenantId, multitenancymodels.TenantConfig{
CoreConfig: map[]interface{}{
"email_verification_token_lifetime": 7200000,
"password_reset_token_lifetime": 3600000,
"postgresql_connection_uri": "postgresql://localhost:5432/db2",
}
})
if err != nil {
// handle error
}
if resp.OK.CreatedNew {
// new tenant was created
} else {
// existing tenant's config was modified.
}
}
- Asyncio
- Syncio
TODO
TODO
- Single app setup
- Multi app setup
curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"tenantId": "customer1",
"coreConfig": {
"email_verification_token_lifetime": 7200000,
"password_reset_token_lifetime": 3600000,
"postgresql_connection_uri": "postgresql://localhost:5432/db2"
}
}'
curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
"tenantId": "customer1",
"coreConfig": {
"email_verification_token_lifetime": 7200000,
"password_reset_token_lifetime": 3600000,
"postgresql_connection_uri": "postgresql://localhost:5432/db2"
}
}'
In the above example, we are setting different values for certain configs for customer1
tenant. All other configs are inherited from the base config (config.yaml file or docker env vars).
We even specify a postgresql_connection_uri
config. This means that all the information related to this tenant (users, roles, metadata etc) will be saved in the db pointed to by the value of postgresql_connection_uri
(A similar config exists for MySQL as well). This can be used to achieve data isolation on a tenant level. This config is not necessary and if not provided, the tenant's information will be stored in the db as specified in the core's config.yaml or docker env vars (it will still be a different user pool though).
Here is the list of full core config variables that can be configured, and below are the lists of variables depending on the database you use:
important
Some configs cannot be different across tenants - they must be the same within an app. In the above links, if a config has a comment saying DIFFERENT_ACROSS_TENANTS
, then it can be changed for each tenant, else if it has DIFFERENT_ACROSS_APPS
, then it must be the same for all tenants within an app.
If a config has neither of these, then it can only be set per core instance.
Once you have set the configs for a specific tenant, you can fetch the tenant info as shown below:
- NodeJS
- GoLang
- Python
- cURL
Important
import Multitenancy from "supertokens-node/recipe/multitenancy";
async function getTenant(tenantId: string) {
let resp = await Multitenancy.getTenant(tenantId);
if (resp === undefined) {
// tenant does not exist
} else {
let coreConfig = resp.coreConfig;
let isEmailPasswordLoginEnabled = resp.emailPassword.enabled;
let isThirdPartyLoginEnabled = resp.thirdParty.enabled;
let isPasswordlessLoginEnabled = resp.passwordless.enabled;
let configuredThirdPartyProviders = resp.thirdParty.providers;
}
}
import (
"github.com/supertokens/supertokens-golang/recipe/multitenancy"
"github.com/supertokens/supertokens-golang/recipe/multitenancy/multitenancymodels"
)
func main() {
tenantId := "customer1"
tenant, err := multitenancy.GetTenant("customer1")
if err != nil {
// handle error
}
if tenant == nil {
// tenant does not exist
} else {
coreConfig := tenant.CoreConfig;
isEmailPasswordLoginEnabled := resp.EmailPassword.Enabled;
isThirdPartyLoginEnabled := resp.ThirdParty.Enabled;
isPasswordlessLoginEnabled := resp.Passwordless.Enabled;
configuredThirdPartyProviders := resp.ThirdParty.Providers;
}
}
- Asyncio
- Syncio
TODO
TODO
- Single app setup
- Multi app setup
curl --location --request GET '/customer1/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json'
curl --location --request GET '/customer1/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json'
Notice that we added customer1
to the path of the request. This tells the core that the tenant you want to get the information about is customer1
(the one we created before in this page).
If the input tenant does not exist, you will get back a 200
status code with the following JSON:
{status: "TENANT_NOT_FOUND_ERROR"}
Otherwise you will get a 200
status code with the following JSON output:
{
"status": "OK",
"emailPassword": {
"enabled": boolean
},
"thirdParty": {
"enabled": boolean,
"providers": [...]
},
"passwordless": {
"enabled": boolean
},
"coreConfig": {
"email_verification_token_lifetime": 7200000,
"password_reset_token_lifetime": 3600000,
"postgresql_connection_uri": "postgresql://localhost:5432/db2"
},
"tenantId": "customer1"
}
The returned coreConfig
is the same as what we had set when creating / updating the tenant. The rest of the core configurations for this tenant are inherited from the app's (or the public
tenant) config. The public
tenant, for the public
app inherits its configs from the config.yaml
/ docker env var values.