Skip to main content
Video tutorial · 1:27

Resource grants

A project role normally covers every resource in the project. With resource grants you can limit a user's role in a project to only the resources you grant them. For example, an admin who manages only the web team's certificates, the servers they are deployed to, and the credentials and scripts used there.

This page describes what this version enforces. Every rule below is checked by the server, and the user interface only hides what the server would refuse anyway.

What is narrowed​

Every resource of a project can be granted:

GroupResource types
CertificatesCertificates, with everything that belongs to one: its distributions, jobs, versions, keys, events and notification history
DistributionTargets, Target groups, Credentials (module credentials), Path sets, Action sets, Modules (module configurations), Variables (project variables)
IssuanceACME accounts, Custom ACME CAs, AD CS connections, CA connections, DNS credentials, Zones, Secret stores
DiscoveryDiscovery sources, with what they found: their runs, endpoints and CT observations, and the discovered certificates and findings
NotificationsNotification channels, Notification rules

The three building blocks​

1. The role's scope. Each project role has a scope, set by the organisation owner in Settings → Users → Roles:

ScopeMeaning
Whole project (default)The role covers every resource in the project. Every role that existed before this feature has this scope.
Only granted resourcesThe role covers only the resources granted to the user.

Org-wide roles and the owner role always cover everything and cannot be limited.

A user group takes roles and grants the same way, and every member has them. A member's own roles and its groups' roles count together (the highest wins), and so do their grants — see User groups → How roles combine. Everything on this page applies to a group's grants as to a user's.

2. Grants. A grant gives a user with Only granted resources a role on a resource:

GrantWhat it gives
A role on one resourceThat resource (for example one certificate or one credential), at viewer, operator or admin
A role on every resource of a typeFor example all certificates or all credentials of the project, including ones created later
May create on a typePermission to create new resources of that type. The creator automatically gets the role they create with on what they create: admin for a user whose granted role is admin, operator for one who creates through a whole-project operator role (so later edits of it still need approval).

3. The effective role. The user acts on a resource with the lower of two roles: their project role, and the highest grant that covers the resource (its own grant or the grant on its whole type).

Project roleGrant on the resourceEffective role on it
adminadminadmin
adminviewerviewer
operatoradminoperator: the project role caps the grant
vieweradminviewer
operatorno grant on it or on its typenone: the resource does not exist for them
operatorevery target: viewer + this target: adminoperator on this target, viewer on the others
note

A grant on a target group gives nothing on the targets in it. Each target is granted on its own.

Setting it up​

  1. Limit the role. In Settings → Users, click Roles on the user. Choose the project, the role, and Only granted resources, then click OK. Only the organisation owner can do this, because only the owner edits roles.
  2. Grant resources. Do this in either of two places:
    • By user: reopen Roles. The Grants button next to the saved role opens the user's grants. It is greyed out until the role is saved with Only granted resources.

      • Under Every resource of a type, set a role on every resource of a type (all certificates, all credentials, …), or switch on May create.
      • Under Single resources, pick a type and a resource and set a role.
      • Click Save grants.
    • By resource: open the resource's Access view, add members, and click Save access.

      • Certificate: the Access tab at the bottom of the certificate page.
      • Target: the Access card under the target's edit form. It is not shown while you create a target.
      • Target group: the shield Access button in the group's row on the Target groups list.
      • Credential, path set, action set, module: the Access card under its edit form.
      • Variable: the shield Access button in the variable's row on the Variables page.
      • ACME account, AD CS connection, CA connection, DNS credential, secret store: the Access card under its edit form.
      • Zone: the Access button in the zone's row on the Zones page.
      • Discovery source: the Access tab on the source's page.
      • Notification channel, notification rule: the Access button in its row on the Notifications page.

      The member picker lists only members whose role is limited to granted resources. Members with a whole-project role reach the resource anyway.

Who manages grants​

ActionWho may do it
Limit a role to granted resources (Roles dialog)Organisation owner only
Edit a user's grantsAn admin of the whole project: org owner or admin, or a project admin with a whole-project role. In the UI the Grants drawer sits in Settings → Users, which only the owner opens; the others use the API (PUT /projects/{projectId}/users/{userId}/grants).
Edit the grants on one resource (Access tab, card or button)A project admin who holds admin on that resource. A whole-project admin always qualifies. A restricted admin cannot hand out a role higher than its own on that resource.
See the grants on one resourceAnyone with admin on that resource

