website/docs: add more content about flows (#10527)

* first pass

* reordered config options to match UI, added more

* tweaks

* add content for creating flows, add links to policies, update Style Guide

* tweaks

* procedurals, info about bindings

* stages stub file

* messy

* reorg procedurals

* tweak titles

* tweaks

* images

* images, remove old images

* tweak

* tweaks and fixes

* smaller image

* tweak

* had to rollback

* starting over after VS Code branch war

* fix links

* more tweaks

* Optimised images with calibre/image-actions

* fighting build break

* remove dupe image

* replace image with diagram code

* add image of UI, and reformat to look more like field names, not headings in the document

* Optimised images with calibre/image-actions

* new image

* rest of Jens' edits

* Optimised images with calibre/image-actions

* fix order of stages in example

* fixed arrows in image

---------

Signed-off-by: Tana M Berry <tanamarieberry@yahoo.com>
Co-authored-by: Tana M Berry <tana@goauthentik.com>
Co-authored-by: authentik-automation[bot] <135050075+authentik-automation[bot]@users.noreply.github.com>
Co-authored-by: Jens Langhammer <jens@goauthentik.io>

website/developer-docs/docs/style-guide.mdx

@@ -2,19 +2,19 @@
 title: Style Guide
 ---
 
-Here are a few guidelines to ensure that the documentation is easy to read and uses similar phrasing. Remember to use our [docs templates](./templates/index.md) when possible; they are already set up to follow may of the style guidelines below.
+The Style Guide provides guidelines to ensure that the authentik documentation is easy to read and uses similar phrasing, formatting, and tone.
+
+We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic. To make the review and merging of your contributions faster and easier, please follow the [writing documentation](./writing-documentation.md) guidelines.
 
 If you find any documentation that doesn't match these guidelines, feel free to either open an [Issue](https://github.com/goauthentik/authentik/issues) or a [PR](https://github.com/goauthentik/authentik/pulls) so they can be fixed.
 
-To test how the documentation renders use the Netlify Deploy Preview, especially when using Docusaurus-specific features. Or [build it locally and test](./writing-documentation.md#set-up-your-local-build), using the `make website-watch` command.
+## General style guidelines
 
-:::info
+-   Try to order the documentation sections in the order that makes it easiest for the user to follow. That is, order the sections in the same order as the actual workflow used to accomplish the task.
-Make sure to add any new pages to the appropriate `sidebar` file. Otherwise, the new page will not appear in the table of contents to the left.
-:::
 
-## General guidelines
+-   Use headings (sub-titles) to break up long documents, and make it easier to find a specific section.
 
--   Try to order the documentation sections in the order that makes it easiest for the user to follow. That is, order the sections in the same order as the actual workflow used to accomplish the task. Use headings (sub-titles) to break up long documents, and make it easier to find a specific section.
+-   Add cross-reference links to related content whenever possible.
 
 -   You can use standard [Docusaurus-specific features](https://docusaurus.io/docs/next/markdown-features), which include MDX elements such as tabs and admonitions.
 
@@ -40,7 +40,7 @@ Make sure to add any new pages to the appropriate `sidebar` file. Otherwise, the
 
 -   Our documentation uses American English ("z" not "s").
 
--   Phrasing should almost always be in present tense and active voice:
+-   Use the present tense and active voice in almost all cases:
 
     -   DON'T: "The Applications page will be loaded."
 
@@ -56,12 +56,17 @@ Make sure to add any new pages to the appropriate `sidebar` file. Otherwise, the
 
 Formatting in documentation is important; it improves comprehension and readability, and allows the brain to more quickly determine what is a command or a configuration setting, what is a field name, or what is a variable.
 
+### Fonts and font styling
+
 -   When referring to UI elements or components in the authentik UI, such as field names, labels, etc., use **bold** text.
 
+-   When referring to internal components in authentik, like the policy engine, or blueprints, do not use any special formatting. Link to the relevant documentation when possible.
+
 -   Use `code` format when referring to:
 
     -   commands
     -   file paths
+    -   file names
     -   directory names
     -   code snippets (single line or a block of code)
 
@@ -77,5 +82,68 @@ Formatting in documentation is important; it improves comprehension and readabil
 
 -   Both titles and headers (H1, H2, H3) use sentence style capitalization, meaning that only the first word is capitalized. However, if the title or header includes a proper noun (name of a product, etc) then capitalize those words.
     Examples:
+
     -   Configure your provider
     -   Configure the Google Workspace provider
+
+-   Make sure the title/header is descriptive, and tells the reader what that section is about. Try to avoid titles or headers like "Overview". Instead say "About authentik policies".
+
+-   Use the imperative verb form (not the gerund form) for procedural topics. For example, use "Configure your instance" instead of "Configuring your instance".
+
+### Examples
+
+When you want to show an example (say, a code snippet), use a new line, bold text, and a semi-colon, like this:
+
+    **Example**:
+    This expression policy uses an expression based on the user's name.
+    ```
+    if request.context["pending_user"].username == "marie":
+      return True
+    return False
+    ```
+
+### Notes and warnings
+
+Use the following convention for a note:
+
+```
+:::info
+Write your note here.
+:::
+```
+
+:::info
+Write your note here.
+:::
+
+For a warning, use this:
+
+```
+:::warning
+Write your note here.
+:::
+```
+
+:::warning
+Write your warning here.
+:::
+
+```
+
+```
+
+## Word choices
+
+-   **May** versus **might** versus **can**
+    Typically, the word "may" is not used in technical writing, because it implies permission (rather than ability) to do something. Instead use the word "can". Use "might" when the scenario could be different in certain environments. Be sparing with your use of "might"; this word implies unpredictability, not our favorite thing with software.
+
+    -   DON'T: "You may use an Expression policy to enforce MFA adherence."
+
+    -   DO: "You can use an Expression policy to enforce MFA adherence."
+
+    -   Do: "Values might differ depending on the source of the property mappings.""
+
+-   **Login**, **log in**, and **log in to**
+    As a descriptive term, use one word: "login". (The login panel.)
+    As a verb, use "log in", with two words. (This stage prompts the user to log in.)
+    As a verb with the proposition "to", use "log in to". (Log in to the application.)

website/developer-docs/docs/templates/combo.md

@@ -9,7 +9,7 @@ title: "Combination topic"
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/combo.tmpl.md
 ```
 
-Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [General Guidelines](../writing-documentation#writing-guidelines) for writing tips and authentik-specific rules.
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
 :::
 
 For a combo topic, the title is typically the name of the feature ("Branding" or "Remote Access Control").

website/developer-docs/docs/templates/conceptual.md

@@ -9,7 +9,7 @@ title: "Conceptual topic"
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/conceptual.tmpl.md
 ```
 
-Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [General Guidelines](../writing-documentation#writing-guidelines) for writing tips and authentik-specific rules.
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
 :::
 
 Use a title that focuses on the feature, component, or technology you are writing about... for example, "About authentik polices" or "Understanding outposts". For conceptual docs, the verb in the title should indicate a concept, such as "About" or "Overview" or "Understanding", followed by the noun (the component or object you are writing about).

website/developer-docs/docs/templates/procedural.md

@@ -9,7 +9,7 @@ title: "Procedural topic"
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/procedural.tmpl.md
 ```
 
-Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [General Guidelines](../writing-documentation#writing-guidelines) for writing tips and authentik-specific rules.
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
 :::
 
 For a procedural topic, use a title that focuses on the task you are writing about. For example, "Add a new Group" or "Edit user profiles". For procedural docs, there should be a verb in the title, and usually the noun (the component or object you are working on). For the title (and all headings) use the infinitive form of the verb (i.e. "add") not the gerund form (i.e. "adding").

website/developer-docs/docs/templates/reference.md

@@ -9,7 +9,7 @@ title: "Reference topic"
 wget https://raw.githubusercontent.com/goauthentik/authentik/main/website/developer-docs/docs/templates/reference.tmpl.md
 ```
 
-Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [General Guidelines](../writing-documentation#writing-guidelines) for writing tips and authentik-specific rules.
+Edit your markdown file as you work, reading this page for the descriptions of each section. You can build out a "stub file" with just headers, then gradually add content to each section. Use screenshots sparingly, only for complex UIs where it is difficult to describe a UI element with words. Refer to our [Style Guide](../style-guide.mdx) for writing tips and authentik-specific rules.
 :::
 
 Create a title that specifies the component you are documenting. For example, "Group attributes".

website/developer-docs/docs/writing-documentation.md

@@ -2,7 +2,21 @@
 title: Writing documentation
 ---
 
-Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project.
+Writing documentation for authentik is a great way for both new and experienced users to improve and contribute to the project. We appreciate contributions to our documentation; everything from fixing a typo to adding additional content to writing a completely new topic.
+
+Adhering to the following guidelines will help us get your PRs merged much easier and faster, with fewer edits needed.
+
+-   Ideally, when you are making contributions to the documentation, you should fork and clone our repo, then [build it locally](#set-up-your-local-build), so that you can test the docs and run the required linting and spell checkers before pushing your PR. While you can do much of the writing and editing within the GitHub UI, you cannot run the required linters from the GitHub UI.
+
+-   Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
+
+-   Remember to use our [docs templates](./templates/index.md) when possible; they are already set up to follow our style guidelines, they make it a lot easier for you (no blank page frights!), and keeps the documentation structure and headings consistent.
+
+-   To test how the documentation renders you can build locally and then use the Netlify Deploy Preview, especially when using Docusaurus-specific features. You can also run the `make website-watch` command on your local build, to see the rendered pages as you make changes.
+
+-   Be sure to run the `make website` command on your local branch, before pushing the PR to the authentik repo. This command does important linting, and the build check in our repo will fail if the linting has not been done.
+
+-   For new entries, make sure to add any new pages to the appropriate `sidebar.js` file. Otherwise, the new page will not appear in the table of contents to the left.
 
 ## Set up your local build
 
@@ -12,7 +26,7 @@ Requirements:
 
 The docs and the code are in the same Github repo, at https://github.com/goauthentik/authentik, so if you have cloned the repo, you already have the docs.
 
-You can do local builds of the documentation to test your changes or review your new content, and to run the required `prettier` and linters before pushing your PR.
+You can do local builds of the documentation to test your changes or review your new content, and to run the required `make website` command (which runs `prettier` and other linters) before pushing your PR.
 
 The documentation site is situated in the `/website` folder of the repo.
 
@@ -28,22 +42,12 @@ The site is built using npm, below are some useful make commands:
 
 -   **Live editing**: `make website-watch`
 
-    For real time viewing of changes, as you make them.
+    For real-time viewing of changes, as you make them.
 
 :::info
 Be sure to run a formatting command before committing changes.
 :::
 
-## Writing guidelines
-
-Please refer to our [Style Guide](./style-guide.mdx) for authentik documentation. Here you will learn important guidelines about not capitalizing authentik, how we format our titles and headers, and much more.
-
-Whenever possible, use one of our [doc templates](./templates/index.md). This makes it a lot easier for you (no blank page frights!) and keeps the documentation consistent.
-
-Make sure to add the new pages to the appropriate place in `/website/sidebars.js`. Otherwise, the content will not appear in the table of contents to the left.
-
-Following the guidelines will make getting your PRs merged much easier and faster, with fewer edits needed. We appreciate our community contributors helping us keep the Docs consistent, easy-to-use, and high quality.
-
 ## Documentation for Integrations
 
 In addition to following the [Style Guide](./style-guide.mdx) please review the following guidelines.

website/docs/flow/index.md

@@ -1,80 +1,103 @@
 ---
-title: Overview
+title: Flows
 ---
 
-Flows are a method of describing a sequence of stages. A stage represents a single verification or logic step. They are used to authenticate users, enroll them, and more.
+Flows are a major component in authentik. In conjunction with stages and [policies](../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.
+
+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:
 
--   Identification, user identifies themselves via a username or email address
+-   **Identification stage**: user identifies themselves via a username or email address
--   Password, the user's password is checked against the hash in the database
+-   **Password stage**: the user's password is checked against the hash in the database
--   Log the user in
+-   **Login stage**: this stage attaches a currently pending user to the current session
 
-Upon flow execution, a plan containing all stages is generated. This means that all attached policies are evaluated upon execution. This behaviour can be altered by enabling the **Evaluate when stage is run** option on the binding.
+When these stages are successfully completed, authentik logs in the user.
+
+![](./simple_stages.png)
+
+By default, policies are evaluated dynamically, right before the stage (to which a policy is bound) is presented to the user. This flexibility allows the login process to continue, change, or stop, based on the success or failure of each policy.
+
+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](../flow/context/index.md).
 
 To determine which flow should be used, authentik will first check which default authentication flow is configured in the active [**Brand**](../core/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 assigned to them. These policies determine if the current user is allowed to see and use this flow.
+Flows can have [policies](../flow/stages/index.md) assigned to them. These policies determine if the current user is allowed to see and use this flow.
 
 Keep in mind that in certain circumstances, policies cannot match against users and groups as there is no authenticated user yet.
 
-### Denied action
-
-Configure what happens when access to a flow is denied by a policy. By default, authentik will redirect to a `?next` parameter if set, and otherwise show an error message.
-
--   `MESSAGE_CONTINUE`: Show a message if no `?next` parameter is set, otherwise redirect.
--   `MESSAGE`: Always show error message.
--   `CONTINUE`: Always redirect, either to `?next` if set, otherwise to the default interface.
-
-## Designation
-
-Flows are designated for a single purpose. This designation changes when a flow is used. The following designations are available:
-
-#### Authentication
-
-This is 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.
-
-#### Invalidation
-
-This designates a flow to be used to invalidate a session.
-
-This flow should always contain a [**User Logout**](stages/user_logout.md) stage, which resets the current session.
-
-#### Enrollment
-
-This designates a flow for enrollment. This flow can contain any amount of verification stages, such as [**email**](stages/email/) or [**captcha**](stages/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.
-
-#### Unenrollment
-
-This designates a flow for unenrollment. This flow can contain any amount of verification stages, such as [**email**](stages/email/) or [**captcha**](stages/captcha/). As a final stage, to delete the account, use the [**user_delete**](stages/user_delete.md) stage.
-
-#### Recovery
-
-This designates a flow for recovery. This flow normally contains an [**identification**](stages/identification/) stage to find the user. It can also contain any amount of verification stages, such as [**email**](stages/email/) or [**captcha**](stages/captcha/).
-Afterwards, use the [**prompt**](stages/prompt/) stage to ask the user for a new password and the [**user_write**](stages/user_write.md) stage to update the password.
-
-#### Stage configuration
-
-This 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 Factors, like change a password and setup TOTP.
-
 ## Import & Export
 
-Flows can be imported and exported to share with other people, the community and for troubleshooting. Flows can be imported to apply new functionality and apply existing workflows.
+Flows can be imported and exported to share with other people, the community, and for troubleshooting. Flows can be imported to apply new functionality and apply existing workflows.
 
 Download our [Example flows](./examples/flows.md) and then import them into your authentik instance.
 
 Starting with authentik 2022.8, flows will be exported as YAML, but JSON-based flows can still be imported.
 
-## Behavior settings
+## Create a custom flow
 
-### Compatibility mode
+To create a flow, follow these steps:
 
-The compatibility mode increases compatibility with password managers. Password managers like [1Password](https://1password.com/) for example don't need this setting to be enabled, when accessing the flow from a desktop browser. However accessing the flow from a mobile device might necessitate this setting to be enabled.
+1. Log in as an admin to authentik, and go to the Admin interface.
+2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
+3. Click **Create**, define the flow using the [configuration settings](#flow-configuration-options) described below, and then click **Finish**.
 
-The technical reasons for this settings' existence is due to the JavaScript libraries we're using for the default flow interface. These interfaces are implemented using [Lit](https://lit.dev/), which is a modern web development library. It uses a web standard called ["Shadow DOMs"](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), which makes encapsulating styles simpler. Due to differences in Browser APIs, many password managers are not compatible with this technology.
+After creating the flow, you can then [bind specific stages](../flow/stages/index.md#bind-a-stage-to-a-flow) to the flow and [bind policies](../policies/working_with_policies/working_with_policies.md) to the flow to further customize the user's log in and authentication process.
 
-When the compatibility mode is enabled, authentik uses a polyfill which emulates the Shadow DOM APIs without actually using the feature, and instead a traditional DOM is rendered. This increases support for password managers, especially on mobile devices.
+To determine which flow should be used, authentik will first check which default authentication flow is configured in the active [**Brand**](../core/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
+
+When creating or editing a flow in the UI of the Admin interface, you can set the following configuration options.
+
+![](./create-flow.png)
+
+**Name**: Enter a descriptive name. This is the name that will appear on the list of flows in the Admin interface.
+
+**Title**: This is the title that will appear on the flow as the end-user logs in and encounters the flow.
+
+**Slug**: The slug will be used, and appear, in the URL when the flow is in use.
+
+**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. The authorization flow `default-provider-authorization-explicit-consent` should always contain a consent stage.
+
+-   **Invalidation**: designates a flow to be used to invalidate a session. This flow should always contain a [**User Logout**](stages/user_logout.md) stage, which resets the current session.
+
+-   **Enrollment**: designates a flow for enrollment. This flow can contain any amount of verification stages, such as [**email**](stages/email/) or [**captcha**](stages/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.
+
+-   **Unenrollment**: designates a flow for unenrollment. This flow can contain any amount of verification stages, such as [**email**](stages/email/) or [**captcha**](stages/captcha/). 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/) stage to find the user. It can also contain any amount of verification stages, such as [**email**](stages/email/) or [**captcha**](stages/captcha/). Afterwards, use the [**prompt**](stages/prompt/) 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 Factors, like change a password and setup TOTP.
+
+**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.
+
+**Behavior settings**:
+
+-   **Compatibility mode**: Toggle this option on to increase compatibility with password managers and mobile devices. Password managers like [1Password](https://1password.com/), for example, don't need this setting to be enabled, when accessing the flow from a desktop browser. However accessing the flow from a mobile device might necessitate this setting to be enabled.
+
+    The technical reasons for this settings' existence is due to the JavaScript libraries we're using for the default flow interface. These interfaces are implemented using [Lit](https://lit.dev/), which is a modern web development library. It uses a web standard called ["Shadow DOMs"](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), which makes encapsulating styles simpler. Due to differences in Browser APIs, many password managers are not compatible with this technology.
+
+    When the compatibility mode is enabled, authentik uses a polyfill which emulates the Shadow DOM APIs without actually using the feature, and instead a traditional DOM is rendered. This increases support for password managers, especially on mobile devices.
+
+-   **Denied action**: Configure what happens when access to a flow is denied by a policy. By default, authentik will redirect to a `?next` parameter if set, and otherwise show an error message.
+
+    -   `MESSAGE_CONTINUE`: Show a message if no `?next` parameter is set, otherwise redirect.
+    -   `MESSAGE`: Always show error message.
+    -   `CONTINUE`: Always redirect, either to `?next` if set, otherwise to the default interface.
+
+-   **Policy engine mode**: Configure the flow to succeed in _any_ policy passes, or only if _all_ policies pass.
+
+**Appearance Settings**:
+
+-   **Layout**: select how the UI displays the flow when it is executed; with stacked elements, content left or right, and sidebar left or right.
+
+-   **Background**: optionally, select a background image for the UI presentation of the flow.

website/docs/flow/stages/index.md

@@ -0,0 +1,56 @@
+---
+title: Stages
+---
+
+Stages are one of the fundamental building blocks in authentik, along with [flows](../index.md) and [policies](docs/policies/index.md).
+
+A stage represents a single verification or logic step within a flow. You can bind one or more stages to a flow to create a customized, flexible login and authentication process.
+
+In the following diagram of the `default-authentication-flow`, you see multiple stages, or steps, in the authentication process for a user. Policies are bound to some stages; this provides for dynamic application of a specific stage _if_ the policy criteria is met.
+
+```mermaid
+graph TD
+flow_pre[["Pre-flow policies"]]
+flow_pre --Binding 10--> flow_policy_0{{"Policy (Event Matcher Policy)
+default-match-update"}}
+flow_policy_0 --Policy denied--> done[["End of the flow"]]
+flow_policy_0 --> flow_start[["Flow
+Welcome to authentik!"]]
+stage_0_policy_0 --Policy passed--> stage_0(["Stage (Identification Stage)
+default-authentication-identification"])
+stage_1_policy_0 --Policy passed--> stage_1(["Stage (Password Stage)
+default-authentication-password"])
+--> stage_2(["Stage (Authenticator Validation Stage)
+default-authentication-mfa-validation"])
+--> stage_3(["Stage (User Login Stage)
+default-authentication-login"])
+flow_start --> stage_0_policy_0{{"Policy (Event Matcher Policy)
+default-match-configuration-error"}}
+stage_0 --> stage_1_policy_0{{"Policy (Expression Policy)
+default-authentication-flow-password-stage"}}
+stage_0_policy_0 --Policy denied--> stage_1(["Stage (Password Stage)
+default-authentication-password"])
+stage_1_policy_0 --Policy denied--> stage_2(["Stage (Authenticator Validation Stage)
+default-authentication-mfa-validation"])
+stage_3 --> done[["End of the flow"]]
+```
+
+## Create a Stage
+
+To create a stage, follow these steps:
+
+1. Log in as an admin to authentik, and go to the Admin interface.
+2. In the Admin interface, navigate to **Flows and Stages -> Stages**.
+3. Click **Create**, define the flow using the configuration settings, and then click **Finish**.
+
+After creating the stage, you can then [bind the stage to a flow](#bind-a-stage-to-a-flow) or [bind a policy to the stage](../../policies/working_with_policies/working_with_policies.md) (the policy determines whether or not the stage will be implemented in the flow).
+
+## Bind a stage to a flow
+
+To bind a stage to a flow, follow these steps:
+
+1. Log in as an admin to authentik, and go to the Admin interface.
+2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
+3. In the list of flows, click the name of the flow to which you want to bind one or more stages.
+4. On the Flow page, click the **Stage Bindings** tab at the top.
+5. Here, you can decide if you want to create a new stage and bind it to the flow (**Create and bind Stage**), or if you want to select an existing stage and bind it to the flow (**Bind existing stage**).

website/docs/policies/expression.mdx

@@ -2,19 +2,32 @@
 title: Expression Policies
 ---
 
-The passing of the policy is determined by the return value of the code. Use
+Expression policies are perhaps the most flexible way to define specific implementations of flows and stages. With Expression polices, you can provide Python code to enforce custom checks and validation.
+
+The passing of the policy is determined by the return value of the code.
+
+To pass a policy, use:
 
 ```python
 return True
 ```
 
-to pass a policy and
+To fail a policy use:
 
 ```python
 return False
 ```
 
-to fail it.
+**Example**:
+Here's a simple policy that you could bind to a MFA validation stage if you want to specify that only certain users should be prompted for MFA validation:
+
+```
+if request.context["pending_user"].username == "marie":
+   return True
+return False
+```
+
+If the return is `True` that means Yes, use this stage (i.e. the user will get the MFA prompt). A return of `False` means remove this stage from the plan.
 
 ## Available Functions
 

website/docs/policies/index.md

@@ -2,30 +2,35 @@
 title: Policies
 ---
 
-## Event-matcher policy
+Policies provide customization and flexibility when defining your users' login and authentication experience.
+
+In effect, policies determine whether or not a specific stage is applied to a flow, or whether certain users can even access the flow.
+
+For example, you can create a policy that, for certain users, skips over a stage that prompts for MFA input. Or, you can define a policy that allows users to access a login flow only if the policy criteria are met. See below for other policies, including the reputation policy and an events-driven policy to manage notifications.
+
+For instructions about creating and binding policies to flows and stages, refer to ["Working with policies](docs/policies/working_with_policies/working_with_policies.md)".
+
+## Standard policies
+
+The following policies are our standard, out-of-the box policies.
+
+### Event-matcher policy
 
 This policy is used by the events subsystem. You can use this policy to match events by multiple different criteria, to choose when you get notified.
 
-## Expression policy
+### Expression Policy
 
-See [Expression policy](expression.mdx).
+See [Expression Policy](expression.mdx).
 
-## GeoIP policy
+### GeoIP policy
 
 Use this policy for simple GeoIP lookups, such as country or ASN matching. (For a more advanced GeoIP lookup, use an [Expression policy](expression.mdx).)
 
-## Have I Been Pwned policy
+### Password-Expiry Policy
-
-:::info
-This policy is deprecated since authentik 2022.11.0, as this can be done with the password policy now.
-:::
-This policy checks the hashed password against the [Have I Been Pwned](https://haveibeenpwned.com/) API. This only sends the first 5 characters of the hashed password. The remaining comparison is done within authentik.
-
-## Password-Expiry policy
 
 This policy can enforce regular password rotation by expiring set passwords after a finite amount of time. This forces users to set a new password.
 
-## Password policy
+### Password Policy
 
 This policy allows you to specify password rules, such as length and required characters.
 The following rules can be set:
@@ -41,10 +46,18 @@ Starting with authentik 2022.11.0, the following checks can also be done with th
 -   Check the password hash against the database of [Have I Been Pwned](https://haveibeenpwned.com/). Only the first 5 characters of the hashed password are transmitted, the rest is compared in authentik
 -   Check the password against the password complexity checker [zxcvbn](https://github.com/dropbox/zxcvbn), which detects weak password on various metrics.
 
-## Reputation policy
+### Reputation Policy
 
 authentik keeps track of failed login attempts by source IP and attempted username. These values are saved as scores. Each failed login decreases the score for the client IP as well as the targeted username by 1 (one).
 
-This policy can be used, for example, to prompt clients with a low score to pass a captcha before they can continue.
+This policy can be used, for example, to prompt clients with a low score to pass a CAPTCHA test before they can continue.
 
 To make sure this policy is executed correctly, set _Evaluate when stage is run_ when using it with a flow.
+
+### Have I Been Pwned Policy
+
+:::info
+This policy is deprecated since authentik 2022.11.0, as this can be done with the password policy now.
+:::
+
+This policy checks the hashed password against the [Have I Been Pwned](https://haveibeenpwned.com/) API. This only sends the first 5 characters of the hashed password. The remaining comparison is done within authentik.

website/docs/policies/working_with_policies/working_with_policies.md

@@ -0,0 +1,48 @@
+---
+title: Working with policies
+---
+
+For an overview of policies, refer to our documentation on [Policies](../index.md).
+
+authentik provides several [standard policy types](../index.md#standard-policies), which can be configured for your specific needs.
+
+We also document how to use a policy to [whitelist email domains](../working_with_policies/whitelist_email.md) and to [ensure unique email addresses](../working_with_policies/unique_email.md).
+
+## Create a policy
+
+To create a new policy, follow these steps:
+
+1. Log in as an admin to authentik, and go to the Admin interface.
+2. In the Admin interface, navigate to **Customization -> Policies**.
+3. Click **Create**, and select the type of policy.
+4. Define the policy and click **Finish**.
+
+## Bind a policy to a flow or stage
+
+After creating the policy, you can bind it to either a [flow](../../flow/index.md) or to a [stage](../../flow/stages/index.md).
+
+:::info
+Bindings are instantiated objects themselves, and conceptually can be considered as the "connector" between the policy and the stage or flow. This is why you might read about "binding a binding", because technically, a binding is "spliced" into another binding, in order to intercept and enforce the criteria defined in the policy. You can edit bindings on a flow's **Stage Bindings** tab.
+:::
+
+### Bind a policy to a flow
+
+These bindings control which users can access a flow.
+
+1. Log in as an admin to authentik, and open the Admin interface.
+2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
+3. In the list of flows, click on the name of the flow to which you want to bind a policy.
+4. Click on the **Policy/Group/User Bindings** tab at the top of the page.
+5. Here, you can decide if you want to create a new policy and bind it to the flow (**Create and bind Policy**), or if you want to select an existing policy and bind it to the flow (**Bind existing policy/group/user**).
+
+### Bind a policy to a stage
+
+These bindings control which stages are applied to a flow.
+
+1. Log in as an admin to authentik, and open the Admin interface.
+2. In the Admin interface, navigate to **Flows and Stages -> Flows**.
+3. In the list of flows, click on the name of the flow to which you want to bind a policy.
+4. Click on the **Stage Bindings** tab at the top of the page.
+5. Click the arrow (**>**) beside the name of the stage to which you want to bind a policy.
+   The details for that stage displays.
+6. Here, you can decide if you want to create a new policy and bind it to the stage (**Create and bind Policy**), or if you want to select an existing policy and bind it to the stage (**Bind existing policy/group/user**).

website/sidebars.js

@@ -264,10 +264,8 @@ const docsSidebar = {
             type: "category",
             label: "Stages",
             link: {
-                type: "generated-index",
+                type: "doc",
-                title: "Stages",
+                id: "flow/stages/index",
-                slug: "flow/stages",
-                description: "Overview of all available stages",
             },
             items: [
                 "flow/stages/authenticator_duo/index",
@@ -302,10 +300,8 @@ const docsSidebar = {
                     type: "category",
                     label: "Working with policies",
                     link: {
-                        type: "generated-index",
+                        type: "doc",
-                        title: "Working with policies",
+                        id: "policies/working_with_policies/working_with_policies",
-                        slug: "policies/working_with_policies",
-                        description: "Overview of policies configuration",
                     },
                     items: [
                         "policies/working_with_policies/whitelist_email",