Documentation Grafana Cloud Account management Authentication and authorization Grafana Cloud Access Policies Authorize your service with an access policy and token

Authorize your service with an access policy and token

You can manage Grafana Cloud Access Policies using the API, the Access Policies page in the Cloud Portal, or the Grafana Administration settings.

To use Grafana Cloud Access Policies, you need to:

1. Create an access policy
2. Create one or more tokens
3. Use the token to:
   • Authorize your agent or Grafana data source, or
   • Authorize Grafana Cloud API requests

Before you begin

• To manage access policies from the Grafana Administration settings, you must have the Admin role within that Grafana. However, to manage access policies in the Cloud Portal, you must have the Admin role within the Cloud Portal. These roles are set independently.

Create an access policy

Following the principle of least privilege, an access policy should only have the necessary scopes.

It is better to create multiple tokens for a human user account to use, each for specific tasks, than to create and always use a token with the abilities needed for the most privileged task. In other words, don’t just create a single token and use it for everything.

Consider whether the access policy needs to apply to only one stack or across multiple stacks within an organization. For example, since publishing metrics is done separately from reading metrics, consider having:

• One access policy to read metrics
• One access policy to write metrics

And similarly:

• One access policy to read logs
• One access policy to write logs

Depending upon how you are setting up your access policies, you may need to create more than one access policy and token.

If the access policies need to apply to multiple stacks within an organization, then the access policy (or policies) and tokens can be created in the Access Policies page in the Cloud Portal. If the access policies and tokens only apply to one stack, then you can configure access policies within that stack’s Grafana.

To use the API, refer to the Create an access policy section of the Grafana Cloud API document.

Create an access policy for a stack

To create an access policy using Cloud access policies:

1. Sign in to Grafana Cloud and start the stack where you wish to create the access policy.

2. Click Administration in the left-side menu and select Cloud access policies.

3. Click Create access policy.

4. Enter a Display Name for the access policy.

5. Optional: Update the Name field. This field is automatically populated with the Display name.

6. Select one or more scopes for the policy. Not all scopes are displayed by default. If you do not see the scope that you are looking for, (for example, stack:read) use the Add scope drop-down towards the bottom of the dialog, and select the scope you would like to configure.

7. Add Label selectors, if desired. The label selectors use Prometheus labels. You can use operators like != and =.
   Tip: Refer to Using label-based access control for additional information.

8. Add IP ranges, if desired.

   For more information, refer to Using IP range based access control with access policies.

9. Select Create to add the access policy.

Create an access policy for an organization

Organization-level access policies apply to all stacks within an organization unless you select specific stacks in the Realm field. To create an access policy using the organization’s Access Policies page:

1. Sign in to Grafana Cloud.

2. Select an organization in the drop-down at the top of the page.

3. Locate Security in the left-hand navigation and select Access Policies.

4. Select Create access policy.

5. Enter a Display Name for the access policy.

6. Optional: Update the Name field. This field is automatically populated with the Display name.

7. Optional: Select one or more stacks from the Realm drop-down. If no stack is selected, then the access policy applies across the organization.

8. Select one or more scopes for the policy.

9. Add Label selectors, if desired. The label selectors use Prometheus labels. You can use operators like != and =.
   Tip: Refer to Using label-based access control for additional information.

10. Add IP ranges, if desired.

    For more information, refer to Using IP range based access control with access policies.

11. Select Create to add the access policy.

Create one or more access policy tokens

Any data source that you use with Grafana Cloud requires a token that is associated with an access policy to use in requests from that data source to a service. For example, if you create an access policy specific for reading logs, then you will need to create a token for that policy that can be added to your Loki configuration.

To use the API, refer to the Create a token section of the Grafana Cloud API documentation.

To create a token for an access policy:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   1. From within a Grafana Stack: Click Administration and select Cloud access policies.
   2. Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Choose an access policy.
4. Select Add token to display the Create new token dialog.
   

5. Enter a Display name for the token.
6. Optional: Enter an Expiration date in year/month/day format. Leave the field blank to prevent the token from expiring.
7. Select Create to generate the token.
   

8. Select Copy to clipboard to copy the generated token.

Next, either add the token to your data source’s or agent’s configuration or save the token in a secure location like a password app so you can refer to it later.

Add the token to your agent or Grafana data source configuration

The token you created needs to be added to the agent or Grafana data source configuration to allow agents to include the token with any request sent to Grafana Cloud. If the API request does an action that is allowed by an access policy (identified by the token), then the API request will be authorized.

You can use these tokens with a data source in Grafana Cloud or with the tool that you use to send data to Grafana.

Grafana Cloud supports many integrations and data sources. The exact steps for adding the token to each integration and data source may vary. In general, agent or service configurations that reference a password or API key can be replaced with the token.

