Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

website/docs: add content about bindings #11787

Merged
merged 28 commits into from
Dec 19, 2024
Merged
Show file tree
Hide file tree
Changes from 15 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion website/docs/add-secure-apps/applications/manage_apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,11 @@ 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 either (Policy) bindings or Application Entitlements.

### Policy-driven authorization

To use a policy to control which users or groups can access an application, 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.
tanberry marked this conversation as resolved.
Show resolved Hide resolved

By default, all users can access applications when no policies are bound.

Expand All @@ -35,6 +39,18 @@ 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

Another method to control which users or groups can access an application is to create an Application Entitlement (which defines the specific application(s)), and then bind that to specific groups or users.

1. To create an Application Entitlement open the Admin interface and navigate to **Applications -> Applications**.
2. Click the **Application entitlements** tab, and then click **Create entitlement**. Provide a name for the entitlement, enter any optional **Attributes** , and then click **Create**.
tanberry marked this conversation as resolved.
Show resolved Hide resolved
3. Locate the entitlement to which you want to bind a user or group, and then **click the caret (>) to expand the entitlement details.**
4. In the expanded area, click **Bind existing Group/User**
In the **Create Binding** modal box, select either the tab for **Group** or **User**.
5. In the drop-down list, select the group or user.
6. 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.
Expand Down
32 changes: 32 additions & 0 deletions website/docs/add-secure-apps/flows-stages/bindings/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
---
title: Bindings
---

A binding is, simply put, a connection between two components (a flow, stage, policy, user, or group) _that adds additional content_ to one those existing components.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Content" is such a weird word. "Functionality?" "Intelligence?"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, content is not at all the right word here. Let me try to reword...


:::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

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_.
tanberry marked this conversation as resolved.
Show resolved Hide resolved

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 the "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.
tanberry marked this conversation as resolved.
Show resolved Hide resolved

:::info
Be aware that some stages and flows do not allow user or group bindings, because in any certain scenarios (authentication or enrollment), the Flow plan doesn't yet know who the user or group is.
:::
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
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/working_with_policies.md#bind-a-policy-to-a-flow-or-stage)
- [Create an Application Entitlement and bind users or Groups](../../applications/manage_apps.md#application-entitlements)
- [Bind users and groups to a stage binding](../stages/index.md#bind-users-and-groups-to-a-flows-stage-binding)
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
21 changes: 21 additions & 0 deletions website/docs/add-secure-apps/flows-stages/stages/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So... what do the users who don't see this stage experience?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They just see the next stage (that they are allowed to see) in the flow. @BeryJu please confirm.


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).
11 changes: 11 additions & 0 deletions website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -302,6 +302,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",
],
},
],
},
{
Expand Down
Loading