From e3674426b75b7fb52272d70c69be76e508f3a409 Mon Sep 17 00:00:00 2001 From: Tana M Berry Date: Wed, 23 Apr 2025 16:39:06 -0500 Subject: [PATCH] website/docs: rearranged brands docs (#14116) * first pass * fixed links. * tweaks * remove extensions in redirects * added edits from review * missed an edit --------- Co-authored-by: Tana M Berry --- .../flow/examples/default_flows.md | 2 +- .../flow/executors/user-settings.md | 2 +- .../flows-stages/flow/index.md | 2 +- website/docs/customize/branding.md | 10 +++ website/docs/customize/brands.md | 39 ------------ website/docs/customize/index.md | 13 ++++ website/docs/enterprise/manage-enterprise.mdx | 2 +- website/docs/releases/2024/v2024.2.md | 2 +- website/docs/releases/2024/v2024.8.md | 2 +- website/docs/sys-mgmt/brands.md | 61 +++++++++++++++++++ website/docs/sys-mgmt/tenancy.md | 2 +- website/netlify.toml | 9 ++- website/sidebars.js | 7 ++- 13 files changed, 103 insertions(+), 50 deletions(-) create mode 100644 website/docs/customize/branding.md delete mode 100644 website/docs/customize/brands.md create mode 100644 website/docs/customize/index.md create mode 100644 website/docs/sys-mgmt/brands.md diff --git a/website/docs/add-secure-apps/flows-stages/flow/examples/default_flows.md b/website/docs/add-secure-apps/flows-stages/flow/examples/default_flows.md index e301339f2b..f99e088b9d 100644 --- a/website/docs/add-secure-apps/flows-stages/flow/examples/default_flows.md +++ b/website/docs/add-secure-apps/flows-stages/flow/examples/default_flows.md @@ -4,7 +4,7 @@ title: Default flows When you create a new provider, you can select certain default flows that will be used with the provider and its associated application. For example, you can [create a custom flow](../index.md#create-a-custom-flow) that override the defaults configured on the brand. -If no default flow is selected when the provider is created, to determine which flow should be used authentik will first check if there is a default flow configured in the active [**Brand**](../../../../customize/brands.md). If no default is configured there, authentik will go through all flows with the matching designation, sorted by `slug` and evaluate policies bound directly to the flows, and the first flow whose policies allow access will be picked. +If no default flow is selected when the provider is created, to determine which flow should be used authentik will first check if there is a default flow configured in the active [**Brand**](../../../../sys-mgmt/brands.md). If no default is configured there, authentik will go through all flows with the matching designation, sorted by `slug` and evaluate policies bound directly to the flows, and the first flow whose policies allow access will be picked. import DefaultFlowList from "../../flow/flow_list/\_defaultflowlist.mdx"; diff --git a/website/docs/add-secure-apps/flows-stages/flow/executors/user-settings.md b/website/docs/add-secure-apps/flows-stages/flow/executors/user-settings.md index f2dfb5a3c5..78c5ed8b60 100644 --- a/website/docs/add-secure-apps/flows-stages/flow/executors/user-settings.md +++ b/website/docs/add-secure-apps/flows-stages/flow/executors/user-settings.md @@ -6,4 +6,4 @@ The user interface (/if/user/) uses a specialized flow executor to allow individ Because the stages in a flow can change during its execution, be aware that configuring this executor to use any stage type other than Prompt or User Write will automatically trigger a redirect to the standard executor. -An admin can customize which fields can be changed by the user by updating the default-user-settings-flow, or copying it to create a new flow with a Prompt Stage and a User Write Stage. Different variants of your flow can be applied to different [Brands](../../../../customize/brands.md) on the same authentik instance. +An admin can customize which fields can be changed by the user by updating the default-user-settings-flow, or copying it to create a new flow with a Prompt Stage and a User Write Stage. Different variants of your flow can be applied to different [Brands](../../../../sys-mgmt/brands.md) on the same authentik instance. diff --git a/website/docs/add-secure-apps/flows-stages/flow/index.md b/website/docs/add-secure-apps/flows-stages/flow/index.md index 62689a8568..bf39074382 100644 --- a/website/docs/add-secure-apps/flows-stages/flow/index.md +++ b/website/docs/add-secure-apps/flows-stages/flow/index.md @@ -46,7 +46,7 @@ To create a flow, follow these steps: After creating the flow, you can then [bind specific stages](../stages/index.md#bind-a-stage-to-a-flow) to the flow and [bind policies](../../../customize/policies/working_with_policies.md) to the flow to further customize the user's log in and authentication process. -To determine which flow should be used, authentik will first check which default authentication flow is configured in the active [**Brand**](../../../customize/brands.md). If no default is configured there, the policies in all flows with the matching designation are checked, and the first flow with matching policies sorted by `slug` will be used. +To determine which flow should be used, authentik will first check which default authentication flow is configured in the active [**Brand**](../../../sys-mgmt/brands.md). If no default is configured there, the policies in all flows with the matching designation are checked, and the first flow with matching policies sorted by `slug` will be used. ## Flow configuration options diff --git a/website/docs/customize/branding.md b/website/docs/customize/branding.md new file mode 100644 index 0000000000..82b5b34099 --- /dev/null +++ b/website/docs/customize/branding.md @@ -0,0 +1,10 @@ +--- +title: Branding +slug: /branding +--- + +You can configure several differently "branded" options depending on the associated domain, even though objects such as applications, providers, etc, are still global. This can be handy to use the same authentik instance, but branded differently for different domains. + +The main settings that control your instance's appearance and behaviour are the _default flows_ and the _branding settings_. + +To create or modify a brand, open the Admin interface and navigate to **System** > **Brands**. For complete instructions refer to our [Brands documentation](../sys-mgmt/brands.md). diff --git a/website/docs/customize/brands.md b/website/docs/customize/brands.md deleted file mode 100644 index f9e42bb853..0000000000 --- a/website/docs/customize/brands.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Brands -slug: /brands ---- - -You can configure several differently "branded" options depending on the associated domain, even though objects such as applications, providers, etc, are still global. This can be handy to use the same authentik instance, but branded differently for different domains. - -The main settings that brands influence are flows and branding. - -## Flows - -You can explicitly select, in your instance's Brand settings, the _default flows_ to use for the current brand. To do so, log in as an administrator, open the Admin interface, and navigate to **System -> Brands**. There you can optionally configure these default flows: - -- Authentication flow: the flow used to authenticate users. If left empty, the first applicable flow sorted by the slug is used. -- Invalidation flow: for typical use cases, select the `default-invalidation-flow` (Logout) flow. This flow logs the user out of authentik when the application session ends (user logs out of the app). -- Recovery flow: if set, the user can access an option to recover their login credentials. -- Unenrollment flow: if set, users are able to unenroll themselves using this flow. If no flow is set, option is not shown. -- User settings flow: if set, users are able to configure details of their profile. -- Device code flow: if set, the OAuth Device Code profile can be used, and the selected flow will be used to enter the code. - -If a default flow is _not_ set in the brand, then authentik selects any flow that: - - - matches the required designation - - comes first sorted by slug - - is allowed by policies - -This means that if you want to select a default flow based on policy, you can leave the brand default empty. To learn more about default flows, refer to our [documentation](../add-secure-apps/flows-stages/flow/examples/default_flows.md). - -## Branding - -The brand configuration controls the branding title (shown in website document title and several other places), the sidebar/header logo that appears in the upper left of the product interface, and the favicon on a browser tab. - -:::info -Starting with authentik 2024.6.2, the placeholder `%(theme)s` can be used in the logo configuration option, which will be replaced with the active theme. -::: - -## External user settings - -You can configure authentik to redirect external users to a default application when they successfully authenticate (without being sent from a specific application). To do so, use the **Default application** configuration on the **System -> Brands** page of the Admin interface. diff --git a/website/docs/customize/index.md b/website/docs/customize/index.md new file mode 100644 index 0000000000..be9881385d --- /dev/null +++ b/website/docs/customize/index.md @@ -0,0 +1,13 @@ +--- +title: Customize your instance +--- + +You can customize the behaviour, look, and available resources for your authentik instance. For more information refer to each of the topics below: + +- [Policies](./policies/working_with_policies.md) +- Interfaces: + - [Flows](./interfaces/flow/customization.mdx) + - [User interface](./interfaces/user/customization.mdx) + - [Admin interface](./interfaces/admin/customization.mdx) +- [Blueprints](./blueprints/index.mdx) +- [Branding](./branding.md) diff --git a/website/docs/enterprise/manage-enterprise.mdx b/website/docs/enterprise/manage-enterprise.mdx index f05079e373..e9ca3fe300 100644 --- a/website/docs/enterprise/manage-enterprise.mdx +++ b/website/docs/enterprise/manage-enterprise.mdx @@ -117,7 +117,7 @@ The following events occur when a license expires or the internal/external user License usage is calculated based on total user counts that authentik regularly captures. This data is checked against all valid licenses, and the sum total of all users. Internal and external users are counted based on the number of active users of the respective type saved in authentik. Service account users are not counted towards the license. -An **internal** user is typically a team member, such as a company employee, who has access to the full Enterprise feature set. An **external** user might be an external consultant, a volunteer in a charitable site, or a B2C customer who logged onto your website to shop. External users don't get access to Enterprise features, nor to the **My applications** page in authentik. Instead, external users are authenticated and then redirected to log directly into their [default application](../customize/brands.md#external-user-settings). +An **internal** user is typically a team member, such as a company employee, who has access to the full Enterprise feature set. An **external** user might be an external consultant, a volunteer in a charitable site, or a B2C customer who logged onto your website to shop. External users don't get access to Enterprise features, nor to the **My applications** page in authentik. Instead, external users are authenticated and then redirected to log directly into their [default application](../sys-mgmt/brands.md#external-user-settings). ### Upgrade the number of users in a license diff --git a/website/docs/releases/2024/v2024.2.md b/website/docs/releases/2024/v2024.2.md index 090867ceb3..de2eefd4aa 100644 --- a/website/docs/releases/2024/v2024.2.md +++ b/website/docs/releases/2024/v2024.2.md @@ -25,7 +25,7 @@ slug: /releases/2024.2 Blueprints using `authentik_tenants.tenant` will need to be changed to use `authentik_brands.brand`. - For more information, refer to the [documentation for _brands_](../../customize/brands.md). + For more information, refer to the [documentation for _brands_](../../sys-mgmt/brands.md). Also, **the event retention settings configured in brands (previously tenants, see above) has been removed and is now a system setting**, managed in the Admin interface or via the API (see below). diff --git a/website/docs/releases/2024/v2024.8.md b/website/docs/releases/2024/v2024.8.md index 939d558bc6..e8d8b25fa9 100644 --- a/website/docs/releases/2024/v2024.8.md +++ b/website/docs/releases/2024/v2024.8.md @@ -110,7 +110,7 @@ slug: "/releases/2024.8" - **WebFinger support** - With the addition of the [default application](../../customize/brands.md#external-user-settings) setting, when the default application uses an OIDC provider, a WebFinger endpoint is available now. + With the addition of the [default application](../../sys-mgmt/brands.md#external-user-settings) setting, when the default application uses an OIDC provider, a WebFinger endpoint is available now. ## Upgrading diff --git a/website/docs/sys-mgmt/brands.md b/website/docs/sys-mgmt/brands.md new file mode 100644 index 0000000000..ddc3ecc92d --- /dev/null +++ b/website/docs/sys-mgmt/brands.md @@ -0,0 +1,61 @@ +--- +title: Brands +slug: /brands +--- + +As an authentik admin, you can customize your instance's appearance and behavior using brands. While a single authentik instance supports only one brand per domain, you can apply a separate brand to each domain. + +For an overview of branding and other customization options in authentik refer to [Customize your instance](../customize/index.md). + +## Create or edit a brand + +To create or edit a brand, follow these steps: + +1. Log in as an administrator, open the authentik Admin interface, and navigate to **System** > **Brands**. + +2. Click **Create** to add a new brand, or click the **Edit** icon next to an existing brand to modify it. + +3. Define the configurations in the following settings: + +### Branding settings + +The brand settings define the visual identity of the brand, including: + +- **Branding title**: Displayed in the browser tab (document title) and throughout the UI; +- **Logo**: Appears in the sidebar/header; +- **Favicon**: Shown on the browser tab. + +:::info +Starting with authentik 2024.6.2, the placeholder `%(theme)s` can be used in the logo configuration option, which will be replaced with the active theme. +::: + +### External user settings + +You can configure authentik to redirect external users to a default application after they log in (if they weren't originally redirected from a specific application). To do this: + +1. Open the authentik Admin interface and navigate to **System** > **Brands**. +2. Click the **Edit** icon for the relevant brand. +3. Under **External user settings** select a **Default application**. + +### Default flows + +You can explicitly select, in your instance's Brand settings, the _default flows_ to use for the current brand. You can optionally configure these default flows ([learn more about each default flow](../add-secure-apps/flows-stages/flow/examples/default_flows.md)): + +- **Authentication** flow: the flow used to authenticate users. If left empty, the first applicable flow sorted by the slug is used. +- **Invalidation flow**: for typical use cases, select the `default-invalidation-flow` (Logout) flow. This flow logs the user out of authentik when the application session ends (user logs out of the app). +- **Recovery flow**: if set, the user can access an option to recover their login credentials. +- **Unenrollment flow**: if set, users are able to unenroll themselves using this flow. If no flow is set, option is not shown. +- **User settings flow**: if set, users are able to configure details of their profile. +- **Device code flow**: if set, the OAuth Device Code profile can be used, and the selected flow will be used to enter the code. + +If a default flow is _not_ set in the brand, then authentik selects any flow that: + + - matches the required designation + - comes first sorted by slug + - is allowed by policies + +This means that if you want to select a default flow based on policy, you can leave the brand default empty. + +## Other global settings + +Under **Other global settings** you can specify an exact web certificate. diff --git a/website/docs/sys-mgmt/tenancy.md b/website/docs/sys-mgmt/tenancy.md index d874b0f47f..74d8129030 100644 --- a/website/docs/sys-mgmt/tenancy.md +++ b/website/docs/sys-mgmt/tenancy.md @@ -8,7 +8,7 @@ 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](../customize/brands.md), which were previously called tenants. +This feature is available from 2024.2 and is not to be confused with [brands](../sys-mgmt/brands.md), which were previously called tenants. :::: ## About tenants diff --git a/website/netlify.toml b/website/netlify.toml index 81b2b4d636..1527050f07 100644 --- a/website/netlify.toml +++ b/website/netlify.toml @@ -63,11 +63,14 @@ status = 302 [[redirects]] - from = "/docs/add-secure-apps/flows-stages/flow/layouts.md" - to = "/docs/add-secure-apps/flows-stages/flow/executors/if-flow.md" + from = "/docs/add-secure-apps/flows-stages/flow/layouts" + to = "/docs/add-secure-apps/flows-stages/flow/executors/if-flow" status = 302 - +[[redirects]] + from = "/docs/customize/brands" + to = "/docs/customize/branding" + status = 302 # Migration to new structure with script Sept 2025 diff --git a/website/sidebars.js b/website/sidebars.js index 08f4132321..d764516416 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -368,6 +368,10 @@ export default { type: "category", label: "Customize your instance", collapsed: true, + link: { + type: "doc", + id: "customize/index", + }, items: [ { type: "category", @@ -438,7 +442,7 @@ export default { }, ], }, - "customize/brands", + "customize/branding", ], }, { @@ -582,6 +586,7 @@ export default { label: "System Management", collapsed: true, items: [ + "sys-mgmt/brands", { type: "category", label: "Operations",