add docs

Signed-off-by: Marc 'risson' Schmitt <marc.schmitt@risson.space>

website/docs/advanced/tenancy.md

@@ -0,0 +1,37 @@
+---
+title: Tenancy
+---
+
+::::warning
+This feature is in alpha. Use at your own risk.
+::::
+
+::::info
+This feature is available from 2024.1.1 and is not to be confused with brands, which used to be called tenants.
+::::
+
+## Preparations
+
+Starting with 2024.1.1, authentik allows for multiple tenants to be created. This allows an operator to manage several authentik installations without having to deploy additional instances.
+
+authentik manages tenants by storing data for each tenant in a separate PostgreSQL schema.
+
+This feature needs to be enabled with the `AUTHENTIK_TENANTS__ENABLED=true`. You also need to set `AUTHENTIK_TENANTS__API_KEY` to a random string, which will be used to authenticate to the tenancy API. This key will allow the creation of recovery keys for every tenant hosted by authentik, store it securely. You will also need to disable the embedded outpost with `AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true` as it is not supported with tenants.
+
+## Usage
+
+Tenants can be created using the API routes associated. Search for `tenant` in the [API browser](../../developer-docs/api/) 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. That `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.
+
+By default, all requests that do not explicitely 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 all other domains will use the default tenant.
+
+::::warning
+Expression policies currently have access to all tenants.
+::::
+
+## Notes
+
+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.

website/sidebars.js

@@ -421,6 +421,17 @@ const docsSidebar = {
                 "security/CVE-2022-46172",
             ],
         },
+        {
+            type: "category",
+            label: "Advanced topics",
+            link: {
+                type: "generated-index",
+                title: "Advanced topics",
+                slug: "advanced",
+                description: "Documentation for advanced features",
+            },
+            items: ["advanced/tenancy"],
+        },
     ],
 };