website/docs: edited Docs about tenants #8549

tanberry · 2024-02-16T18:19:23Z

Added a bit more info about tenants, and separated the Usage section into the three main parts, wrote to be more procedural style.

If applicable

The documentation has been updated
The documentation has been formatted (make website)

netlify · 2024-02-16T18:19:40Z

✅ Deploy Preview for authentik-storybook canceled.

Name	Link
🔨 Latest commit	`df205a9`
🔍 Latest deploy log	https://app.netlify.com/sites/authentik-storybook/deploys/65cfe02bc7b9c200082b3818

website/docs/advanced/tenancy.md

netlify · 2024-02-16T18:21:09Z

✅ Deploy Preview for authentik ready!

Name	Link
🔨 Latest commit	`df205a9`
🔍 Latest deploy log	https://app.netlify.com/sites/authentik/deploys/65cfe02be108b80008122632
😎 Deploy Preview	https://deploy-preview-8549--authentik.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

rissson · 2024-02-16T18:23:42Z

website/docs/advanced/tenancy.md


-Starting with 2024.2, authentik allows an administrator or operator to create multiple tenants. This means that an operator can manage several authentik installations without having to deploy additional instances.
+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.


So the relationships between an installation, tenants, and licenses are as follows (the leftmost items contain the items under them):

Authentik installation (i.e. a docker-compose or kubernetes deployment)

Install ID (unique to the installation)

Default Tenant

License 1

License 2

Brand 1

Brand 2

Tenant 1

[...]

Tenant 2

[...]

Yep, that is the relationship I finally understood yesterday (thanks to your patience), and attempted to say in the words above. Do you see any word changes that need to be made?

I don't really know tbh. Whatever you think is best to explain this

rissson

Very much needed improvements, thank you @tanberry!

website/docs/advanced/tenancy.md

github-actions · 2024-02-16T18:46:46Z

authentik PR Installation instructions

Instructions for docker-compose

Add the following block to your .env file:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-df205a96c53a1227f1f21fe1872351bf94dd326e
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

For arm64, use these values:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-ghcr.io/goauthentik/dev-server:gh-df205a96c53a1227f1f21fe1872351bf94dd326e-arm64
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

Afterwards, run the upgrade commands from the latest release notes.

Instructions for Kubernetes

Add the following block to your values.yml file:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
    repository: ghcr.io/goauthentik/dev-server
    tag: gh-ghcr.io/goauthentik/dev-server:gh-df205a96c53a1227f1f21fe1872351bf94dd326e

For arm64, use these values:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
image:
    repository: ghcr.io/goauthentik/dev-server
    tag: gh-ghcr.io/goauthentik/dev-server:gh-df205a96c53a1227f1f21fe1872351bf94dd326e-arm64

Afterwards, run the upgrade commands from the latest release notes.

Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

kensternberg-authentik

The usual comments, etc. etc. It's shippable as is.

website/docs/advanced/tenancy.md

kensternberg-authentik · 2024-02-16T20:50:09Z

website/docs/advanced/tenancy.md


-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 all other domains will use the default tenant.
+Then set `AUTHENTIK_TENANTS__API_KEY` to a random string, which 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.


I read "first/then" awkwardly. Maybe eliminate "First, " in the first sentence? Or numbers?

Enable multi-tenancy with the ...

Set the AUTHENTIK_TENANTS__API_KEY to a random string. This string will be used to ...

In the second task, I separated the task from the reason to make it clear that one is an action, the other an explanation. The context is supported by their being in the same paragraph.

Also, maybe recommend how someone could generate a random string? My favorite that works on both Linux and Mac is:

$ cut -b1-2048 < /dev/urandom | head -1 | md5sum 9df3b806764fcdfd2e9ac532bf912fc2 $

The "2048" can be any length, but more is better than less.

Yes! I want more of this in our docs... helpful ways to do things... so that we don't come across assuming everyone is a senior dev. ;-) (Though it is challenging to find the right balance, and not be too pedantic!)

