RHIDP-3975 Managing authorization using the REST API

themr0c · themr0c · commit 335c02225117 · 2024-11-07T13:50:14.000+01:00
Signed-off-by: Fabrice Flore-Thébault &lt;ffloreth@redhat.com&gt;
diff --git a/assemblies/assembly-configuring-authorization-in-rhdh-by-using-the-rest-api.adoc b/assemblies/assembly-configuring-authorization-in-rhdh-by-using-the-rest-api.adoc
@@ -0,0 +1,27 @@
+[id='configuring-authorization-in-rhdh']
+= Configuring authorization in {product} by using the REST API
+
+To automate the maintenance of {product} permission policies and roles, you can use {product-short} role-based access control (RBAC) REST API.
+
+You can perform the following actions with the REST API:
+
+* Retrieve information about:
+** All permission policies
+** Specific permission policies
+** Specific roles
+** Static plugins permission policies
+* Create, update, or delete:
+** Permission policy
+** Role
+
+
+include::modules/authorization/proc-sending-request-to-the-rbac-rest-api-by-using-curl.adoc[leveloffset=+1]
+
+
+include::modules/authorization/proc-sending-request-to-the-rbac-rest-api-by-using-a-rest-client.adoc[leveloffset=+1]
+
+
+include::modules/authorization/ref-rbac-rest-api-endpoints.adoc[leveloffset=+1]
+
+
+include::modules/authorization/con-permission-policy-and-role-source.adoc[leveloffset=+1]
diff --git a/assemblies/assembly-configuring-authorization-in-rhdh.adoc b/assemblies/assembly-configuring-authorization-in-rhdh.adoc
@@ -62,7 +62,7 @@ include::modules/authorization/con-user-stats-rhdh.adoc[leveloffset=+1]
 include::modules/authorization/proc-download-user-stats-rhdh.adoc[leveloffset=+2]
 
 
-include::modules/authorization/con-rbac-rest-api.adoc[leveloffset=+1]
+include::modules/authorization/con-permission-policy-and-role-source.adoc[leveloffset=+1]
 
 
 include::modules/authorization/proc-rbac-send-request-rbac-rest-api.adoc[leveloffset=+2]
