Chapter 5. Managing authorizations by using the REST API
To automate the maintenance of Red Hat Developer Hub permission policies and roles, you can use Developer Hub 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
5.1. Sending requests to the RBAC REST API by using the curl utility Copy linkLink copied to clipboard!
You can send RBAC REST API requests by using the curl utility.
Prerequisites
Procedure
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 Developer Hub 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.
In a terminal, run the curl command and review the response:
GETorDELETErequest$ curl -v \ -H "Authorization: Bearer <token>" \ -X <method> "https://<my_developer_hub_domain>/<endpoint>" \POSTorPUTrequest requiring JSON body data$ curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -X POST "https://<my_developer_hub_domain>/<endpoint>" \ -d <body>- <token>
- Enter your saved authorization token.
- <method>
Enter the HTTP method for your 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.
-
- https://<my_developer_hub_domain>
- Enter your Developer Hub URL.
- <endpoint>
-
Enter the API endpoint to which you want to send a request, such as
/api/permission/policies. - <body>
-
Enter the JSON body with data that your API endpoint might need with the HTTP
POSTorPUTrequest.
Example request to create a role
$ curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -X POST "https://<my_developer_hub_domain>/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
$ curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -X PUT "https://<my_developer_hub_domain>/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
$ curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer $token" \ -X POST "https://<my_developer_hub_domain>/api/permission/policies" \ -d '[{ "entityReference":"role:default/test", "permission": "catalog-entity", "policy": "read", "effect":"allow" }]'Example request to update a permission policy
$ curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer $token" \ -X PUT "https://<my_developer_hub_domain>/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
$ curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer $token" \ -X POST "https://<my_developer_hub_domain>/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
$ curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer $token" \ -X PUT "https://<my_developer_hub_domain>/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:
200OK- The request was successful.
201Created- The request resulted in a new resource being successfully created.
204No Content- The request was successful, and the response payload has no more content.
400Bad Request- Input error with the request.
401Unauthorized- Lacks valid authentication for the requested resource.
403Forbidden- Refusal to authorize request.
404Not Found- Could not find requested resource.
409Conflict- Request conflict with the current state and the target resource.
5.2. Sending requests to the RBAC REST API by using a REST client Copy linkLink copied to clipboard!
You can send RBAC REST API requests using any REST client.
Prerequisites
Procedure
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 Developer Hub 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.
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 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 Developer Hub URL and API endpoint: https://<my_developer_hub_domain>/<endpoint>, such as
https://<my_developer_hub_domain>/api/permission/policies. - Body
-
Enter the JSON body with data that your API endpoint might need with the HTTP
POSTrequest.
5.3. Supported RBAC REST API endpoints Copy linkLink copied to clipboard!
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.3.1. Roles Copy linkLink copied to clipboard!
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.
Expand Table 5.1. Request parameters Name Description Type Presence bodyThe
memberReferences,group,namespace, andnamethe new role to be created.Request body
Required
Example request body (JSON)
{ "memberReferences": ["group:default/test"], "name": "role:default/test_admin" }Example response
201 Created- [PUT] /api/permission/roles/<kind>/<namespace>/<name>
Updates
memberReferences,kind,namespace, ornamefor a role in Developer Hub.Request parameters
The request body contains the
oldRoleandnewRoleobjects:Expand Name Description Type Presence bodyThe
memberReferences,group,namespace, andnamethe 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
200 OK- [DELETE] /api/permission/roles/<kind>/<namespace>/<name>?memberReferences=<VALUE>
Deletes the specified user or group from a role in Developer Hub.
Expand Table 5.2. Request parameters Name Description Type Presence kindKind of the entity
String
Required
namespaceNamespace of the entity
String
Required
nameName of the entity
String
Required
memberReferencesAssociated group information
String
Required
Example response
204- [DELETE] /api/permission/roles/<kind>/<namespace>/<name>
Deletes a specified role from Developer Hub.
Expand Table 5.3. Request parameters Name Description Type Presence kindKind of the entity
String
Required
namespaceNamespace of the entity
String
Required
nameName of the entity
String
Required
Example response
204
5.3.2. Permission policies Copy linkLink copied to clipboard!
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.
Expand Table 5.4. Request parameters Name Description Type Presence kindKind of the entity
String
Required
namespaceNamespace of the entity
String
Required
nameName 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.
Expand Table 5.5. Request parameters Name Description Type Presence entityReferenceReference values of an entity including
kind,namespace, andnameString
Required
permissionPermission from a specific plugin, resource type, or name
String
Required
policyPolicy action for the permission, such as
create,read,update,delete, oruseString
Required
effectIndication 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
201 Created- [PUT] /api/permission/policies/<kind>/<namespace>/<name>
Updates a permission policy for a specified entity.
Request parameters
The request body contains the
oldPolicyandnewPolicyobjects:Expand Name Description Type Presence permissionPermission from a specific plugin, resource type, or name
String
Required
policyPolicy action for the permission, such as
create,read,update,delete, oruseString
Required
effectIndication 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
200- [DELETE] /api/permission/policies/<kind>/<namespace>/<name>?permission={value1}&policy={value2}&effect={value3}
Deletes a permission policy added to the specified entity.
Expand Table 5.6. Request parameters Name Description Type Presence kindKind of the entity
String
Required
namespaceNamespace of the entity
String
Required
nameName related to the entity
String
Required
permissionPermission from a specific plugin, resource type, or name
String
Required
policyPolicy action for the permission, such as
create,read,update,delete, oruseString
Required
effectIndication of allowing or not allowing the policy
String
Required
Example response
204 No Content- [DELETE] /api/permission/policies/<kind>/<namespace>/<name>
Deletes all permission policies added to the specified entity.
Expand Table 5.7. Request parameters Name Description Type Presence kindKind of the entity
String
Required
namespaceNamespace of the entity
String
Required
nameName related to the entity
String
Required
Example response
204 No Content- [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" } ] }, ... ]
- [GET] /api/permission/plugins/id
Returns object with list plugin IDs:
Example response (JSON)
[ { "ids": ["catalog", "permission"] } ]- [POST] /api/permission/plugins/id
Add more plugins IDs defined in the request object.
Request Parameters: object in JSON format.
Example request body (JSON)
[ { "ids": ["scaffolder"] } ]Returns a status code of 200 and JSON with actual object stored in the server:
Example response (JSON)
[ { "ids": ["catalog", "permission", "scaffolder"] } ]- [DELETE] /api/permission/plugins/id
Delete plugins IDs defined in the request object.
Request Parameters: object in JSON format.
Example request body (JSON)
[ { "ids": ["scaffolder"] } ]Returns a status code of 200 and JSON with actual object stored in the server:
Example response (JSON)
[ { "ids": ["catalog", "permission"] } ]
In order to prevent an inconsistent state after a deployment restart, the REST API does not allow deletion of plugin IDs that were provided by using the application configuration. These ID values can only be removed through the configuration file.
5.3.3. Conditional policies Copy linkLink copied to clipboard!
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, "$schema": "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, "$schema": "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, "$schema": "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, "$schema": "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, "$schema": "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, "$schema": "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.
Expand Table 5.8. Request parameters Name Description Type Presence resultAlways has the value
CONDITIONALString
Required
roleEntityRefString entity reference to the RBAC role, such as
role:default/devString
Required
pluginIdCorresponding plugin ID, such as
catalogString
Required
permissionMappingArray permission action, such as
['read', 'update', 'delete']String array
Required
resourceTypeResource type provided by the plugin, such as
catalog-entityString
Required
conditionsCondition JSON with parameters or array parameters joined by criteria
JSON
Required
nameName of the role
String
Required
metadata.descriptionThe 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.
Expand Table 5.9. Request parameters Name Description Type Presence resultAlways has the value
CONDITIONALString
Required
roleEntityRefString entity reference to the RBAC role, such as
role:default/devString
Required
pluginIdCorresponding plugin ID, such as
catalogString
Required
permissionMappingArray permission action, such as
['read', 'update', 'delete']String array
Required
resourceTypeResource type provided by the plugin, such as
catalog-entityString
Required
conditionsCondition JSON with parameters or array parameters joined by criteria
JSON
Required
nameName of the role
String
Required
metadata.descriptionThe 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
200- [DELETE] /api/permission/roles/conditions/:id
Deletes a conditional policy for the specified ID.
Example response
204
5.3.4. User statistics Copy linkLink copied to clipboard!
The licensed-users-info-backend plugin exposes various REST API endpoints to retrieve data related to logged-in users.
No additional configuration is required for the licensed-users-info-backend plugin. If the RBAC backend plugin is enabled, then an administrator role must be assigned to access the endpoints, as the endpoints are protected by the policy.entity.read permission.
The base URL for user statistics endpoints is http://SERVER:PORT/api/licensed-users-info, such as http://localhost:7007/api/licensed-users-info.
- [GET] /users/quantity
Returns the total number of logged-in users.
Example request
curl -X GET "http://localhost:7007/api/licensed-users-info/users/quantity" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $token"Example response
{ "quantity": "2" }- [GET] /users
Returns a list of logged-in users with their details.
Example request
curl -X GET "http://localhost:7007/api/licensed-users-info/users" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $token"Example response
[ { "userEntityRef": "user:default/dev", "lastTimeLogin": "Thu, 22 Aug 2024 16:27:41 GMT", "displayName": "John Leavy", "email": "dev@redhat.com" } ]- [GET] /users
Returns a list of logged-in users in CSV format.
Example request
curl -X GET "http://localhost:7007/api/licensed-users-info/users" \ -H "Content-Type: text/csv" \ -H "Authorization: Bearer $token"Example response
userEntityRef,displayName,email,lastTimeLogin user:default/dev,John Leavy,dev@redhat.com,"Thu, 22 Aug 2024 16:27:41 GMT"