website/docs: add info about invalidation flow, default flows in gene…

…ral (#11800)

* restructure

* tweak

* fix header

* added more definitions

* jens excellent idea

* restructure the Layouts content

* tweaks

* links fix

* links still

* fighting links and cache

* argh links

* ditto

* remove link

* anothe link

* Jens' edit

* listed default flows set by brand

* add links back

* tweaks

* used import for list

* tweak

* rewrite some stuff

Signed-off-by: Jens Langhammer <[email protected]>

* format

Signed-off-by: Jens Langhammer <[email protected]>

* mangled rebase, fixed

* bump

---------

Signed-off-by: Jens Langhammer <[email protected]>
Co-authored-by: Tana M Berry <[email protected]>
Co-authored-by: Jens Langhammer <[email protected]>

website/docs/add-secure-apps/applications/manage_apps.md

@@ -26,7 +26,7 @@ To add an application to authentik and have it display on users' **My applicatio
 
 ## Authorization
 
-Application access can be configured using (Policy) Bindings. Click on an application in the applications list, and select the _Policy / Group / User Bindings_ tab. There you can bind users/groups/policies to grant them access. When nothing is bound, everyone has access. You can use this to grant access to one or multiple users/groups, or dynamically give access using policies.
+Application access can be configured using (Policy) bindings. Click on an application in the applications list, and select the _Policy / Group / User Bindings_ tab. There you can bind users/groups/policies to grant them access. When nothing is bound, everyone has access. You can use this to grant access to one or multiple users/groups, or dynamically give access using policies.
 
 By default, all users can access applications when no policies are bound.
 

website/docs/add-secure-apps/flows-stages/flow/examples/default_flows.md

@@ -0,0 +1,11 @@
+---
+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.
+
+import DefaultFlowList from "../../flow/flow_list/\_defaultflowlist.mdx";
+
+<DefaultFlowList />

website/docs/add-secure-apps/flows-stages/flow/examples/flows.md

@@ -1,5 +1,5 @@
 ---
-title: Example Flows
+title: Example flows
 ---
 
 :::info

website/docs/add-secure-apps/flows-stages/flow/executors/if-flow.md

@@ -7,3 +7,27 @@ This is the default, web-based environment that flows are executed in. All stage
 :::info
 All flow executors use the same [API](../../../../developer-docs/api/flow-executor.md), which allows for the implementation of custom flow executors.
 :::
+
+## Layouts
+
+Starting with authentik 2022.5, the layout of the default flow executor can be changed. Below are examples for the available options:
+
+### Stacked (default)
+
+![](../layouts/stacked.png)
+
+### Content besides logo (left)
+
+![](../layouts/content_left.png)
+
+### Content besides logo (right)
+
+![](../layouts/content_right.png)
+
+### Sidebar (left)
+
+![](../layouts/sidebar_left.png)
+
+### Sidebar (right)
+
+![](../layouts/sidebar_right.png)

website/docs/add-secure-apps/flows-stages/flow/flow_list/_defaultflowlist.mdx

@@ -0,0 +1,13 @@
+-   **Authentication**: this option designates a flow to be used for authentication. The authentication flow should always contain a [**User Login**](../../stages/user_login/index.md) stage, which attaches the staged user to the current session.
+
+-   **Authorization**: designates a flow to be used for authorization of an application. Can be used to add additional verification steps before the user is allowed to access an application. This flow is defined per provider, when the provider is created, to state whether implicit or explicit authorization is required.
+
+-   **Enrollment**: designates a flow for enrollment. This flow can contain any amount of verification stages, such as [**Email**](../../stages/email/index.mdx) or **Captcha**. At the end, to create the user, you can use the [**User Write**](../../stages/user_write.md) stage, which either updates the currently staged user, or if none exists, creates a new one.
+
+-   **Invalidation**: designates a default flow to be used to invalidate a session. Use `default-invalidation-flow` for invalidation from authentik itself, or use `default-provider-invalidation-flow` to invalidate when the session of an application ends. When you use the `default-invalidation-flow` as a global invalidation flow, it should contain a [**User Logout**](../../stages/user_logout.md) stage. When you use the `default-provider-invalidation-flow` (supported with OIDC, SAML, Proxy, and RAC providers), you can configure this default flow to present users log-off options such as "log out of the app but remain logged in to authentik" or "return to the **My Applications** page", or "log out completely". (Alternatively, you can create a custom invalidation flow, with a branded background image.)
+
+-   **Recovery**: designates a flow for recovery. This flow normally contains an [**Identification**](../../stages/identification/index.md) stage to find the user. It can also contain any amount of verification stages, such as [**Email**](../../stages/email/index.mdx) or [**CAPTCHA**](../../stages/captcha/index.md). Afterwards, use the [**Prompt**](../../stages/prompt/index.md) stage to ask the user for a new password and the [**User Write**](../../stages/user_write.md) stage to update the password.
+
+-   **Stage configuration**: designates a flow for general setup. This designation doesn't have any constraints in what you can do. For example, by default this designation is used to configure authenticators, like change a password and set up TOTP.
+
+-   **Unenrollment**: designates a flow for unenrollment. This flow can contain any amount of verification stages, such as [**email**](../../stages/email/index.mdx) or [**Captcha**](../../stages/captcha/index.md). As a final stage, to delete the account, use the [**user_delete**](../../stages/user_delete.md) stage.

website/docs/add-secure-apps/flows-stages/flow/index.md

@@ -4,11 +4,11 @@ title: Flows
 
 Flows are a major component in authentik. In conjunction with stages and [policies](../../../customize/policies/index.md), flows are at the heart of our system of building blocks, used to define and execute the workflows of authentication, authorization, enrollment, and user settings.
 
-There are over a dozen default, out-of-the box flows available in authentik. Users can decide if they already have everything they need with the default flows or if they want to [create](#create-a-custom-flow) their own custom flow, using the Admin interface.
+There are over a dozen default, out-of-the box flows available in authentik. Users can decide if they already have everything they need with the [default flows](../flow/examples/default_flows.md) or if they want to [create](#create-a-custom-flow) their own custom flow, using the Admin interface, Terraform, or via the API.
 
 A flow is a method of describing a sequence of stages. A stage represents a single verification or logic step. By connecting a series of stages within a flow (and optionally attaching policies as needed) you can build a highly flexible process for authenticating users, enrolling them, and more.
 
-For example, a standard login flow would consist of the following stages:
+For example a standard login flow would consist of the following stages:
 
 -   **Identification stage**: user identifies themselves via a username or email address
 -   **Password stage**: the user's password is checked against the hash in the database
@@ -22,8 +22,6 @@ By default, policies are evaluated dynamically, right before the stage (to which
 
 This default behaviour can be altered by enabling the **Evaluate when flow is planned** option on the stage binding. With this setting a _flow plan_ containing all stages is generated upon flow execution. This means that all attached policies are evaluated upon execution. For more information about flow plans, read our [flow context documentation](./context/index.md).
 
-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.
-
 ## Permissions
 
 Flows can have [policies](../stages/index.md) assigned to them. These policies determine if the current user is allowed to see and use this flow.
@@ -64,19 +62,9 @@ When creating or editing a flow in the UI of the Admin interface, you can set th
 
 **Designation**: Flows are designated for a single purpose. This designation changes when a flow is used. The following designations are available:
 
--   **Authentication**: this option designates a flow to be used for authentication. The authentication flow should always contain a [**User Login**](../stages/user_login/index.md) stage, which attaches the staged user to the current session.
-
--   **Authorization**: designates a flow to be used for authorization of an application. Can be used to add additional verification steps before the user is allowed to access an application.
-
--   **Invalidation**: designates a flow to be used to invalidate a session. Both used to invalidate a session from authentik and when the session of an application ends. When used as a global invalidation flow should contain a [**User Logout**](../stages/user_logout.md) stage.
-
--   **Enrollment**: designates a flow for enrollment. This flow can contain any amount of verification stages, such as [**Email**](../stages/email/index.mdx) or [**Captcha**](../stages/captcha/index.md). At the end, to create the user, you can use the [**User Write**](../stages/user_write.md) stage, which either updates the currently staged user, or if none exists, creates a new one.
-
--   **Unenrollment**: designates a flow for unenrollment. This flow can contain any amount of verification stages, such as [**email**](../stages/email/index.mdx) or [**Captcha**](../stages/captcha/index.md). As a final stage, to delete the account, use the [**user_delete**](../stages/user_delete.md) stage.
-
--   **Recovery**: designates a flow for recovery. This flow normally contains an [**Identification**](../stages/identification/index.md) stage to find the user. It can also contain any amount of verification stages, such as [**Email**](../stages/email/index.mdx) or [**captcha**](../stages/captcha/index.md). Afterwards, use the [**Prompt**](../stages/prompt/index.md) stage to ask the user for a new password and the [**User Write**](../stages/user_write.md) stage to update the password.
+import Defaultflowlist from "../flow/flow_list/\_defaultflowlist.mdx";
 
--   **Stage configuration**: designates a flow for general setup. This designation doesn't have any constraints in what you can do. For example, by default this designation is used to configure authenticators, like change a password and setup TOTP.
+<Defaultflowlist />
 
 **Authentication**: Using this option, you can configure whether the the flow requires initial authentication or not, whether the user must be a superuser, or if the flow requires an outpost.
 

website/docs/add-secure-apps/providers/index.mdx

@@ -13,7 +13,9 @@ Applications can use additional providers to augment the functionality of the ma
 
 You can create a new provider in the Admin interface, or you can use the [Application wizard](../applications/manage_apps.md#instructions) to create a new application and its provider at the same time.
 
-Refer to the documentation for each provider:
+When you create certain types of providers, you need to select specific [flows](../flows-stages/flow/index.md) to apply to users who access authentik via the provider. To learn more, refer to our [default flow documentation](../flows-stages/flow/examples/default_flows.md).
+
+To learn more about each provider type, refer to the documentation for each provider:
 
 <DocCardList />
 

website/docs/customize/brands.md

@@ -9,13 +9,22 @@ The main settings that brands influence are flows and branding.
 
 ## Flows
 
-authentik picks a default flow by selecting the flow that is configured in the current brand, otherwise any flow that:
+You can explicitly select, in your instance's Brand settings, the default flow to use for the following configurations:
+
+-   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.
+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
 

website/netlify.toml

@@ -62,7 +62,10 @@
   to = "/docs/providers/property-mappings/expression"
   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"
+  status = 302
 
 
 

website/sidebars.js

@@ -251,14 +251,14 @@ export default {
                                 id: "add-secure-apps/flows-stages/flow/index",
                             },
                             items: [
-                                "add-secure-apps/flows-stages/flow/layouts",
                                 "add-secure-apps/flows-stages/flow/inspector",
                                 "add-secure-apps/flows-stages/flow/context/index",
                                 {
                                     type: "category",
-                                    label: "Examples",
+                                    label: "Defaults and Examples",
                                     items: [
                                         "add-secure-apps/flows-stages/flow/examples/flows",
+                                        "add-secure-apps/flows-stages/flow/examples/default_flows",
                                         "add-secure-apps/flows-stages/flow/examples/snippets",
                                     ],
                                 },