Google authentication

This document explains how to configure authentication between Grafana and Google Cloud Platform (GCP). You must configure authentication before you can use the Google Cloud Monitoring data source to query metrics and SLOs.

All requests to Google APIs are performed on the server-side by the Grafana backend.

Before you begin

Before you configure authentication, ensure you have the following:

• A Google Cloud Platform project with the Monitoring API enabled.
• Permissions to create service accounts or configure GCE instance settings in your GCP project.
• Access to the Grafana data source configuration page.

Supported authentication methods

The Google Cloud Monitoring data source supports the following authentication methods:

Use a Google service account key file

Use this method when Grafana runs outside of Google Cloud Platform, or when you need explicit control over which credentials are used.

Each Grafana data source connects to one GCP project by default. To visualize data from multiple GCP projects, create one data source per project, or use service account impersonation.

Create a GCP service account and key file

To create a service account and download its key file:

1. Navigate to the APIs and Services Credentials page in the GCP Console.

2. Click the Create credentials dropdown and select Service account.

3. In Service account name, enter a name for the account.

4. Click Create and continue.

5. In the Grant this service account access to project section, select the Monitoring Viewer role from the Role dropdown.

6. Click Continue, then click Done.

7. In the service accounts list, click the service account you created.

8. Go to the Keys tab and click Add key > Create new key.

9. Select JSON and click Create.

   A JSON key file downloads to your computer.

10. Store the key file securely. It grants access to your Google Cloud data.

Upload the key file to Grafana

1. In Grafana, navigate to the Google Cloud Monitoring data source configuration page.
2. Under Authentication type, select Google JWT File.
3. Upload the JSON key file using one of the available methods (drag and drop, browse, or paste).
4. Click Save & test to verify the connection.

Grant access to multiple projects

You can configure a single service account to access multiple GCP projects:

1. Create a service account and key file following the steps above.
2. Note the service account email address (for example, [email protected]).
3. In each additional project you want to access:
   1. Navigate to IAM & Admin > IAM.
   2. Click Grant access.
   3. Enter the service account email address.
   4. Assign the Monitoring Viewer role.
   5. Click Save.
4. Use the original key file in Grafana. The service account can now access all configured projects.

Use GCE Default Service Account

When Grafana runs on a Google Compute Engine (GCE) virtual machine, it can automatically retrieve credentials from the GCE metadata server. This method doesn't require you to create or manage key files.

Prerequisites for GCE authentication

Before using this method, ensure the following:

• Grafana is running on a GCE virtual machine.
• The VM has a service account assigned with the Monitoring Viewer role.
• The VM has the Cloud Monitoring API scope enabled.

Configure the GCE instance

1. In the GCP Console, navigate to Compute Engine > VM instances.
2. Stop the VM if it's running (you can't change scopes on a running VM).
3. Click the VM name, then click Edit.
4. Under Service account, select a service account with the Monitoring Viewer role.
5. Under Access scopes, select Set access for each API and enable the Cloud Monitoring API (read-only).
6. Click Save and restart the VM.

Configure the data source

1. In Grafana, navigate to the Google Cloud Monitoring data source configuration page.
2. Under Authentication type, select GCE Default Service Account.
3. Click Save & test to verify the connection.

For more information about GCE service accounts, refer to the Google documentation on service accounts for instances.

Use Forward OAuth Identity

Use this method when your Grafana instance authenticates users with Google OAuth and you want each query to run as the signed-in user instead of as a shared service account. This enables per-user access control: a viewer who lacks Cloud Monitoring permissions on a project sees no data from that project, even when the dashboard's data source is shared.

Grafana forwards the user's existing Google OAuth access token as the bearer token on outgoing Cloud Monitoring API requests. No service account key is stored on the server.

Prerequisites for Forward OAuth Identity

Before using this method, ensure the following:

• Your Grafana instance is configured to sign users in with Google authentication.
• The Google OAuth client requests the https://www.googleapis.com/auth/monitoring.read scope on top of the default openid email profile scopes. Without this scope, the user's token is rejected by the Cloud Monitoring API with a 403 response.
• Each user who needs to query the data source has the Monitoring Viewer role (roles/monitoring.viewer) on the target GCP project.

Configure the Google OAuth scope

Add the Cloud Monitoring read scope to your Google authentication configuration in grafana.ini or custom.ini:

[auth.google]
scopes = openid email profile https://www.googleapis.com/auth/monitoring.read

If you configure Google authentication through the Grafana SSO settings UI, add the same scope value to the Scopes field.

After you change the scopes, existing user sessions still hold tokens issued under the old scope set. Each affected user must sign out, revoke the existing grant at https://myaccount.google.com/permissions, and sign in again to consent to the new scope. Otherwise, queries continue to fail with 403.

Configure the data source

1. In Grafana, navigate to the Google Cloud Monitoring data source configuration page.
2. Under Authentication type, select Forward OAuth Identity.
3. In Default project, enter the GCP project ID to query. This field is required because the user's OAuth token doesn't carry a project context.
4. Click Save & test to verify the connection.

{{< admonition type="note" >}} Service account impersonation isn't compatible with Forward OAuth Identity. The data source authenticates as the signed-in user, so there's no service account to impersonate. {{< /admonition >}}

Configure service account impersonation

Service account impersonation allows Grafana to authenticate as one service account but act as a different service account when making API requests. This is useful for:

• Accessing resources across multiple projects with a single configuration.
• Following the principle of least privilege by separating authentication from authorization.
• Auditing and tracking which service account accessed specific resources.

Prerequisites for impersonation

The service account used by Grafana (the "caller") must have the following:

• The iam.serviceAccounts.getAccessToken permission on the target service account.
• This permission is included in the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator).

The service account being impersonated (the "target") must have:

• The Monitoring Viewer role on the projects you want to access.

Configure impersonation

1. In the GCP Console, grant the caller service account the Service Account Token Creator role on the target service account.
2. Grant the target service account the Monitoring Viewer role on the relevant projects.
3. In Grafana, navigate to the Google Cloud Monitoring data source configuration page.
4. Configure authentication using either Google JWT File or GCE Default Service Account.
5. Enable Service Account Impersonation.
6. Enter the email address of the target service account.
7. Click Save & test to verify the connection.

For more information, refer to the Google documentation on service account impersonation.