> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Grafana

> Learn how to connect Opal to Grafana to manage access to Grafana folders, dashboards, roles, and teams.

With the Grafana integration, you can manage observability platform access through Opal:

* Allow users to request just-in-time access to Grafana folders, dashboards, and roles from the web and Slack
* Set the right resource owners to delegate approvals to those with the most context
* Configure day-one access to Grafana resources with groups from your identity provider
* Automatically escalate and revoke privileged access based on on-call schedules, e.g., [PagerDuty](/integrations/pagerduty-oncall) or [Opsgenie](/integrations/opsgenie)

## Supported resources

| Resource           | Read | Grant and revoke access | Notes                     |
| ------------------ | ---- | ----------------------- | ------------------------- |
| Grafana Folders    | ✔️   | ✔️                      |                           |
| Grafana Dashboards | ✔️   | ✔️                      |                           |
| Grafana Roles      | ✔️   | ✔️                      | Enterprise and Cloud only |
| Grafana Teams      | ✔️   | ✔️                      |                           |

## Requirements

* You must be an Opal admin.
* Your Grafana instance must be version 10 or higher.
* You must have a Grafana service account with the ability to generate service tokens, because this is how Opal authenticates with Grafana.
* Be on version 1.1143.0 or greater, if you self-host Opal.

## 1. Create a Grafana service account and token

In Grafana, add a service account by navigating to **Administration** > **Users and access** > **Service accounts** > **Add service account**. Give it a name (e.g., `Opal`), and add the **Role** based on instance type.

* For OSS instances, add `Admin` role.
* For Cloud and Enterprise, the service account must have the following permissions. If you prefer not to use the `Admin` role, you can create a custom role with these specific permissions.

| Permission                     | Type                                    |
| ------------------------------ | --------------------------------------- |
| `org.users:read`               | <Badge color="gray">Required</Badge>    |
| `roles:read`                   | <Badge color="gray">Required</Badge>    |
| `users.roles:read`             | <Badge color="gray">Required</Badge>    |
| `teams:read`                   | <Badge color="surface">Optional</Badge> |
| `teams.permissions:read`       | <Badge color="surface">Optional</Badge> |
| `folders:read`                 | <Badge color="surface">Optional</Badge> |
| `folders.permissions:read`     | <Badge color="surface">Optional</Badge> |
| `dashboards:read`              | <Badge color="surface">Optional</Badge> |
| `dashboards.permissions:read`  | <Badge color="surface">Optional</Badge> |
| `teams.permissions:write`      | <Badge color="surface">Optional</Badge> |
| `folders.permissions:write`    | <Badge color="surface">Optional</Badge> |
| `dashboards.permissions:write` | <Badge color="surface">Optional</Badge> |
| `teams.roles:read`             | <Badge color="surface">Optional</Badge> |
| `users.roles:add`              | <Badge color="surface">Optional</Badge> |
| `users.roles:remove`           | <Badge color="surface">Optional</Badge> |
| `teams.roles:add`              | <Badge color="surface">Optional</Badge> |
| `teams.roles:remove`           | <Badge color="surface">Optional</Badge> |

<Info>
  Optional permissions control which resources Opal can read and manage. Missing
  optional permissions will limit which resource types are available to import.
</Info>

<Info>
  Grafana uses the `permissions:type:delegate` scope for role assignment actions
  by default. This means the service account can only assign permissions that
  are attached to it (or a subset of them) to users or groups.
</Info>

Next, generate a service account token to be used in the following step.

## 2. Create a Grafana app in Opal

In Opal, go to **Inventory > +App** and select **Grafana** . Fill in the following fields and hit create.

| Field                | Value                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| App admin            | The team or user that should manage the Grafana app in Opal.                                        |
| Description          | Let your end users know what they're requesting access to.                                          |
| Grafana instance URL | The base URL of your Grafana instance (e.g., `https://grafana.mycompany.com`).                      |
| Instance type        | Select **OSS**, **Enterprise**, or **Cloud** based on your Grafana deployment.                      |
| Service token        | The service account token you generated in [Step 1](#1-create-a-grafana-service-account-and-token). |

<Note>
  Stack ID is a required field for cloud instances. You can go to
  `https://grafana.com/orgs/org-name/stacks` to get the value.
</Note>

## 3. Import Grafana resources

After creating the app, you can import resources from **... > Import items**. Users will now be able to request access to Grafana resources through Opal.

## User provisioning

<Info>
  User provisioning is only available for **Enterprise** and **Cloud** instances
  with SCIM enabled. Follow the [Grafana SCIM provisioning
  guide](https://grafana.com/docs/grafana/latest/setup-grafana/configure-access/configure-scim-provisioning/#configure-scim-using-the-grafana-user-interface)
  to enable it. `Enable User Sync` is the required setting.
</Info>

Opal can automatically provision and deprovision users in Grafana.

When provisioning is enabled, users who don't already have a Grafana account are automatically created when they are granted access to a Grafana resource. Deprovisioning removes users from Grafana when their access is revoked.

This is configurable in **Setup > Edit > Provision Grafana users** and **Deprovision Grafana users**. For more details, see [User provisioning](/docs/user-provisioning).