Chapter 5. Role-based Access Control (RBAC) REST API

PDF

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 $token

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.
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 $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 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.

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

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

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

204 No Content

[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

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

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,
               "$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 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

Chapter 5. Role-based Access Control (RBAC) REST API

5.1. Sending requests with the RBAC REST API using a REST client or curl utility

5.2. Supported RBAC REST API endpoints

5.2.1. Roles

5.2.2. Permission policies

5.2.3. Conditional policies

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