website/docs: Document flow planner (#22660)

2026-06-17 19:09:11 +03:00 · 2026-06-04 13:14:10 -04:00
parent 5ad73a0f6a
commit 0b1dc626c9
12 changed files with 61 additions and 21 deletions
@@ -11,6 +11,8 @@ However, any flow can be executed via an API from anywhere, in fact that is what
 Because the flow executor stores its state in the HTTP Session, so you need to ensure that cookies between flow executor requests are persisted.
 :::

+When a flow execution starts, authentik creates a [flow plan](/docs/add-secure-apps/flows-stages/flow/planner/) for the current session. The flow executor advances through that plan as each stage completes.
+
 :::info
 Note that the HTTP session must be obtained as a cookie before `GET /api/v3/flows/executor/:slug` can be called. If you are using a JWT for authentication, you first have to obtain a session cookie via `GET /api/v3/flows/instances/:slug/execute/` before requesting `GET /api/v3/flows/executor/:slug`.
 :::
@@ -132,23 +132,18 @@ If a target has no applicable bindings, authentik treats the result as passing b

 A flow-stage binding attaches a stage to a flow and defines the order in which that stage runs.

-Flow-stage bindings are also called stage bindings. authentik uses them while building the flow plan that determines which stages a user will see and in what order.
+Flow-stage bindings are also called stage bindings. authentik uses them while building the [flow plan](../flows-stages/flow/planner.md) that determines which stages a user will see and in what order.

 This matters because stages are reusable objects. The same stage can appear in multiple flows, but each flow-stage binding can have its own policies, users, groups, order, and evaluation settings. When you bind a policy to a stage in a specific flow, you are binding it to that flow-stage binding, not to the reusable stage definition itself.

 ### When authentik evaluates stage-binding policies

-Flow-stage bindings have two evaluation settings:
+Flow-stage bindings have two policy evaluation options:

- **Evaluate when flow is planned**: authentik evaluates the binding while it is building the flow plan. If the binding does not pass at planning time, the stage is not added to the plan.
- **Evaluate when the stage is run**: authentik adds the stage to the flow plan, then evaluates the binding again immediately before the stage is shown. If the binding no longer passes, authentik removes that stage from the flow plan.
+- **Evaluate when flow is planned**: authentik evaluates policies while building the flow plan.
+- **Evaluate when stage is run**: authentik evaluates policies immediately before presenting the stage.

-The second option is useful when the decision depends on context that is only available later in the flow. For example, after an identification stage completes, a subsequent stage binding can assess the identified user and then trigger a CAPTCHA or Deny stage as needed.
-
-In other words:
-
- use **Evaluate when flow is planned** when the decision can already be made before the user reaches the stage
- use **Evaluate when the stage is run** when the decision depends on flow context that is created by an earlier stage
+At least one of these options must be enabled, and both can be enabled at the same time. For the full behavior and guidance on choosing the right setting, see [Flow Planner](../flows-stages/flow/planner.md#planning-and-stage-policies).

 ## What to remember

@@ -18,9 +18,9 @@ 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.
+By default, policies bound to stage bindings are evaluated dynamically, right before the stage 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 behavior 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.mdx).
+You can change this behavior by enabling the **Evaluate when flow is planned** option on the stage binding. When this option is enabled, authentik uses the [Flow Planner](./planner.md) to evaluate the stage binding's policies when the flow starts, and includes the stage in the flow plan only if those policies pass.

 ## Policies and permissions

@@ -2,7 +2,7 @@
 title: Flow Inspector
 ---

-The Flow Inspector allows administrators to visually determine how custom flows work, inspect the current [flow context](./context/index.mdx) by stepping through the flow process and observing the Inspector with each step, and investigate issues.
+The Flow Inspector allows administrators to visually determine how custom flows work, inspect the current [flow context](./context/index.mdx) by stepping through the flow process and observing the Inspector with each step, and investigate issues. It shows details from the active [flow plan](./planner.md).

 As shown in the screenshot below, the Flow Inspector displays to the right, beside the selected flow (in this case, "Change Password"), with [information](#flow-inspector-details) about that specific flow and flow context.

@@ -45,13 +45,13 @@ The following information is shown in the Inspector:

 #### Next stage

-This is the currently planned next stage. If you have stage bindings configured to `Evaluate when flow is planned`, then you see the result here. If, however, you have them configured to re-evaluate (`Evaluate when stage is run`), then this does not show up, because the results vary based on your input.
+This is the currently planned next stage. Stages that are evaluated when they run can still be skipped before they are shown. For more information, see [Planning and stage policies](./planner.md#planning-and-stage-policies).

 The name and kind of the stage, as well as the unique ID, are shown.

 #### Plan history

-Here you can see an overview of which stages have run, which is currently active, and which is planned to come next. Same caveats as above apply.
+Here you can see an overview of which stages have run, which is currently active, and which is planned to come next.

 #### Current plan context

@@ -0,0 +1,42 @@
+---
+title: Flow Planner
+---
+
+The Flow Planner is the component of authentik that takes a configured [flow](./index.md) and, for each incoming request for that flow, determines the specific stages to run and the order in which they will run.
+
+A flow describes a sequence of stages and policies. A flow plan is the per-session execution plan derived from that flow after authentik evaluates the request, the user, and the policies bound to the flow and its stage bindings.
+
+## How the planner works
+
+When a flow is executed, authentik creates a flow plan and does the following:
+
+1. Verifies that the flow can be used in the current authentication context.
+2. Evaluates policies bound directly to the flow.
+3. Loads the flow's stage bindings in order.
+4. Evaluates stage binding policies when **Evaluate when flow is planned** is enabled.
+5. Stores the resulting ordered stage list and [flow context](./context/index.mdx) in the user's session.
+
+The [flow executor](./executors/if-flow.md) then presents the first stage of the flow plan. When the stage completes successfully, authentik removes it from the flow plan and continues with the next stage. When no stages remain, the flow plan has completed.
+
+## Planning and stage policies
+
+Stage binding policies can be evaluated at two different times:
+
+- **Evaluate when flow is planned**: The policy is evaluated when the flow plan is created. If the policy does not pass, that stage is not included in the plan.
+- **Evaluate when stage is run** (_default_): The policy is evaluated immediately before the stage is presented. If the policy does not pass at that point, authentik skips that stage and continues with the next planned stage.
+
+Both options can be enabled for the same stage binding. Use planning-time evaluation when a policy can be evaluated before any stages run. Use run-time evaluation when a policy depends on data that might be added to the flow context by earlier stages.
+
+For example, a password stage usually depends on the user identified by an earlier identification stage. If a policy for a later stage depends on `pending_user`, evaluate that policy when the stage is run, or ensure `pending_user` is already present when the plan is created.
+
+## Inspecting a plan
+
+Use the [Flow Inspector](./inspector.md) to execute a flow and, while it executes, view the current stage, the next planned stage, the plan history, and the current plan context.
+
+The Flow Inspector is accessed via the Flow Overview page and is particularly useful for troubleshooting flows and determining why stage binding policies fail to pass. It's also useful to evaluate values for use in policies.
+
+## Caching and session state
+
+authentik can cache flow plans so repeated executions of the same flow for the same user do not need to rebuild the same stage list every time. The active plan for a running flow is stored in the HTTP session, so browser-based and API-based flow executors must keep using the same session while the flow is running.
+
+If flow behavior changes after editing stage bindings or policies, start a new flow execution before troubleshooting. Existing sessions may already have a plan in progress.
@@ -19,7 +19,7 @@ Bind this stage where a flow should stop after a policy or earlier stage determi
 ## Notes

 :::caution
-To use this stage effectively, make sure **Evaluate when flow is planned** is disabled on the stage binding.
+To use this stage effectively, make sure **Evaluate when flow is planned** is disabled on the stage binding. See [Planning and stage policies](../../flow/planner.md#planning-and-stage-policies).
 :::

 If the binding is evaluated during flow planning, the denial can happen earlier than intended and skip the checks that were meant to decide whether the user should be denied.
@@ -54,7 +54,7 @@ You can use a binding to determine which exact [stages](../stages/index.md) (all
 For an overview about all the different types of bindings in authentik and how they are used, refer to [About authentik bindings](../../bindings-overview/index.md).

 :::info
-Be aware that some stages and flows do not allow user or group bindings, because in certain scenarios (authentication or enrollment), the flow plan doesn't yet know who the user or group is.
+Be aware that some stages and flows do not allow user or group bindings, because in certain scenarios (authentication or enrollment), the [flow plan](../flow/planner.md) doesn't yet know who the user or group is.
 :::

 ### Bind a stage to a flow
@@ -53,7 +53,7 @@ To configure this setup:
 3. Configure the expression so that it returns `True` only when the Password stage should run. Use one of the expressions below, depending on the authenticator type.
 4. Navigate to **Flows and Stages** > **Flows** and open your authentication flow.
 5. Open the **Stage Bindings** tab, expand the Password stage binding, and bind the Expression Policy there. Do not bind it to the flow itself or directly to the stage object. For more background, see [Bind a policy to a stage binding](../../../../customize/policies/working_with_policies.md#bind-a-policy-to-a-stage-binding).
-6. On the Password stage binding, enable **Evaluate when stage is run**. Disable **Evaluate when flow is planned** unless the user is already known before the flow starts.
+6. On the Password stage binding, enable **Evaluate when stage is run**. Disable **Evaluate when flow is planned** unless the user is already known before the flow starts. See [Planning and stage policies](../../flow/planner.md#planning-and-stage-policies).

 #### WebAuthn

@@ -6,7 +6,7 @@ tags:
    - flows
 ---

-[Flow context](../../../../add-secure-apps/flows-stages/flow/context/index.mdx) can be read and updated from an [Expression policy](./index.mdx) through `context["flow_plan"].context`.
+[Flow context](../../../../add-secure-apps/flows-stages/flow/context/index.mdx) can be read and updated from an [Expression policy](./index.mdx) through `context["flow_plan"].context`. For more information about the active plan, see [Flow Planner](../../../../add-secure-apps/flows-stages/flow/planner.md).

 This is useful when you want to influence later stages in the same flow, such as changing a redirect target or passing data to another stage.

@@ -39,7 +39,7 @@ The threshold defaults to a low score, so the policy is naturally suited to "tri

 ## Use it on stage bindings

-When you use a Reputation policy on a flow stage binding, configure the stage binding to **Evaluate when stage is run** so authentik can use the latest request context.
+When you use a Reputation policy on a flow stage binding, configure the stage binding to **Evaluate when stage is run** so authentik can use the latest request context. For more information, see [Planning and stage policies](../../../add-secure-apps/flows-stages/flow/planner.md#planning-and-stage-policies).

 This is especially important when the policy should react to the current login attempt rather than only to the initial planned flow state.

@@ -67,7 +67,7 @@ When you bind a policy to a stage binding, this task is done per flow, and does
 5. Click the arrow (**>**) beside the name of the stage to which you want to bind a policy. The details for that stage are displayed.
 6. Either create and bind a new policy, or bind an existing policy, group, or user.

-If the policy depends on request data that is only known after the user has interacted with the flow, configure the stage binding to **Evaluate when stage is run** instead of only at planning time.
+If the policy depends on request data that is only known after the user has interacted with the flow, configure the stage binding to **Evaluate when stage is run**. For more information, see [Planning and stage policies](../../add-secure-apps/flows-stages/flow/planner.md#planning-and-stage-policies).

 ### Bind a policy to an application

@@ -290,6 +290,7 @@ const items = [
                            id: "add-secure-apps/flows-stages/flow/index",
                        },
                        items: [
+                            "add-secure-apps/flows-stages/flow/planner",
                            "add-secure-apps/flows-stages/flow/inspector",
                            "add-secure-apps/flows-stages/flow/context/index",
                            {