From c6fd931663a086cdb561d5e1059cddc4faafdc22 Mon Sep 17 00:00:00 2001 From: Connor Peshek Date: Mon, 5 Jan 2026 15:56:12 -0600 Subject: [PATCH] Add docs for roles (#19196) * Add docs for roles * update users and roles --- .../docs/users-sources/groups/group_ref.md | 15 ++++++++++- .../users-sources/groups/manage_groups.mdx | 4 +++ website/docs/users-sources/roles/index.md | 26 +++++++++++++++++++ .../user/user_basic_operations.md | 4 +++ 4 files changed, 48 insertions(+), 1 deletion(-) diff --git a/website/docs/users-sources/groups/group_ref.md b/website/docs/users-sources/groups/group_ref.md index 3d7629f491..d02996d569 100644 --- a/website/docs/users-sources/groups/group_ref.md +++ b/website/docs/users-sources/groups/group_ref.md @@ -9,7 +9,8 @@ The group object has the following properties: - `name`: The group's display name. - `is_superuser`: A boolean field that determines if the group's users are superusers. - `parents`: The parent groups of this group. -- `roles`: The roles assigned to this group. +- `roles`: The roles directly assigned to this group. +- `all_roles()`: Returns all roles for this group, including roles inherited from parent groups. - `attributes`: Dynamic attributes, see [Attributes](#attributes). ## Examples @@ -29,6 +30,18 @@ from authentik.core.models import Group Group.objects.get(name="name of group").users.all() ``` +### List all roles for a group + +Use the following examples to list roles assigned to a group: + +```python title="Get directly assigned roles for a group object" +group.roles.all() +``` + +```python title="Get all roles including inherited from parent groups" +group.all_roles() +``` + ## Attributes By default, authentik group objects are created with no attributes, however custom attributes can be set. diff --git a/website/docs/users-sources/groups/manage_groups.mdx b/website/docs/users-sources/groups/manage_groups.mdx index 086ef66f4d..8c452fe2df 100644 --- a/website/docs/users-sources/groups/manage_groups.mdx +++ b/website/docs/users-sources/groups/manage_groups.mdx @@ -47,6 +47,10 @@ To delete a group, follow these steps: You can assign a role to a group, and then all users in the group inherit the permissions assigned to that role. For instructions and more information, see [Assign a role to a group](../roles/manage_roles.md#assign-a-role-to-a-group). +:::info +Roles are inherited through group hierarchy. If a parent group has a role assigned, all child groups (and their users) automatically inherit that role's permissions. You can view both directly assigned and inherited roles on a group's detail page under the **Roles** tab. +::: + ## Delegating group member management:ak-version[2024.4] To give a specific role or user the ability to manage group members, the following permissions need to be granted on the matching group object: diff --git a/website/docs/users-sources/roles/index.md b/website/docs/users-sources/roles/index.md index c41b11d4ca..ae86d28833 100644 --- a/website/docs/users-sources/roles/index.md +++ b/website/docs/users-sources/roles/index.md @@ -8,12 +8,38 @@ Roles are a way to simplify the assignment of permissions. Roles are also the ba Think of roles as a collection of permissions. A role, along with its "bucket" of assigned permissions, can then be assigned to a user, or it can be assigned to a group (which means that every user who is a part of that group will inherit all of the permissions in that role's "bucket"). +Roles are also inherited through group hierarchy. When a role is assigned to a parent group, all child groups automatically inherit that role. This means users in any descendant group will have the permissions from roles assigned to any of their ancestor groups. + For example, let's take a look at the following scenario: > You need to add 5 new users, all new hires, to authentik, your identity management system. These users will be the first team members on the brand new Security team, so they will need some high-level permissions, with object permissions to create and remove other users, revoke permissions, and send recovery emails. They will also need [global permissions](../access-control/permissions.md#fundamentals-of-authentik-permissions) to control access to flows and stages. The easiest workflow for setting up these new users involves [creating a role](./manage_roles.md#create-a-role) specifically for their type of work, and then [assigning that role to a group](./manage_roles.md#assign-a-role-to-a-group) to which all of the users belong. +## Viewing roles for users and groups + +You can view the roles assigned to a user or group through their detail pages in the Admin interface. + +### User roles + +To view roles for a user: + +1. Navigate to **Directory > Users** and click on a user's name. +2. Click the **Roles** tab. +3. The tab has two sub-tabs: + - **Assigned Roles**: Shows roles directly assigned to this user. + - **All Roles**: Shows all roles the user has, including roles inherited from groups they belong to. Inherited roles are marked with an "Inherited" label. + +### Group roles + +To view roles for a group: + +1. Navigate to **Directory > Groups** and click on a group's name. +2. Click the **Roles** tab. +3. The tab has two sub-tabs: + - **Assigned Roles**: Shows roles directly assigned to this group. + - **All Roles**: Shows all roles the group has, including roles inherited from parent groups. Inherited roles are marked with an "Inherited" label. + To learn more about working with roles in authentik, refer to the following topics: diff --git a/website/docs/users-sources/user/user_basic_operations.md b/website/docs/users-sources/user/user_basic_operations.md index 3cb8ea7603..fda88bb4ba 100644 --- a/website/docs/users-sources/user/user_basic_operations.md +++ b/website/docs/users-sources/user/user_basic_operations.md @@ -97,6 +97,10 @@ For more information, review ["Permissions"](../access-control/permissions.md). 2. Click the name of the user to display the full user details page. 3. Click the **Roles** tab, and then click either **Add to existing role** (or **Add new role** first). +:::info +Users also inherit roles from the groups they belong to. The **Roles** tab has two sub-tabs: **Assigned Roles** shows roles directly assigned to the user, while **All Roles** shows all roles including those inherited from groups. Inherited roles are marked with an "Inherited" label. +::: + ## User credentials recovery If a user has lost their credentials and needs to recover their account, there are two available options: