Cherry-pick #16878 to version-2025.4 (with conflicts)

This cherry-pick has conflicts that need manual resolution.

Original PR: #16878
Original commit: dbf85d0

Author: tanberry

website/docs/customize/policies/expression.mdx

@@ -2,9 +2,9 @@
 title: Expression Policies
 ---
 
-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.
+Expression policies are perhaps the most flexible way to define specific implementations of flows and stages. When you [create](./working_with_policies.md#create-a-policy) an expression policy, you provide your own custom Python code to enforce custom checks and validation.
 
-The passing of the policy is determined by the return value of the code.
+The passing of the policy is determined by the return value of the code: `True` or `False`.
 
 To pass a policy, use:
 
@@ -27,9 +27,18 @@ if request.context["pending_user"].username == "marie":
 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.
+When the policy returns `True`, the MFA validation stage is enforced. When it returns `False`, the MFA validation stage is skipped.
 
-## Available Functions
+## Sample expression policies
+
+Expressions policies with sample Python that we have documented:
+
+- [Source-switching based on email address](./expression/source_switch.md)
+- [Managing flow context keys](./expression/managing_flow_context_keys.md)
+- [Unique email addresses](./expression/unique_email.md)
+- [Create an email address allow list](./expression/whitelist_email.md)
+
+## Available functions
 
 ### `ak_message(message: str)`
 

website/docs/customize/policies/expression/source_switch.md

@@ -0,0 +1,45 @@
+---
+title: Switch which source is used based on email address
+---
+
+You can use an expression policy to determine which [source](../../../../users-sources/sources/) (a set of user credentials and data, stored in authentik, Google, GitHub, etc) is used for a particular user, based on the domain of the email address the user enters when they log in and authenticate.
+
+To switch which source is used for a specific user based on their email domain, you need to 1. and then 2. bind that policy to the appropriate stage.
+
+## 1. Create an expression policy
+
+[Create](../working_with_policies.md#create-a-policy) an expression policy] that does the following:
+
+    1. Maps the desired source for each user domain.
+    2. Determines the user's domain based on their email address.
+    3. Then "switches" the user to the desired source.
+
+## Bind the policy to the stage
+
+The new expression policy needs to be bound to the stage binding that comes after the Identification stage (or any custom stage that you might have created). For more information read our documentation about [bindings](../../../../add-secure-apps/flows-stages/bindings/), and for instructions to bind a policy, see [Bind a policy to a stage]](../../../../customize/policies/working_with_policies/#bind-a-policy-to-a-stage).
+
+## Example expression
+
+```python
+# This is a mapping of domains to sources
+# the key is a domain for the user and the value is the `slug` of the source to redirect to
+source_email_map = {
+    "foo.bar.com": "entra-foo",
+    "bar.baz.com": "entra-bar",
+}
+
+user_email = request.context["pending_user_identifier"]
+
+_username, _, domain = user_email.partition("@")
+source = source_email_map.get(domain)
+if not source:
+    return True
+plan = request.context.get("flow_plan")
+if not plan:
+    return False
+# For OIDC
+# plan.redirect(f"/source/oauth/login/{source}/")
+# For SAML
+plan.redirect(f"/source/saml/{source}")
+return False
+```

website/docs/customize/policies/index.md

@@ -8,11 +8,13 @@ In effect, policies determine whether or not a specific stage is applied to a fl
 
 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](./working_with_policies.md)".
+## Create and manage policies
+
+For instructions about creating and binding policies to flows and stages, refer to [Working with policies](./working_with_policies.md).
 
 ## Standard policies
 
-The following policies are our standard, out-of-the box policies.
+The following are our standard, out-of-the box policies that you can [create and customize](./working_with_policies.md) as needed.
 
 ### Event-matcher policy
 
@@ -61,9 +63,9 @@ The following rules can be set:
 - Minimum length.
 - Symbol charset (define which characters are counted as symbols).
 
-Starting with authentik 2022.11.0, the following checks can also be done with this policy:
+The following checks can also be done with this policy:
 
-- 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 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.
 
 ### Password Uniqueness Policy

website/docs/customize/policies/working_with_policies.md

@@ -4,19 +4,27 @@ 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.
+authentik provides several [standard policy types](./index.md#standard-policies), which can be configured for your specific needs. We also document several useful [expression policies](./expression.mdx#sample-expression-policies).
 
-We also document how to use a policy to [whitelist email domains](./expression/whitelist_email.md) and to [ensure unique email addresses](./expression/unique_email.md).
+:::info
+You can add expressions to our standard policies to further customize them.
+:::
 
-To learn more see also [bindings](../../add-secure-apps/flows-stages/bindings/index.md) and how to [bind policy bindings to a new application when the application is created](../../add-secure-apps/applications/manage_apps.mdx#instructions) (for example, to configure application-specific access).
+To learn more, see the [bindings](../../add-secure-apps/flows-stages/bindings/index.md) and how to [bind policy bindings to a new application when the application is created](../../add-secure-apps/applications/manage_apps.mdx#instructions) documentation (for example, to configure application-specific access).
 
 ## Create a policy
 
-To create a new policy, follow these steps:
+To create a new policy, _either a pre-configured one or an expression policy_, follow these steps:
 
+<<<<<<< HEAD
 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.
+=======
+1. Log in to authentik as an administrator and open the authentik Admin interface.
+2. Navigate to **Customization** > **Policies**.
+3. Click **Create**, and select the type of policy. Here you select whether you want to create a custom expression policy, or a standard, out-of-the box one.
+>>>>>>> dbf85d04e (website/docs: add docs for source switch expression policy (#16878))
 4. Define the policy and click **Finish**.
 
 ## Bind a policy to a flow or stage
@@ -41,9 +49,15 @@ These bindings control which users can access a flow.
 
 These bindings control which stages are applied to a flow.
 
+<<<<<<< HEAD
 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.
+=======
+1. Log in to authentik as an administrator and open the authentik Admin interface.
+2. Navigate to **Flows and Stages > Stages**.
+3. In the list of stages, click on the name of the stage to which you want to bind a policy.
+>>>>>>> dbf85d04e (website/docs: add docs for source switch expression policy (#16878))
 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.