authentik/website/docs/sys-mgmt/tenancy.md

5.0 KiB

title
Tenancy

Enterprise


::::warning This feature is in alpha. Use at your own risk. ::::

::::info This feature is available from 2024.2 and is not to be confused with brands, which were previously called tenants. ::::

About tenants

Starting with version 2024.2, authentik allows an administrator or operator to create multiple tenants. This means that an operator can manage several different and distinct authentik installations, each with it's own Install ID and license(s). The relationships between tenant and installation (Install ID) is a 1:1 relationship, so for each tenant, there is a unique Install ID.

::::danger Expression policies currently have access to all tenants. ::::

The data for each tenant is stored in a separate PostgreSQL schema, providing full separation of user data. License data for the tenant is also stored in the schema.

Note that creating and managing multiple tenants is handled using authentik APIs, not in the Admin interface. For typical authentik installations in which only a single tenant is needed, the default tenant is automatically created by authentik, and does not need to be managed in the Admin interface.

Licensing

For each additional tenant (beyond the default one), one or more licenses is required; a license key cannot be used for more than one tenant. Note that the license for the default tenant must be valid and up-to-date in order to create additional tenants.

A single tenant and its corresponding installation can have multiple license keys. For example, a company might purchase one license for 50 users, and then later in the same year need to buy another license for 50 more users, due to company growth. Both licenses are associated to the one installation, the one tenant.

Learn more in our documentation about Enterprise licenses.

Important considerations

  • Upon creating another tenant, a new schema will be created by cloning the template schema. This special schema is like a tenant with no data created in it. Cloning an existing schema instead of creating a new one and running migrations on it is done for efficiency purposes.

  • In a typical deployment, all data stored in Redis (such as tasks, locks, and cached objects) will have its keys prefixed by the schema_name.

  • Files are isolated on a per-tenant basis, with each tenant folder named according to the schema_name. For example, /media/t_example. The same is true regardless of the storage backend.

  • Using an embedded outpost with multi-tenancy is not currently supported. Disable the embedded outpost with AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true configuration setting.

Usage

To create one or more additional tenants (beyond the default tenant) use the following instructions.

1. Configure authentik to allow multiple tenants

First, enable the multi-tenancy feature with the AUTHENTIK_TENANTS__ENABLED=true configuration setting.

Next, set AUTHENTIK_TENANTS__API_KEY to a random string. This string will be used to authenticate to the tenancy API. This key allows the creation of recovery keys for every tenant hosted by authentik, so be sure to store it securely. Be aware that creating a recovery key allows access to all data stored inside a tenant.

Be sure to disable the embedded outpost with AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true because it is not supported with tenants.

2. Create a new tenant with authentik API endpoints

Tenants are created using the API routes associated. Search for tenant in the API browser for the available endpoints.

When creating a tenant you must specify a name, used for display purposes, and a schema_name, used to create the PostgreSQL schema associated with the tenant.

:::info The schema_name must start with t_ and not be more than 64 characters long. :::

There is always at least one tenant, public. This is the default tenant and cannot be deleted. Despite its name, it is not freely available to the world. Instead, it is stored in the public schema of the PostgreSQL database.

3. Associate the new tenant with a domain

By default, all requests that do not explicitly belong to a tenant are redirected to the default tenant. Thus, after creating a tenant, you must associate a domain for which incoming requests will be redirected to said tenant.

You can do so with API endpoints. After creating a domain example.org that is associated to the tenant t_example, all requests made to example.org will use the t_example tenant. However, requests made to authentik.tld, subdomain.example.org and any other domain that is not associated with the t_example tenant will use the default tenant.

In summary, if you access a domain that is not explicitly associated with a specific tenant, it will be routed to the default tenant.