Grafana Cloud Access Policies
Grafana Cloud Access Policies implement an authorization process for actions requested on Grafana Mimir (metrics), Grafana Loki (logs), Grafana Tempo (traces), and Grafana Cloud Alerts services, as well as for some Grafana Cloud API endpoints. This page describes cloud access policies concepts. To create an access policy and associated token, follow the instructions to authorize your service.
Caution
Grafana Cloud Access Policies have replaced Grafana Cloud API keys. Use access policies and tokens instead of Cloud API keys.
Access policies contain tokens, which grant other applications access to take certain actions on your Grafana Cloud hosted services. You can create one or more tokens for each access policy and use those tokens when configuring the Grafana Agent, setting up a Grafana data source, provisioning alerts, or otherwise interacting with Grafana Cloud’s APIs.
An individual access policy is composed of one or more scopes and a realm.
The scope is a specific action on a specific service.
For example, the metrics:read
scope defines an action that reads data from the Mimir service.
The logs:write
scope defines an action that creates data in the Loki service.
The realm identifies whether the scope will be applied during authorization to an org
(organization) or to a stack
(a set of services).
A decision to authorize an API request is made by comparing the request’s token with the associated Grafana Cloud access policy. If the API request performs an action that is allowed by an access policy (identified by the token), the API request is authorized.
In addition to scopes and realms, access policies also support IP range based access controls. For more information, refer to IP range based access control.
Grafana Cloud migration from API keys to access policies
A legacy Grafana Cloud API key with the proper role allows programmatic interaction with the Grafana Cloud API and hosted services.
Each API key is linked to an organization and provides Admin
, Editor
, and Viewer
roles.
These roles apply at the organization level which includes all stacks and data within an organization.
These API keys lack fine-grained access control: access is controlled only by a few roles.
To address this issue, Grafana Cloud Access Policies provide granular access control over Grafana Cloud by adding the ability to limit access to a single stack, select fine-grained scopes, define label filters, and set token expirations. One or more tokens are created for an access policy, and these tokens are only capable of what is defined within their access policy.
Capability | Legacy Grafana Cloud API keys | New Grafana Cloud Access Policies |
---|---|---|
Control based at which level | Organization level | Organization or stack level |
Permissions | Viewer, Editor, Admin roles | Limited granular scopes |
Token expiration | Not available | Available |
Label-based access control | Not available | Available, with read scopes for metrics and logs |
IP range based access control | Not available | Available |
Use with the API, Grafana Stacks, and Cloud Portal
You can use access policies via the API, the Grafana Administration settings, and the Cloud Portal.
The Grafana Cloud Access Policies API adds two new API endpoints points for access policies (/v1/accesspolicies
) and tokens (/v1/tokens
).
These endpoints are described in the Grafana Cloud API documentation.
Access policy interface | Access policies for stacks | Access policies for an organization | Requires Cloud Portal Admin role | Requires Grafana Admin role |
---|---|---|---|---|
Cloud API | Yes | Yes | Yes | No |
In a Grafana Stack | Single stack where created | No | No | Yes |
Cloud Portal | Yes | Yes | Yes | No |
The Access Policies page in the Cloud Portal lets you manage access policies and tokens across an organization and all of its stacks.
![The Access Policies page in the Cloud Portal The Access Policies page in the Cloud Portal](/static/img/docs/grafana-cloud/access-policies/policies-cloud-portal.png)
The Cloud access policies in the Grafana Administration settings allow access policies and tokens to be managed for a specific stack.
![The Cloud access policies page. The Cloud access policies page.](/static/img/docs/grafana-cloud/access-policies/access-policies-ui.png)
Access policies
Each access policy has one or more tokens, a realm, one or more scopes, and optional label filters. The table above summarizes access policies for stacks and organizations.
Each access policy has a unique name within an organization. Access policies are only used within one Grafana Cloud organization and do not span multiple organizations.
For more information about stacks and organizations, refer to the Grafana Cloud Stack section of Use the Cloud Portal to manage your Grafana Cloud account.
Realms
A realm has a type, such as organization or stack, an identifier, and a list of label policies. A realm must be specified when using the API or the Access Policies page in the Cloud Portal, but the realm is automatically set when managing access policies in the Grafana Administration settings.
You can specify an organization or stack ID.
The org
realm type can be used for applying access policies to any stack within an organization.
If you specify a stack
realm type, then the tokens under that particular policy can be used only for that stack.
Tokens
A token belongs to an access policy and is used programmatically to identify the entity that requests actions on resources. Authorization is based on rules defined by an access policy and the token presented with a request. An access policy can have one or more tokens.
Tokens are created in the same places as access policies. You can use the Cloud Access Policy API, the Access Policies page in the Cloud Portal, or the Cloud access policies page in the Grafana Administration settings. Any tokens defined in the Grafana Administration settings are limited to that Grafana’s stack.
Scopes
A scope defines which permissions a token has.
For example, metrics:read
, metrics:write
, etc.
Scopes let you specify which actions can be performed with resources such as metrics, logs, traces, alerts, rules, and access policies.
Additional scopes are available within the Cloud Portal UI.
Service | Requested action | Permissions | Scope identifier |
---|---|---|---|
metrics | Publish or query metrics. | read, write | metrics:read , metrics:write |
logs | Publish or query logs. | read, write | logs:read , logs:write |
traces | Publish or query traces. | read, write | traces:read , traces:write |
alerts | View or create alerts in alert manager or configure an instance of alert manager. | read, write | alerts:read , alerts:write |
rules | View or create Prometheus alerting and recording rules | read, write | rules:read , rules:write |
accesspolicies | View or create access policies and tokens | read, write, delete | accesspolicies:read , accesspolicies: write , accesspolicies: delete |
The scopes you select limit the Grafana Cloud services you can query and the actions you can perform using the given access policy.
Let’s say that you want to read metrics, traces, and logs and not write them.
In this case, the access policy includes the metrics:read
, logs:read,
and traces:read
scopes.
In the Grafana Administration settings, the same set of scopes, metrics:read
, logs:read
, and traces:read
, are selected using checkboxes.
![The available scopes in Cloud access policies within a stack. The available scopes in Cloud access policies within a stack.](/static/img/docs/grafana-cloud/access-policies/policies-plugin-scopes.png)
The Access Policies page in the Cloud Portal also has these scopes. You can specify a different realm using the Access policies page in the Cloud Portal.
LabelPolicy or Label selectors
A LabelPolicy is a set of Prometheus label selectors used to limit metrics and logs data to specific label criteria.
For example, adding a label policy of {env="dev"}
returns matches from the dev environment.
If you create an access policy with that label selector, then entities with a token for that access policy will only be able to query for metrics or logs that include the { env="dev" }
label.
LabelPolicies are only available for reading logs and metrics.
In the Cloud Access Policies Plugin, LabelPolicies
are referred to as Label selectors.
Refer to Using label-based access control with access policies for additional information.
IP range based access control
You can use IP range based access control with access policies to limit access to your Grafana Cloud services based on IP subnets. When configured, all tokens created under the access policy will obey the settings. Connections initiated from IP addresses outside of the specified ranges will be denied.
Refer to Using IP range based access control with access policies for additional information.
Was this page helpful?
Related resources from Grafana Labs
![Getting started with the Grafana LGTM Stack](/static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=200 200w, /static/assets/featured/getting-started-with-grafana-lgtm-stack-amer_featured.png?w=400 400w)
![Intro to Kubernetes monitoring in Grafana Cloud](/media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=200 200w, /media/webinar/Screenshot-2024-02-12-at-4.09.30-PM.png?w=400 400w)
![Building advanced Grafana dashboards](/media/webinar/AMER_buildadv_notxt.png?w=200 200w, /media/webinar/AMER_buildadv_notxt.png?w=400 400w)