diff --git a/modules/authorization/con-permission-policy-and-role-source.adoc b/modules/authorization/con-permission-policy-and-role-source.adoc
@@ -0,0 +1,26 @@
+[id='con-permission-policy-and-role-source']
+= Permission policy and role source
+
+Each permission policy and role created using the RBAC plugin is associated with a source to maintain data consistency within the plugin.
+You can manipulate permission policies and roles based on the following designated source information:
+
+* CSV file
+* Configuration file
+* REST API
+* Legacy
+
+Managing roles and permission policies originating from CSV files and REST API involves straightforward modification based on their initial source information.
+
+The Configuration file pertains to the default `role:default/rbac_admin` role provided by the RBAC plugin.
+The default role has limited permissions to create, read, update, and delete permission policies or roles, and to read catalog entities.
+
+[NOTE]
+====
+In case the default permissions are insufficient for your administrative requirements, you can create a custom admin role with required permission policies.
+====
+
+The legacy source applies to policies and roles defined before RBAC backend plugin version `2.1.3`, and is the least restrictive among the source location options.
+You must update the permissions and roles in legacy source to use either REST API or the CSV file sources.
+
+You can use the `GET` requests to query roles and policies and determine the source information, if required.
+
diff --git a/modules/authorization/con-rbac-rest-api.adoc b/modules/authorization/con-rbac-rest-api.adoc
diff --git a/modules/authorization/proc-enabling-the-rbac-plugin.adoc b/modules/authorization/proc-enabling-the-rbac-plugin.adoc
@@ -1,4 +1,4 @@
-[id='enabling-and-giving-access-to-rbac']
+[id='from the web console in a browser.]
 = Enabling and giving access to the Role-Based Access Control (RBAC) feature
 
 The Role-Based Access Control (RBAC) feature is disabled by default.
diff --git a/modules/authorization/proc-rbac-send-request-rbac-rest-api.adoc b/modules/authorization/proc-rbac-send-request-rbac-rest-api.adoc
diff --git a/modules/authorization/proc-sending-request-to-the-rbac-rest-api-by-using-a-rest-client.adoc b/modules/authorization/proc-sending-request-to-the-rbac-rest-api-by-using-a-rest-client.adoc
@@ -0,0 +1,33 @@
+[id='proc-rbac-sending-requests-to-the-rbac-rest-api-by-using-a-rest-client_{context}']
+= Sending requests to the RBAC REST API by using a REST client
+
+You can send RBAC REST API requests using any REST client.
+
+.Prerequisites
+* xref:enabling-and-giving-access-to-rbac[You have access to the RBAC feature].
+
+.Procedure
+include::snip-finding-bearer-token.adoc[]
+
+. In your REST client, run a command with the following parameters and review the response:
++
+--
+Authorization::
+Enter your saved authorization token.
+
+HTTP method::
+Enter the HTTP method for your xref:ref-rbac-rest-api-endpoints_{context}[API endpoint].
+
+* `GET`: To retrieve specified information from a specified resource endpoint.
+* `POST`: To create or update a resource.
+* `PUT`: To update a resource.
+* `DELETE`: To delete a resource.
+
+URL::
+Enter your {product-short} URL and xref:ref-rbac-rest-api-endpoints_{context}[API endpoint]: pass:c,a,q[{my-product-url}/__<endpoint>__], such as
+`pass:c,a,q[{my-product-url}/api/permission/policies]`.
+
+Body::
+Enter the JSON body with data that your xref:ref-rbac-rest-api-endpoints_{context}[API endpoint] might need with the HTTP `POST` request.
+--
+
diff --git a/modules/authorization/proc-sending-request-to-the-rbac-rest-api-by-using-curl.adoc b/modules/authorization/proc-sending-request-to-the-rbac-rest-api-by-using-curl.adoc
@@ -0,0 +1,113 @@
+[id='proc-sending-requests-to-the-rbac-rest-api-by-using-curl_{context}']
+= Sending requests to the RBAC REST API by using the curl utility
+
+You can send RBAC REST API requests by using the curl utility.
+
+.Prerequisites
+* xref:enabling-and-giving-access-to-rbac[You have access to the RBAC feature].
+
+.Procedure
+include::snip-finding-bearer-token.adoc[]
+
+. In a terminal, run the curl command and review the response:
++
+--
+.Default request
+[source,subs="+attributes,+quotes"]
+----
+curl -v -H "Content-Type: application/json" \
+  -H "Authorization: Bearer _<token>_" \
+  -X __<method>__ "{my-product-url}/__<endpoint>__" \
+----
+
+.POST request requiring JSON body data
+[source,subs="+attributes,+quotes"]
+----
+curl -v -H "Content-Type: application/json" \
+  -H "Authorization: Bearer _<token>_" \
+  -X POST "{my-product-url}/__<endpoint>__" \
+  -d __<body>__
+----
+
+__<token>__::
+Enter your saved authorization token.
+
+__<method>__::
+Enter the HTTP method for your xref:ref-rbac-rest-api-endpoints_{context}[API endpoint].
+
+* `GET`: To retrieve specified information from a specified resource endpoint.
+* `POST`: To create or update a resource.
+* `PUT`: To update a resource.
+* `DELETE`: To delete a resource.
+
+pass:c,a,q[{my-product-url}]::
+Enter your {product-short} URL.
+
+__<endpoint>__::
+Enter the xref:ref-rbac-rest-api-endpoints_{context}[API endpoint] to which you want to send a request, such as `/api/permission/policies`.
+
+__<body>__::
+Enter the JSON body with data that your xref:ref-rbac-rest-api-endpoints_{context}[API endpoint] might need with the HTTP `POST` request.
+
+.Example request to create or update a role
+[source,subs="+attributes,+quotes"]
+----
+curl -v -H "Content-Type: application/json" \
+  -H "Authorization: Bearer _<token>_" \
+  -X POST "{my-product-url}/api/permission/roles" \
+  -d '{
+      "memberReferences": ["group:default/example"],
+      "name": "role:default/test",
+      "metadata": { "description": "This is a test role" }
+    }'
+----
+
+.Example request to create or update a permission policy
+[source,subs="+attributes,+quotes"]
+----
+curl -v -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $token" \
+  -X POST "{my-product-url}/api/permission/policies" \
+  -d '[{
+      "entityReference":"role:default/test",
+      "permission": "catalog-entity",
+      "policy": "read", "effect":"allow"
+    }]'
+----
+
+.Example request to create or update a condition
+[source,subs="+attributes,+quotes"]
+----
+
+curl -v -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $token" \
+  -X POST "{my-product-url}/api/permission/roles/conditions"\
+  -d '{
+      "result": "CONDITIONAL",
+      "roleEntityRef": "role:default/test",
+      "pluginId": "catalog",
+      "resourceType": "catalog-entity",
+      "permissionMapping": ["read"],
+      "conditions": {
+        "rule": "IS_ENTITY_OWNER",
+        "resourceType": "catalog-entity",
+        "params": {"claims": ["group:default/janus-authors"]}
+      }
+    }'
+----
+
+--
+
+.Verification
+* Review the returned HTTP status code:
++
+--
+`200` OK:: The request was successful.
+`201` Created:: The request resulted in a new resource being successfully created.
+`204` No Content:: The request was successful, and the response payload has no more content.
+`400` Bad Request:: Input error with the request.
+`401` Unauthorized:: Lacks valid authentication for the requested resource.
+`403` Forbidden:: Refusal to authorize request.
+`404` Not Found:: Could not find requested resource.
+`409` Conflict:: Request conflict with the current state and the target resource.
+--
diff --git a/modules/authorization/snip-finding-bearer-token.adoc b/modules/authorization/snip-finding-bearer-token.adoc
@@ -0,0 +1,5 @@
+. Find your Bearer token to authenticate to the REST API.
+.. In your browser, open the web console *Network* tab.
+.. In the main screen, reload the {product-short} *Homepage*.
+.. In the web console *Network* tab, search for the `query?term=` network call.
+.. Save the *token* in the response JSON for the next steps.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-[id='enabling-and-giving-access-to-rbac']`
	`1`	`+[id='from the web console in a browser.]`
`2`	`2`	`= Enabling and giving access to the Role-Based Access Control (RBAC) feature`
`3`	`3`
`4`	`4`	`The Role-Based Access Control (RBAC) feature is disabled by default.`