goauthentik · authentik-cherry-pick · Jul 14, 2026
@@ -69,7 +69,7 @@ An authentik admin can create an entitlement [in the Admin interface](#create-an
 
 Because entitlements exist within an application, names of entitlements must be unique within an application. This also means that entitlements are deleted when an application is deleted.
 
-### Using entitlements
+### Use entitlements
 
 Entitlements to which a user has access can be retrieved using the `user.app_entitlements()` function in property mappings/policies. This function needs to be passed the specific application for which to get the entitlements. For example:
 

@@ -5,7 +5,7 @@ toc_max_heading_level: 5
 
 Each flow execution has an independent _context_. This context holds all of the arbitrary data about that specific flow, data which can then be used and transformed by stages and policies.
 
-## Managing data in a flow context
+## Manage data in a flow context
 
 You create and manage the data for a context by configuring policies, stages, and bindings. As you plan your flow, and set up the required stages, etc. you are creating the context data for that flow.
 

@@ -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.
+
+## Inspect 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.
@@ -35,7 +35,13 @@ To require Duo during authentication, add an [Authenticator Validation stage](..
 Due to the way the Duo API works, authentik can only automatically import existing Duo users when a Duo MFA or higher license is active.
 :::
 
+<<<<<<< HEAD
 If you already have Duo users, you can import their authenticators into authentik from the admin UI. The Duo username can be found in the Duo Admin dashboard under **Users**. If needed, you can also use the Duo user ID shown in the Duo Admin URL for that user.
+=======
+The Duo Auth API enrollment flow creates a new Duo user. If a Duo user already exists with the same username, Duo rejects the enrollment request. To use that existing Duo user in authentik, configure the optional Duo Admin API credentials on the stage and import the authenticator instead of using the enrollment flow. If the Admin API is not available, delete or rename the existing Duo user before enrolling the authenticator.
+
+If you already have Duo users, you can import their authenticators into authentik from the Admin interface. The Duo username can be found in the Duo Admin dashboard under **Users**. If needed, you can also use the Duo user ID shown in the Duo Admin URL for that user.
+>>>>>>> a694dcffc (website/docs: cleanup 07-12: use direct documentation wording (#23967))
 
 For direct API use, the import endpoint accepts:
 

@@ -76,7 +76,7 @@ Common follow-ups include:
 
 ## Notes
 
-### Accessing submitted data
+### Access submitted data
 
 Prompt values are stored in `prompt_data`:
 

@@ -56,7 +56,7 @@ By default, authentik only maps a group's name, `mail_enabled` status, `security
 
 Refer to the Entra ID documentation for further details on these attributes and which attributes can be mapped: [Microsoft Graph - Create Group](https://learn.microsoft.com/en-us/graph/api/group-post-groups?view=graph-rest-1.0&tabs=http#request-body)
 
-### Skipping objects during synchronization
+### Skip objects during synchronization
 
 To exclude specific users or groups from Entra ID synchronization, you can create a property mapping that raises the `SkipObject` exception. When this exception is raised during the evaluation of a property mapping, the object is skipped and the sync continues with the next object.
 

@@ -58,7 +58,7 @@ By default, authentik only maps a group's name.
 
 Refer to Google documentation for further details on which attributes can be mapped: [Google Workspace Reference - Resource: Group](https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups#Group)
 
-### Skipping objects during synchronization
+### Skip objects during synchronization
 
 To exclude specific users or groups from Google Workspace synchronization, you can create a property mapping that raises the `SkipObject` exception. When this exception is raised during the evaluation of a property mapping, the object is skipped and the sync continues with the next object.
 

@@ -0,0 +1,81 @@
+---
+title: Token exchange
+---
+
+Token exchange allows a client to trade a token it already holds for a new token issued by a different authentik provider. It is defined by [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693), whose abstract states:
+
+> This specification defines a protocol for an HTTP- and JSON-based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 authorization servers, including security tokens employing impersonation and delegation.
+
+The typical use is a service that must call another service on behalf of the user who called it. The calling service presents the access token it received as a _subject token_, and receives a token that the second service accepts.
+
+authentik implements _impersonation_: the issued token speaks for the user identified by the subject token, and records no acting party. _Delegation_, in which the issued token names both the user and the service acting on their behalf, is not supported.
+
+### Requirements
+
+The provider performing the exchange must have `Token exchange` selected under **Grant Types**.
+
+The subject token must be verifiable by that provider. Under **Machine-to-Machine authentication settings**, either:
+
+- Add the provider that issued the subject token to **Federated OAuth2/OpenID Providers**, or
+- Add the source that issued the subject token to **Federated OIDC Sources**.
+
+A subject token that neither trust relationship covers is rejected. This is the same trust configuration used by the [machine-to-machine](./machine_to_machine.mdx) JWT flow.
+
+Confidential clients must authenticate to the token endpoint. The subject token is not a substitute for client credentials.
+
+### Exchange a token
+
+Send a POST request to the token endpoint:
+
+```http
+POST /application/o/token/ HTTP/1.1
+Host: authentik.company
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
+client_id=application_client_id&
+client_secret=application_client_secret&
+subject_token=token_issued_by_the_federated_provider&
+subject_token_type=urn:ietf:params:oauth:token-type:access_token&
+scope=openid email
+```
+
+The response contains the following fields:
+
+- `access_token`: The issued token
+- `issued_token_type`: The type identifier of the issued token
+- `token_type`: Always `Bearer`
+- `expires_in`: The total seconds after which the issued token will expire
+- `scope`: The scopes granted to the issued token
+
+The issued token is a new access token for the requesting provider, carrying the identity of the user named by the subject token.
+
+### Supported token types
+
+`subject_token_type` and `requested_token_type` accept:
+
+- `urn:ietf:params:oauth:token-type:access_token`
+- `urn:ietf:params:oauth:token-type:jwt`
+
+authentik access tokens are themselves JWTs, so both identifiers refer to the same token. `requested_token_type` is optional and defaults to `urn:ietf:params:oauth:token-type:access_token`.
+
+Any other token type is rejected with `invalid_request`.
+
+### Unsupported parameters
+
+authentik rejects the following rather than ignoring them, so that a client is never led to believe a restriction was applied when it was not:
+
+- `actor_token` and `actor_token_type` are rejected with `invalid_request`, because delegation is not supported.
+- `audience` and `resource` are rejected with `invalid_target`, because the issued token cannot be scoped to a named target.
+
+### Scopes
+
+The scopes granted to the issued token are the requested `scope` values, reduced to those the requesting provider is configured to issue. If `scope` is omitted, the issued token is granted no scopes.
+
+### Configure token exchange
+
+1. Log in to authentik as an administrator and open the authentik Admin interface.
+2. Navigate to **Applications** > **Providers** and click the **Edit** icon on the provider that will perform the exchange.
+3. Under **Grant Types**, select `Token exchange`.
+4. Expand **Machine-to-Machine authentication settings** and add the issuing provider to **Federated OAuth2/OpenID Providers**.
+5. Click **Update**.
@@ -85,7 +85,7 @@ The outpost listens on port `9000` for HTTP and port `9443` for HTTPS.
 If your upstream host is HTTPS, and you're not using forward auth, you need to access the outpost over HTTPS too.
 :::
 
-## Logging out
+## Log out
 
 Login is initiated automatically when you visit the protected application without a valid cookie.
 
@@ -96,7 +96,7 @@ To log out, navigate to `/outpost.goauthentik.io/sign_out` on the host that serv
 
 Logging out of a provider invalidates all sessions for that user within the respective outpost.
 
-## Allowing unauthenticated requests
+## Allow unauthenticated requests
 
 To allow unauthenticated requests to specific paths or URLs, use the **Unauthenticated Paths** or **Unauthenticated URLs** field on the proxy provider.
 

@@ -28,11 +28,11 @@ The previous binding-specific endpoints (`/sso/binding/redirect/`, `/sso/binding
 
 SAML Metadata ensures that SAML single sign-on works reliably by exchanging and maintaining identity and connection information. SAML metadata is an XML document that defines how IdPs and SPs securely interact for authentication. It includes information such as endpoints, bindings, certificates, and unique identifiers.
 
-### Importing SP SAML metadata
+### Import SP SAML metadata
 
 You can [import SP SAML metadata](./create-saml-provider.md#create-a-saml-provider-from-sp-metadata-import-sp-metadata) to automatically configure a SAML provider based on the requirements of an SP.
 
-### Exporting authentik SAML metadata
+### Export authentik SAML metadata
 
 You can [export SAML metadata from an authentik SAML provider](./create-saml-provider.md#export-authentik-saml-provider-metadata) to an SP to automatically provide important endpoint and certificate information to the SP.
 

@@ -67,5 +67,5 @@ If you selected **OAuth (Interactive)** as the **Authentication mode** for the S
 2. Navigate to **Applications** > **Providers** and click the name of the new SCIM provider.
 3. Next to **OAuth Status**, click **(Re-)Authenticate**.
 4. You should be redirected to the SCIM endpoint that you are provisioning to for authentication.
-5. Once authenticated, you should be redirected back to authentik. If successful, **OAuth Status** should now show as **Authenticated**.
+5. After you authenticate, you should be redirected back to authentik. If successful, **OAuth Status** should now show as **Authenticated**.
    This step is only required when initially configuring the SCIM provider; subsequent authentications will be automatic.
@@ -83,7 +83,7 @@ return {
 
 Use the schema URN and field names expected by the target SCIM service. If the remote service supports only a fixed set of schemas or filters unknown attributes from responses, the attribute might not appear even when authentik sends it.
 
-#### Skipping objects during synchronization
+#### Skip objects during synchronization
 
 To exclude specific users or groups from SCIM synchronization, you can create a property mapping that raises the `SkipObject` exception. When this exception is raised during the evaluation of a property mapping, the object is skipped and the sync continues with the next object.
 

@@ -19,13 +19,13 @@ Refer to our documentation to learn how to [create a SSF provider](./create-ssf-
 
 ## Example use cases
 
-One important use case for SSF is to [integrate Apple Business Manager](https://integrations.goauthentik.io/device-management/apple/) or any of the Apple device management platforms with authentik, so that users can enroll their Apple devices using their authentik credentials. When a user signs in with their email address, Apple redirects them to authentik for authentication. Once authenticated, Apple enrolls the user's device and grants access to Apple services.
+One important use case for SSF is to [integrate Apple Business Manager](https://integrations.goauthentik.io/device-management/apple/) or any of the Apple device management platforms with authentik, so that users can enroll their Apple devices using their authentik credentials. When a user signs in with their email address, Apple redirects them to authentik for authentication. After authentication, Apple enrolls the user's device and grants access to Apple services.
 
 Another use case for SSF is when an administrator wants to know when a user logs out of authentik, so that the user is then also automatically logged out of all other work-focused applications.
 
 Another example use case is when an application uses SSF to subscribe to authorization events because the application needs to know if a user changed their password in authentik. If a user did change their password, then the application receives a POST request to write the fact that the password was changed.
 
-## Using the authentik SSF provider
+## Use the authentik SSF provider
 
 The SSF provider serves as a [backchannel provider](../../applications/manage_apps#backchannel-providers). Backchannel providers are used to augment the functionality of the main provider for an application.
 

@@ -18,6 +18,6 @@ A specific flow with its attached stages, policies, and other objects can be exp
 
 This export can be triggered via the API or the Admin interface by clicking the **Export** button (download icon) next to the flow in the flow list.
 
-## Cleaning up
+## Clean up
 
 Exports from either method will contain a (potentially) long list of objects, all with hardcoded primary keys and no ability for templating/instantiation. This is because currently, authentik does not check which primary keys are used where. It is assumed that for most exports, there'll be some manual changes done regardless, to filter out unwanted objects, adjust properties, etc.
@@ -8,7 +8,7 @@ Blueprints are used to manage authentik's default flows and other system objects
 
 Custom blueprints can be used to replace or modify default blueprints in certain circumstances. For example, you could create a new flow that is based on the `default-authentication-flow` but adds an additional stage or policy.
 
-## Applying blueprints
+## Apply blueprints
 
 To _apply_ a blueprint means that the content in the blueprint file is instantiated and then implemented by authentik. Blueprints can be applied in one of two ways:
 
@@ -79,7 +79,7 @@ Any additional `.yaml` file in `/blueprints` will be discovered and automaticall
 
 To disable existing blueprints, an empty file can be mounted over the existing blueprint.
 
-File-based blueprints are automatically removed once they become unavailable, however none of the objects created by those blueprints are affected by this.
+File-based blueprints are automatically removed when they become unavailable. However, none of the objects created by those blueprints are affected.
 
 :::info
 Please note that, by default, blueprint discovery and evaluation is not guaranteed to follow any specific order.

@@ -48,7 +48,7 @@ authentik resolves `%(theme)s` to:
 
 This resolution happens on the backend, which means it also works with storage backends that need signed URLs, such as S3.
 
-The `%(theme)s` placeholder is supported in all current Admin UI fields that use the shared file picker:
+The `%(theme)s` placeholder is supported in all current Admin interface fields that use the shared file picker:
 
 - Brand **Logo**
 - Brand **Favicon**

@@ -31,7 +31,7 @@ The shared file picker is a UI on top of the files API and the storage backends.
 
 ```mermaid
 flowchart LR
-    A["Admin user"] --> B["Admin UI<br/>ak-file-search-input / ak-file-upload-form"]
+    A["Admin user"] --> B["Admin interface<br/>ak-file-search-input / ak-file-upload-form"]
     B --> C["authentik server router<br/>(lightweight Go router / proxy)"]
     C --> D["authentik Core backend"]
     D --> E["FileView API<br/>/api/v3/admin/file/"]

@@ -1,4 +1,4 @@
-### Enabling/disabling features
+### Enable or disable features
 
 The features listed below can be enabled or disabled through attributes set on the Brand. By default, all of the listed features are enabled. To disable a specific feature, set its value to `false`.
 

@@ -23,7 +23,7 @@ If the new password matches one of those historical entries, the policy fails an
 Password history is maintained automatically while the policy is in use.
 
 :::info Password History Start
-This policy only starts building password history once it is in use. The first password change after you enable it seeds the history; there is no older password history to compare against before that point.
+This policy starts building password history after you enable it. The first subsequent password change seeds the history; there is no older password history to compare against before that point.
 :::
 
 ## When to use it