Questo contenuto non è disponibile nella lingua selezionata.

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.

Procedure

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

Procedure

  1. 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.
  2. 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
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"
}

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:

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

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

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

Deletes a specified role from Developer Hub.

Table 4.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

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

[POST] /api/permission/policies

Creates a permission policy for a specified entity.

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

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:

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

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.

Table 4.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

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

Deletes all permission policies added to the specified entity.

Table 4.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

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

Example response (JSON)

{
  "id": 1
}

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

Updates a condition policy for a specified ID.

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

Example response

200

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

Deletes a conditional policy for the specified ID.

Example response

204

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"

Red Hat logoGithubRedditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita ilBlog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

© 2024 Red Hat, Inc.