Configure authorization and permissionsGrafana Cloud Access Policies

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.

Grafana Cloud Access Policies will eventually replace Grafana Cloud API keys. Until that time, use the access policies and tokens wherever possible, and only use the Cloud API keys for scopes not covered by Grafana Cloud Access Policies.

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.

Grafana Cloud migration from API keys to access policies

A legacy Grafana Cloud API key with the proper role allows interacting programmatically with the Grafana Cloud API and hosted services. Each API key is tied to an organization and provides Admin, Editor, and Viewer roles. These roles apply at the organization level and include all stacks, services, 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 interactions with Grafana Cloud resources using access policies and tokens. The tokens identify requests, and an authorization mechanism respects the controls defined by the access policies. These access policies and tokens provide stack-specific policies and tokens, label-based access control (LBAC), define specific scopes, and provide token expiration.

CapabilityLegacy Grafana Cloud API keysNew Grafana Cloud Access Policies
Control based at which levelOrganization levelOrganization or stack level
PermissionsViewer, Editor, Admin rolesLimited granular scopes
Token expirationNot availableAvailable
Label-based access controlNot availableAvailable, with read scopes for metrics and logs

Grafana Cloud Access Policies API and plugin

You can use access policies via the API or the Grafana Cloud Access Policies Plugin. The API lets you manage access policies and tokens across an organization and all of its stacks. 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.

The Cloud Access Policies Plugin allows access policies and tokens to be managed for a specific stack. Once installed, your Grafana account must have the Admin role to use the plugin.

The Grafana Cloud Access Policies Plugin UI.
The Grafana Cloud Access Policies Plugin UI.

Access policies

An access policy is created using either the API or by using the Grafana Cloud Access Policies Plugin. All access policies and tokens created using the plugin are specific to a stack. 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.

You can specify an organization or stack ID. The org realm type can be used for applying access policies to any stack within the selected 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 using the Cloud Access Policy API or by using the Grafana Cloud Access Policy Plugin. Any tokens defined using the plugin are specific to the stack where they are created.

Scopes

A scope defines an action (for example, metrics:read, metrics:write) an entity (represented by a presented token) is allowed to perform. The available scopes let you define the actions used with metrics, logs, traces, alerts, rules, and access policies.

ServiceRequested actionPermissionsScope identifier
metricsPublish or query metrics.read, writemetrics:read, metrics:write
logsPublish or query logs.read, writelogs:read, logs:write
tracesPublish or query traces.read, writetraces:read, traces:write
alertsView or create alerts in alert manager or configure an instance of alert manager.read, writealerts:read, alerts:write
rulesView or create Prometheus alerting and recording rulesread, writerules:read, rules:write
accesspoliciesView or create access policies and tokensread, write, deleteaccesspolicies: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.

Using the Grafana Cloud Access Policies Plugin, the same set of scopes, metrics:read, logs:read, and traces:read, are selected using checkboxes.

The available scopes in the Cloud Access Policies plugin.
The available scopes in the Cloud Access Policies plugin.

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.