website/docs: add content about bindings #11787

tanberry · 2024-10-23T22:18:43Z

This PR:

adds a new topic about Bindings, with an overview page and a page that will list all of the How Tos (bind a binding to stage, to a policy, to a group, etc)
adds new content to the procedural for how to create an app in the Wizard, with info about the new Bindings option
add new content about App Entitlements
adds a lot of links between all the things, because Bindings are everywhere

TODO:

in a future PR, add back in the link to entitlements scope on line 51. (That link is broken for now until Jen's PR for app entitlements is merged.)

Related to #11587

The documentation has been updated
The documentation has been formatted (make website)

netlify · 2024-10-23T22:18:58Z

✅ Deploy Preview for authentik-docs ready!

Name	Link
🔨 Latest commit	`abe2cfc`
🔍 Latest deploy log	https://app.netlify.com/sites/authentik-docs/deploys/67623af0235ab20008450a91
😎 Deploy Preview	https://deploy-preview-11787--authentik-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify · 2024-10-23T22:19:00Z

✅ Deploy Preview for authentik-storybook canceled.

Name	Link
🔨 Latest commit	`abe2cfc`
🔍 Latest deploy log	https://app.netlify.com/sites/authentik-storybook/deploys/67623af087505f0008eed3f4

codecov · 2024-10-23T22:24:27Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.76%. Comparing base (4b5e66f) to head (abe2cfc).
Report is 62 commits behind head on main.

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #11787      +/-   ##
==========================================
- Coverage   92.77%   92.76%   -0.02%     
==========================================
  Files         767      767              
  Lines       38522    38523       +1     
==========================================
- Hits        35737    35734       -3     
- Misses       2785     2789       +4

Flag	Coverage Δ
e2e	`48.86% <ø> (-0.06%)`	⬇️
integration	`24.69% <ø> (+<0.01%)`	⬆️
unit	`90.32% <ø> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

github-actions · 2024-10-23T22:49:13Z

authentik PR Installation instructions

Instructions for docker-compose

Add the following block to your .env file:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-abe2cfc0f62caaa51554d159e28d786c48f2a50d
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

For arm64, use these values:

AUTHENTIK_IMAGE=ghcr.io/goauthentik/dev-server
AUTHENTIK_TAG=gh-abe2cfc0f62caaa51554d159e28d786c48f2a50d-arm64
AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s

Afterwards, run the upgrade commands from the latest release notes.

Instructions for Kubernetes

Add the following block to your values.yml file:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
global:
    image:
        repository: ghcr.io/goauthentik/dev-server
        tag: gh-abe2cfc0f62caaa51554d159e28d786c48f2a50d

For arm64, use these values:

authentik:
    outposts:
        container_image_base: ghcr.io/goauthentik/dev-%(type)s:gh-%(build_hash)s
global:
    image:
        repository: ghcr.io/goauthentik/dev-server
        tag: gh-abe2cfc0f62caaa51554d159e28d786c48f2a50d-arm64

Afterwards, run the upgrade commands from the latest release notes.

authentik-automation · 2024-12-10T23:04:38Z

Images automagically compressed by Calibre's image-actions ✨

Compression reduced images by 44.7%, saving 168.00 KB.

Filename	Before	After	Improvement	Visual comparison
`website/docs/add-secure-apps/flows-stages/stages/edit_stage_binding.png`	376.17 KB	208.17 KB	-44.7%	View diff

159 images did not require optimisation.

kensternberg-authentik

Had a couple of concerns.

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

kensternberg-authentik

Much more clear, thanks!

kensternberg-authentik

I'm approving because I suspect I may misunderstand some of the instructions. But if I misunderstand, others may as well, so I left comments.

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

kensternberg-authentik · 2024-12-16T16:14:32Z

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

+
+- **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 display of the new application on the **My applications** page, you can optionally define [bindings](../flows-stages/bindings/index.md) for a specific policy, group, or user. To do so in the Wizard, click **Bind existing policy/group/user** to add a binding. You can select an existing policy binding, or create a new binding specifically for a group or user. For example, if you select **User** and then choose an existing user from the drop-down menu, you create a new binding between the user and this specific application. Note that if you do not define any bindings, then all users have access to the application. For more information, refer to [authorization](#authorization).


I worry that this confuses the issue for experienced users. I don't know that there's a need to explain the difference between Users, Groups, and other Policies here. That's the problem with having "Policy" Policy bindings. Maybe we should call them something else, I dunno, "Custom" bindings.

I am interested in the idea of calling them something else... maybe Application bindings. And then once you say you want an application binding, you choose via radio buttons if you want to bind a Group, a User, or an existing Policy binding. So it ends up with same result, but the beginning part, with the three tabs, might not be so confusing.

kensternberg-authentik · 2024-12-16T16:17:05Z

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

+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.


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

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

kensternberg-authentik · 2024-12-16T16:28:53Z

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

+
+## 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.


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

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

kensternberg-authentik

Man, I'm in a nitpicky mood. Sorry about this. I still learned a lot just from reading it.

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

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

kensternberg-authentik · 2024-12-18T02:23:32Z

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

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


Suggestion: "In scenarios where the user or group cannot be known, such as authentication or enrollment, user and group bindings will not work. To prevent mistakes, stages and flows meant to be seen by unauthorized or pre-authorized users will not permit user and group bindings." (Is this true?)

I'm not actually sure. The original sentence came from Jens telling me that before the system nows who a user is, they can't possibly create a bindings between the stage or flow and the [unknown] user. I think it is that simple, but will find out. So I don;t think it is as fancy as your second sentence... it's not that the system is explicitly preventing because the user is not supposed to see it (unauthorized to see it) but rather that the user is not yet authenticated, so we don't know what user object to bind too. @BeryJu?

website/docs/customize/brands.md

rissson · 2024-12-19T19:35:18Z

/cherry-pick version-2024.12

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

Tana M Berry added 3 commits October 23, 2024 16:35

drafts

5cbf33c

add bindings to sidebar

c069ec7

more words

650a263

tanberry requested a review from a team as a code owner October 23, 2024 22:18

tanberry marked this pull request as draft October 23, 2024 22:18

tanberry changed the title ~~Docs bindings~~ website/docs: add content about bindings Oct 24, 2024

Tana M Berry added 5 commits October 24, 2024 10:10

more content

77bf28b

fixed links

5bdaddc

really fix

fd9cf3b

tweaks

187fcab

typo

0be6ede

tanberry requested a review from BeryJu October 28, 2024 12:49

Tana M Berry added 3 commits December 9, 2024 15:05

Merge branch 'main' into docs-bindings

4d5590e

new arrangement

4149f25

tweak

60272d4

tanberry marked this pull request as ready for review December 10, 2024 13:39

Tana M Berry and others added 4 commits December 10, 2024 16:39

links, add apps entitlements

41b3570

fix image link

a7277a2

polishes

5ebc3fb

Optimised images with calibre/image-actions

866da10

kensternberg-authentik reviewed Dec 11, 2024

View reviewed changes

website/docs/add-secure-apps/applications/manage_apps.md Outdated Show resolved Hide resolved

website/docs/add-secure-apps/applications/manage_apps.md Outdated Show resolved Hide resolved

Tana M Berry added 3 commits December 11, 2024 15:37

ken found a missing step

52d6b28

ken's other excellent edit

599bbb9

added link, more tweaks

7fae1e7

tanberry requested a review from kensternberg-authentik December 11, 2024 23:01

kensternberg-authentik approved these changes Dec 12, 2024

View reviewed changes

Tana M Berry added 5 commits December 13, 2024 10:21

add link about bindings in wizard

581c506

tweak to bump

42c1624

Merge branch 'main' into docs-bindings

9d8f0a3

added new bindings panel to How To create an app

d5fc8bb

links, tweaks

db924ee

kensternberg-authentik approved these changes Dec 16, 2024

View reviewed changes

Tana M Berry added 4 commits December 16, 2024 13:10

added improvement to Brands page

bc1a723

kens edits and tweak brands

4b0babe

add Jens content, rearrange

554d984

temporarily removed breaking link

a0e18ce

kensternberg-authentik reviewed Dec 18, 2024

View reviewed changes

more fine Ken edits

abe2cfc

rissson merged commit d5ea0ff into main Dec 19, 2024
72 checks passed

rissson deleted the docs-bindings branch December 19, 2024 19:35

gcp-cherry-pick-bot bot mentioned this pull request Dec 19, 2024

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

Closed

gcp-cherry-pick-bot bot mentioned this pull request Dec 19, 2024

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

Merged

BeryJu mentioned this pull request Dec 20, 2024

flows: more tests #11587

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

website/docs: add content about bindings #11787

website/docs: add content about bindings #11787

tanberry commented Oct 23, 2024 •

edited

Loading

netlify bot commented Oct 23, 2024 •

edited

Loading

netlify bot commented Oct 23, 2024 •

edited

Loading

codecov bot commented Oct 23, 2024 •

edited

Loading

github-actions bot commented Oct 23, 2024 •

edited

Loading

authentik-automation bot commented Dec 10, 2024

kensternberg-authentik left a comment

kensternberg-authentik left a comment

kensternberg-authentik left a comment

kensternberg-authentik Dec 16, 2024

tanberry Dec 16, 2024

kensternberg-authentik Dec 16, 2024

tanberry Dec 16, 2024

kensternberg-authentik Dec 16, 2024

tanberry Dec 16, 2024

kensternberg-authentik left a comment

kensternberg-authentik Dec 18, 2024

tanberry Dec 18, 2024

rissson commented Dec 19, 2024


		- 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 display of the new application on the My applications page, you can optionally define [bindings](../flows-stages/bindings/index.md) for a specific policy, group, or user. To do so in the Wizard, click Bind existing policy/group/user to add a binding. You can select an existing policy binding, or create a new binding specifically for a group or user. For example, if you select User and then choose an existing user from the drop-down menu, you create a new binding between the user and this specific application. Note that if you do not define any bindings, then all users have access to the application. For more information, refer to [authorization](#authorization).


		## 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.

website/docs: add content about bindings #11787

website/docs: add content about bindings #11787

Conversation

tanberry commented Oct 23, 2024 • edited Loading

netlify bot commented Oct 23, 2024 • edited Loading

✅ Deploy Preview for authentik-docs ready!

netlify bot commented Oct 23, 2024 • edited Loading

✅ Deploy Preview for authentik-storybook canceled.

codecov bot commented Oct 23, 2024 • edited Loading

Codecov Report

github-actions bot commented Oct 23, 2024 • edited Loading

authentik-automation bot commented Dec 10, 2024

kensternberg-authentik left a comment

Choose a reason for hiding this comment

kensternberg-authentik left a comment

Choose a reason for hiding this comment

kensternberg-authentik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kensternberg-authentik left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rissson commented Dec 19, 2024

tanberry commented Oct 23, 2024 •

edited

Loading

netlify bot commented Oct 23, 2024 •

edited

Loading

netlify bot commented Oct 23, 2024 •

edited

Loading

codecov bot commented Oct 23, 2024 •

edited

Loading

github-actions bot commented Oct 23, 2024 •

edited

Loading