Added docs for new RBAC changes #15150

tvo318 · 2024-04-26T16:10:10Z

SUMMARY

Added docs about the new DAC RBAC changes but kept the existing content for backward compatibility since the concepts and functionality still applies. We can keep adding to this when new stuff comes in, like UI changes.
Addresses issue #15048.
See rendered content here: https://ansible--15150.org.readthedocs.build/projects/awx/en/15150/userguide/rbac.html

ISSUE TYPE

New or Enhanced Feature

COMPONENT NAME

Docs

AWX VERSION

latest

AlanCoding · 2024-04-26T18:27:07Z

docs/docsite/rst/userguide/rbac.rst

+
+If you do not want to allow custom roles, you can change the setting ``ANSIBLE_BASE_ALLOW_CUSTOM_ROLES`` to ``False``. This is still a file-based setting for now.
+
+The newly “add” permissions capability is one of the major highlights of this change. You could create a custom organization role that allows users to create all (or some) types of resources, and apply it to a particular organization. So instead of allowing a user to edit all projects, they can create a new project, and after creating it, they will automatically get admin role just for the objects they created.


The newly “add” permissions capability

Grammar of this is hard!

I would try to avoid using the "capability" word. Formally, there are new "add" permissions in the backend. This corresponds to the Django notion of permissions... meaning there is a literal Permission model in Django that this corresponds to. Users don't really need to know this, but that's a nuance of what I mean when I say "permission". These are model-specific, which affects my use of pluralization. You already got that, talking about the project add permission, for example. Here, I would try to phrase it like "New "add" permissions are a major highlight of this change"

AlanCoding · 2024-04-26T18:31:28Z

docs/docsite/rst/userguide/rbac.rst

+ single: roles 
+ pair: legacy; RBAC
+
+RBACs are easiest to think of in terms of Roles which define precisely who or what can see, change, or delete an "object" for which a specific capability is being set. RBAC is the practice of granting roles to users or teams.


RBAC in general usually isn't object-specific. Some other apps do things backwards, where a role includes a list of object permissions. Whereas this new system (and the old system) has abstract roles (role definitions) which can give a user to an object. Some RBAC is kind of per-domain, which we accomplish by organization-level roles, which are object-roles with inheritance added.

I would start out saying that a role contains a list of permissions. There is a domain-ness to this, where organization-level roles can give you a permission (like update_project) to everything in that domain, which means all projects in that organizations.

I tried my best to reword this in order to tie it back to the legacy RBAC model.

AlanCoding · 2024-04-26T18:33:32Z

docs/docsite/rst/userguide/rbac.rst

+
+There are a few main concepts that you should become familiar with regarding AWX's RBAC design--roles, resources, and users. Users can be members of a role, which gives them certain access to any resources associated with that role, or any resources associated with "descendant" roles.
+
+A role is essentially a collection of capabilities. Users are granted access to these capabilities and AWX's resources through the roles to which they are assigned or through roles inherited through the role hierarchy.


Again I'd like to push back against "capabilities". A role list a list of permissions. The DAB RBAC system adds a constraint that it is type-specific, which is how we talk about job template admin_role in the old system. The names are renamed in the new system like for "Job Template Admin"

Ok, just note, this section remained untouched as it is the old RBAC but I'll add your changes if that helps clarify the future RBAC.

AlanCoding · 2024-04-26T18:39:29Z

docs/docsite/rst/userguide/rbac.rst

+
+|rbac-role-hierarchy|
+
+.. |rbac-role-hierarchy| image:: ../common/images/rbac-role-hierarchy.png


The DAB RBAC system actually explicitly ditches the "role hierarchy" system. It's actually really specific about this. The old system used the role hierarchy for everything, but the new system is different.

In DAB RABC, to spell it out, the "Project Admin" role doesn't need to exist for other organization-level roles to give permissions to a project. This is accomplished by the role permission list instead. So the organization admin role has project CRUD permissions (like change_project, delete_project) in its permission list. There is still somewhat of a hierarchy, but at the resource level, in that organizations are the parent object (RBAC-wise) of projects.

The information about the new RBAC only exists in section 9.1 only. Section 9.2 pertains to only legacy RBAC stuff. I left them both in for those who still need reference to the old RBAC.

vidyanambiar

Looks great 🎉 Thanks, @tvo318!

I added a few comments.

vidyanambiar · 2024-05-07T14:37:19Z

docs/docsite/rst/userguide/rbac.rst

+
+::
+
+ {"team": "011-323-232", "role_definition": 4, "object_id": "123-432-233"}


This is not a message from the API, it is an example of what we should be sending as the payload for the POST request made above.
Also, since this is AWX it's probably better to have numbers as IDs in the example:
{"team": 25, "role_definition": 4, "object_id": "10"}

