How Grafana Cloud access controls work together
Grafana Cloud has more than one access control feature because it protects more than one kind of resource. Your billing details, your dashboards, and your log lines each need a different boundary, so each is governed separately.
This page describes the five building blocks of access control inside a Grafana stack, the three layers that Grafana Cloud adds around them, the features that are often confused with each other, and the order in which Grafana evaluates them.
The five building blocks
Inside a stack, access control is built from five features. Each one answers a single question about a request, and each one depends on the one before it.
The following three design rules follow from this sequence.
- Identity lives outside Grafana. Your identity provider is the source of truth for who exists. SSO answers who is signing in. SCIM answers who should exist and in which teams. Keep the two configured separately.
- Grant access to teams, never to individual users. A person’s access is the sum of their teams, so there is one place to reason about who can do what.
- Capability and content are separate. Roles grant features, such as using Explore or querying a data source. Folders decide which dashboards, alert rules, and library panels you can touch. An
Editorcan’t edit a folder until that folder grants access.
The three layers
Two things sit outside the five blocks in Grafana Cloud: the Cloud Portal, which manages your organization and every stack, and machine access, which uses tokens instead of a sign-in. A third layer is the data layer which includes the telemetry backends that hold your metrics, logs, traces, and profiles.
The Grafana Cloud Portal
The Cloud Portal is where you manage your Grafana Cloud organization which includes billing, subscriptions, stacks, organization members, and access policies.
People sign in with a Grafana.com account using basic authentication, social login, or SAML (currently in private preview). What they can do is governed by their Cloud Portal role. For the tasks each role covers, refer to Grafana Cloud user roles and permissions.
Machines authenticate to this layer with access policy tokens, which also reach the telemetry backends described in Data.
Grafana Cloud stacks
A stack is a Grafana instance at an address such as your-org.grafana.net, together with the Mimir, Loki, Tempo, and Pyroscope backends behind it.
By default the Cloud Portal is the identity provider for every stack in your organization, and a person’s Cloud Portal role becomes their role in each stack. You can instead connect an identity provider directly to a stack, which decouples the two layers. Refer to Configure authentication and authorization for the two models.
Inside a stack, the five building blocks apply in order:
- SSO establishes who the user is and sets their basic role of
Admin,Editor,Viewer, orNone. - Teams group users. You populate them through SCIM, through team sync, or by hand.
- RBAC grants fixed or custom roles to teams, and also to users and service accounts. Data source permissions, which control who can query, edit, or administer each data source, are part of this block.
- Folder and dashboard permissions decide which content each team can view, edit, or administer, and override the basic role for those resources.
- LBAC filters which rows a query returns from a shared data source.
Machines authenticate to this layer with service account tokens.
Data
The telemetry backends hold your metrics, logs, traces, and profiles. Nobody signs in to this layer directly. Requests arrive either through a stack data source or as HTTP API calls carrying an access policy token.
Two features filter what a request can read, and both are called label-based access control. Refer to The two kinds of LBAC.
Access management features compared
Several access features share a name or a purpose, and a common cause of an access problem is picking the wrong one. The following comparisons cover the four most common points of confusion: roles with the same names in two layers, two kinds of machine credential, three kinds of stack permission that layer on each other, and two features both called LBAC.
How Cloud Portal roles compare to stack roles
Both use the names Admin, Editor, and Viewer, but they govern different things.
A Cloud Portal Admin manages the Grafana.com organization which includes billing, stacks, members, and access policies.
A stack Admin manages one Grafana instance which includes dashboards, data sources, users, and plugins.
In the default model, a person’s Cloud Portal role propagates to every stack, so the same person holds both. When you connect an identity provider to a stack, the roles separate, and you set stack roles through your identity provider or in Grafana.
Service accounts compared to access policies
Both authenticate machines rather than people, and each reaches APIs the other can’t.
A service account token can’t call the Mimir, Loki, or Tempo APIs directly, although it can run queries through the Grafana data source query API, and an access policy token can’t call the Grafana HTTP API. If a request fails with an authorization error, check that you’re using the right kind of token before you change any permissions.
Basic roles, RBAC, and resource permissions
These stack level features stack on top of each other rather than replacing each other. Every permission in RBAC is an action plus a scope, and a role is a bundle of those permissions. Grafana has three types of roles:
- Basic roles are the organization-wide baseline. Every user has exactly one, usually set by SSO role sync.
Viewercan read every dashboard by default. AssignNoneto users whose access should come entirely from the roles below. If you modify a basic role instead, Grafana still adds newly introduced permissions to it on upgrade, soNoneplus team roles is the pattern for full control. - Fixed roles are built-in, read-only capability packs maintained by Grafana, such as
fixed:datasources:explorer. - Custom roles are action and scope sets you define yourself, for capabilities the fixed roles don’t bundle the way you need.
Two more features decide what those roles can reach:
- Folder and dashboard permissions apply to specific content and override the basic role for it. Folder permissions cascade to subfolders and to the alert rules and library panels inside. Roles grant capability while folders grant content.
- Data source permissions of
Query,Edit, andAdmincontrol access to each data source.
Permissions are additive,so a user gets the highest level of access granted by any of these. When you design a stack, make these choices, in this order:
- Choose a baseline. A transparent stack sets the SSO baseline to
Viewer, so everyone can read shared context, and uses team roles to grant changes. A closed stack sets the baseline toNone, so every useful view starts as a team grant. - Assign roles to teams, not users. Prefer fixed roles, and write a custom role only when no fixed role fits.
- Let folders determine ownership. Set permissions once at the top level folder for each team and let child folders inherit.
- Don’t leave standing administrators. Treat
Adminas temporary. Grant a reduced custom administrator role to the on-call team that needs it, and remove it when the shift ends, rather than granting it to individuals indefinitely.
For a rollout sequence, refer to Plan your RBAC rollout strategy.
The two kinds of LBAC
Both features filter query results by label, and they’re configured in different places by different people.
Keep the following in mind when you use either feature.
- Access policy label selectors override LBAC rules on a data source. If you configure LBAC rules on a data source, make sure the access policy its credentials come from has no label selectors.
- A team with query access and no rules sees everything. Write rules for every team that can query an LBAC-enabled data source. Because permissions are additive, a user who belongs to one team with rules and one team without is still restricted by the rules.
- LBAC rules apply to administrators too, if the administrator belongs to a team that has rules.
- You must create an LBAC-enabled data source manually. You can’t add rules to a provisioned data source, such as the default Prometheus data source in your stack, although you can provision the rules themselves with Terraform.
For details, refer to Use label-based access control (LBAC) with access policies and Label-based access control (LBAC) for data sources.
How a query is authorized
A request passes the building blocks in order. SSO establishes identity, RBAC decides capability, LBAC is the final barrier before the database. When someone runs a query in a dashboard against a Grafana Cloud data source, the request passes each of the following in turn.
- Stack authentication establishes who the user is and their basic role.
- RBAC and data source permissions decide whether the user can query that data source at all.
- LBAC rules for data sources add the label or attribute filters for the user’s teams.
- The data source credentials, which are an access policy token, carry the scopes and any label selectors on that policy.
- The backend returns only the data that satisfies every filter applied along the way.
Because the token’s label selectors are applied last and override the data source rules, use one mechanism or the other for a given data source, not both.


