tenant-binding

A tenant-binding is a catalog resource that grants permissions to users or groups across your entire tenant. Each tenant-binding pairs a set of principals — GitHub logins and/or groups — with either inline permissions or a named role. Tenant-bindings with the murmur- name prefix are platform builtins and cannot be modified.

Fields

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	GitHub logins. 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 the grant to resources whose name matches this pattern. Supports variable substitution (`${provider}`, `${username}`) and trailing `*` glob.

Permission strings use the format {kind}.{verb} where kind is a catalog resource kind and verb is one of read, list, create, edit, delete, assume, encrypt, or endorse. 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
      - agent.list
      - workspace.read
      - workspace.list
description: "On-call engineers can view agents and workspaces"

Scope a grant with a name pattern

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

The name_pattern restricts this tenant-binding so each user can only access resources under their own namespace. ${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`	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`	`invalid permission: must be "", "{kind}.", "*.{verb}", or "{kind}.{verb}"`	Fix the permission string format.
`INVALID_ARGUMENT`	`invalid permission: unknown kind`	The kind portion of the permission string does not match a registered catalog kind.
`INVALID_ARGUMENT`	`invalid permission: unknown verb`	The verb portion is not one of `read`, `list`, `create`, `edit`, `delete`, `assume`, `encrypt`, `endorse`.
`INVALID_ARGUMENT`	`duplicate permission`	Remove the duplicated permission string from the list.
`INVALID_ARGUMENT`	`"*" makes other permissions redundant`	A full wildcard `` is present alongside other permissions. Use `` alone or list specific permissions.
`INVALID_ARGUMENT`	`permission is subsumed by wildcard`	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`	`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

Fields

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

​Fields

​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

Fields

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