website/docs: add content about bindings (cherry-pick #11787) (#12428)

website/docs: add content about bindings (#11787)

Co-authored-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>

website/docs/add-secure-apps/applications/manage_apps.md

@@ -20,13 +20,21 @@ To add an application to authentik and have it display on users' **My applicatio
 
 2. Click **Create with Wizard**. (Alternatively, use our legacy process and click **Create**. The legacy process requires that the application and its authentication provider be configured separately.)
 
-3. In the **New application** wizard, define the application details, the provider type and configuration, and then click **Submit**.
+3. In the **New application** wizard, define the application details, the provider type, bindings for the application.
 
-4. To manage the display of the new application on the **My applications** page, you can optionally define the bindings for a specific policy, group, or user. Note that if you do not define bindings, then all users have access to the application, For more information, refer to [authorization](#authorization).
+    - **Application**: provide a name, an optional group for the type of application, the policy engine mode, and optional UI settings.
 
-## Authorization
+    - **Choose a Provider**: select the provider types for this application.
 
-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.
+    - **Configure a Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and any additional required configurations.
+
+    - **Configure Bindings**: to manage the listing and access to applications on a user's **My applications** page, you can optionally create a [binding](../flows-stages/bindings/index.md) between the application and a specific policy, group, or user. Note that if you do not define any bindings, then all users have access to the application. For more information about user access, refer to our documentation about [authorization](#policy-driven-authorization) and [hiding an application](#hide-applications).
+
+4. On the **Review and Submit Application** panel, review the configuration for the new application and its provider, and then click **Submit**.
+
+## Policy-driven authorization
+
+To use a [policy](../../customize/policies/index.md) to control which users or groups can access an application, click on an application in the applications list and then 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. Binding a policy restricts access to specific Users or Groups, or by other custom policies such as restriction to a set time-of-day or a geographic region.
 
 By default, all users can access applications when no policies are bound.
 
@@ -35,6 +43,49 @@ When multiple policies/groups/users are attached, you can configure the _Policy
 - Require users to pass all bindings/be member of all groups (ALL), or
 - Require users to pass either binding/be member of either group (ANY)
 
+## Application Entitlements
+
+<span class="badge badge--preview">Preview</span>
+<span class="badge badge--version">authentik 2024.12+</span>
+
+Application entitlements can be used through authentik to manage authorization within an application (what areas of the app users or groups can access). Entitlements are scoped to a single application and can be bound to multiple users and/or groups (binding policies is not currently supported), giving them access to the entitlement. An application can either check for the name of the entitlement (via the `entitlements` scope), or via attributes stored in entitlements.
+
+An authentik admin can create an entitlement [in the Admin interface](#create-an-application-entitlement) or using the [authentik API](../../developer-docs/api/api.md).
+
+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
+
+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:
+
+```python
+entitlements = [entitlement.name for entitlement in request.user.app_entitlements(provider.application)]
+return {
+    "entitlements": entitlements,
+}
+```
+
+### Attributes
+
+Each entitlement can store attributes similar to user and group attributes. These attributes can be accessed in property mappings and passed to applications via `user.app_entitlements_attributes`. For example:
+
+```python
+attrs = request.user.app_entitlements(provider.application)
+return {
+    "my_attr": attrs.get("my_attr")
+}
+```
+
+### Create an application entitlement
+
+1. Open the Admin interface and navigate to **Applications -> Applications**.
+2. Click the name of the application for which you want to create an entitlement.
+3. Click the **Application entitlements** tab at the top of the page, and then click **Create entitlement**. Provide a name for the entitlement, enter any optional **Attributes**, and then click **Create**.
+4. In the list locate the entitlement to which you want to bind a user or group, and then **click the caret (>) to expand the entitlement details.**
+5. In the expanded area, click **Bind existing Group/User**.
+6. In the **Create Binding** modal box, select either the tab for **Group** or **User**, and then in the drop-down list, select the group or user.
+7. Optionally, configure additional settings for the binding, and then click **Create** to create the binding and close the modal box.
+
 ## Hide applications
 
 To hide an application without modifying its policy settings or removing it, you can simply set the _Launch URL_ to `blank://blank`, which will hide the application from users.

website/docs/add-secure-apps/flows-stages/bindings/index.md

@@ -0,0 +1,33 @@
+---
+title: Bindings
+---
+
+A binding is, simply put, a connection between two components (a flow, stage, policy, user, or group). The use of a binding adds additional functionality to one those existing components; for example, a policy binding can cause a new stage to be presented within a flow to a specific user or group.
+
+:::info
+For information about creating and managing bindings, refer to [Working with bindings](./work_with_bindings.md).
+:::
+
+Bindings are an important part of authentik; the majority of configuration options are set in bindings.
+
+Bindings are analyzed by authentik's Flow Plan, which starts with the flow, then assesses all of the bound policies, and then runs them in order to build out the plan.
+
+The two most common types of bindings in authentik are:
+
+- stage bindings
+- policy bindings
+- user and group bindings
+
+A _stage binding_ connects a stage to a flow. The "additional content" (i.e. the content in the stage) is now added to the flow.
+
+A _policy binding_ connects a specific policy to a flow or to a stage. With the binding, the flow (or stage) will now have additional content (i.e. the policy rules).
+
+You can also bind groups and users to another component (a policy, a stage, a flow, etc.). For example, you can create a binding for a specific group, and then [bind that to a stage binding](../stages/index.md#bind-users-and-groups-to-a-flows-stage-binding), with the result that everyone in that group now will see that stage (and any policies bound to that stage) as part of their flow. Or more specifically, and going one step deeper, you can also _bind a binding to a binding_.
+
+Bindings are also used for [Application Entitlements](../../applications/manage_apps.md#application-entitlements), where you can bind specific users or groups to an application as a way to manage who has access to the application.
+
+It's important to remember that bindings are instantiated objects themselves, and conceptually can be considered as a "connector" between two components. 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 second binding.
+
+:::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.
+:::

website/docs/add-secure-apps/flows-stages/bindings/work_with_bindings.md

@@ -0,0 +1,13 @@
+---
+title: Work with bindings
+---
+
+As covered in the [overview](./index.md), bindings interact with many other components.
+
+For instructions to create a binding, refer to the documentation for the specific components:
+
+- [Bind a stage to a flow](../stages/index.md#bind-a-stage-to-a-flow)
+- [Bind a policy to a flow or stage](../../../customize/policies/working_with_policies#bind-a-policy-to-a-flow-or-stage)
+- [Bind users or groups to a specific application with an Application Entitlement](../../applications/manage_apps.md#application-entitlements)
+- [Bind a policy to a specific application when you create a new app using the Wizard](../../applications/manage_apps.md#instructions)
+- [Bind users and groups to a stage binding, to define whether or not that stage is shown](../stages/index.md#bind-users-and-groups-to-a-flows-stage-binding)

website/docs/add-secure-apps/flows-stages/stages/index.md

@@ -54,3 +54,24 @@ To bind a stage to a flow, follow these steps:
 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**).
+
+## Bind users and groups to a flow's stage binding
+
+You can use bindings to determine whehther or not a stage is presented to a single user or any users within a group. You do this by binding the user or group to a stage binding within a specific flow. For example, if you have a flow that contains a stage that prompts the user for multi-factor authentication, but you only want certain users to see this stage (and fulfill the MFA prompt), then you would bind the appropriate group (or single user) to the stage binding for that flow.
+
+To bind a user or a group to a stage binding for a specific 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. Locate the stage binding to which you want to bind a user or group, and then **click the caret (>) to expand the stage binding details.**
+
+![](./edit_stage_binding.png)
+
+6. In the expanded area, click **Bind existing policy/group/user**.
+7. In the **Create Binding** modal box, select either the tab for **Group** or **User**.
+8. In the drop-down list, select the group or user.
+9. Optionally, configure additional settings for the binding, and then click **Create** to create the binding and close the modal box.
+
+Learn more about [bindings](../bindings/index.md) and [working with them](../bindings/work_with_bindings.md).

website/docs/customize/brands.md

@@ -9,7 +9,7 @@ The main settings that brands influence are flows and branding.
 
 ## Flows
 
-You can explicitly select, in your instance's Brand settings, the default flow to use for the following configurations:
+You can explicitly select, in your instance's Brand settings, the _default flows_ to use for the current brand. To do so, log in as an administrator, open the Admin interface, and navigate to **System -> Brands**. There you can optionally configure these default flows:
 
 - 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).

website/docs/customize/policies/working_with_policies.md

@@ -8,6 +8,8 @@ authentik provides several [standard policy types](./index.md#standard-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).
 
+To learn more see also [bindings](../../add-secure-apps/flows-stages/bindings/index.md) and how to use the [authentik Wizard to bind policy bindings to the new application](../../add-secure-apps/applications/manage_apps.md#add-new-applications) (for example, to configure application-specific access).
+
 ## Create a policy
 
 To create a new policy, follow these steps:
@@ -22,7 +24,7 @@ To create a new policy, follow these steps:
 After creating the policy, you can bind it to either a [flow](../../add-secure-apps/flows-stages/flow/index.md) or to a [stage](../../add-secure-apps/flows-stages/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.
+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. To learn more refer to our [Bindings documentation](../../add-secure-apps/flows-stages/bindings/index.md).
 :::
 
 ### Bind a policy to a flow

website/sidebars.js

@@ -306,6 +306,17 @@ export default {
                                 "add-secure-apps/flows-stages/stages/user_write",
                             ],
                         },
+                        {
+                            type: "category",
+                            label: "Bindings",
+                            link: {
+                                type: "doc",
+                                id: "add-secure-apps/flows-stages/bindings/index",
+                            },
+                            items: [
+                                "add-secure-apps/flows-stages/bindings/work_with_bindings",
+                            ],
+                        },
                     ],
                 },
                 {