A grant can only be given to a user or user group that holds a role in the project. A group's grants are edited on Settings → Groups → Roles and grants → Grants (owner) or through the API by an admin of the whole project; on a resource's Access view the picker lists groups with a Group tag.

What a restricted user can do​

The project role column is the role the route requires in any case. The role on the resource column is the effective role the user must have on it.

Certificates​

ActionProject roleRole on the certificate
See it in the list, export it to CSV, open it, its timeline, jobs, versions, keys, dependency graph, discovery sightings, distributions and rollback candidatesviewerviewer
Edit owner, description, auto-renew, renewal threshold and mode, key rotationoperatoroperator
Renew, re-issue, revoke, validate manual DNS, run the DNS check, downloadoperatoroperator
Re-importadminadmin
Deleteadminadmin
Issue a new certificateoperatorMay create on certificates
Import a certificateadminMay create on certificates
Renew several at once (bulk renew)operatoroperator on every selected certificate

Distributions​

A distribution belongs to its certificate.

ActionProject roleNeeded
See the certificate's distributionsviewerviewer on the certificate
Link, edit, unlink, run, dry run, roll backoperatoroperator on the certificate and viewer on the module and on every target and target group it deploys to, override targets included

If the module reaches a single target the user was not granted, the action is refused with the module … deploys to a target you have no access to.

Targets​

ActionProject roleRole on the target
See it in the list, open it, see its usage and host keyviewerviewer
Edit, delete, approve a changed SSH host keyoperatoroperator
Run its health checkadminadmin
Create a targetoperatorMay create on targets

A target's usage view lists only the certificates the user can see.

Target groups​

ActionProject roleNeeded
See it in the list, open it, list its membersviewerviewer on the group. The member list shows only the targets the user can see.
Edit, deleteoperatoroperator on the group
Add or remove membersoperatoroperator on the group and viewer on each target added or removed
Create a group (with initial members)operatorMay create on target groups, and viewer on each initial member

Credentials, path sets, action sets, modules, variables​

ResourceSee it (list, open)CreateEdit, deleteOther
Credentialviewerproject admin + May createadmin on itTest it: admin on it
Path setviewerproject operator + May createoperator on it
Action setviewerproject operator + May createoperator on itSee the variables it uses: viewer on it
Moduleviewerproject operator + May createoperator on itHealth check: admin on it. Usage: viewer on it (shows only the certificates the user can see).
Variableviewerproject operator + May createoperator on it

A credential's secret reference (the external store path) is shown only to an admin of that credential.

Certificate authorities, DNS, zones, secret stores​

ResourceSee it (list, open, usage)CreateEdit, deleteOther
ACME accountviewerproject admin + May createadmin on itValidate: admin on it
AD CS connectionviewerproject admin + May createadmin on itTest, sync templates: admin on it
CA connectionviewerproject admin + May createadmin on itTest: admin on it
DNS credentialviewerproject admin + May createadmin on itTest: admin on it
Zoneviewer (also its certificates and rate limits)project admin + May createadmin on it
Secret storeviewerproject admin + May createadmin on itTest: admin on it

A resource's usage view lists only what the user can see: the certificates of an ACME account, AD CS or CA connection, and the zones of a DNS credential.

Discovery and notifications​

ResourceSee itCreateEdit, deleteOther
Discovery sourceviewer (also its runs, endpoints, locations, certificates and CT observations)project admin + May create; a server certificate scan also needs admin on every target, group and group member it readsadmin on it (a server certificate scan: the same target rule)Scan now: operator on it
Notification channelviewerproject admin + May createadmin on itSend a test: admin on it
Notification ruleviewerproject admin + May createadmin on it

The discovered inventory follows the sources. A restricted user sees a discovered certificate only when a discovery source it was granted has seen it (on an endpoint, or as a CT-log entry). The same holds for findings, the discovery summary and the cryptographic inventory. A certificate seen only by other sources is not found. A granted server certificate scan shows everything it read — target names, addresses, error texts, file paths and store entries — whatever the user's grants on those targets. Changing a finding's status needs operator in the project and a finding the user can see.