My usual go-to is tr -dc 'a-zA-Z0-9' < /dev/urandom | head -c 32; echo, but we can provide the more generic pwgen 64 1

kensternberg-authentik · 2024-02-16T20:51:25Z

website/docs/advanced/tenancy.md

-::::warning
-Expression policies currently have access to all tenants.
-::::
+You will need to disable the embedded outpost with `AUTHENTIK_OUTPOSTS__DISABLE_EMBEDDED_OUTPOST=true` because it is not supported with tenants.


That seems like a pretty damn big takeaway! Is that noted anywhere before someone starts down this merry path? Also, if we plan on updating the outpost in the future to support multi-tenancy, we should definitely note that here, even if it's just a weak "... it's on the roadmap" statement.

Fair point. I can move this up higher, under the "Important considerations" section, but @jens or @marc will need to address the rest of your point.

tanberry added 5 commits February 15, 2024 14:47

add info

7fc56d8

more usage deets

c5f053c

add steps

93c7af0

polish procedurals

18b2740

comma tweak

9282774

tanberry requested a review from a team as a code owner February 16, 2024 18:19

rissson reviewed Feb 16, 2024

View reviewed changes

website/docs/advanced/tenancy.md Show resolved Hide resolved

rissson reviewed Feb 16, 2024

View reviewed changes

website/docs/advanced/tenancy.md Outdated Show resolved Hide resolved

website/docs/advanced/tenancy.md Outdated Show resolved Hide resolved

website/docs/advanced/tenancy.md Show resolved Hide resolved

website/docs/advanced/tenancy.md Outdated Show resolved Hide resolved

tanberry and others added 3 commits February 16, 2024 12:56

Update website/docs/advanced/tenancy.md

8f2ed8f

Co-authored-by: Marc 'risson' Schmitt <marc.schmitt@risson.space> Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>

marc's edits

aee9896

comma tweak

ab598f9

kensternberg-authentik approved these changes Feb 16, 2024

View reviewed changes

tanberry added 2 commits February 16, 2024 15:44

kens edits

3a143c6

typo

df205a9

tanberry merged commit 24d2c40 into main Feb 19, 2024
69 checks passed

tanberry deleted the docs-tenants branch February 19, 2024 14:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

website/docs: edited Docs about tenants #8549

website/docs: edited Docs about tenants #8549

tanberry commented Feb 16, 2024 •

edited

Loading

netlify bot commented Feb 16, 2024 •

edited

Loading

netlify bot commented Feb 16, 2024 •

edited

Loading

rissson Feb 16, 2024

tanberry Feb 16, 2024

rissson Feb 19, 2024

rissson left a comment •

edited

Loading

github-actions bot commented Feb 16, 2024 •

edited

Loading

kensternberg-authentik left a comment

kensternberg-authentik Feb 16, 2024

kensternberg-authentik Feb 16, 2024

tanberry Feb 16, 2024

rissson Feb 19, 2024

kensternberg-authentik Feb 16, 2024

tanberry Feb 16, 2024


		Starting with 2024.2, authentik allows an administrator or operator to create multiple tenants. This means that an operator can manage several authentik installations without having to deploy additional instances.
		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.


		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 all other domains will use the default tenant.
		Then set `AUTHENTIK_TENANTS__API_KEY` to a random string, which 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.

website/docs: edited Docs about tenants #8549

website/docs: edited Docs about tenants #8549

Conversation

tanberry commented Feb 16, 2024 • edited Loading

netlify bot commented Feb 16, 2024 • edited Loading

✅ Deploy Preview for authentik-storybook canceled.

netlify bot commented Feb 16, 2024 • edited Loading

✅ Deploy Preview for authentik ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rissson left a comment • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Feb 16, 2024 • edited Loading

kensternberg-authentik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tanberry commented Feb 16, 2024 •

edited

Loading

netlify bot commented Feb 16, 2024 •

edited

Loading

netlify bot commented Feb 16, 2024 •

edited

Loading

rissson left a comment •

edited

Loading

github-actions bot commented Feb 16, 2024 •

edited

Loading