Ah, thanks for the clarification!

vidyanambiar · 2024-05-07T14:40:35Z

docs/docsite/rst/userguide/rbac.rst

+
+.. image:: ../common/images/rbac_team_access_add-roles-success.png
+
+In the API, the following message displays to confirm the changes were successfully applied:


Same comment as above. This is the POST request body. Example:
{"user": 25, "role_definition": 4, "object_id": "10"}

docs/docsite/rst/userguide/rbac.rst

vidyanambiar · 2024-05-07T14:49:02Z

docs/docsite/rst/userguide/rbac.rst

+
+::
+
+ GET <awxAPI>/role_team_assignments/?object_id=<template_id>&content_type__model=jobtemplate


Can we replace all the references to <awxAPI>/ with https://<awx-host>/api/v2/ or /api/v2/?

Yes, for sure! Good catch!

Co-authored-by: Vidya Nambiar <[email protected]>

AlanCoding

Seems good for the new content here.

Added docs for new RBAC changes

bc076f9

tvo318 requested a review from AlanCoding April 26, 2024 16:10

github-actions bot added the component:docs label Apr 26, 2024

AlanCoding reviewed Apr 26, 2024

View reviewed changes

tvo318 added 2 commits May 2, 2024 17:12

Added UI changes with screens and API endpoints with sample commands.

ef319aa

Merge branch 'devel' into newrbac

f35120b

tvo318 requested a review from AlanCoding May 3, 2024 14:14

vidyanambiar reviewed May 7, 2024

View reviewed changes

tvo318 and others added 3 commits May 7, 2024 08:56

Update docs/docsite/rst/userguide/rbac.rst

85d9460

Co-authored-by: Vidya Nambiar <[email protected]>

Incorporated review feedback from @vidyanambiar.

fba5de6

Merge branch 'newrbac' of https://github.com/tvo318/awx into newrbac

7980e2e

tvo318 requested a review from vidyanambiar May 7, 2024 22:10

vidyanambiar approved these changes May 8, 2024

View reviewed changes

AlanCoding approved these changes May 17, 2024

View reviewed changes

jessicamack merged commit 7de350d into ansible:devel May 18, 2024
21 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added docs for new RBAC changes #15150

Added docs for new RBAC changes #15150

tvo318 commented Apr 26, 2024 •

edited

AlanCoding Apr 26, 2024

AlanCoding Apr 26, 2024

tvo318 May 2, 2024

AlanCoding Apr 26, 2024

tvo318 May 2, 2024

AlanCoding Apr 26, 2024

tvo318 May 2, 2024

vidyanambiar left a comment

vidyanambiar May 7, 2024

tvo318 May 7, 2024

vidyanambiar May 7, 2024

vidyanambiar May 7, 2024

tvo318 May 7, 2024 •

edited

AlanCoding left a comment


		If you do not want to allow custom roles, you can change the setting ``ANSIBLE_BASE_ALLOW_CUSTOM_ROLES`` to ``False``. This is still a file-based setting for now.

		The newly “add” permissions capability is one of the major highlights of this change. You could create a custom organization role that allows users to create all (or some) types of resources, and apply it to a particular organization. So instead of allowing a user to edit all projects, they can create a new project, and after creating it, they will automatically get admin role just for the objects they created.


		There are a few main concepts that you should become familiar with regarding AWX's RBAC design--roles, resources, and users. Users can be members of a role, which gives them certain access to any resources associated with that role, or any resources associated with "descendant" roles.

		A role is essentially a collection of capabilities. Users are granted access to these capabilities and AWX's resources through the roles to which they are assigned or through roles inherited through the role hierarchy.


		\|rbac-role-hierarchy\|

		.. \|rbac-role-hierarchy\| image:: ../common/images/rbac-role-hierarchy.png


		::

		{"team": "011-323-232", "role_definition": 4, "object_id": "123-432-233"}


		.. image:: ../common/images/rbac_team_access_add-roles-success.png

		In the API, the following message displays to confirm the changes were successfully applied:


		::

		GET <awxAPI>/role_team_assignments/?object_id=<template_id>&content_type__model=jobtemplate

Added docs for new RBAC changes #15150

Added docs for new RBAC changes #15150

Conversation

tvo318 commented Apr 26, 2024 • edited

SUMMARY

ISSUE TYPE

COMPONENT NAME

AWX VERSION

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

vidyanambiar 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

tvo318 May 7, 2024 • edited

Choose a reason for hiding this comment

AlanCoding left a comment

Choose a reason for hiding this comment

tvo318 commented Apr 26, 2024 •

edited

tvo318 May 7, 2024 •

edited