Documentation Grafana Cloud Security and account management Authentication and authorization Grafana Cloud Access Policies

Grafana Cloud Access Policies

Grafana Cloud Access Policies implement an authorization process for:

• Actions requested on instances of your Grafana Cloud Stack, such as integrating with Grafana Mimir (metrics), Grafana Loki (logs), Grafana Tempo (traces), and more.
• Interacting with Grafana Cloud API endpoints.

This page describes Cloud Access Policy concepts. To create an Access Policy and associated token, follow the instructions to authorize your service.

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 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.

For an introduction to Grafana Cloud Access Policies, read the November 22, 2022, blog post by Ryan Melendez, “Grafana Cloud Access Policies: Say hi to the new Cloud API keys.”

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.

The Access Policies page in the Cloud Portal lets you manage access policies and tokens across an organization and all of its stacks.

The Cloud access policies in the Grafana Administration settings allow access policies and tokens to be managed for a specific stack.

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.

Token expiration

Tokens can optionally have an expiration date. If a token is configured to expire, it stops working after the specified date. You can locate expired tokens in the Access Policies page, where they are indicated as “Expired.”

Before a token reaches its expiration date, warning emails are sent to the relevant administrators, depending on the realm in the token’s access policy:

• stack realm: Warning emails are sent to the admins of the corresponding stack.
• org realm: Warning emails are sent to the admins of the associated Cloud Portal organization.

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.

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 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.

Migrate Grafana Cloud API keys to access policies

To access legacy Grafana Cloud API keys, log into your Grafana Cloud instance, click on Administration in the left-side menu, then Users and access -> API Keys.

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 the token expiration dates. One or more tokens are created for an access policy, and these tokens are only capable of what is defined within their access policy.