A rule only reports what its owner can see. A rule created or last edited by a user whose role is limited to granted resources delivers only events about certificates that user can see at the moment of the event. Events about no certificate are not delivered through such a rule. Discovery events (discovery.*) are about discovery sources instead: such a rule delivers one when its owner is granted at least one of the sources the event names — its copy then names only those sources — and each per-source summary reaches only the rules of users granted that source. Findings of a certificate no endpoint serves any more name no source and reach only rules without that restriction. An edit by a whole-project admin keeps the rule's owner. If that user is deleted or loses its role in the project, the rule delivers nothing at all; recreate it as a whole-project admin to make it report everything again.

Using one resource in another​

Picking a resource inside another needs viewer on the picked one. A resource the user cannot see is refused as not found, exactly like an id that does not exist.

WhereNeeds viewer on
A target's credentials (the default credential, the SMTP password and PKCS#12 passphrase slots)each credential
An SSH or WinRM target's path set and action seteach of them
A target group's default credentialthe credential
A module's targets block (create, and an edit that changes the configuration)every target, target group and credential it names
A distribution: link, edit, run, dry run, roll back, unlinkthe module, every target and group it deploys to, and the path and action sets an override selects
A remote picker on a saved target (module browse)the target's own credential
Issuing a new certificateits ACME account (or AD CS / CA connection) and its zone
A zone's DNS credential (create, and an edit that changes it)the DNS credential
A credential read from a secret storethe secret store
A notification rule's channelthe channel
A secret store's authentication credentialthe credential

Editing an object resends the references it holds. A target that uses a credential or path set the user cannot see therefore cannot be saved by that user, even when the field is not changed: grant the referenced resource, or ask someone who sees it.

Jobs, approvals and project settings​

