Role Based Access Control (RBAC)

In the previous section, you learnt how to authenticate users (that is, who they are). In this section you will learn how to authorize users to perform actions in RHDH (that is, what they can do in RHDH).

Role-Based Access Control (RBAC) is a security concept that controls access to resources in a system, and specifies a mapping between users of the system, and the actions they can perform on resources in the system. You define roles with specific permissions , and then assign the roles to users.

RBAC on RHDH is built on top of the Permissions framework in Backstage, which defines RBAC policies in code. Rather than define policies in code, the RHDH RBAC feature allows you to define policies in a declarative fashion using a simple CSV based format.

To apply RBAC in RHDH, you need to do two things:

  1. Configure an authenticated user as a Policy Administrator

  2. Configure policies in a CSV file and import it into RHDH

Declarative Role Based Access Control

RBAC in RHDH is configured using a CSV file that follows the casbin (https://casbin.org) format, a popular declarative domain specific language (DSL) for access control.

A RBAC policy CSV consists of a number of lines of declarations. A policy declaration consists of lines in the following format:

type, role_name, resource, action, permission

where,

  • type = should be a single letter - p for policy type, or g for role assignments to users

  • role_name = A custom role name defined by you, for example admins, users, viewers

  • resource = features in RHDH, for example catalog-entity, policy-entity, scaffolder-template, and more

  • action = create, update, delete, or read

  • permission = allow or deny

Consult the references section at the bottom of this page for the full list of resource types in RHDH.

Consider the following policy snippet:

p, role:default/myrole, catalog-entity, read, allow
p, role:default/myrole, catalog.entity.delete, delete, deny
g, user:default/myuser, role:default/myrole

It defines a custom role named myrole that permits read only access to the RHDH catalog, but denies deletes. The last line in the policy CSV file assigns the myuser user the myrole role. The myuser user should be a valid identity that is authenticated by one of the identity providers supported by RHDH.

Lab: Configure Policy Administrators

The main reason to declare policy administrators is to allow a certain limited number of authenticated users to invoke the RBAC REST API. The actual policies are defined in a separate CSV file and referenced in the app-config-rhdh ConfigMap. This can be done by OpenShift platform or cluster administrators who have access to the namespace where RHDH is running.

  1. To declare users as policy administrators, add the following permission attribute to the app-config-rhdh ConfigMap (At the same indentation level as the app and below the catalog attribute).

    1. Switch to Developer profile and select ConfigMaps and click on app-config-rhdh:

      config2
      Figure 1. Select ConfigMaps

    2. Select YAML view and ensure that you added a valid authenticated user for the admin.users attribute:

      catalog:
      providers:
        github:
          ...
        githubOrg:
          ...
permission:
  enabled: true
  rbac:
    admin:
      users:
        - name: user:default/<your_policy_administrator_name>

      Here the <your_policy_administrator_name> could be found by navigating to your Developer Hub Application, select Settings, select tab Authentication Providers and select the name highlighted in below image:

      adminname
      Figure 2. Policy Administrator Name

  2. The RBAC plugin is disabled by default. Enable it by adding it to the list of dynamic plugins in the ConfigMap dynamic-plugins-rhdh-local.

    ...
data:
  dynamic-plugins.yaml: |
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-dynamic'
        disabled: false
      - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github-org-dynamic'
        disabled: false
      - package: './dynamic-plugins/dist/backstage-community-plugin-rbac'
        disabled: false

  3. Restart rollout of the RHDH pod from the Topology view.

  4. Sign out from the existing RHDH session and log in again using the GitHub ID of the declared policy administrator.

  5. Navigate to the Catalog page in RHDH. Note that the Create button is not visible. You are not allowed to create new components.

  6. Next, try navigating to the API page. The Register button is not visible. With RBAC enabled, most features are disabled by default. You need to explicitly enable permissions to resources in RHDH.

Lab: RBAC Administration UI

To selectively allow RHDH features, you need to declare roles with allowed policies, and then assign these roles to users or groups. Previous versions of RHDH allowed you to do this using CSV files stored in ConfigMaps. Recent versions of RHDH have introduced a convienient web based UI to manage policies.

This section covers the RBAC Admin UI. Consult the product documentation for the process to manually specify policies using CSV files.

It is recommended to keep the RBAC system disabled when trying out features and functionality of RHDH like Software Templates, plugins, Search, and more. Turn it back on only if you know what you are doing, and you fully understand the impact of policies.

  1. After you have enabled the RBAC dynamic plugin and add users to the rbac.admin.users list in the app-config-rhdh ConfigMap, log in to RHDH and then click Administration in the bottom of the left sidebar.

    admin1
    Figure 3. Administration

  2. Notice that a new tab called RBAC is now enabled. There is a single role named rbac_admin declared with the users you declared in the rbac.admin.users list assigned to this role.

    admin2
    Figure 4. RBAC Admin UI

  3. Click on the role:default/rbac_admin link. The policy details page lists the users assigned to this role in the left column, and the list of permitted policies on the right.

    rbac policy details
    Figure 5. RBAC Policy Mapping

    This user is allowed to create, edit, update and delete RBAC policies and view catalog items. With RBAC enabled, you need to explicitly allow users to create catalog items.

  4. Switch back the RBAC Administration page. Click Create to add a new policy.

    create1
    Figure 6. Create Policy

  5. In the Create Role screen, enter allow-catalog-create-policy as the policy name, and enter a brief description. Click Next.

    rolename
    Figure 7. Enter Role Name

  6. In the Add users and groups screen, select users and groups that should be assigned to this role and click Next.

    group
    Figure 8. Enter User/Group

  7. In the Add permission policies screen, select catalog in the Plugin field, and catalog.entity.create in the Resource type field. Ensure Create is selected in the actions and click Next.

    permit
    Figure 9. Permission policies

  8. Review your choices and click Create to create the policy.

    review
    Figure 10. RBAC Policy to allow creation of catalog items

  9. You should get a confirmation message that the policy creation was successful. Log out and log in as the user to whom you assigned the policy. Navigate to the Catalog page. Verify that a Create button is now visible. Similarly, click APIs and verify that you can see a Register Existing API button. This user is now allowed to create catalog items. You can assign permissions to delete and update catalog items in a similar manner using the RBAC Admin UI.

RBAC REST API

RHDH provides an RBAC REST API that you can use to manage the permissions and roles programmatically. This API can be used to automate the maintenance of RHDH permission policies and roles.

You can perform the following actions with the REST API:

  • 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

If RBAC is enabled, you may need to permit actions on the policy.entity resource for read, create and update to view and change policies using the REST API. Recall that the default policy is to deny, so you will see HTTP 401 or 403 errors if you make REST calls without policy changes.

Detailed coverage of the REST API is beyond the scope of this course. Consult the references section for more details.

Lab: RBAC REST API

  • Log in to RHDH and log in as a user who has access to RBAC policies in the RHDH (Red Hat Dynamic Host Configuration) interface.

  • Open Developer Tools:

    1. You can open the developer tools by pressing Ctrl + Shift + I (Windows/Linux) or Cmd + Option + I (Mac), or right-click anywhere on the page and select Inspect. Alternatively, you can press Ctrl + Shift + C (Windows/Linux) or Cmd + Shift + C (Mac) to open the developer tools and directly start inspecting elements on the page.

  • Go to the Network Tab:

    1. In the developer tools pane, click on the Network tab. This tab shows all network requests made by the page, including HTTP requests.

  • Navigate to the Catalog Page:

    1. While the developer tools are open, go back to the RHDH page, and navigate to the Catalog page or the part of the UI where RBAC policies are listed or accessed.

  • Look for the Request:

    1. As you interact with the page (like clicking or navigating), you’ll see network activity in the Network tab. The requests will appear as the page loads.

    2. Look for HTTP requests that contain the keyword entity-facets?facet=kind. These are usually requests made to fetch certain data related to RBAC policies or catalog items.

    3. You can filter the requests by typing entity-facets?facet=kind in the search box inside the Network tab or look for a request with this string in the URL.

  • Click on the Request:

    1. When you find a request that matches entity-facets?facet=kind, click on it to view the request details.

  • Find the Authorization Header:

    1. In the Request Headers section of the request details, you will find a key called Authorization. The Authorization header contains the JWT token that you need.

  • Copy the value of the token (the part after Bearer)

    rbac token
    Figure 11. Get the Bearer token for the logged in RHDH user

    1. Save the token value and RHDH URL to environment variables:

      export token=<your token value>

export RHDH_URL=https://backstage-rhdh-devhub.apps.cluster-<guid>.dynamic.redhatworkshops.io

    2. Use the curl and jq CLI tools, or a REST API client, to invoke the RBAC REST API. For example, to list the policies existing in the current RHDH instance:

      curl $RHDH_URL/api/permission/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $token" \
  -k -s | jq .

      You should see the output as follows:

      [
  {
    "memberReferences": [
      "user:default/<you-account-name>"
    ],
    "name": "role:default/rbac_admin",
    "metadata": {
      "source": "configuration",
      "description": "The default permission policy for the admin role allows for the creation, deletion, updating, and reading of roles and permission policies.",
      "author": "application configuration",
      "modifiedBy": "application configuration",
      "createdAt": "2025-01-28T11:17:50.000Z",
      "lastModified": "2025-01-11T11:00:02.000Z"
    }
  },
  {
    "memberReferences": [
      "user:default/<you-account-name>"
    ],
    "name": "role:default/allow-catalog-create-policy",
    "metadata": {
      "source": "rest",
      "description": "This policy allows users to create catalog items",
      "author": "user:default/<you-account-name>",
      "modifiedBy": "user:default/<you-account-name>",
      "createdAt": "2025-01-11T12:03:27.000Z",
      "lastModified": "2025-01-11T12:03:27.000Z"
    }
  }
]

      Consult the RBAC REST API product documentation to send other queries (POST, PUT etc) to add, modify, update and delete policies.

References