This documentation is for a release that is no longer maintained
See documentation for the latest supported version.이 콘텐츠는 선택한 언어로 제공되지 않습니다.
Chapter 4. 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
4.1. 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
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:
GET
orDELETE
requestcurl -v \ -H "Authorization: Bearer <token>" \ -X <method> "https://<my_developer_hub_url>/<endpoint>" \
curl -v \ -H "Authorization: Bearer <token>" \ -X <method> "https://<my_developer_hub_url>/<endpoint>" \
Copy to Clipboard Copied! Toggle word wrap Toggle overflow POST
orPUT
request requiring JSON body datacurl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -X POST "https://<my_developer_hub_url>/<endpoint>" \ -d <body>
curl -v -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -X POST "https://<my_developer_hub_url>/<endpoint>" \ -d <body>
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - <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_url>
- 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
POST
orPUT
request.
Example request to create a role
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example request to update a role
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example request to create a permission policy
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example request to update a permission policy
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example request to create a condition
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example request to update a condition
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
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.
4.2. Sending requests to the RBAC REST API by using a REST client 링크 복사링크가 클립보드에 복사되었습니다!
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_url>/<endpoint>, such as
https://<my_developer_hub_url>/api/permission/policies
. - Body
-
Enter the JSON body with data that your API endpoint might need with the HTTP
POST
request.
4.3. 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.
4.3.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)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [GET] /api/permission/roles/<kind>/<namespace>/<name>
Returns information for a single role in Developer Hub.
Example response (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [POST] /api/permission/roles/<kind>/<namespace>/<name>
Creates a role in Developer Hub.
Expand Table 4.1. Request parameters Name Description Type Presence body
The
memberReferences
,group
,namespace
, andname
the new role to be created.Request body
Required
Example request body (JSON)
{ "memberReferences": ["group:default/test"], "name": "role:default/test_admin" }
{ "memberReferences": ["group:default/test"], "name": "role:default/test_admin" }
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
201 Created
201 Created
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [PUT] /api/permission/roles/<kind>/<namespace>/<name>
Updates
memberReferences
,kind
,namespace
, orname
for a role in Developer Hub.Request parameters
The request body contains the
oldRole
andnewRole
objects:Expand Name Description Type Presence body
The
memberReferences
,group
,namespace
, andname
the new role to be created.Request body
Required
Example request body (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
200 OK
200 OK
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [DELETE] /api/permission/roles/<kind>/<namespace>/<name>?memberReferences=<VALUE>
Deletes the specified user or group from a role in Developer Hub.
Expand Table 4.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
204
204
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [DELETE] /api/permission/roles/<kind>/<namespace>/<name>
Deletes a specified role from Developer Hub.
Expand Table 4.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
204
204
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.3.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)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [GET] /api/permission/policies/<kind>/<namespace>/<name>
Returns permission policies related to the specified entity reference.
Expand Table 4.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)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [POST] /api/permission/policies
Creates a permission policy for a specified entity.
Expand Table 4.5. Request parameters Name Description Type Presence entityReference
Reference values of an entity including
kind
,namespace
, andname
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
, oruse
String
Required
effect
Indication of allowing or not allowing the policy
String
Required
Example request body (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
201 Created
201 Created
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [PUT] /api/permission/policies/<kind>/<namespace>/<name>
Updates a permission policy for a specified entity.
Request parameters
The request body contains the
oldPolicy
andnewPolicy
objects:Expand 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
, oruse
String
Required
effect
Indication of allowing or not allowing the policy
String
Required
Example request body (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
200
200
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [DELETE] /api/permission/policies/<kind>/<namespace>/<name>?permission={value1}&policy={value2}&effect={value3}
Deletes a permission policy added to the specified entity.
Expand Table 4.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
, oruse
String
Required
effect
Indication of allowing or not allowing the policy
String
Required
Example response
204 No Content
204 No Content
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [DELETE] /api/permission/policies/<kind>/<namespace>/<name>
Deletes all permission policies added to the specified entity.
Expand Table 4.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
204 No Content
204 No Content
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [GET] /api/permission/plugins/policies
Returns permission policies for all static plugins.
Example response (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.3.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)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [GET] /api/permission/roles/conditions/:id
Returns conditions for the specified ID.
Example response (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [GET] /api/permission/roles/conditions
Returns list of all conditions for all roles.
Example response (JSON)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [POST] /api/permission/roles/conditions
Creates a conditional policy for the specified role.
Expand Table 4.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)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response (JSON)
{ "id": 1 }
{ "id": 1 }
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [PUT] /permission/roles/conditions/:id
Updates a condition policy for a specified ID.
Expand Table 4.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)
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
200
200
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [DELETE] /api/permission/roles/conditions/:id
Deletes a conditional policy for the specified ID.
Example response
204
204
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
4.3.4. User statistics 링크 복사링크가 클립보드에 복사되었습니다!
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"
curl -X GET "http://localhost:7007/api/licensed-users-info/users/quantity" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $token"
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
{ "quantity": "2" }
{ "quantity": "2" }
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [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"
curl -X GET "http://localhost:7007/api/licensed-users-info/users" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $token"
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - [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"
curl -X GET "http://localhost:7007/api/licensed-users-info/users" \ -H "Content-Type: text/csv" \ -H "Authorization: Bearer $token"
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example response
userEntityRef,displayName,email,lastTimeLogin user:default/dev,John Leavy,dev@redhat.com,"Thu, 22 Aug 2024 16:27:41 GMT"
userEntityRef,displayName,email,lastTimeLogin user:default/dev,John Leavy,dev@redhat.com,"Thu, 22 Aug 2024 16:27:41 GMT"
Copy to Clipboard Copied! Toggle word wrap Toggle overflow