Skip to content

RHIDP-5483: Update Authorization Preface #1052

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.

Sign up for GitHub

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

RHIDP-5483: Update Authorization Preface #1052

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e46ca4
RHIDP-5483: Update Authorization Preface
linfraze Apr 3, 2025
72e9677
RHIDP-5483: Update Authorization Abstract
linfraze Apr 3, 2025
888d5f5
RHIDP-5483: Apply reviewer suggestions
linfraze Apr 16, 2025
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
23 changes: 7 additions & 16 deletions assemblies/assembly-configuring-authorization-in-rhdh.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,26 +1,18 @@
[id='configuring-authorization-in-rhdh']
= Configuring authorization in {product}

In link:{authorization-book-url}[{authentication-book-title}], you learnt how to authenticate users to {product}.
{product-short} knowns who the users are.
Administrators can authorize users to perform actions and define what users can do in {product-short}.
Copy link
Member

Choose a reason for hiding this comment

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

For clarity, consider not using "Administrators" alone. We have different admin roles: "platform engineer aka. OCP administrator" / "RHDH administrator" / "RBAC administrator".

The distinction is also missing in the previous content.

It would be nice if the introduction would clarify the roles:

  • (A) Platform engineer / OpenShift user with developer privileges. Roles in authorization:

    • Enable the RBAC feature
    • Define RBAC administrators
    • When using policy files: define authorizations

  • (B) RBAC policy administrator = RHDH user with manager priveleges on RBAC policies. Roles in authorization:

    • When using the RBAC REST API: define authorizations.

  • (C) RHDH administrator => this is a confusing role, with 2 indentities:

    • First identity: (A) OpenShift user with developer privileges that manages the RHDH instance on OpenShift; authenticated in Openshift. Roles in authorization: see (A).
    • Second identity: (D) RHDH user with administrative privileges; authenticated in RHDH authentication provider, which is external, and might be different from the OpenShift authentication provider. Roles in authorization: see (B).

Copy link
Member Author

Choose a reason for hiding this comment

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

@themr0c so which role / permission is required to authorize users to perform actions and define what users can do in RHDH?

If you're saying there are conditions and various admins can do this in various ways, then I agree that we should probably describe those roles / perms in detail, but that doesn't necessarily mean that the statement with the general Administrators term is not true and valid.

I think we definitely need some further exploration and enhancement there, but this PR is intended to be a copyedit to comply with Minimalism and grammar standards rather than a deep content edit.

Copy link
Member Author

@linfraze linfraze Apr 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I also think it might be ok to speak more generally in the assembly, as long as our content in technically accurate, and then outline each of these roles / responsibilities in more detail in modules (or a reference module) within the assembly. Think about how a user / particular persona would navigate the docs to find out who, what, and how to authorize users.


In this book, learn how to authorize users to perform actions in {product-short}.
Define what users can do in {product-short}.
Role-based access control (RBAC) is a security concept that defines how to control access to resources in a system by specifying a mapping between users of the system and the actions that those users can perform on resources in the system.
You can use RBAC to define roles with specific permissions and then assign the roles to users and groups.

Role-Based Access Control (RBAC) is a security concept that controls access to resources in a system, and specifies a mapping between users of the system, and the actions they can perform on resources in the system.
You define roles with specific permissions, and then assign the roles to users and groups.
RBAC on {product-short} is built on top of the Permissions framework, which defines RBAC policies in code. Rather than defining policies in code, you can use the {product-short} RBAC feature to define policies in a declarative fashion by using a simple CSV based format. You can define the policies by using {product-short} web interface or REST API instead of editing the CSV directly.

RBAC on {product-short} is built on top of the Permissions framework, which defines RBAC policies in code.
Rather than defining policies in code,
the {product-short} RBAC feature allows you
to define policies in a declarative fashion using a simple CSV based format.
You can define the policies by using {product-short} web interface or REST API, rather than editing the CSV directly.
An administrator can define authorizations in {product-short} by taking the following steps:

To define authorizations in {product-short}:
. Enable the RBAC feature and give authorized users access to the feature.

. The {product-short} administrator enables and gives access to the RBAC feature.

. You define your roles and policies by combining the following methods:
. Define roles and policies by combining the following methods:

* The {product-short} policy administrator uses the {product-short} web interface or REST API.
* The {product-short} administrator edits the main {product-short} configuration file.
Expand Down Expand Up @@ -58,4 +50,3 @@ include::modules/authorization/con-user-stats-rhdh.adoc[leveloffset=+1]


include::modules/authorization/proc-download-user-stats-rhdh.adoc[leveloffset=+2]

1 change: 0 additions & 1 deletion titles/authentication/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,3 @@ include::artifacts/attributes.adoc[]
//{abstract}

include::assemblies/assembly-enabling-authentication.adoc[]

2 changes: 1 addition & 1 deletion titles/authorization/master.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ include::artifacts/attributes.adoc[]
:imagesdir: images
:title: Authorization in {product}
:subtitle: Configuring authorization by using role based access control (RBAC) in {product}
:abstract: As a {product} platform engineer, you can manage authorizations of other users by using role based access control (RBAC) to meet the specific needs of your organization.
:abstract: {product} administrators can use role-based access control (RBAC) to manage authorizations of other users.
//[id="{context}"]
//= {title}

Expand Down