tenant-binding

A tenant-binding grants permissions to users or groups across your tenant. Each binding pairs a set of principals, which can be GitHub logins or groups, with either inline permissions or a named role. Tenant-bindings with the murmur- name prefix are platform builtins and cannot be modified.

Synopsis

murmur get tenant-binding [name]
murmur set tenant-binding <name> < binding.yaml
murmur rm tenant-binding <name>

Use murmur get, murmur set, and murmur rm to manage this resource.

Arguments

Name	Type	Required	Description
`name`	string	yes	Unique identifier. DNS label format: `[a-z][a-z0-9-]{0,62}`. The `murmur-` prefix is reserved for platform builtins.
`grant`	object	yes	Defines who gets what permissions. See Grant fields.
`description`	string	no	Human-readable description shown in the dashboard. Maximum 1024 bytes.

Grant fields

The grant object names the principals and the permissions they receive.

Name	Type	Required	Description
`grant.groups`	string[]	conditional	Group names in the same tenant. At least one of `groups` or `users` is required.
`grant.users`	string[]	conditional	Exact principal names, such as a GitHub login, `service-profile:deploy`, or `agent-runtime:github_app/acme/w/backend/github_oauth/alice/fix-auth`. Family-prefix patterns such as `service-profile:` and `agent-runtime:github_app/acme/w/backend/github_oauth/alice/` are supported. A bare `*` or login glob does not match. At least one of `groups` or `users` is required.
`grant.inline`	object	conditional	Inline permissions list. Exactly one of `inline` or `role` is required.
`grant.inline.permissions`	string[]	yes	Permission strings in `{kind}.{verb}` format. Wildcards: `` (all), `{kind}.`, `*.{verb}`.
`grant.role`	string	conditional	Name of a role in the same tenant. Exactly one of `inline` or `role` is required.
`grant.name_pattern`	string	no	Restricts target catalog names. Exact match or trailing `*` prefix match, with name-pattern variables: `${provider}`, `${username}`, `${service_profile}`, `${owner_provider}`, `${owner_account}`, `${workspace}`. A referenced variable with no value matches nothing.
`grant.extend_to_runtime_agents`	bool	no	Default `false`. When `true`, each request also evaluates this grant against the running agent’s current acting identity: its recorded service profile, including a borrowed one, or its developer owner. Current membership and the grant’s pattern apply. Grant edits and revocations affect already-running agents on subsequent requests.

Permission strings use the format {kind}.{verb} where kind is a catalog resource kind and verb is one of read, create, edit, delete, assume, encrypt, endorse, login (only as tenant.login), purge, or use (only as workspace.use). read also covers seeing a resource in listings; list is not a valid verb. See role for the full list of kinds and verbs. Use * for a full wildcard, {kind}.* for all verbs on a kind, or *.{verb} for one verb across all kinds.

Examples

Grant a role to a group

name: engineers-workspace-admin
grant:
  groups:
    - platform-team
  role: workspace-admin
description: "Platform team gets workspace-admin role"

cat <<'EOF' | murmur set tenant-binding engineers-workspace-admin
name: engineers-workspace-admin
grant:
  groups:
    - platform-team
  role: workspace-admin
description: "Platform team gets workspace-admin role"
EOF

Grant inline permissions to specific users

name: oncall-read-access
grant:
  users:
    - alice
    - bob
  inline:
    permissions:
      - agent.read
      - workspace.read
description: "On-call engineers can view agents and workspaces"

Scope a grant with a name pattern

name: user-self-secrets
grant:
  groups:
    - murmur-all-members
  inline:
    permissions:
      - user-secret.read
      - user-secret.create
      - user-secret.edit
      - user-secret.delete
  name_pattern: "${provider}/${username}/*"
description: "Users manage their own secrets"

The name_pattern restricts this tenant-binding so each user can only access user-secrets under their own {provider}/{username}/ prefix. The builtin murmur-member-self binding already grants this. ${provider} and ${username} are resolved from the caller’s identity at evaluation time.

Listing tenant-bindings

murmur get tenant-binding

Reading a single tenant-binding

murmur get tenant-binding engineers-workspace-admin

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`name must match [a-z][a-z0-9-]{0,62}`	Use a lowercase DNS label: starts with a letter, followed by up to 62 lowercase letters, digits, or hyphens.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit (N bytes)`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`grant is required`	Provide a `grant` block with principals and permissions.
`INVALID_ARGUMENT`	`grant must specify at least one group or user`	Add at least one entry to `grant.groups` or `grant.users`.
`INVALID_ARGUMENT`	`grant must specify inline permissions or a role reference`	Set exactly one of `grant.inline` or `grant.role`.
`INVALID_ARGUMENT`	`grant role reference must be non-empty`	The `grant.role` field is present but empty. Provide a role name.
`INVALID_ARGUMENT`	`grant permissions must be non-empty`	The `grant.inline.permissions` list is empty. Add at least one permission string.
`INVALID_ARGUMENT`	`grant permissions[N]: invalid permission "...": must be "", "{kind}.", "*.{verb}", or "{kind}.{verb}"`	Fix the permission string format.
`INVALID_ARGUMENT`	`grant permissions[N]: invalid permission "...": unknown kind "..."`	The kind portion of the permission string does not match a valid kind.
`INVALID_ARGUMENT`	`grant permissions[N]: invalid permission "...": unknown verb "..."`	Use `read`, `create`, `edit`, `delete`, `assume`, `encrypt`, `endorse`, `login`, `purge`, or `use`. `list` is rejected.
`INVALID_ARGUMENT`	`grant permissions[N]: invalid permission "...": verb "..." applies only to ...`	Use `login` with `tenant` and `use` with `workspace`.
`INVALID_ARGUMENT`	`grant permissions[N]: duplicate permission "..."`	Remove the duplicated permission string from the list.
`INVALID_ARGUMENT`	`grant permissions: "*" makes other permissions redundant`	A full wildcard `` is present alongside other permissions. Use `` alone or list specific permissions.
`INVALID_ARGUMENT`	`grant permissions: "..." is subsumed by "..."`	A specific permission like `agent.read` is redundant because `agent.` or `.read` is already in the list. Remove the narrower entry.
`INVALID_ARGUMENT`	`group "..." does not exist`	The referenced group does not exist in the tenant. Create it first with `murmur set group`.
`INVALID_ARGUMENT`	`group "..." is an agent_runtime group, which only a platform-builtin binding may grant to`	Name a different group.
`INVALID_ARGUMENT`	`role "..." does not exist`	The referenced role does not exist in the tenant. Create it first with `murmur set role`.

Permissions: how permission strings work
Authorization: how grants are evaluated
role: named permission bundle referenced by grant.role
group: named principal set referenced by grant.groups
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

tenant-binding

Synopsis

Arguments

Grant fields

Examples

Grant a role to a group

Grant inline permissions to specific users

Scope a grant with a name pattern

Listing tenant-bindings

Reading a single tenant-binding

Errors

​Synopsis

​Arguments

​Grant fields

​Examples

​Grant a role to a group

​Grant inline permissions to specific users

​Scope a grant with a name pattern

​Listing tenant-bindings

​Reading a single tenant-binding

​Errors

​Related

Synopsis

Arguments

Grant fields

Examples

Grant a role to a group

Grant inline permissions to specific users

Scope a grant with a name pattern

Listing tenant-bindings

Reading a single tenant-binding

Errors

Related