Custom Roles and Bindings

This guide walks through creating custom roles and role bindings to control access in your OpenChoreo installation using the Access Control UI in Backstage.

Access Control UI

Navigate to Settings in the Backstage left sidebar, then select the Access Control tab. The page has three sections in the left sidebar:

• Roles — manage cluster and namespace-scoped roles
• Role Bindings — manage bindings that connect subjects to roles
• Actions — browse all available actions in the system

The Roles section has a dropdown to switch between Cluster Roles and Namespace Roles for managing resources at the appropriate scope.

Creating a Role

1. Go to Settings → Access Control → Roles
2. Use the dropdown to select Cluster Roles or Namespace Roles depending on the scope you need
   • For namespace roles, select the target namespace from the dropdown first
3. Click New Cluster Role or New Namespace Role
4. In the dialog:
   • Optionally select a quick start template (Developer, Viewer, or Admin) to pre-fill actions
   • Enter a Role Name
   • Click Select Actions to open the action picker — actions are grouped by resource type, and you can select individual actions, all actions for a resource type (e.g., component:*), or all actions (*)
5. Click Create

Creating a Role Binding

Role bindings connect a subject to one or more roles, each with its own scope. The UI uses a step-by-step wizard on a dedicated page to guide you through the process — use the Next and Back buttons in the header to move between steps.

1. Go to Settings → Access Control → Role Bindings
2. Use the dropdown to select Cluster Role Bindings or Namespace Role Bindings
   • For namespace bindings, select the target namespace from the dropdown first
3. Click New Cluster Role Binding or New Namespace Role Binding to open the wizard page

The wizard walks through the following steps:

Step 1: Select Subject

Choose the subject type (e.g., User or Service Account) and provide an identifier value. Each subject type maps to a specific JWT claim — for example, the "User" type maps to the groups claim, so entering platform-team as the identifier means the binding matches any request where the groups claim contains platform-team.

note

The subject types shown in the wizard are dynamic and reflect what is configured in your installation. You can customize the available types, display names, and claim mappings through the Helm values — see Subject Types.

Step 2: Configure Role Mappings

Add one or more role-scope pairs. Each role mapping combines a role (defining what actions are permitted), a scope (defining where those actions apply), and optional conditions (defining under what circumstances they apply).

For each mapping:

1. Select a role from the dropdown. For namespace bindings, both namespace roles and cluster roles are available. For cluster bindings, only cluster roles are shown.
2. Set the scope to narrow where the role's permissions apply:
   • For cluster bindings: optionally select a namespace, then a project, then a component
   • For namespace bindings: optionally select a project, then a component
   • Omitting scope means the role applies at the widest level (cluster-wide or namespace-wide)
3. Add conditions (optional) to gate specific actions on request attributes — see Conditions (Optional) below.
4. Confirm the mapping by clicking the checkmark

You can add multiple mappings to a single binding. For example, you might grant developer access scoped to a specific project alongside cluster-reader access with no scope — all in one binding.

tip

The scope you choose determines the effective permissions of the mapping — a user can only perform an action if the role grants that action and the target resource falls within the scope. For more details, see Scope and Effective Permissions.

Select a role and configure its scope inline. The Conditions section below the role and scope fields lets you attach optional CEL-based restrictions (covered next). Click the checkmark to confirm the mapping.

Once confirmed, each mapping appears as a row in the table. You can add more mappings, or edit and delete existing ones.

Conditions (Optional)

Each role mapping can carry one or more conditions that gate specific actions on attributes of the request — for example, allowing release-binding mutations only outside production. Conditions are configured inline while editing a role mapping, before you confirm it.

1. With a role mapping open for editing, locate the Conditions section under the role and scope fields.
2. Click Add condition to create a new entry. The button is disabled until a role is selected and the role grants at least one action that supports conditions.
3. In the condition card:
   • Actions — select one or more action patterns this condition applies to. Only actions granted by the role's action list are selectable.
   • Expression — write a CEL expression that must evaluate to true for the listed actions to be permitted.
   • Available attributes — chips below the Expression field list every attribute valid for your action selection. Click a chip to insert it at the cursor.

4. Click the checkmark to confirm the condition, or X to discard it.

Multiple conditions on the same mapping are combined with OR — at least one matching condition must evaluate to true for the action to be permitted. A mapping with no conditions, or whose conditions don't target the requested action, behaves as an unrestricted grant for that action.

tip

Available attributes are filtered to those supported by every action you've selected. After the first action is picked, the picker hides actions with no overlap, and if the resulting selection has no shared attribute the Expression field is disabled until the conflict is removed. For the full attribute model and YAML reference, see Conditions.

Step 3: Choose Effect and Name

Select the effect:

• Allow — grant the selected roles' permissions to the subject
• Deny — explicitly block these permissions for the subject

A binding name is auto-suggested based on your selections. You can customize it if needed. The name cannot be changed after creation.

Step 4: Review

Review all your selections before creating the binding. The summary shows the subject, effect, and a table of all role mappings with their scopes.

Editing and Deleting

Editing

Click the edit (pencil) icon on any role or binding row to open the edit dialog. The name field cannot be changed after creation.

Deleting a Role

Click the delete (trash) icon on a role row. If the role has active bindings, you'll see a warning listing the affected bindings and can choose to Force Delete, which removes both the role and all its bindings.

Deleting a Role Binding

Click the delete icon on a binding row and confirm.

Browsing Actions

The Actions tab provides a read-only view of all available actions in the system, grouped by resource type. Use the search field to filter actions by name. This is useful when deciding which actions to include in a role.

See Also

• Authorization Overview — Core concepts and how authorization works
• Authorization CRD References — Detailed field reference for authorization CRDs