Creating a data source with a Grafana Cloud token in Grafana UI

Follow these steps to create or configure a data source in Grafana using a Cloud Access Policy token:

1. Copy the token: Start by copying the token associated with the service you are integrating (e.g., Loki, Prometheus, Tempo).
2. Navigate to Connections: In Grafana, open the left-side menu and select Connections.
3. Select or Add a Data Source: Use the filter to find the data source you want to add or update. When adding a new data source, Grafana will guide you to the configuration page for that source.
4. Configure Authentication:
   • Go to the Settings tab for the data source.
   • In the Basic Auth section, enter the required credentials:
     • For services like Loki, use the log tenant ID as the User.
     • Enter the Grafana Cloud token as the Password.
5. Save and Test: Click Save & Test to confirm the configuration. Grafana will verify the connection to ensure that it is correctly set up.

For further guidance and specific details, refer to the relevant integration documentation.

• Alertmanager
• Graphite
• Loki
• Prometheus
• Tempo

Creating a data source with a Grafana Cloud token using Terraform

You can provision a data source using a Terraform resource by providing a Cloud Access Policy token. Here is a sample Terraform configuration you can use as a base:

terraform Copy

// Provision a Cloud Access Policy
resource "grafana_cloud_access_policy" "test" {
  provider      = grafana
  region        = "eu"
  name          = "terraform-test-policy-assets"
  display_name  = "Terraform Test Policy ASSETS"
  scopes        = ["metrics:read", "logs:read", "metrics:write", "logs:write"]

  realm {
    type       = "org"
    identifier = data.grafana_cloud_organization.current.id

    label_policy {
      selector = "{namespace=\"default\"}"
    }
  }
}

// Provision a Cloud Access Policy token
resource "grafana_cloud_access_policy_token" "test" {
  region           = "eu"
  access_policy_id = grafana_cloud_access_policy.test.policy_id
  name             = "my-policy-token"
  display_name     = "My Policy Token"
  expires_at       = "2024-01-01T00:00:00Z"
}

# Provision a datasource using the access policy token we just made
resource "grafana_data_source" "prometheus" {
  provider            = grafana
  type                = "prometheus"
  name                = "mimir"
  url                 = "https://prometheus-us-central1.grafana.net/api/prom"
  basic_auth_enabled  = true
  basic_auth_username = "740141"

  json_data_encoded = jsonencode({
    httpMethod        = "POST",
    tokenName         = "terraform-test-policy-assets",
    prometheusType    = "Mimir",
    prometheusVersion = "2.4.0"
  })

  secure_json_data_encoded = jsonencode({
    basicAuthPassword = grafana_cloud_access_policy_token.test.token
  })
}

Use the token to authenticate Grafana Cloud API requests

To use the Grafana Cloud API, authenticate requests with an access policy token. Include the token in the Authorization header for all requests:

http Copy

GET https://grafana.com/api/instances/<STACK_SLUG>/plugins HTTP/1.1
Accept: application/json
Authorization: Bearer <CLOUD ACCESS POLICY TOKEN>

Requests to the Grafana Cloud API are authenticated using the Authorization header:

bash Copy

Authorization: Bearer <CLOUD ACCESS POLICY TOKEN>

Modify an access policy

You can change an access policy created within a stack using the Access Policy page in the Cloud Portal. However, an access policy created in the Cloud Portal and applied to a stack can not be modified using the Cloud access policies from within the stack; the policy has to be changed at the Access Policies page.

To use the API, refer to the Access Policies endpoint section of the Grafana Cloud API documentation.

To modify an access policy:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   • From within a Grafana Stack: Click Administration and select Cloud access policies.
   • Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Locate and select the access policy you wish to modify.
4. Modify the policy as desired and select Update to save the changes.

Delete an access policy token

Once a token has been created, it can not be modified. Removing the token prevents it from being used with any defined access policies.

For API instructions, refer to the Delete a token section of the Grafana Cloud API documentation.

To delete a token:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   • From within a Grafana Stack: Click Administration and select Cloud access policies.
   • Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Locate the access policy associated with the token you wish to remove.
4. Select the trash can icon to the right side to remove the token.
5. Confirm the removal by selecting Delete on the Delete token dialog.

Delete an access policy

Deleting an access policy removes all tokens associated with it. There may be a few minutes delay to apply everywhere.

To use the API, refer to the Access Policies endpoint section of the Grafana Cloud API documentation.

To delete an access policy:

1. Sign in to Grafana Cloud.
2. Navigate to the access policies page.
   • From within a Grafana Stack: Click Administration and select Cloud access policies.
   • Using the Cloud Portal: Select your organization, then under Security, select Access Policies.
3. Locate the access policy you wish to remove.
4. Select the trash can icon to the right side to remove the policy.
5. Confirm the removal by selecting Delete on the dialog.