ActionProject roleNeeded
See a job, its logsviewerviewer on the job's certificate. Jobs that belong to no certificate are not shown.
Retry or cancel a jobadminadmin on the job's certificate
Approve, reject or execute someone's approval requestadminadmin on the request's resource: the certificate for certificate operations and distribution actions; the target, target group, module, path set, action set or variable for a configuration change. A creation request needs May create on its type.
Change the project, its certificate policy, or another user's grantsadmina whole-project role
Create, edit, delete or preview a discovery tag ruleadmina whole-project role (tag rules apply to the whole project's inventory)
Browse a remote system with an unsaved target (the pickers in a new target's form)adminMay create on targets
Browse a saved target with a different credentialadminadmin on the target and viewer on the credential

Nobody can approve their own request. A restricted admin's Pending reviews list shows only the requests they can review.

Approval gates​

Approval gates compare the user's role on the resource. A restricted user with admin on a target edits it directly, like any admin, and the change is recorded as auto-executed. With operator on it, the same edit becomes an approval request when the project's approval policy gates configuration changes for that user. When a creation request is approved and executed, the requester gets the role they create with on the new resource, not the approver. An approved change runs with the requester's access, not the approver's: everything it references (a credential, a module, a target, a path or action set) must still be one the requester may use, otherwise the execution fails with the same refusal the direct request would have got.

What a restricted user sees​

ScreenWhat is shown
Certificates, Targets, Target groups lists, CSV export, a zone's certificatesOnly the granted resources
A resource that was not grantedNot found, exactly like one that does not exist (API: 404)
A resource seen without the role an action needsThe action button is hidden. The API answers 403 with code ACCESS_DENIED (the same code marks any refusal for a missing role — on the resource or on the project).
Dashboard, the header's Healthy / Expiring / Failed counts, 47-day readinessCounts and lists cover only the granted certificates
JobsOnly jobs of granted certificates
Notification historyOnly entries about granted certificates
Project audit logEntries the user made, and entries about resources the user can see. Everything else is hidden — entries about users, groups and grant changes, the project itself, approval and certificate policies, tag rules, distributions, jobs, bulk actions, discovery rows and live pickers are shown only when the user made them. Opening an entry and the CSV / JSON export follow the same rules (the project's own entry route).
Delete refused because of dependentsDependents the user cannot see are counted but not named
Credentials, path sets, action sets, modules, variables listsOnly the granted ones
A target's usageOnly the modules the user can see
An action set's variable checkLists only the variables the user can see, but never reports a variable the user cannot see as missing (it exists and is used when the action runs)
ACME accounts, custom ACME CAs, AD CS and CA connections, DNS credentials, zones, secret stores lists (and the certificate wizard's pickers)Only the granted ones
Discovery sources, notification channels and rules listsOnly the granted ones
Discovered certificates, endpoints, servers and a server's page, findings and a finding's history, the discovery summary, Overview, Insights, Activity and Quantum readinessOnly what the granted sources found (see the limit below)
Discovery tag rules listThe rules are listed, but each rule's matched count and time are left out (they count the whole project)

How much discovery data a restricted user can see​

What a user limited to some discovery sources sees in the discovered inventory and the findings is worked out on every request from the certificates those sources found. Measured on MongoDB 8.3, this works up to about 185,000 distinct certificates found by the granted sources and fails at 190,000. Past that limit the discovery pages and their API answer 503 with code: DISCOVERY_VISIBILITY_UNAVAILABLE instead of an empty list — grant fewer sources, or give the user the whole project. Users who see the whole project are not affected.

When grants disappear​

EventGrants removed
Any granted resource is deletedEvery grant on it
The user's role in the project is removed (Roles dialog)The user's grants in that project
The user is deletedAll of the user's grants
A user group is deletedAll of the group's grants
A user group's role in the project is removedThe group's grants in that project
The project is deletedEvery grant in the project

Switching a role back to Whole project keeps the grants. They apply again if the role is limited later.

Multi-node installs​

A node running an older version ignores the scope and would show such a user the whole project. A user's role cannot be limited to granted resources until every node runs a version that supports it (nor can a group be given any role). Until then the Roles dialog answers every node must run a version that supports resource grants… (API: 409 CLUSTER_UPGRADE_REQUIRED) and names the nodes that still need the upgrade.

Known limitations​

  • A certificate's page names its ACME account (or connection) and zone even when the user has no grant on them, and renewing or re-issuing a granted certificate does not need grants on its account or zone: they belong to the certificate. Only issuing a new certificate does.
  • Deploys, dry runs and health checks use every variable of the project and each target's own credential, whether or not the user who started them can see those: running needs access to the certificate, module and targets, not to their settings.
  • A target group's Target count includes targets the user cannot see.
  • The Pending reviews list of a restricted admin is filtered page by page, so a page can show fewer rows than its size.
  • A discovered certificate's Managed tag links to the managed certificate even when the user has no grant on it; opening it then shows not found.
  • If a user holds two roles in one project, one Whole project and a higher one Only granted resources, the lower role covers every resource and the higher role applies only to the granted ones.

Troubleshooting​

The Grants button is greyed out​

Save the role with Only granted resources first (click OK), then reopen Roles.

A member does not appear in the Access picker​

The picker lists only members (users and groups) whose role in the project is limited to granted resources. A member with a whole-project role already reaches the resource. A user's role and scope there include the roles it has through its groups.

The user sees "not found" for a certificate that exists​

The user has no grant on it and no grant on every certificate. Grant it on the certificate's Access tab or in the user's Grants.

The user can see a target but cannot edit it​

Their effective role on it is viewer. Either the grant is viewer, or their project role is viewer, which caps every grant.

"credential … not found" or "path set … not found" while saving a target​

The target uses a credential, path set or action set the user has no grant on. See Using one resource in another.

"deploys to a target you have no access to"​

Linking or running a distribution needs viewer on every target and target group of the module, including override targets. Grant the missing targets, or use a module that reaches only granted ones.

API​

MethodPathPurpose
PUT/users/{id}/rolesscope: "granted" on a project role
GET/projects/{projectId}/my-accessThe caller's own standing per type (enforced, all, can_create)
GET/projects/{projectId}/membersMembers with their role and scope
GET / PUT/projects/{projectId}/grants/{resourceType}/{resourceId}The grants on one resource
GET / PUT/projects/{projectId}/users/{userId}/grantsOne user's grants in the project
GET / PUT/projects/{projectId}/groups/{groupId}/grantsOne user group's grants in the project

Narrowed resources carry access_role, the caller's effective role on them, in list and detail responses when the caller is restricted. Full details: API reference → Project access.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Groups and Resource Grants (Least Privilege)YouTube ↗