Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

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 $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"
}
Copy to Clipboard Toggle word wrap
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
Copiar o link

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

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

  2. Execute the request and review the response.

5.2. Supported RBAC REST API endpoints
Copiar o link

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
Copiar o link

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"
  }
]
Copy to Clipboard Toggle word wrap

[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"
  }
]
Copy to Clipboard Toggle word wrap

[POST] /api/permission/roles/{kind}/{namespace}/{name}

Creates a role in Developer Hub.

Expand
Table 5.1. Request parameters
NameDescriptionTypePresence

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"
}
Copy to Clipboard Toggle word wrap

Example response

201 Created
Copy to Clipboard Toggle word wrap

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

Expand
NameDescriptionTypePresence

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"
  }
}
Copy to Clipboard Toggle word wrap

Example response

200 OK
Copy to Clipboard Toggle word wrap

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

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
Copy to Clipboard Toggle word wrap

[DELETE] /api/permission/roles/{kind}/{namespace}/{name}

Deletes a specified role from Developer Hub.

Expand
Table 5.3. Request parameters
NameDescriptionTypePresence

kind

Kind of the entity

String

Required

namespace

Namespace of the entity

String

Required

name

Name of the entity

String

Required

Example response

204
Copy to Clipboard Toggle word wrap

5.2.2. Permission policies
Copiar o link

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"
    }
  },
]
Copy to Clipboard Toggle word wrap

[GET] /api/permission/policies/{kind}/{namespace}/{name}

Returns permission policies related to the specified entity reference.

Expand
Table 5.4. Request parameters
NameDescriptionTypePresence

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"
    }
  }
]
Copy to Clipboard Toggle word wrap

[POST] /api/permission/policies

Creates a permission policy for a specified entity.

Expand
Table 5.5. Request parameters
NameDescriptionTypePresence

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"
  }
]
Copy to Clipboard Toggle word wrap

Example response

201 Created
Copy to Clipboard Toggle word wrap

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

Expand
NameDescriptionTypePresence

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"
    }
  ]
}
Copy to Clipboard Toggle word wrap

Example response

200
Copy to Clipboard Toggle word wrap

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

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
Copy to Clipboard Toggle word wrap

[DELETE] /api/permission/policies/{kind}/{namespace}/{name}

Deletes all permission policies added to the specified entity.

Expand
Table 5.7. Request parameters
NameDescriptionTypePresence

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
Copy to Clipboard Toggle word wrap

[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"
      }
    ]
  },
  ...
]
Copy to Clipboard Toggle word wrap

5.2.3. Conditional policies
Copiar o link

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>
]
Copy to Clipboard Toggle word wrap

[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"]
        }
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

[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"]
          }
        }
      ]
    }
  }
]
Copy to Clipboard Toggle word wrap

[POST] /api/permission/roles/conditions

Creates a conditional policy for the specified role.

Expand
Table 5.8. Request parameters
NameDescriptionTypePresence

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"]
    }
  }
}
Copy to Clipboard Toggle word wrap

Example response (JSON)

{
  "id": 1
}
Copy to Clipboard Toggle word wrap

[PUT] /permission/roles/conditions/:id

Updates a condition policy for a specified ID.

Expand
Table 5.9. Request parameters
NameDescriptionTypePresence

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"]
        }
      }
    ]
  }
}
Copy to Clipboard Toggle word wrap

Example response

200
Copy to Clipboard Toggle word wrap

[DELETE] /api/permission/roles/conditions/:id

Deletes a conditional policy for the specified ID.

Example response

204
Copy to Clipboard Toggle word wrap

Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat