diff --git a/website/docs/add-secure-apps/applications/manage_apps.md b/website/docs/add-secure-apps/applications/manage_apps.md index db6ad6c8a8..72cc5c9fa9 100644 --- a/website/docs/add-secure-apps/applications/manage_apps.md +++ b/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. 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 new file mode 100644 index 0000000000..e301339f2b --- /dev/null +++ b/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"; + + diff --git a/website/docs/add-secure-apps/flows-stages/flow/examples/flows.md b/website/docs/add-secure-apps/flows-stages/flow/examples/flows.md index 7143797e13..b81bcdd5eb 100644 --- a/website/docs/add-secure-apps/flows-stages/flow/examples/flows.md +++ b/website/docs/add-secure-apps/flows-stages/flow/examples/flows.md @@ -1,5 +1,5 @@ --- -title: Example Flows +title: Example flows --- :::info diff --git a/website/docs/add-secure-apps/flows-stages/flow/executors/if-flow.md b/website/docs/add-secure-apps/flows-stages/flow/executors/if-flow.md index 20419a1a67..101f945a21 100644 --- a/website/docs/add-secure-apps/flows-stages/flow/executors/if-flow.md +++ b/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) diff --git a/website/docs/add-secure-apps/flows-stages/flow/flow_list/_defaultflowlist.mdx b/website/docs/add-secure-apps/flows-stages/flow/flow_list/_defaultflowlist.mdx new file mode 100644 index 0000000000..5a49106c8f --- /dev/null +++ b/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. 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 18707cd67a..53617a786e 100644 --- a/website/docs/add-secure-apps/flows-stages/flow/index.md +++ b/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. +import Defaultflowlist from "../flow/flow_list/\_defaultflowlist.mdx"; -- **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. - -- **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. + **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. diff --git a/website/docs/add-secure-apps/flows-stages/flow/layouts.md b/website/docs/add-secure-apps/flows-stages/flow/layouts.md deleted file mode 100644 index 77b15a3b6c..0000000000 --- a/website/docs/add-secure-apps/flows-stages/flow/layouts.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: 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) diff --git a/website/docs/add-secure-apps/providers/index.mdx b/website/docs/add-secure-apps/providers/index.mdx index 99790ab300..b88c6aad57 100644 --- a/website/docs/add-secure-apps/providers/index.mdx +++ b/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: diff --git a/website/docs/customize/brands.md b/website/docs/customize/brands.md index dc4931f05a..fbaa057517 100644 --- a/website/docs/customize/brands.md +++ b/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 diff --git a/website/netlify.toml b/website/netlify.toml index 4747ceed7c..de729ecb93 100644 --- a/website/netlify.toml +++ b/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 diff --git a/website/sidebars.js b/website/sidebars.js index 0fd73b6e29..d7ae2be133 100644 --- a/website/sidebars.js +++ b/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", ], },