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:
| Group | Resource types |
|---|---|
| Certificates | Certificates, with everything that belongs to one: its distributions, jobs, versions, keys, events and notification history |
| Distribution | Targets, Target groups, Credentials (module credentials), Path sets, Action sets, Modules (module configurations), Variables (project variables) |
| Issuance | ACME accounts, Custom ACME CAs, AD CS connections, CA connections, DNS credentials, Zones, Secret stores |
| Discovery | Discovery sources, with what they found: their runs, endpoints and CT observations, and the discovered certificates and findings |
| Notifications | Notification 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:
| Scope | Meaning |
|---|---|
| Whole project (default) | The role covers every resource in the project. Every role that existed before this feature has this scope. |
| Only granted resources | The 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:
| Grant | What it gives |
|---|---|
| A role on one resource | That resource (for example one certificate or one credential), at viewer, operator or admin |
| A role on every resource of a type | For example all certificates or all credentials of the project, including ones created later |
| May create on a type | Permission 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 role | Grant on the resource | Effective role on it |
|---|---|---|
| admin | admin | admin |
| admin | viewer | viewer |
| operator | admin | operator: the project role caps the grant |
| viewer | admin | viewer |
| operator | no grant on it or on its type | none: the resource does not exist for them |
| operator | every target: viewer + this target: admin | operator on this target, viewer on the others |
A grant on a target group gives nothing on the targets in it. Each target is granted on its own.
Setting it up
- 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.
- 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
| Action | Who may do it |
|---|---|
| Limit a role to granted resources (Roles dialog) | Organisation owner only |
| Edit a user's grants | An 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 resource | Anyone 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
| Action | Project role | Role 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 candidates | viewer | viewer |
| Edit owner, description, auto-renew, renewal threshold and mode, key rotation | operator | operator |
| Renew, re-issue, revoke, validate manual DNS, run the DNS check, download | operator | operator |
| Re-import | admin | admin |
| Delete | admin | admin |
| Issue a new certificate | operator | May create on certificates |
| Import a certificate | admin | May create on certificates |
| Renew several at once (bulk renew) | operator | operator on every selected certificate |
Distributions
A distribution belongs to its certificate.
| Action | Project role | Needed |
|---|---|---|
| See the certificate's distributions | viewer | viewer on the certificate |
| Link, edit, unlink, run, dry run, roll back | operator | operator 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
| Action | Project role | Role on the target |
|---|---|---|
| See it in the list, open it, see its usage and host key | viewer | viewer |
| Edit, delete, approve a changed SSH host key | operator | operator |
| Run its health check | admin | admin |
| Create a target | operator | May create on targets |
A target's usage view lists only the certificates the user can see.
Target groups
| Action | Project role | Needed |
|---|---|---|
| See it in the list, open it, list its members | viewer | viewer on the group. The member list shows only the targets the user can see. |
| Edit, delete | operator | operator on the group |
| Add or remove members | operator | operator on the group and viewer on each target added or removed |
| Create a group (with initial members) | operator | May create on target groups, and viewer on each initial member |
Credentials, path sets, action sets, modules, variables
| Resource | See it (list, open) | Create | Edit, delete | Other |
|---|---|---|---|---|
| Credential | viewer | project admin + May create | admin on it | Test it: admin on it |
| Path set | viewer | project operator + May create | operator on it | |
| Action set | viewer | project operator + May create | operator on it | See the variables it uses: viewer on it |
| Module | viewer | project operator + May create | operator on it | Health check: admin on it. Usage: viewer on it (shows only the certificates the user can see). |
| Variable | viewer | project operator + May create | operator 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
| Resource | See it (list, open, usage) | Create | Edit, delete | Other |
|---|---|---|---|---|
| ACME account | viewer | project admin + May create | admin on it | Validate: admin on it |
| AD CS connection | viewer | project admin + May create | admin on it | Test, sync templates: admin on it |
| CA connection | viewer | project admin + May create | admin on it | Test: admin on it |
| DNS credential | viewer | project admin + May create | admin on it | Test: admin on it |
| Zone | viewer (also its certificates and rate limits) | project admin + May create | admin on it | |
| Secret store | viewer | project admin + May create | admin on it | Test: 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
| Resource | See it | Create | Edit, delete | Other |
|---|---|---|---|---|
| Discovery source | viewer (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 reads | admin on it (a server certificate scan: the same target rule) | Scan now: operator on it |
| Notification channel | viewer | project admin + May create | admin on it | Send a test: admin on it |
| Notification rule | viewer | project admin + May create | admin 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.
| Where | Needs 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 set | each of them |
| A target group's default credential | the 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, unlink | the 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 certificate | its 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 store | the secret store |
| A notification rule's channel | the channel |
| A secret store's authentication credential | the 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
| Action | Project role | Needed |
|---|---|---|
| See a job, its logs | viewer | viewer on the job's certificate. Jobs that belong to no certificate are not shown. |
| Retry or cancel a job | admin | admin on the job's certificate |
| Approve, reject or execute someone's approval request | admin | admin 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 grants | admin | a whole-project role |
| Create, edit, delete or preview a discovery tag rule | admin | a 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) | admin | May create on targets |
| Browse a saved target with a different credential | admin | admin 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
| Screen | What is shown |
|---|---|
| Certificates, Targets, Target groups lists, CSV export, a zone's certificates | Only the granted resources |
| A resource that was not granted | Not found, exactly like one that does not exist (API: 404) |
| A resource seen without the role an action needs | The 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 readiness | Counts and lists cover only the granted certificates |
| Jobs | Only jobs of granted certificates |
| Notification history | Only entries about granted certificates |
| Project audit log | Entries 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 dependents | Dependents the user cannot see are counted but not named |
| Credentials, path sets, action sets, modules, variables lists | Only the granted ones |
| A target's usage | Only the modules the user can see |
| An action set's variable check | Lists 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 lists | Only 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 readiness | Only what the granted sources found (see the limit below) |
| Discovery tag rules list | The 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
| Event | Grants removed |
|---|---|
| Any granted resource is deleted | Every grant on it |
| The user's role in the project is removed (Roles dialog) | The user's grants in that project |
| The user is deleted | All of the user's grants |
| A user group is deleted | All of the group's grants |
| A user group's role in the project is removed | The group's grants in that project |
| The project is deleted | Every 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
| Method | Path | Purpose |
|---|---|---|
| PUT | /users/{id}/roles | scope: "granted" on a project role |
| GET | /projects/{projectId}/my-access | The caller's own standing per type (enforced, all, can_create) |
| GET | /projects/{projectId}/members | Members with their role and scope |
| GET / PUT | /projects/{projectId}/grants/{resourceType}/{resourceId} | The grants on one resource |
| GET / PUT | /projects/{projectId}/users/{userId}/grants | One user's grants in the project |
| GET / PUT | /projects/{projectId}/groups/{groupId}/grants | One 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 →