diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index edebf3db72f7..dfe017f299ea 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -102,6 +102,8 @@ Topics: File: rhcl-ocp-web-console - Name: Sharing and consuming APIs across teams File: rhcl-api-management +- Name: RBAC and permissions for the developer hub plugin + File: devhub-plugin-rbac-ref --- Name: Observability Dir: observe diff --git a/develop/devhub-plugin-rbac-ref.adoc b/develop/devhub-plugin-rbac-ref.adoc new file mode 100644 index 000000000000..bafb862f9c52 --- /dev/null +++ b/develop/devhub-plugin-rbac-ref.adoc @@ -0,0 +1,44 @@ +:_mod-docs-content-type: ASSEMBLY +include::_attributes/attributes.adoc[] +[id="devhub-plugin-rbac-ref"] += RBAC reference for the developer hub plugin +:context: devhub-plugin-rbac-ref + +toc::[] + +[role="_abstract"] +To control who can publish APIs, request API access, and approve requests in the {prodname} {rhdh} plugin, configure role-based access control (RBAC). The {prodname} plugin uses the {rhdh} RBAC system with a consistent ownership-based permission model. + +include::modules/con-devhub-rbac-overview.adoc[leveloffset=+1] + +include::modules/con-devhub-rbac-design-principles.adoc[leveloffset=+1] + +include::modules/ref-devhub-rbac-permission-structure.adoc[leveloffset=+1] + +include::modules/ref-devhub-rbac-permission-list.adoc[leveloffset=+1] + +include::modules/ref-devhub-rbac-role-definitions.adoc[leveloffset=+1] + +include::modules/ref-devhub-rbac-permissions-matrix.adoc[leveloffset=+1] + +include::modules/con-devhub-rbac-ownership-model.adoc[leveloffset=+1] + +include::modules/con-devhub-rbac-approval-workflow.adoc[leveloffset=+1] + +include::modules/ref-devhub-rbac-per-apiproduct-access.adoc[leveloffset=+1] + +include::modules/con-devhub-rbac-catalog-integration.adoc[leveloffset=+1] + +include::modules/ref-devhub-rbac-configuration.adoc[leveloffset=+1] + +include::modules/con-devhub-rbac-security.adoc[leveloffset=+1] + +include::modules/ref-devhub-rbac-frontend-permissions.adoc[leveloffset=+1] + +include::modules/con-devhub-rbac-two-layer-model.adoc[leveloffset=+1] + +[id="additional-resources_devhub-pligin-rbac-ref"] +[role="_additional-resources"] +== Additional resources + +* link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/1.10/html/authorization_in_red_hat_developer_hub/role-based-access-control-in-rhdh_authorization-in-rhdh[Role-based access control in Developer Hub] \ No newline at end of file diff --git a/modules/con-devhub-rbac-approval-workflow.adoc b/modules/con-devhub-rbac-approval-workflow.adoc new file mode 100644 index 000000000000..74d9de5574bb --- /dev/null +++ b/modules/con-devhub-rbac-approval-workflow.adoc @@ -0,0 +1,26 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-devhub-rbac-approval-workflow_{context}"] += Approval workflow + +[role="_abstract"] +The {prodname} {rhdh} plugin controls access to the approval queue and enforces ownership checks when users approve or reject API key requests. + +[id="con-devhub-rbac-approval-queue-visibility_{context}"] +== Approval queue visibility + +The approval queue card is visible only to users who have the `kuadrant.apikey.approve` permission. This permission determines whether a user can see the approval interface in the {rhdh} UI. + +API consumers:: Do not see the approval queue because they do not have the `approve` permission. +API owners:: See the approval queue and can approve requests for their own APIs. +API administrators:: See the approval queue and can approve any request. + +[id="con-devhub-rbac-backend-approval-enforcement_{context}"] +== Backend approval enforcement + +The backend uses tiered permission checks for approve and reject actions independently from the frontend UI. The backend first checks if the user has the `kuadrant.apikey.update.all` permission for administrator-level access. If the user does not have that permission, the backend verifies that the user owns the `APIProduct` resource associated with the request. + +The `kuadrant.apikey.approve` permission controls UI visibility of the approval queue. The backend enforces ownership separately to ensure that API owners can only approve requests for their own APIs. diff --git a/modules/con-devhub-rbac-catalog-integration.adoc b/modules/con-devhub-rbac-catalog-integration.adoc new file mode 100644 index 000000000000..5c355d5a8931 --- /dev/null +++ b/modules/con-devhub-rbac-catalog-integration.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-devhub-rbac-catalog-integration_{context}"] += Catalog integration + +[role="_abstract"] +The `APIProduct` entity provider syncs only products that have ownership annotations to the {rhdh} catalog. If an `APIProduct` resource does not have a `backstage.io/owner` annotation, it is not synced and does not appear in the catalog. + +This behavior ensures clean separation between resources managed through the {rhdh} plugin and resources managed directly by using `oc` or `kubectl` commands. diff --git a/modules/con-devhub-rbac-design-principles.adoc b/modules/con-devhub-rbac-design-principles.adoc new file mode 100644 index 000000000000..06ff5053fe58 --- /dev/null +++ b/modules/con-devhub-rbac-design-principles.adoc @@ -0,0 +1,20 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-devhub-rbac-design-principles_{context}"] += RBAC design principles + +[role="_abstract"] +The {prodname} {rhdh} plugin follows a set of design principles for authorization decisions. Understanding these principles helps you configure and troubleshoot RBAC policies. + +Pure RBAC only:: All authorization decisions use {rhdh} RBAC permissions. If you need to control access to a feature, create a permission for it. The plugin does not use group membership checks, data-based ownership checks for UI visibility, or role flags derived from user identity. + +One permission per distinct capability:: Each permission represents a single, well-defined capability. Permissions are not overloaded with meanings. For example, `kuadrant.apikey.approve` is a separate permission specifically for approval queue access. This is instead of reusing `kuadrant.apikey.update.own` for both editing and approving. + +UI visibility matches permission checks:: If a UI element is hidden from certain users, that element is gated by a permission check rather than a data query. The plugin does not use data queries to allow a user to see a resource or action. + +Backend enforces, front-end hints:: Permissions in the front-end control the user experience by hiding buttons and displaying the appropriate UI. The backend enforces permissions independently and does not rely on front-end permission checks. + +Scope permissions appropriately:: Permissions use `.own` scope for resources the user created, `.all` scope for any resource regardless of ownership, and no scope for actions that apply globally. For actions that do not fit the ownership model, such as viewing an approval queue, the plugin uses an unscoped permission. diff --git a/modules/con-devhub-rbac-overview.adoc b/modules/con-devhub-rbac-overview.adoc new file mode 100644 index 000000000000..d7ccea4e9ae5 --- /dev/null +++ b/modules/con-devhub-rbac-overview.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-devhub-rbac-overview_{context}"] += The RBAC permission model + +[role="_abstract"] +The {prodname} {rhdh} plugin uses the {rhdh} role-based-access-system (RBAC) system for access control across API products, API keys, and plan policies. Permissions follow a consistent `.own` and `.all` pattern for resource-level access control. + +With `.own` permissions, a user can act on resources that they created or own. With `.all` permissions, a user can act on any resource regardless of ownership. Permissions without a scope, such as `list` and `create`, apply globally. diff --git a/modules/con-devhub-rbac-ownership-model.adoc b/modules/con-devhub-rbac-ownership-model.adoc new file mode 100644 index 000000000000..89bf49d67aea --- /dev/null +++ b/modules/con-devhub-rbac-ownership-model.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-devhub-rbac-ownership-model_{context}"] += Ownership model + +[role="_abstract"] +The {prodname} {rhdh} plugin tracks ownership of `APIProduct` resources and uses ownership information to enforce `.own` scoped permissions. + +[id="con-devhub-rbac-ownership-tracking_{context}"] +== Ownership tracking + +`APIProduct` resources track ownership by using a standard annotation: + +[source,yaml] +---- +metadata: + annotations: + backstage.io/owner: "user:default/jmadigan" +---- + +The owner reference uses the entity reference format: `__:__/__`. + +The ownership annotation is set when the resource is created and cannot be modified. This prevents ownership hijacking and maintains clear accountability. Kubernetes automatically sets `metadata.creationTimestamp` for audit purposes. + +[id="con-devhub-rbac-backend-enforcement_{context}"] +== Backend enforcement + +All sensitive endpoints use tiered permission checks. The backend first checks if the user has the `.all` permission, which grants administrator-level access to any resource. If the user does not have the `.all` permission, the backend checks the `.own` permission and verifies that the user owns the resource. If neither permission check passes, the backend denies access. + +[id="con-devhub-rbac-list-filtering_{context}"] +== List endpoint filtering + +List endpoints return different results based on the user's permissions. A user with the `.read.all` permission sees all resources. A user with the `.read.own` permission sees only resources that they own. A user without either permission is denied access. diff --git a/modules/con-devhub-rbac-security.adoc b/modules/con-devhub-rbac-security.adoc new file mode 100644 index 000000000000..4e4b762c9aab --- /dev/null +++ b/modules/con-devhub-rbac-security.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-devhub-rbac-security_{context}"] += Security considerations + +[role="_abstract"] +The {prodname} {rhdh} plugin enforces several security measures to protect API resources and user data. + +[id="con-devhub-rbac-input-validation_{context}"] +== Input validation + +All mutating endpoints validate request bodies against explicit schemas with field-level allowlists. Only permitted fields are accepted, and any unrecognized fields are rejected. This prevents users from modifying fields that they are not authorized to change. + +[id="con-devhub-rbac-ownership-immutability_{context}"] +== Ownership immutability + +PATCH endpoints explicitly prevent modification of the ownership annotation. If a request body includes a change to the `backstage.io/owner` annotation, the backend removes that change before processing the request. This prevents ownership hijacking. + +[id="con-devhub-rbac-authentication-required_{context}"] +== Authentication requirement + +All endpoints require valid authentication. The plugin does not support guest access or anonymous requests. If a request does not include valid credentials, the backend denies access. diff --git a/modules/con-devhub-rbac-two-layer-model.adoc b/modules/con-devhub-rbac-two-layer-model.adoc new file mode 100644 index 000000000000..c9d0401f2d38 --- /dev/null +++ b/modules/con-devhub-rbac-two-layer-model.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: CONCEPT +[id="con-devhub-rbac-two-layer-model_{context}"] += Two-layer RBAC model + +[role="_abstract"] +The {prodname} {rhdh} plugin uses two separate RBAC layers with clear separation and no overlap. + +Layer 1: {rhdh} RBAC (portal access control):: +Controls who can interact with API management through the {rhdh} UI. This layer governs catalog visibility, which determines who can see API entities. It also governs request creation, which determines who can request API keys. Approval permissions control who can approve or reject requests. Management permissions control who can create and delete `APIProduct` resources. + +Layer 2: {prodname} and gateway RBAC (runtime access control):: +Controls how APIs behave at runtime. API key validation through `AuthPolicy` resources determines whether a key is valid. Rate limiting through `PlanPolicy` predicate checks determines what limits apply. Authentication through `AuthPolicy` resources determines whether a request has valid credentials. + +The two layers do not overlap. The {rhdh} layer controls who gets API keys, while the {prodname} and gateway layer enforces runtime limits. diff --git a/modules/ref-devhub-rbac-configuration.adoc b/modules/ref-devhub-rbac-configuration.adoc new file mode 100644 index 000000000000..469d683bb1db --- /dev/null +++ b/modules/ref-devhub-rbac-configuration.adoc @@ -0,0 +1,31 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-devhub-rbac-configuration_{context}"] += RBAC configuration + +[role="_abstract"] +Configure RBAC for the {prodname} {rhdh} plugin by using a policy file and the application configuration. + +[id="ref-devhub-rbac-policy-file_{context}"] +== Policy file location + +The RBAC policy file is `rbac-policy.csv`, located at the repository root. + +[id="ref-devhub-rbac-app-config_{context}"] +== Application configuration + +Enable RBAC and configure the policy file in your `app-config` file: + +[source,yaml] +---- +permission: + enabled: true + rbac: + policies-csv-file: ./rbac-policy.csv + policyFileReload: true +---- + +Setting `policyFileReload` to `true` enables automatic reloading of the policy file when you make changes. diff --git a/modules/ref-devhub-rbac-frontend-permissions.adoc b/modules/ref-devhub-rbac-frontend-permissions.adoc new file mode 100644 index 000000000000..61822a2eb9c5 --- /dev/null +++ b/modules/ref-devhub-rbac-frontend-permissions.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-devhub-rbac-frontend-permissions_{context}"] += Frontend permission checks + +[role="_abstract"] +The {prodname} {rhdh} plugin uses permission checks in the frontend to control UI visibility and available actions. + +The plugin uses the `useKuadrantPermission` hook to check whether the current user has a specific permission. If the user does not have the required permission, the corresponding UI element is hidden. For example, the *Create API Product* button is visible only to users with the `kuadrant.apiproduct.create` permission. + +For ownership-aware actions, the plugin checks both the user's permissions and the resource ownership. A *Delete* button is visible only if the user has either the `.delete.all` permission or the `.delete.own` permission and owns the resource. + +[IMPORTANT] +==== +Frontend permission checks are for user experience only. The backend enforces permissions independently and does not rely on frontend checks. Hiding a button in the UI does not prevent access to the underlying API endpoint. +==== diff --git a/modules/ref-devhub-rbac-per-apiproduct-access.adoc b/modules/ref-devhub-rbac-per-apiproduct-access.adoc new file mode 100644 index 000000000000..ce9571f99a65 --- /dev/null +++ b/modules/ref-devhub-rbac-per-apiproduct-access.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-devhub-rbac-per-apiproduct-access_{context}"] += Per-APIProduct access control + +[role="_abstract"] +The `kuadrant.apikey.create` permission supports resource references for fine-grained control over which API products a user can request access to. Use resource references in your RBAC policy to restrict API access by namespace or by specific API product. + +The following examples show RBAC policy entries that control per-product access: + +[source,csv] +---- +# Allow all consumers to request any API +p, role:default/api-consumer, kuadrant.apikey.create, create, allow, apiproduct:*/* + +# Restrict specific APIs to specific roles +p, role:default/partner, kuadrant.apikey.create, create, allow, apiproduct:toystore/toystore-api +p, role:default/internal, kuadrant.apikey.create, create, allow, apiproduct:internal/* +---- + +The backend validates the resource reference when processing a request. It checks the permission against the specific `APIProduct` namespace and name, formatted as `apiproduct:__/__`. diff --git a/modules/ref-devhub-rbac-permission-list.adoc b/modules/ref-devhub-rbac-permission-list.adoc new file mode 100644 index 000000000000..1741b50397bf --- /dev/null +++ b/modules/ref-devhub-rbac-permission-list.adoc @@ -0,0 +1,151 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-devhub-rbac-permission-list_{context}"] += Complete permission list + +[role="_abstract"] +The following tables list all permissions available in the {prodname} {rhdh} plugin, organized by resource type. + +[id="ref-devhub-rbac-planpolicy-permissions_{context}"] +== PlanPolicy permissions + +.PlanPolicy permissions +[cols="2,3,2",options="header"] +|=== +|Permission |Description |Notes + +|`kuadrant.planpolicy.create` +|Creates plan policies. +|Not exposed through the plugin. Managed on the cluster. + +|`kuadrant.planpolicy.read` +|Reads plan policy details. +| + +|`kuadrant.planpolicy.update` +|Updates plan policies. +|Not exposed through the plugin. + +|`kuadrant.planpolicy.delete` +|Deletes plan policies. +|Not exposed through the plugin. + +|`kuadrant.planpolicy.list` +|Lists plan policies. +| +|=== + +[id="ref-devhub-rbac-apiproduct-permissions_{context}"] +== APIProduct permissions + +.APIProduct permissions +[cols="2,3,1",options="header"] +|=== +|Permission |Description |Scope + +|`kuadrant.apiproduct.create` +|Creates API products. +|- + +|`kuadrant.apiproduct.read.own` +|Reads your own API products. +|Own + +|`kuadrant.apiproduct.read.all` +|Reads any API product. +|All + +|`kuadrant.apiproduct.update.own` +|Updates your own API products. +|Own + +|`kuadrant.apiproduct.update.all` +|Updates any API product. +|All + +|`kuadrant.apiproduct.delete.own` +|Deletes your own API products. +|Own + +|`kuadrant.apiproduct.delete.all` +|Deletes any API product. +|All + +|`kuadrant.apiproduct.list` +|Lists API products. Results are filtered by read permissions. +|- +|=== + +[id="ref-devhub-rbac-apikey-permissions_{context}"] +== APIKey permissions + +.APIKey permissions +[cols="2,3,1",options="header"] +|=== +|Permission |Description |Scope + +|`kuadrant.apikey.create` +|Requests API access. +|Resource (`APIProduct`) + +|`kuadrant.apikey.read.own` +|Reads requests that you created. +|Own + +|`kuadrant.apikey.read.all` +|Reads any request. +|All + +|`kuadrant.apikey.update.own` +|Edits your own pending requests. +|Own + +|`kuadrant.apikey.update.all` +|Updates any request. +|All + +|`kuadrant.apikey.delete.own` +|Deletes your own requests. +|Own + +|`kuadrant.apikey.delete.all` +|Deletes any request. +|All + +|`kuadrant.apikey.approve` +|Accesses the approval queue and approves or rejects requests. +|- + +|`kuadrant.apikey.list` +|Lists requests. Results are filtered by read permissions. +|- +|=== + +[id="ref-devhub-rbac-authpolicy-permissions_{context}"] +== AuthPolicy permissions + +.AuthPolicy permissions +[cols="2,3,2",options="header"] +|=== +|Permission |Description |Notes + +|`kuadrant.authpolicy.list` +|Lists `AuthPolicy` resources. +|Read-only access for API administrators and owners. +|=== + +[id="ref-devhub-rbac-ratelimitpolicy-permissions_{context}"] +== RateLimitPolicy permissions + +.RateLimitPolicy permissions +[cols="2,3,2",options="header"] +|=== +|Permission |Description |Notes + +|`kuadrant.ratelimitpolicy.list` +|Lists `RateLimitPolicy` resources. +|Read-only access for API administrators and owners. +|=== diff --git a/modules/ref-devhub-rbac-permission-structure.adoc b/modules/ref-devhub-rbac-permission-structure.adoc new file mode 100644 index 000000000000..a2a06d7928b3 --- /dev/null +++ b/modules/ref-devhub-rbac-permission-structure.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-devhub-rbac-permission-structure_{context}"] += Permission naming conventions and types + +[role="_abstract"] +Permissions for the {prodname} {rhdh} plugin follow a consistent naming pattern and are organized into distinct types. + +[id="ref-devhub-rbac-naming-convention_{context}"] +== Naming convention + +Permissions follow the pattern `kuadrant.__.__[.__]`, where: + +`__`:: The target resource type. Accepted values are `planpolicy`, `apiproduct`, and `apikey`. +`__`:: The operation to perform. Accepted values are `create`, `read`, `update`, `delete`, and `list`. +`__`:: An optional ownership scope. Use `own` for the user's resources or `all` for any resource. Omit the scope for permissions that are not tied to ownership. + +[id="ref-devhub-rbac-permission-types_{context}"] +== Permission types + +Basic permissions:: Permissions without an ownership scope that apply globally. For example, `kuadrant.planpolicy.create`, `kuadrant.planpolicy.read`, and `kuadrant.planpolicy.list`. + +Scoped permissions:: Ownership-aware permissions that differentiate between a user's own resources and all resources. For example, `kuadrant.apiproduct.read.own` grants access to read your own API products, while `kuadrant.apiproduct.read.all` grants access to read any API product. + +Resource permissions:: Permissions that include resource references for fine-grained control over specific resources. For example, `kuadrant.apikey.create` can include a resource reference such as `apiproduct:__/__` to restrict which API products a user can request access to. diff --git a/modules/ref-devhub-rbac-permissions-matrix.adoc b/modules/ref-devhub-rbac-permissions-matrix.adoc new file mode 100644 index 000000000000..a616464bb2ba --- /dev/null +++ b/modules/ref-devhub-rbac-permissions-matrix.adoc @@ -0,0 +1,81 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-devhub-rbac-permissions-matrix_{context}"] += RBAC permissions matrix + +[role="_abstract"] +Use the following matrix to understand what each persona can and cannot do in the {prodname} {rhdh} plugin. + +.Permissions matrix by persona +[cols="1,2,2",options="header"] +|=== +|Persona |Can do |Cannot do + +|Platform engineer +|Manage {prodname} infrastructure, including `Gateway` and `HTTPRoute` resources. Create, update, and delete `PlanPolicy` resources. Manage RBAC policies and permissions. Configure platform-wide settings. Full cluster administrator access for platform management. +|Typically does not manage day-to-day API products. Delegates that responsibility to API administrators and API owners. Coordinates with API administrators and API owners before changing rate limits. + +|API administrator +|Read all API products. Create, update, and delete any API product. Approve or reject any API key request. Manage all API keys, including read and delete operations. View all API keys. Troubleshoot on behalf of API owners. All `.all` scoped permissions. +|Cannot create, update, or delete `PlanPolicy` resources. Cannot modify platform infrastructure, including `HTTPRoute` and `Gateway` resources. + +|API owner +|Read and list `HTTPRoute` resources for publishing APIs. Create, update, and delete own API products. Read all API products. Approve or reject API key requests for own APIs. Delete API key requests for own APIs. Manage own API documentation. View and manage API keys for own APIs. +|Cannot create or update `PlanPolicy` resources. Cannot modify platform infrastructure. Cannot approve requests for other owners' APIs. Cannot update or delete other owners' API products. + +|API consumer +|Read and list API products. Create API keys. Read, update, and delete own API keys. View own request status. Manage own API keys. Use APIs within rate limit quotas. +|Cannot approve requests. Cannot view others' requests. Cannot create or publish APIs. Cannot modify rate limits. +|=== + +[id="ref-devhub-rbac-permissions-by-resource_{context}"] +== Permission breakdown by resource + +`PlanPolicy` (rate limit tiers):: +* Platform engineer: create, read, update, delete +* API administrator: read, list +* API owner: read, list +* API consumer: none + +`HTTPRoute`:: +* Platform engineer: create, read, update, delete, annotate +* API administrator: read, list +* API owner: read, list (to select for publishing) +* API consumer: none (indirect read through `APIProduct`) + +`APIProduct` (catalog entries):: +* Platform engineer: typically none (delegated to API administrators and owners) +* API administrator: create, read, update, delete (all) +* API owner: create, read (all), update (own), delete (own) +* API consumer: read, list + +`APIKey` (access requests):: +* Platform engineer: typically none (delegated to API administrators) +* API administrator: create, read (all), update (all), delete (all), approve +* API owner: create, read (own), update (own), delete (own), approve (for own APIs) +* API consumer: create, read (own), update (own, edit pending), delete (own) + +`AuthPolicy` (authentication rules):: +* Platform engineer: create, read, update, delete +* API administrator: list +* API owner: list +* API consumer: none + +`RateLimitPolicy` (rate limiting rules):: +* Platform engineer: create, read, update, delete +* API administrator: list +* API owner: list +* API consumer: none + +[id="ref-devhub-rbac-role-hierarchy_{context}"] +== Role hierarchy + +The four personas form a clear hierarchy, where each layer builds on the capabilities of the layer below it: + +. *Platform engineer* - infrastructure layer, including cluster, gateways, and rate limits +. *API administrator* - management layer, including all API products and all requests +. *API owner* - ownership layer, including own API products and own API requests +. *API consumer* - consumption layer, including browse, request, and use diff --git a/modules/ref-devhub-rbac-role-definitions.adoc b/modules/ref-devhub-rbac-role-definitions.adoc new file mode 100644 index 000000000000..79d41678447e --- /dev/null +++ b/modules/ref-devhub-rbac-role-definitions.adoc @@ -0,0 +1,78 @@ +// Module included in the following assemblies: +// +// * develop/devhub-plugin-rbac.adoc + +:_mod-docs-content-type: REFERENCE +[id="ref-devhub-rbac-role-definitions_{context}"] += Role definitions + +[role="_abstract"] +The {prodname} {rhdh} plugin defines four personas with distinct responsibilities and permissions. + +[id="ref-devhub-rbac-api-consumer_{context}"] +== API consumer + +API consumers are end users who consume APIs. An API consumer has the following permissions: + +* `kuadrant.apiproduct.read.all` - Browse the API catalog +* `kuadrant.apiproduct.list` - List API products +* `kuadrant.apikey.create` - Request API access +* `kuadrant.apikey.read.own` - View own requests and API keys +* `kuadrant.apikey.update.own` - Edit own pending requests +* `kuadrant.apikey.delete.own` - Cancel own requests or revoke own API keys + +An API consumer cannot create or manage API products, approve or reject requests, or view other users' API keys. + +[id="ref-devhub-rbac-api-owner_{context}"] +== API owner + +API owners publish and manage their own APIs. An API owner has all API consumer permissions, plus the following: + +* `kuadrant.planpolicy.read` - View plan policies for reference +* `kuadrant.planpolicy.list` - List plan policies +* `kuadrant.apiproduct.create` - Create API products +* `kuadrant.apiproduct.read.own` - View own API products +* `kuadrant.apiproduct.update.own` - Update own API products +* `kuadrant.apiproduct.delete.own` - Delete own API products +* `kuadrant.apikey.approve` - Access the approval queue and approve or reject requests for own APIs +* `kuadrant.apikey.read.own` - View API keys for own APIs +* `kuadrant.apikey.delete.own` - Delete API keys for own APIs + +An API owner cannot view or modify other owners' API products, create or delete `PlanPolicy` resources, or approve requests for other owners' APIs. + +[id="ref-devhub-rbac-api-admin_{context}"] +== API administrator + +API administrators are platform engineers who manage all API products. An API administrator has the following responsibilities: + +* Managing all API products across the platform +* Approving or rejecting any API key request across teams +* Troubleshooting issues on behalf of API owners +* Providing second-level support for API management + +An API administrator has all `.all` scoped permissions, including: + +* `kuadrant.apiproduct.create` - Create any API product +* `kuadrant.apiproduct.read.all` - View all API products +* `kuadrant.apiproduct.update.all` - Update any API product +* `kuadrant.apiproduct.delete.all` - Delete any API product +* `kuadrant.apikey.read.all` - View all requests +* `kuadrant.apikey.update.all` - Update any request +* `kuadrant.apikey.approve` - Access the approval queue and approve or reject any request +* `kuadrant.apikey.delete.all` - Delete any request or API key +* RBAC policy management permissions + +An API administrator cannot create, update, or delete `PlanPolicy`, `AuthPolicy`, or `RateLimitPolicy` resources, which are managed on the cluster. An API administrator also cannot modify platform infrastructure such as `HTTPRoute` and `Gateway` resources. + +[id="ref-devhub-rbac-platform-engineer_{context}"] +== Platform engineer + +Platform engineers manage the {prodname} platform infrastructure. A platform engineer has the following responsibilities: + +* Managing cluster infrastructure, including `Gateway`, `HTTPRoute`, and `PlanPolicy` resources +* Creating `PlanPolicy` resources with rate limit tiers +* Coordinating with API administrators and API owners when changing rate limits + +A platform engineer has full cluster administrator access through Kubernetes RBAC, including the ability to create, read, update, and delete `PlanPolicy`, `HTTPRoute`, and `Gateway` resources, and to manage RBAC policies. + +A platform engineer typically does not manage day-to-day API products, delegating that responsibility to API administrators and API owners.