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

You have access to the RBAC feature.

Procedure

Find your Bearer token to authenticate to the REST API.
1. In your browser, open the web console Network tab.
2. In the main screen, reload the Developer Hub Homepage.
3. In the web console Network tab, search for the query?term= network call.
4. Save the token in the response JSON for the next steps.

In a terminal, run the curl command and review the response:

GET or DELETE request

curl -v \
  -H "Authorization: Bearer <token>" \
  -X <method> "https://<my_developer_hub_url>/<endpoint>" \

POST or PUT request requiring JSON body data

curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -X POST "https://<my_developer_hub_url>/<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_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 or PUT request.

Example request to create a role

curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -X POST "https://<my_developer_hub_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

curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -X PUT "https://<my_developer_hub_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

curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -X POST "https://<my_developer_hub_url>/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_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

curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -X POST "https://<my_developer_hub_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

curl -v -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -X PUT "https://<my_developer_hub_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.

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

You have access to the RBAC feature.

Procedure

Find your Bearer token to authenticate to the REST API.
1. In your browser, open the web console Network tab.
2. In the main screen, reload the Developer Hub Homepage.
3. In the web console Network tab, search for the query?term= network call.
4. 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)

[
  {
    "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 4.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

201 Created

[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

200 OK

[DELETE] /api/permission/roles/<kind>/<namespace>/<name>?memberReferences=<VALUE>

Deletes the specified user or group from a role in Developer Hub.

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

[DELETE] /api/permission/roles/<kind>/<namespace>/<name>

Deletes a specified role from Developer Hub.

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

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)

[
  {
    "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 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)

[
  {
    "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 4.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

201 Created

[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 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`, or `use`	String	Required
`effect`	Indication 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.

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

[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"
      }
    ]
  },
  ...
]

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)

[
   {
      "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.

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)

{
  "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 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)

{
  "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

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"

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"

Chapter 4. Managing authorizations by using the REST API

4.1. Sending requests to the RBAC REST API by using the curl utility

4.2. Sending requests to the RBAC REST API by using a REST client

4.3. Supported RBAC REST API endpoints

4.3.1. Roles

4.3.2. Permission policies

4.3.3. Conditional policies

4.3.4. User statistics

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links