RBAC policies in Workload Credentials

Access control in Pathfinder

Role-based access control (RBAC) is a new Pathfinder platform capability. Every product built on Pathfinder shares one policy language, one policy API, one set of principals, and one policy lifecycle. What each product contributes is its own resource types, roles, and actions.

This guide covers the platform model first, then Workload Credentials (WLC), a product that uses it. Cedar identifiers make the boundary explicit: Pathfinder:: names platform concepts, WorkloadCredentials:: names the product's.

Pathfinder RBAC

Overview

Access is denied by default: a principal can perform only the actions it has been explicitly granted, on the resources those grants name.

There are two ways to grant access:

• Assign a built-in role in the Role and Group Management view of the Administration console. A built-in role is assigned to a group, and every member of that group inherits it. This is the broad option: a single assignment grants a whole level of access across the product.

• Write a policy through the policy API. A policy grants a principal, down to an individual user, a specific set of actions on a specific resource. This is the fine-grained option, for access too narrow for a built-in role to express.

Policies are declarative and idempotent, so applying the same one twice produces the same grant.

Principals

A principal is the identity a policy grants to. All principals are platform identities in the Pathfinder:: namespace.

Policies and how they take effect

A policy is a Cedar document naming one principal, one or more actions, and one resource.

A policy takes effect in two phases:

1. WRITE (immediate)
   The policy is submitted.
      the engine authorizes the caller, validates the document, stores it
      returns 202 Accepted   (stored, but granting nothing yet)

2. BIND (moments later, automatic)
   A background pipeline resolves the resource path to a concrete
   resource, compiles the grant, and writes it into the authorization
   graph. The grant is now live.

Two timing rules follow from this:

• A policy may name a resource that does not exist yet; it binds automatically once that resource is created.
• A policy for a principal with no access to the product is rejected on submit, so the principal must be enabled for the product first.

The policy API

Policies are managed at https://api.beyondtrust.io/platform/iam. Every request requires a bearer token.

A policy is identified by {name}. PUT is create-or-replace: submitting an existing name updates it in place.

The request body is raw Cedar text with Content-Type: text/plain, and it begins with a @siteId("<site-uuid>") annotation naming the site the policy applies to.

Here is an example written to a file named alice-admin.cedar:

@siteId("11111111-1111-1111-1111-111111111111")
permit(
  principal == Pathfinder::User::Email::"[email protected]",
  action == Pathfinder::Action::"Admin",
  resource is WorkloadCredentials::Product
);

Then submit it with PUT:

curl -sS -X PUT https://api.beyondtrust.io/platform/iam/policies/alice-admin \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: text/plain' \
  --data-binary @alice-admin.cedar

A successful submit returns 202 Accepted. GET /policies/{name} reports status, which reaches ACTIVE once bound, or WAITING_FOR_RESOURCE while the named resource does not yet exist. DELETE /policies/{name} revokes it.

A policy document must satisfy the following:

• Exactly one permit statement. forbid and conditional clauses (when / unless) are not supported.

• principal == a single principal from Section 2.

• action == a single action, or action in [ ... ] for several.

• resource == a path-addressed resource, or resource is <Product> for a product-wide grant.

• Fully qualified names, with PascalCase action ids.

Product roles

Every Pathfinder product exposes a standard set of roles at the product scope, granted through the Pathfinder::Action namespace with the product as the resource.

A user enabled for a product automatically receives a baseline, typically Standard User. Any access beyond that baseline is granted explicitly, either by assigning a built-in role or by writing a policy such as this one for product administration:

@siteId("11111111-1111-1111-1111-111111111111")
permit(
  principal == Pathfinder::User::Email::"[email protected]",
  action == Pathfinder::Action::"Admin",
  resource is WorkloadCredentials::Product
);

Grants come at two granularities. A role bundles a whole level of access, whether one of the product roles here or a resource role a product defines, while a fine-grained action grants a single capability.

Identities, groups, and roles

Identities, groups, and role assignments are managed in the Role and Group Management view of the Administration console, separately from the policy API.

