Chapter 5. Role-based Access Control (RBAC) REST API
Chapter 5. Role-based Access Control (RBAC) REST API Red Hat Developer Hub provides RBAC REST API that you can use to manage the permissions and roles in the Developer Hub. This API supports you to facilitate and automate the maintenance of Developer Hub 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 USDtoken For example, on the Developer Hub 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 http://SERVER:PORT/api/permission/policies , such as 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: 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 http://localhost:7007/api/permission/policies : { "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. 5.1. 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 Developer Hub without using the user interface. You can send RBAC REST API requests using any REST client or curl utility. Prerequisites Red Hat Developer Hub is installed and running. For more information about installing Red Hat Developer Hub, see Installing Red Hat Developer Hub on OpenShift Container Platform with the Helm chart . You have access to the Developer Hub. 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 http://localhost:7007/api/permission/policies . For curl utility : -X : Set to POST -H : Set the following header: Content-type: application/json Authorization: Bearer USDtoken USDtoken is the requested token from the web console in a browser. URL: Enter the following RBAC REST API base URL endpoint, such as 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 USDtoken" -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 USDtoken" -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 USDtoken" -v Execute the request and review the response. 5.2. Supported RBAC REST API endpoints The RBAC REST API provides endpoints for managing roles, permissions, and conditional policies in the Developer Hub and for retrieving information about the roles and policies. 5.2.1. Roles The RBAC REST API supports the following endpoints for managing roles in the Red Hat Developer Hub. [GET] /api/permission/roles Returns all roles in Developer Hub. Example response (JSON) [ { "memberReferences": ["user:default/username"], "name": "role:default/guests" }, { "memberReferences": [ "group:default/groupname", "user:default/username" ], "name": "role:default/rbac_admin" } ] [GET] /api/permission/roles/{kind}/{namespace}/{name} Returns information for a single role in Developer Hub. Example response (JSON) [ { "memberReferences": [ "group:default/groupname", "user:default/username" ], "name": "role:default/rbac_admin" } ] [POST] /api/permission/roles/{kind}/{namespace}/{name} Creates a role in Developer Hub. Table 5.1. Request parameters Name Description Type Presence body The memberReferences , group , namespace , and name the new role to be created. Request body Required Example request body (JSON) { "memberReferences": ["group:default/test"], "name": "role:default/test_admin" } Example response [PUT] /api/permission/roles/{kind}/{namespace}/{name} Updates memberReferences , kind , namespace , or name for a role in Developer Hub. Request parameters The request body contains the oldRole and newRole objects: Name Description Type Presence body The memberReferences , group , namespace , and name the new role to be created. Request body Required Example request body (JSON) { "oldRole": { "memberReferences": ["group:default/test"], "name": "role:default/test_admin" }, "newRole": { "memberReferences": ["group:default/test", "user:default/test2"], "name": "role:default/test_admin" } } Example response [DELETE] /api/permission/roles/{kind}/{namespace}/{name}?memberReferences=<VALUE> Deletes the specified user or group from a role in Developer Hub. Table 5.2. Request parameters Name Description Type Presence kind Kind of the entity String Required namespace Namespace of the entity String Required name Name of the entity String Required memberReferences Associated group information String Required Example response [DELETE] /api/permission/roles/{kind}/{namespace}/{name} Deletes a specified role from Developer Hub. Table 5.3. Request parameters Name Description Type Presence kind Kind of the entity String Required namespace Namespace of the entity String Required name Name of the entity String Required Example response 5.2.2. Permission policies The RBAC REST API supports the following endpoints for managing permission policies in the Red Hat Developer Hub. [GET] /api/permission/policies Returns permission policies list for all users. Example response (JSON) [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "read", "effect": "allow", "metadata": { "source": "csv-file" } }, { "entityReference": "role:default/test", "permission": "catalog.entity.create", "policy": "use", "effect": "allow", "metadata": { "source": "csv-file" } }, ] [GET] /api/permission/policies/{kind}/{namespace}/{name} Returns permission policies related to the specified entity reference. Table 5.4. Request parameters Name Description Type Presence kind Kind of the entity String Required namespace Namespace of the entity String Required name Name related to the entity String Required Example response (JSON) [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "read", "effect": "allow", "metadata": { "source": "csv-file" } }, { "entityReference": "role:default/test", "permission": "catalog.entity.create", "policy": "use", "effect": "allow", "metadata": { "source": "csv-file" } } ] [POST] /api/permission/policies Creates a permission policy for a specified entity. Table 5.5. Request parameters Name Description Type Presence entityReference Reference values of an entity including kind , namespace , and name String Required permission Permission from a specific plugin, resource type, or name String Required policy Policy action for the permission, such as create , read , update , delete , or use String Required effect Indication of allowing or not allowing the policy String Required Example request body (JSON) [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "read", "effect": "allow" } ] Example response [PUT] /api/permission/policies/{kind}/{namespace}/{name} Updates a permission policy for a specified entity. Request parameters The request body contains the oldPolicy and newPolicy objects: Name Description Type Presence permission Permission from a specific plugin, resource type, or name String Required policy Policy action for the permission, such as create , read , update , delete , or use String Required effect Indication of allowing or not allowing the policy String Required Example request body (JSON) { "oldPolicy": [ { "permission": "catalog-entity", "policy": "read", "effect": "allow" }, { "permission": "catalog.entity.create", "policy": "create", "effect": "allow" } ], "newPolicy": [ { "permission": "catalog-entity", "policy": "read", "effect": "deny" }, { "permission": "policy-entity", "policy": "read", "effect": "allow" } ] } Example response [DELETE] /api/permission/policies/{kind}/{namespace}/{name}?permission={value1}&policy={value2}&effect={value3} Deletes a permission policy added to the specified entity. Table 5.6. Request parameters Name Description Type Presence kind Kind of the entity String Required namespace Namespace of the entity String Required name Name related to the entity String Required permission Permission from a specific plugin, resource type, or name String Required policy Policy action for the permission, such as create , read , update , delete , or use String Required effect Indication of allowing or not allowing the policy String Required Example response [DELETE] /api/permission/policies/{kind}/{namespace}/{name} Deletes all permission policies added to the specified entity. Table 5.7. Request parameters Name Description Type Presence kind Kind of the entity String Required namespace Namespace of the entity String Required name Name related to the entity String Required Example response [GET] /api/permission/plugins/policies Returns permission policies for all static plugins. Example response (JSON) [ { "pluginId": "catalog", "policies": [ { "isResourced": true, "permission": "catalog-entity", "policy": "read" }, { "isResourced": false, "permission": "catalog.entity.create", "policy": "create" }, { "isResourced": true, "permission": "catalog-entity", "policy": "delete" }, { "isResourced": true, "permission": "catalog-entity", "policy": "update" }, { "isResourced": false, "permission": "catalog.location.read", "policy": "read" }, { "isResourced": false, "permission": "catalog.location.create", "policy": "create" }, { "isResourced": false, "permission": "catalog.location.delete", "policy": "delete" } ] }, ... ] 5.2.3. Conditional policies The RBAC REST API supports the following endpoints for managing conditional policies in the Red Hat Developer Hub. [GET] /api/permission/plugins/condition-rules Returns available conditional rule parameter schemas for the available plugins that are enabled in Developer Hub. Example response (JSON) [ { "pluginId": "catalog", "rules": [ { "name": "HAS_ANNOTATION", "description": "Allow entities with the specified annotation", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "annotation": { "type": "string", "description": "Name of the annotation to match on" }, "value": { "type": "string", "description": "Value of the annotation to match on" } }, "required": [ "annotation" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "HAS_LABEL", "description": "Allow entities with the specified label", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "label": { "type": "string", "description": "Name of the label to match on" } }, "required": [ "label" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "HAS_METADATA", "description": "Allow entities with the specified metadata subfield", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "key": { "type": "string", "description": "Property within the entities metadata to match on" }, "value": { "type": "string", "description": "Value of the given property to match on" } }, "required": [ "key" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "HAS_SPEC", "description": "Allow entities with the specified spec subfield", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "key": { "type": "string", "description": "Property within the entities spec to match on" }, "value": { "type": "string", "description": "Value of the given property to match on" } }, "required": [ "key" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "IS_ENTITY_KIND", "description": "Allow entities matching a specified kind", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "string" }, "description": "List of kinds to match at least one of" } }, "required": [ "kinds" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "IS_ENTITY_OWNER", "description": "Allow entities owned by a specified claim", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "claims": { "type": "array", "items": { "type": "string" }, "description": "List of claims to match at least one on within ownedBy" } }, "required": [ "claims" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } } ] } ... <another plugin condition parameter schemas> ] [GET] /api/permission/roles/conditions/:id Returns conditions for the specified ID. Example response (JSON) { "id": 1, "result": "CONDITIONAL", "roleEntityRef": "role:default/test", "pluginId": "catalog", "resourceType": "catalog-entity", "permissionMapping": ["read"], "conditions": { "anyOf": [ { "rule": "IS_ENTITY_OWNER", "resourceType": "catalog-entity", "params": { "claims": ["group:default/team-a"] } }, { "rule": "IS_ENTITY_KIND", "resourceType": "catalog-entity", "params": { "kinds": ["Group"] } } ] } } [GET] /api/permission/roles/conditions Returns list of all conditions for all roles. Example response (JSON) [ { "id": 1, "result": "CONDITIONAL", "roleEntityRef": "role:default/test", "pluginId": "catalog", "resourceType": "catalog-entity", "permissionMapping": ["read"], "conditions": { "anyOf": [ { "rule": "IS_ENTITY_OWNER", "resourceType": "catalog-entity", "params": { "claims": ["group:default/team-a"] } }, { "rule": "IS_ENTITY_KIND", "resourceType": "catalog-entity", "params": { "kinds": ["Group"] } } ] } } ] [POST] /api/permission/roles/conditions Creates a conditional policy for the specified role. Table 5.8. Request parameters Name Description Type Presence result Always has the value CONDITIONAL String Required roleEntityRef String entity reference to the RBAC role, such as role:default/dev String Required pluginId Corresponding plugin ID, such as catalog String Required permissionMapping Array permission action, such as ['read', 'update', 'delete'] String array Required resourceType Resource type provided by the plugin, such as catalog-entity String Required conditions Condition JSON with parameters or array parameters joined by criteria JSON Required name Name of the role String Required metadata.description The description of the role String Optional Example request body (JSON) { "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/team-a"] } } } Example response (JSON) { "id": 1 } [PUT] /permission/roles/conditions/:id Updates a condition policy for a specified ID. Table 5.9. Request parameters Name Description Type Presence result Always has the value CONDITIONAL String Required roleEntityRef String entity reference to the RBAC role, such as role:default/dev String Required pluginId Corresponding plugin ID, such as catalog String Required permissionMapping Array permission action, such as ['read', 'update', 'delete'] String array Required resourceType Resource type provided by the plugin, such as catalog-entity String Required conditions Condition JSON with parameters or array parameters joined by criteria JSON Required name Name of the role String Required metadata.description The description of the role String Optional Example request body (JSON) { "result": "CONDITIONAL", "roleEntityRef": "role:default/test", "pluginId": "catalog", "resourceType": "catalog-entity", "permissionMapping": ["read"], "conditions": { "anyOf": [ { "rule": "IS_ENTITY_OWNER", "resourceType": "catalog-entity", "params": { "claims": ["group:default/team-a"] } }, { "rule": "IS_ENTITY_KIND", "resourceType": "catalog-entity", "params": { "kinds": ["Group"] } } ] } } Example response [DELETE] /api/permission/roles/conditions/:id Deletes a conditional policy for the specified ID. Example response
{ "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "delete", "effect": "allow" } [ { "memberReferences": ["user:default/username"], "name": "role:default/guests" }, { "memberReferences": [ "group:default/groupname", "user:default/username" ], "name": "role:default/rbac_admin" } ] [ { "memberReferences": [ "group:default/groupname", "user:default/username" ], "name": "role:default/rbac_admin" } ] { "memberReferences": ["group:default/test"], "name": "role:default/test_admin" } 201 Created { "oldRole": { "memberReferences": ["group:default/test"], "name": "role:default/test_admin" }, "newRole": { "memberReferences": ["group:default/test", "user:default/test2"], "name": "role:default/test_admin" } } 200 OK 204 204 [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "read", "effect": "allow", "metadata": { "source": "csv-file" } }, { "entityReference": "role:default/test", "permission": "catalog.entity.create", "policy": "use", "effect": "allow", "metadata": { "source": "csv-file" } }, ] [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "read", "effect": "allow", "metadata": { "source": "csv-file" } }, { "entityReference": "role:default/test", "permission": "catalog.entity.create", "policy": "use", "effect": "allow", "metadata": { "source": "csv-file" } } ] [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "read", "effect": "allow" } ] 201 Created { "oldPolicy": [ { "permission": "catalog-entity", "policy": "read", "effect": "allow" }, { "permission": "catalog.entity.create", "policy": "create", "effect": "allow" } ], "newPolicy": [ { "permission": "catalog-entity", "policy": "read", "effect": "deny" }, { "permission": "policy-entity", "policy": "read", "effect": "allow" } ] } 200 204 No Content 204 No Content [ { "pluginId": "catalog", "policies": [ { "isResourced": true, "permission": "catalog-entity", "policy": "read" }, { "isResourced": false, "permission": "catalog.entity.create", "policy": "create" }, { "isResourced": true, "permission": "catalog-entity", "policy": "delete" }, { "isResourced": true, "permission": "catalog-entity", "policy": "update" }, { "isResourced": false, "permission": "catalog.location.read", "policy": "read" }, { "isResourced": false, "permission": "catalog.location.create", "policy": "create" }, { "isResourced": false, "permission": "catalog.location.delete", "policy": "delete" } ] }, ] [ { "pluginId": "catalog", "rules": [ { "name": "HAS_ANNOTATION", "description": "Allow entities with the specified annotation", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "annotation": { "type": "string", "description": "Name of the annotation to match on" }, "value": { "type": "string", "description": "Value of the annotation to match on" } }, "required": [ "annotation" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "HAS_LABEL", "description": "Allow entities with the specified label", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "label": { "type": "string", "description": "Name of the label to match on" } }, "required": [ "label" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "HAS_METADATA", "description": "Allow entities with the specified metadata subfield", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "key": { "type": "string", "description": "Property within the entities metadata to match on" }, "value": { "type": "string", "description": "Value of the given property to match on" } }, "required": [ "key" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "HAS_SPEC", "description": "Allow entities with the specified spec subfield", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "key": { "type": "string", "description": "Property within the entities spec to match on" }, "value": { "type": "string", "description": "Value of the given property to match on" } }, "required": [ "key" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "IS_ENTITY_KIND", "description": "Allow entities matching a specified kind", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "string" }, "description": "List of kinds to match at least one of" } }, "required": [ "kinds" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } }, { "name": "IS_ENTITY_OWNER", "description": "Allow entities owned by a specified claim", "resourceType": "catalog-entity", "paramsSchema": { "type": "object", "properties": { "claims": { "type": "array", "items": { "type": "string" }, "description": "List of claims to match at least one on within ownedBy" } }, "required": [ "claims" ], "additionalProperties": false, "USDschema": "http://json-schema.org/draft-07/schema#" } } ] } ... <another plugin condition parameter schemas> ] { "id": 1, "result": "CONDITIONAL", "roleEntityRef": "role:default/test", "pluginId": "catalog", "resourceType": "catalog-entity", "permissionMapping": ["read"], "conditions": { "anyOf": [ { "rule": "IS_ENTITY_OWNER", "resourceType": "catalog-entity", "params": { "claims": ["group:default/team-a"] } }, { "rule": "IS_ENTITY_KIND", "resourceType": "catalog-entity", "params": { "kinds": ["Group"] } } ] } } [ { "id": 1, "result": "CONDITIONAL", "roleEntityRef": "role:default/test", "pluginId": "catalog", "resourceType": "catalog-entity", "permissionMapping": ["read"], "conditions": { "anyOf": [ { "rule": "IS_ENTITY_OWNER", "resourceType": "catalog-entity", "params": { "claims": ["group:default/team-a"] } }, { "rule": "IS_ENTITY_KIND", "resourceType": "catalog-entity", "params": { "kinds": ["Group"] } } ] } } ] { "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/team-a"] } } } { "id": 1 } { "result": "CONDITIONAL", "roleEntityRef": "role:default/test", "pluginId": "catalog", "resourceType": "catalog-entity", "permissionMapping": ["read"], "conditions": { "anyOf": [ { "rule": "IS_ENTITY_OWNER", "resourceType": "catalog-entity", "params": { "claims": ["group:default/team-a"] } }, { "rule": "IS_ENTITY_KIND", "resourceType": "catalog-entity", "params": { "kinds": ["Group"] } } ] } } 200 204