diff --git a/assemblies/assembly-configuring-authorization-in-rhdh.adoc b/assemblies/assembly-configuring-authorization-in-rhdh.adoc index e383912234..573e48d07a 100644 --- a/assemblies/assembly-configuring-authorization-in-rhdh.adoc +++ b/assemblies/assembly-configuring-authorization-in-rhdh.adoc @@ -33,6 +33,9 @@ include::modules/authorization/proc-enabling-the-rbac-plugin.adoc[leveloffset=+1 include::assembly-managing-authorizations-by-using-the-rhdh-web-ui.adoc[leveloffset=+1] +include::assembly-managing-authorizations-by-using-the-rest-api.adoc[leveloffset=+1] + + include::modules/authorization/ref-rbac-permission-policies.adoc[leveloffset=+1] @@ -55,17 +58,8 @@ include::modules/authorization/ref-rbac-conditional-policy-definition.adoc[level include::modules/authorization/proc-rbac-config-conditional-policy-file.adoc[leveloffset=+2] - 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/proc-rbac-send-request-rbac-rest-api.adoc[leveloffset=+2] - - -include::modules/authorization/ref-rbac-rest-api-endpoints.adoc[leveloffset=+2] diff --git a/assemblies/assembly-managing-authorizations-by-using-the-rest-api.adoc b/assemblies/assembly-managing-authorizations-by-using-the-rest-api.adoc new file mode 100644 index 0000000000..b83e28a5c1 --- /dev/null +++ b/assemblies/assembly-managing-authorizations-by-using-the-rest-api.adoc @@ -0,0 +1,25 @@ +[id='managing-authorizations-by-using-the-rest-api'] += Managing authorizations 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] + diff --git a/modules/authorization/con-rbac-rest-api.adoc b/modules/authorization/con-rbac-rest-api.adoc deleted file mode 100644 index ea956895bc..0000000000 --- a/modules/authorization/con-rbac-rest-api.adoc +++ /dev/null @@ -1,119 +0,0 @@ -[id='con-rbac-rest-api_{context}'] -= Role-based Access Control (RBAC) REST API - -{product} provides RBAC REST API that you can use to manage the permissions and roles in the {product-short}. This API supports you to facilitate and automate the maintenance of {product-short} permission policies and roles. - -Using the RBAC REST API, you can perform the following actions: - -* Retrieve information about all permission policies or specific permission policies, or roles -* Create, update, or delete a permission policy or a role -* Retrieve permission policy information about static plugins - -The RBAC REST API requires the following components: - -Authorization:: -+ --- - -The RBAC REST API requires Bearer token authorization for the permitted user role. For development purposes, you can access a web console in a browser. When you refresh a token request in the list of network requests, you find the token in the response JSON. - -`Authorization: Bearer $token` - -For example, on the {product-short} *Homepage*, navigate to the *Network* tab and search for the `query?term=` network call. Alternatively, you can go to the *Catalog* page and select any Catalog API network call to acquire the Bearer token. --- - -HTTP methods:: -+ --- - -The RBAC REST API supports the following HTTP methods for API requests: - -* `GET`: Retrieves specified information from a specified resource endpoint -* `POST`: Creates or updates a resource -* `PUT`: Updates a resource -* `DELETE`: Deletes a resource --- - -Base URL:: -+ --- - -The base URL for RBAC REST API requests is `pass:c[http://SERVER:PORT/api/permission/policies]`, such as `pass:c[http://localhost:7007/api/permission/policies]`. - --- - -Endpoints:: -+ --- - -RBAC REST API endpoints, such as `/api/permission/policies/[kind]/[namespace]/[name]` for specified `kind`, `namespace`, and `name`, are the URI that you append to the base URL to access the corresponding resource. - -Example request URL for `/api/permission/policies/[kind]/[namespace]/[name]` endpoint is: - -`pass:c[http://localhost:7007/api/permission/policies/user/default/johndoe]` - -[NOTE] -==== -If at least one permission is assigned to `user:default/johndoe`, then the example request URL mentioned previously returns a result if sent in a `GET` response with a valid authorization token. However, if permission is only assigned to roles, then the example request URL does not return an output. -==== --- - -Request data:: -+ --- - -HTTP `POST` requests in the RBAC REST API may require a JSON request body with data to accompany the request. - -Example `POST` request URL and JSON request body data for -`pass:c[http://localhost:7007/api/permission/policies]`: - -[source,json] ----- -{ - "entityReference": "role:default/test", - "permission": "catalog-entity", - "policy": "delete", - "effect": "allow" -} ----- --- - -HTTP status codes:: -+ --- - -The RBAC REST API supports the following HTTP status codes to return as responses: - -* `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, but there is no additional content to send in the response payload. -* `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 --- - -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/proc-rbac-send-request-rbac-rest-api.adoc b/modules/authorization/proc-rbac-send-request-rbac-rest-api.adoc deleted file mode 100644 index 2721eb99d8..0000000000 --- a/modules/authorization/proc-rbac-send-request-rbac-rest-api.adoc +++ /dev/null @@ -1,53 +0,0 @@ -[id='proc-rbac-send-request-rbac-rest-api_{context}'] -= Sending requests with the RBAC REST API using a REST client or curl utility - -The RBAC REST API enables you to interact with the permission policies and roles in {product-short} without using the user interface. You can send RBAC REST API requests using any REST client or curl utility. - -.Prerequisites - -* {product} is installed and running. - -For more information about installing {product}, see link:{installing-on-ocp-book-url}#assembly-install-rhdh-ocp-helm[{installing-on-ocp-book-title} with the Helm chart]. - -* You have access to the {product-short}. - -.Procedure - -. Identify a relevant API endpoint to which you want to send a request, such as `POST /api/permission/policies`. Adjust any request details according to your use case. -+ --- -*For REST client*: - -* Authorization: Enter the generated token from the web console. -* HTTP method: Set to `POST`. -* URL: Enter the RBAC REST API base URL and endpoint such as -`pass:c[http://localhost:7007/api/permission/policies]`. - - -*For curl utility*: - -* `-X`: Set to `POST` -* `-H`: Set the following header: -+ -`Content-type: application/json` -+ -`Authorization: Bearer $token` -+ -`$token` is the requested token from the web console in a browser. - -* URL: Enter the following RBAC REST API base URL endpoint, such as `pass:c[http://localhost:7007/api/permission/policies]` -* `-d`: Add a request JSON body - -*Example requests*: - -`curl -X POST "http://localhost:7007/api/permission/roles" -d '{"memberReferences": ["group:default/example"], "name": "role:default/test", "metadata": { "description": "This is a test role" } }' -H "Content-Type: application/json" -H "Authorization: Bearer $token" -v` - -`curl -X POST "http://localhost:7007/api/permission/policies" -d '[{"entityReference":"role:default/test", "permission": "catalog-entity", "policy": "read", "effect":"allow"}]' -H "Content-Type: application/json" -H "Authorization: Bearer $token" -v` - -`curl -X POST "http://localhost:7007/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"]}}}' -H "Content-Type: application/json" -H "Authorization: Bearer $token" -v` - --- - -. Execute the request and review the response. - - 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 new file mode 100644 index 0000000000..b09b24fb58 --- /dev/null +++ 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}/____], 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 new file mode 100644 index 0000000000..b0b9933c09 --- /dev/null +++ b/modules/authorization/proc-sending-request-to-the-rbac-rest-api-by-using-curl.adoc @@ -0,0 +1,171 @@ +[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: ++ +-- +.`GET` or `DELETE` request +[source,subs="+attributes,+quotes"] +---- +curl -v \ + -H "Authorization: Bearer __" \ + -X ____ "{my-product-url}/____" \ +---- + +.`POST` or `PUT` request requiring JSON body data +[source,subs="+attributes,+quotes"] +---- +curl -v -H "Content-Type: application/json" \ + -H "Authorization: Bearer __" \ + -X POST "{my-product-url}/____" \ + -d ____ +---- + +____:: +Enter your saved authorization token. + +____:: +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. + +____:: +Enter the xref:ref-rbac-rest-api-endpoints_{context}[API endpoint] to which you want to send a request, such as `/api/permission/policies`. + +____:: +Enter the JSON body with data that your xref:ref-rbac-rest-api-endpoints_{context}[API endpoint] might need with the HTTP `POST` or `PUT` request. + +.Example request to create a role +[source,subs="+attributes,+quotes"] +---- +curl -v -H "Content-Type: application/json" \ + -H "Authorization: Bearer __" \ + -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 update a role +[source,subs="+attributes,+quotes"] +---- +curl -v -H "Content-Type: application/json" \ + -H "Authorization: Bearer __" \ + -X PUT "{my-product-url}/api/permission/roles/role/default/test" \ + -d '{ + "oldRole": { + "memberReferences": [ "group:default/example" ], + "name": "role:default/test" + }, + "newRole": { + "memberReferences": [ "group:default/example", "user:default/test" ], + "name": "role:default/test" + } + }' +---- + +.Example request to create 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 update a permission policy +[source,subs="+attributes,+quotes"] +---- +curl -v -H "Content-Type: application/json" \ + -H "Authorization: Bearer $token" \ + -X PUT "{my-product-url}/api/permission/policies/role/default/test" \ + -d '{ + "oldPolicy": [ + { + "permission": "catalog-entity", "policy": "read", "effect": "allow" + } + ], + "newPolicy": + [ + { + "permission": "policy-entity", "policy": "read", "effect": "allow" + } + ] + }' +---- + +.Example request to create 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"]} + } + }' +---- + +.Example request to update a condition +[source,subs="+attributes,+quotes"] +---- +curl -v -H "Content-Type: application/json" \ + -H "Authorization: Bearer $token" \ + -X PUT "{my-product-url}/api/permission/roles/conditions/1" \ + -d '{ + "result":"CONDITIONAL", + "roleEntityRef":"role:default/test", + "pluginId":"catalog", + "resourceType":"catalog-entity", + "permissionMapping": ["read", "update", "delete"], + "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 new file mode 100644 index 0000000000..617fa8a8f7 --- /dev/null +++ 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.