The model is simple: a role holds permissions, a role is assigned to a group, and a group contains users, so a user receives a role's access through the groups they belong to.

User groups

A group links users to roles. You create a group, add users as members, and assign it one or more roles, and every member then holds those roles.

Role Management

Each product publishes built-in roles, scoped to the product in a site. For example, for Workload Credentials these are Product Admin, Product Standard User, Product Auditor, and Product Viewer, the product roles. Assign a built-in role to a group to grant it to that group's members.

A policy can also name a group or a role as its principal, so the fine-grained path builds on these same groups and roles. A principal must have some product access before a policy can apply to it, which a built-in role provides through a group; until then, a policy naming it is rejected.

Workload Credentials

Workload Credentials (WLC) is a product built on Pathfinder RBAC. It uses the policy language, API, principals, lifecycle, and product roles from Part 1. This part documents the resource types, roles, and actions WLC adds.

Resources

WLC resources are addressed by path. Folders, secrets, and dynamic secrets form a hierarchy: a folder contains subfolders, secrets, and dynamic secrets, and a grant on a folder is inherited by everything beneath it. Integrations sit outside this tree, attaching directly to the product. Because the product is the root, a product-scoped grant covers every resource in it.

Roles

WLC defines three roles that apply to its resources, in addition to the product roles in Section 5. Owner on a folder cascades to everything beneath it, and Admin on the product cascades to the entire product.

Action reference

Each action grants a single capability and is checked on the object in the "Checked on" column. Create actions are checked on the parent folder, not on the item being created.

Static secrets

Folders

Integrations

Dynamic secrets and leases

Permission dependencies

• Listing and reading are separate permissions. Seeing items in a folder requires browse (ListFolderContents) on the container, and each item is then filtered by whether the principal has any access to it. A principal granted only ReadSecret on one secret can read that secret by its path, but the secret does not appear when browsing its folder unless the principal also has browse on the folder. An empty listing means no reachable items, not an empty folder. To grant read plus browse of a whole branch, use Viewer on the folder; to grant browsing without reading values, use Lister.
• Create is checked on the parent. CreateSecret, CreateFolder, and CreateDynamicSecret are checked on the parent folder, or on the product at the root, and CreateIntegration is checked on the product.
• Write access does not grant discoverability. A principal can hold a write grant on an item that does not appear in listings; the item stays reachable by path.
• Generating a credential is a product-level capability. GenerateDynamicCredential is held by every product Standard User and Admin, and it can also be granted directly on a single dynamic secret. A resource Owner grant, such as owner of the containing folder, does not include it: generating credentials requires the Standard User or Admin product role, or a direct GenerateDynamicCredential grant.
• Inspecting and revoking leases is separate from generating. Reading and revoking individual leases (ReadLease, RevokeLease) belong to Owner, so a principal can generate credentials without being able to inspect or revoke existing ones.
  Grants cascade down only. A grant on /prod applies to /prod/db-password and every subfolder, while a grant on /prod/db-password applies to nothing above or beside it.

Recipes

Full control of a folder branch:

@siteId("<site-uuid>")
permit(
  principal == Pathfinder::Group::"payments-team",
  action == WorkloadCredentials::Action::"Owner",
  resource == WorkloadCredentials::Folder::"/payments"
);

Read-only, browsable access to a branch:

@siteId("<site-uuid>")
permit(
  principal == Pathfinder::Group::"payments-readers",
  action == WorkloadCredentials::Action::"Viewer",
  resource == WorkloadCredentials::Folder::"/payments"
);

A workload that can generate credentials for one dynamic secret and nothing else:

@siteId("<site-uuid>")
permit(
  principal == Pathfinder::Workload::Id::"<workload-uuid>",
  action == WorkloadCredentials::Action::"GenerateDynamicCredential",
  resource == WorkloadCredentials::DynamicSecret::"/prod/db-dynamic"
);

WLC administrator for the whole site:

@siteId("<site-uuid>")
permit(
  principal == Pathfinder::User::Email::"[email protected]",
  action == Pathfinder::Action::"Admin",
  resource is WorkloadCredentials::Product
);

Troubleshooting