# APIs ## Requirements To access the APIs for the RBAC Backend plugin, a user will need to have admin access. Refer to the [README](../README.md#configure-policy-admins) on how to set up admin access. Each endpoint also requires an Authorization header with the Bearer token that was generated by Backstage. If not using the RBAC Frontend plugin, then to access this token, traverse to your deployed instance and inspect the web page. Here are two places and example network calls that will have the Bearer token - From the Homepage, the network call `query?term=` - From the Catalog, any network call with `entity-facets` ## Source Each permission policy and role that is created through the RBAC Backend plugin will have a source associated with it. When adding new permission policies and roles, we evaluate the ability to modify them based on the location of the first role that was defined. This means that permissions policies that are associated with a role that was created in the CSV file will also need to be defined in the CSV file. This strictness helps to keep the integrity and consistency of the data. A permission policy defined in by the REST API with a role in the CSV file can lead to issues in the event that the role was removed from the CSV file. The permission policy would be hanging without a role and would not show up in the RBAC Frontend. We have four options for source locations: CSV file, Configuration file, REST API, and legacy. The CSV file and REST API are fairly straightforward and involve modifying the role and permissions policies from that particular source only. Configuration file involves the `role:default/rbac_admin` role where the role can only be modified from the `app-config.yaml`. You are unable to add permission policies to the `role:default/rbac_admin` role. This is because we consider this as a default role for starting out. It is encouraged to either use the `superUsers` configuration feature or to craft your own admin role with the permission policies that are required of your admins. Finally, the legacy source is a source that may appear if your permission policies and roles were defined prior to RBAC Backend plugin `2.1.3`. It is recommended to update these legacy sourced roles and permission polices to a source of REST API or CSV file. This can be done by redefining these permission policies and roles using one of the available options. Remember that future permission policies and members of the role will be based on the first originating role with the new source. Be sure to add the role first through one of the described methods, then proceed to add additional members and permission policies to the roles. ## Role ### GET role GET Lists all roles. Returns: ```json [ { "memberReferences": ["user:default/adam"], "name": "role:default/rbac_admin", "metadata": { "source": "configuration", "description": null } }, { "memberReferences": [ "group:default/backstage-community-authors", "user:default/matt" ], "name": "role:default/test", "metadata": { "source": "csv-file", "description": null } } ] ``` --- GET ex. List the single role and the members associated with that role. Request Parameters: | Parameter name | Description | Type | | -------------- | --------------------- | ------ | | kind | role | String | | namespace | Namespace of the role | String | | name | name of the role | String | Returns: ```json [ { "memberReferences": [ "group:default/backstage-community-authors", "user:default/matt" ], "name": "role:default/test", "metadata": { "source": "csv-file", "description": null } } ] ``` --- ### POST role POST Creates a new role. Request Parameters: | Parameter name | Description | Type | | -------------------- | ---------------------------------------------------------------- | ------ | | memberReferences | users / groups to be added to the role `:/` | Array | | name | name of the role | String | | metadata.description | description of the role | String | body: ```json { "memberReferences": ["group:default/test"], "name": "role:default/test_admin", "metadata": { "description": "This is a test admin role" } } ``` Returns a status code of 201 upon success. --- ### PUT role PUT ex. Updates a specified role. Request Parameters: | Parameter name | Description | Type | | -------------- | --------------------- | ------ | | kind | role | String | | namespace | Namespace of the role | String | | name | name of the role | String | Request Parameters for oldRole and newRole: | Parameter name | Description | Type | | -------------------- | ---------------------------------------------------------------- | ------ | | memberReferences | users / groups to be added to the role `:/` | Array | | name | name of the role | String | | metadata.description | description of the role | String | body: ```json { "oldRole": { "memberReferences": ["group:default/test"], "name": "role:default/test_admin", "metadata": { "description": "This is a test admin role" } }, "newRole": { "memberReferences": ["group:default/test", "user:default/test2"], "name": "role:default/test_admin", "metadata": { "description": "This is a test admin role with a group and user" } } } ``` Returns a status code of 200 upon success. --- ### DELETE role DELETE ex. Deletes a single user / group from a role. Request Parameters: | Parameter name | Description | Type | | ---------------- | ---------------------------------------------------------------- | ------ | | kind | role | String | | namespace | Namespace of the role | String | | name | name of the role | String | | memberReferences | users / groups to be added to the role `:/` | String | | name | name of the role | String | before: ```json { "memberReferences": ["group:default/test, user:default/test2"], "name": "role:default/test_admin", "metadata": { "description": "This is a test admin role with a group and user" } } ``` after: ```json { "memberReferences": ["group:default/test"], "name": "role:default/test_admin", "metadata": { "description": "This is a test admin role with a group and user" } } ``` Returns a status code of 204 upon success. --- DELETE ex. Deletes a single role and all users associated with that role. Request Parameters: | Parameter name | Description | Type | | -------------- | --------------------- | ------ | | kind | role | String | | namespace | Namespace of the role | String | | name | name of the role | String | Returns a status code of 204 upon success. --- ## Permission ### GET permission GET Lists all permission polices. Returns: ```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": "create", "effect": "allow", "metadata": { "source": "csv-file" } }, ... ] ``` --- GET ex. List permission policies related to the specified entity reference `:/`. Request parameters: | Parameter name | Description | Type | | -------------- | ----------------------- | ------ | | kind | Kind of the entity | String | | namespace | Namespace of the entity | String | | name | Username of the entity | String | Returns: ```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": "create", "effect": "allow", "metadata": { "source": "csv-file" } } ] ``` --- ### POST permission POST Creates one or more permission policies for a specified entity. Request parameters: | Parameter name | Description | Type | | --------------- | ----------------------------------------------------------------------------- | ------ | | entityReference | Entity `:/` | String | | permission | Permission from a specific plugin, Resource type or name | String | | policy | Policy action for the permission, `create`, `read`, `update`, `delete`, `use` | String | | effect | `allow` or `deny` | String | The `permission` string must not contain double quotes (`"`). Embedded quotes are not handled safely in the current Casbin DB persistence path. body: ```json [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "delete", "effect": "allow" } ] ``` Returns a status code of 201 upon success. --- ### PUT permission PUT ex. Updates one or more permission policies for a specified entity. Request parameters: | Parameter name | Description | Type | | -------------- | ----------------------- | ------ | | kind | Kind of the entity | String | | namespace | Namespace of the entity | String | | name | Username of the entity | String | Request parameters for oldPolicy and newPolicy objects: | Parameter name | Description | Type | | -------------- | ----------------------------------------------------------------------------- | ------ | | permission | Permission from a specific plugin, Resource type or name | String | | policy | Policy action for the permission, `create`, `read`, `update`, `delete`, `use` | String | | effect | `allow` or `deny` | String | 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": "create", "effect": "allow" } ] } ``` Returns a status code of 200 upon success. --- ### Delete permission DELETE ex. Deletes a permission policy of a specified entity. Returns a status code of 204 upon success. --- DELETE ex. Deletes a group of permission policies of a specified entity. Request Parameters: | Parameter name | Description | Type | | -------------- | ----------------------- | ------ | | kind | Kind of the entity | String | | namespace | Namespace of the entity | String | | name | Username of the entity | String | body: ```json [ { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "delete", "effect": "allow" }, { "entityReference": "role:default/test", "permission": "catalog-entity", "policy": "update", "effect": "allow" } ] ``` Returns a status code of 204 upon success. --- ## Plugin ### GET plugin permission policies GET Lists all plugin permission policies from plugins installed in your Backstage instance. Returns: ```json [ { "pluginId": "catalog", "policies": [ { "name": "catalog.entity.read", "policy": "read", "resourceType": "catalog-entity" }, { "name": "catalog.entity.create", "policy": "create" }, { "name": "catalog.entity.delete", "policy": "delete", "resourceType": "catalog-entity" }, { "name": "catalog.entity.refresh", "policy": "update", "resourceType": "catalog-entity" }, { "name": "catalog.location.read", "policy": "read" }, { "name": "catalog.location.create", "policy": "create" }, { "name": "catalog.location.delete", "policy": "delete" } ] }, ... ] ``` --- ## Conditions Conditional permission policies are fairly complex. For more information on how to structure your conditional policies, consult our documentation on [conditions](./conditions.md). ### GET conditional rules GET Provides conditional rule parameter schemas. ```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#" } } ] } ... ] ``` --- ### POST condition POST Creates a new condition. Request Parameters: condition object in json format described above. 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"] } } } ``` Returns a status code of 201 and json with id upon success: ```json { "id": 1 } ``` --- ### PUT condition PUT Update conditions by id. Request Parameters: condition object in json format described above. 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"] } } ] } } ``` Returns a status code of 200 upon success. --- ### Get condition by id GET Returns condition by id: ```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"] } } ] } } ``` Returns a status code of 200 upon success. --- ### GET conditions GET Returns lists all conditions: ```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"] } } ] } } ] ``` Returns a status code of 200 upon success. --- ### DELETE condition by id DELETE Deletes condition by id. Returns a status code of 204 upon success. --- ## Refresh permission policies provider API The API to update permissions allows triggering the Provider to refresh the permissions list. ### POST RBAC permission policies POST Refreshes RBAC permission policies by provider id. Request Parameters: provider 'id' in the url path. Returns a status code of 200 upon success. --- ## Plugin IDs that support the Backstage permission framework API to manage the list of permission IDs that support the Backstage permission framework at runtime without a server restart. This API is important to control rendering the plugin list in the UI. List plugins IDs stored in the object: | Parameter name | Description | Type | | -------------- | ---------------- | ------------ | | ids | list plugins IDs | String Array | ### GET object with list plugin IDs GET Returns object with list plugin IDs: ```json { "ids": ["catalog", "permission"] } ``` Returns a status code of 200 upon success. --- ### POST object with list plugin IDs POST Add more plugins IDs defined in the request object. Request Parameters: object in json format described above. body: ```json { "ids": ["scaffolder"] } ``` Returns a status code of 200 and json with actual object stored in the server: ```json { "ids": ["catalog", "permission", "scaffolder"] } ``` --- ### DELETE plugin IDs DELETE Delete plugins IDs defined in the request object. Request Parameters: object in json format described above. body: ```json { "ids": ["scaffolder"] } ``` Returns a status code of 200 and json with actual object stored in the server: ```json { "ids": ["catalog", "permission"] } ``` ## HTTP status codes | Code | Descriptions | | ---- | ----------------------------------------------- | | 200 | Request was successful | | 201 | New resource was successfully created | | 204 | No additional content to send in response | | 400 | Input Error | | 401 | Lacks valid authentication | | 403 | Refusal to authorize | | 404 | Could not find resource | | 409 | Conflict with current state and target resource | --- ## Curl Request Examples Create role `role:default/test` for `group:default/example`: ```bash 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 ``` Create permission policy for `role:default/test`: ```bash 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 ``` Create conditional permission policy for `role:default/test`: ```bash 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/backstage-community-authors"] } } }' \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $token" \ -v ```