Grafana Enterprise on Grafana Labs

Data source permissions

Fri, 07 Mar 2025 11:34:44 +0100

Data source permissions

Data source permissions allow you to restrict access for users to query a data source. For each data source there is a permission page that allows you to enable permissions and restrict query permissions to specific Users and Teams.

Only available in Grafana Enterprise.

Enable data source permissions

By default, data sources in an organization can be queried by any user in that organization. For example, a user with the Viewer role can issue any possible query to a data source, not just queries that exist on dashboards they have access to.

When permissions are enabled for a data source in an organization, you restrict admin and query access for that data source to admin users in that organization.

Enable permissions for a data source:

Navigate to Configuration > Data Sources.
Select the data source you want to enable permissions for.
On the Permissions tab, click Enable.

Allow users and teams to query a data source

After you have enabled permissions for a data source you can assign query permissions to users and teams which will allow access to query the data source.

Assign query permission to users and teams:

Navigate to Configuration > Data Sources.
Select the data source you want to assign query permissions for.
On the Permissions tab, click Add Permission.
Select Team or User.
Select the entity you want to allow query access and then click Save.

Disable data source permissions

If you have enabled permissions for a data source and want to return data source permissions to the default, then you can disable permissions with a click of a button.

Note that all existing permissions created for the data source will be deleted.

Disable permissions for a data source:

Navigate to Configuration > Data Sources.
Select the data source you want to disable permissions for.
On the Permissions tab, click Disable Permissions.

Enhanced LDAP Integration

Fri, 07 Mar 2025 11:34:44 +0100

Enhanced LDAP integration

The enhanced LDAP integration adds additional functionality on top of the LDAP integration available in the open source edition of Grafana.

Enhanced LDAP integration is only available in Grafana Enterprise.

LDAP group synchronization for teams

With enhanced LDAP integration, you can set up synchronization between LDAP groups and teams. This enables LDAP users that are members of certain LDAP groups to automatically be added or removed as members to certain teams in Grafana.

Grafana keeps track of all synchronized users in teams, and you can see which users have been synchronized from LDAP in the team members list, see LDAP label in screenshot. This mechanism allows Grafana to remove an existing synchronized user from a team when its LDAP group membership changes. This mechanism also allows you to manually add a user as member of a team, and it will not be removed when the user signs in. This gives you flexibility to combine LDAP group memberships and Grafana team memberships.

Learn more about team sync.

Active LDAP synchronization

In the open source version of Grafana, user data from LDAP is synchronized only during the login process when authenticating using LDAP.

With active LDAP synchronization, available in Grafana Enterprise v6.3+, you can configure Grafana to actively sync users with LDAP servers in the background. Only users that have logged into Grafana at least once are synchronized.

Users with updated role and team membership will need to refresh the page to get access to the new features.

Removed users are automatically logged out and their account disabled. These accounts are displayed in the Server Admin > Users page with a disabled label. Disabled users keep their custom permissions on dashboards, folders, and data sources, so if you add them back in your LDAP database, they have access to the application with the same custom permissions as before.

[auth.ldap]
...

# You can use the Cron syntax or several predefined schedulers -
# @yearly (or @annually) | Run once a year, midnight, Jan. 1st        | 0 0 0 1 1 *
# @monthly               | Run once a month, midnight, first of month | 0 0 0 1 * *
# @weekly                | Run once a week, midnight between Sat/Sun  | 0 0 0 * * 0
# @daily (or @midnight)  | Run once a day, midnight                   | 0 0 0 * * *
# @hourly                | Run once an hour, beginning of hour        | 0 0 * * * *
sync_cron = "0 0 1 * * *" # This is default value (At 1 am every day)
# This cron expression format uses 6 space-separated fields (including seconds), for example
# sync_cron = "* */10 * * * *"
# This will run the LDAP Synchronization every 10th minute, which is also the minimal interval between the Grafana sync times i.e. you cannot set it for every 9th minute

# You can also disable active LDAP synchronization
active_sync_enabled = true # enabled by default

Single bind configuration (as in the Single bind example) is not supported with active LDAP synchronization because Grafana needs user information to perform LDAP searches.

Enterprise configuration

Fri, 07 Mar 2025 11:34:44 +0100

Grafana Enterprise configuration

This page describes Grafana Enterprise-specific configuration options that you can specify in a .ini configuration file or using environment variables. Refer to Configuration for more information about available configuration options.

[white_labeling]

app_title

Set to your company name to override application title.

login_logo

Set to complete URL to override login logo.

login_background

Set to complete CSS background expression to override login background. Example:

[white_labeling]
login_background = url(http://www.bhmpics.com/wallpapers/starfield-1920x1080.jpg)

menu_logo

Set to complete URL to override menu logo.

fav_icon

Set to complete URL to override fav icon (icon shown in browser tab).

apple_touch_icon

Set to complete URL to override Apple/iOS icon.

footer_links

List the link IDs to use here. Grafana will look for matching link configurations, the link IDs should be space-separated and contain no whitespace.

[meta_analytics]

max_file_age

Max age for data files before they get deleted.

max_data_directory_size

Max size in megabytes of the data files directory before files get deleted.

data_path

The directory where events will be stored in.

[analytics.summaries]

buffer_write_interval

Interval for writing dashboard usage stats buffer to database.

buffer_write_timeout

Timeout for writing dashboard usage stats buffer to database.

rollup_interval

Interval for trying to roll up per dashboard usage summary. Only rolled up at most once per day.

rollup_timeout

Timeout for trying to rollup per dashboard usage summary.

[analytics.views]

recent_users_age

Age for recent active users.

[reporting]

rendering_timeout

Timeout for each panel rendering request.

concurrent_render_limit

Maximum number of concurrent calls to the rendering service.

image_scale_factor

Scale factor for rendering images. Value 2 is enough for monitor resolutions, 4 would be better for printed material. Setting a higher value affects performance and memory.

[auth.saml]

enabled

If true, the feature is enabled. Defaults to false.

certificate

Base64-encoded public X.509 certificate. Used to sign requests to the IdP.

certificate_path

Path to the public X.509 certificate. Used to sign requests to the IdP.

private_key

Base64-encoded private key. Used to decrypt assertions from the IdP.

private_key_path

Path to the private key. Used to decrypt assertions from the IdP.

idp_metadata

Base64-encoded IdP SAML metadata XML. Used to verify and obtain binding locations from the IdP.

idp_metadata_path

Path to the SAML metadata XML. Used to verify and obtain binding locations from the IdP.

idp_metadata_url

URL to fetch SAML IdP metadata. Used to verify and obtain binding locations from the IdP.

max_issue_delay

Time since the IdP issued a response and the SP is allowed to process it. Defaults to 90 seconds.

metadata_valid_duration

How long the SPs metadata is valid. Defaults to 48 hours.

assertion_attribute_name

Friendly name or name of the attribute within the SAML assertion to use as the user name.

assertion_attribute_login

Friendly name or name of the attribute within the SAML assertion to use as the user login handle.

assertion_attribute_email

Friendly name or name of the attribute within the SAML assertion to use as the user email.

assertion_attribute_groups

Friendly name or name of the attribute within the SAML assertion to use as the user groups.

assertion_attribute_role

Friendly name or name of the attribute within the SAML assertion to use as the user roles.

assertion_attribute_org

Friendly name or name of the attribute within the SAML assertion to use as the user organization.

allowed_organizations

List of comma- or space-separated organizations. Each user must be a member of at least one organization to log in.

org_mapping

List of comma- or space-separated Organization:OrgId mappings.

role_values_editor

List of comma- or space-separated roles that will be mapped to the Editor role.

role_values_admin

List of comma- or space-separated roles that will be mapped to the Admin role.

role_values_grafana_admin

List of comma- or space-separated roles that will be mapped to the Grafana Admin (Super Admin) role.

[keystore.vault]

url

Location of the Vault server.

namespace

Vault namespace if using Vault with multi-tenancy.

auth_method

Method for authenticating towards Vault. Vault is inactive if this option is not set. Current possible values: token.

token

Secret token to connect to Vault when auth_method is token.

lease_renewal_interval

Time between checking if there are any secrets which needs to be renewed.

lease_renewal_expires_within

Time until expiration for tokens which are renewed. Should have a value higher than lease_renewal_interval.

lease_renewal_increment

New duration for renewed tokens. Vault may be configured to ignore this value and impose a stricter limit.

Export dashboard as PDF

Wed, 14 Apr 2021 09:32:57 +0200

Export dashboard as PDF

You can generate PDFs from any of your dashboards and save it to file.

Only available in Grafana Enterprise v6.7+.

In the upper right corner of the dashboard that you want to export as PDF, click the Share dashboard icon.
On the PDF tab, select the layout option for exported dashboard: Portrait or Landscape.
Click Save as PDF to render dashboard as a PDF document. Grafana opens the PDF in a new window or browser tab.

License Expiration

Wed, 14 Apr 2021 09:32:57 +0200

License expiration

If your license has expired most of Grafana keeps working as normal. Some enterprise functionality stops or runs with reduced functionality and Grafana displays a banner informing the users that Grafana is running on an expired license. Your Grafana admin needs to upload a new license file to restore full functionality.

Replace your license as soon as possible. Running Grafana Enterprise with an expired license is unsupported and can lead to unexpected consequences.

Update your license

Locate your current license.jwt file. In a standard installation it is stored inside Grafana’s data directory, which on a typical Linux installation is in /var/lib/grafana/data. This location might be overridden in the ini file Configuration.
ini
```
[enterprise]
license_path = /path/to/your/license.jwt
```
The configuration file’s location may also be overridden by the GF_ENTERPRISE_LICENSE_PATH environment variable.
Log in to your Grafana Cloud Account and make sure you’re in the correct organization in the dropdown at the top of the page.
Under the Grafana Enterprise section in the menu bar to the left, choose licenses and download the currently valid license with which you want to run Grafana. If you cannot see a valid license on Grafana.com, please contact your account manager at Grafana Labs to renew your subscription.
Replace the current license.jwt-file with the one you’ve just downloaded.
Restart Grafana.

If your license expires

If your Grafana Enterprise license expires, the following functionality affected as follows.

Data source permissions

Your current data source permissions will keep working as expected, but you’ll be unable to add new data source permissions until the license has been renewed.

LDAP authentication

LDAP synchronization is not affected by an expired license.
Enhanced LDAP debugging is unavailable.

SAML authentication

SAML authentication is not affected by an expired license.

Reporting

You’re unable to configure new reports or generate previews.
Scheduled reports are not generated or sent.

Enterprise plugins

Enterprise plugins might stop working.

White labeling

The white labeling feature is turned off, meaning that any white labeling options will not have any effect.

Usage insights

All the usage insights features are turned off, meaning that you won’t be able to look at dashboard usage, presence indicator or to use improved search. Grafana still collects usage data and you will have access to it as soon as you update your license.

Vault integration

Vault integration is not affected by an expired license.

Reporting

Fri, 07 Mar 2025 11:34:44 +0100

Reporting

Reporting allows you to automatically generate PDFs from any of your dashboards and have Grafana email them to interested parties on a schedule.

Only available in Grafana Enterprise v6.4+.

Any changes you make to a dashboard used in a report are reflected the next time the report is sent. For example, if you change the time range in the dashboard, then the time range in the report changes as well.

Requirements

SMTP must be configured for reports to be sent. Refer to SMTP in Configuration for more information.
The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to Image rendering for more information.

Create or update a report

Currently only Organization Admins can create reports.

Click on the reports icon in the side menu. The Reports tab allows you to view, create, and update your reports.
Enter report information. All fields are required unless otherwise indicated.
- Name - Name of the report as you want it to appear in the Reports list.
- Choose dashboard - Select the dashboard to generate the report from.
- Recipients - Enter the emails of the people or teams that you want to receive the report.
- Reply to - (optional) The address that will appear in the Reply to field of the email.
- Custom message - (optional) Message body in the email with the report.
Preview the report to make sure it appears as you expect. Update if necessary
Select the layout option for generated report: Portrait or Landscape.
Enter scheduling information. Options vary depending on the frequency you select.
Save the report.
Send test mail after saving the report to verify that the whole configuration is working as expected.

Layout

We’re actively working on developing new report layout options. Contact us if you would like to get involved in the design process.

Name	Support	Description	Preview
Portrait	v6.4+	Portrait generates an A4 page in portrait mode with three panels per page.
Landscape	v6.7+	Landscape generates an A4 page in landscape mode with a single panel per page.

Scheduling

Scheduled reports can be sent on a weekly, daily, or hourly basis. You may also disable scheduling for when you either want to pause a report or send it via the API.

All scheduling indicates when the reporting service will start rendering the dashboard. It can take a few minutes to render a dashboard with a lot of panels.

Hourly

Hourly reports are generated once per hour. All fields are required.

At minute - The number of minutes after full hour when the report should be generated.
Time zone - Time zone to determine the offset of the full hour. Does not currently change the time in the rendered report.

Daily

Daily reports are generated once per day. All fields are required.

Time - Time the report is sent, in 24-hour format.
Time zone - Time zone for the Time field.

Weekly

Weekly reports are generated once per week. All fields are required.

Day - Weekday which the report should be sent on.
Time - Time the report is sent, in 24-hour format.
Time zone - Time zone for the Time field.

Monthly

Only available in Grafana Enterprise v7.1+.

Monthly reports are generated once per month. All fields are required.

Day in month - Day of the month when the report should be sent. You can select last for reports that should go out on the last day of the month.
Time - Time the report is sent, in 24-hour format.
Time zone - Time zone for the Time field.

Never

Only available in Grafana Enterprise v7.0+.

Reports which are scheduled to never be sent have no parameter and will not be sent to the scheduler. They may be manually generated from the Send test email prompt or via the Reporting API.

Send test mail

Only available in Grafana Enterprise v7.0+.

In the report, click Send test mail.
In the Email field, enter the email address or addresses that you want to test, separated by semicolon. If you want to use email addresses from the report, then select the Use emails from report check box.
Click Send.

The last saved version of the report will be sent to selected emails. You can use this to verify emails are working and to make sure the report is generated and displayed as you expect.

Send report via the API

You can send reports programmatically with the send report endpoint in the HTTP APIs.

Rendering configuration

When generating reports, each panel renders separately before being collected in a PDF. The per panel rendering timeout and number of concurrently rendered panels can be configured.

To modify the panels’ clarity you can set a scale factor for the rendered images. A higher scale factor is more legible but will increase the file size of the generated PDF.

These options are available in the configuration file.

[reporting]
# Set timeout for each panel rendering request
rendering_timeout = 10s
# Set maximum number of concurrent calls to the rendering service
concurrent_render_limit = 4
# Set the scale factor for rendering images. 2 is enough for monitor resolutions
# 4 would be better for printed material. Setting a higher value affects performance and memory
image_scale_factor = 2

Report time range

Reports use the saved time range of the dashboard. Changing the time range of the report is done by saving a modified time range to the dashboard.

The page header of the report displays the time range for the dashboard’s data queries. Dashboards set to use the browser’s time zone will use the time zone on the Grafana server.

If the time zone is set differently between your Grafana server and its remote image renderer, then the time ranges in the report might be different between the page header and the time axes in the panels. We advise always setting the time zone to UTC for dashboards when using a remote renderer to avoid this.

Troubleshoot reporting

To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to Configuration for more information.

[log]
filters = report:debug

SAML Authentication

Fri, 07 Mar 2025 11:34:44 +0100

SAML authentication

SAML authentication integration allows your Grafana users to log in by using an external SAML 2.0 Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.

The SAML single-sign-on (SSO) standard is varied and flexible. Our implementation contains the subset of features needed to provide a smooth authentication experience into Grafana.

Only available in Grafana Enterprise v6.3+. If you encounter any problems with our implementation, please don’t hesitate to contact us.

Supported SAML

Grafana supports the following SAML 2.0 bindings:

From the Service Provider (SP) to the Identity Provider (IdP):
- HTTP-POST binding
- HTTP-Redirect binding
From the Identity Provider (IdP) to the Service Provider (SP):
- HTTP-POST binding

In terms of security:

Grafana supports signed and encrypted assertions.
Grafana does not support signed or encrypted requests.

In terms of initiation:

Grafana supports SP-initiated requests.
Grafana does not support IdP-initiated request.

Set up SAML authentication

The table below describes all SAML configuration options. Continue reading below for details on specific options. Like any other Grafana configuration, you can apply these options as environment variables.

Setting	Required	Description	Default
`enabled`	No	Whether SAML authentication is allowed	`false`
`certificate` or `certificate_path`	Yes	Base64-encoded string or Path for the SP X.509 certificate
`private_key` or `private_key_path`	Yes	Base64-encoded string or Path for the SP private key
`idp_metadata`, `idp_metadata_path`, or `idp_metadata_url`	Yes	Base64-encoded string, Path or URL for the IdP SAML metadata XML
`max_issue_delay`	No	Duration, since the IdP issued a response and the SP is allowed to process it	`90s`
`metadata_valid_duration`	No	Duration, for how long the SP metadata is valid	`48h`
`assertion_attribute_name`	No	Friendly name or name of the attribute within the SAML assertion to use as the user name	`displayName`
`assertion_attribute_login`	No	Friendly name or name of the attribute within the SAML assertion to use as the user login handle	`mail`
`assertion_attribute_email`	No	Friendly name or name of the attribute within the SAML assertion to use as the user email	`mail`
`assertion_attribute_groups`	No	Friendly name or name of the attribute within the SAML assertion to use as the user groups
`assertion_attribute_role`	No	Friendly name or name of the attribute within the SAML assertion to use as the user roles
`assertion_attribute_org`	No	Friendly name or name of the attribute within the SAML assertion to use as the user organization
`allowed_organizations`	No	List of comma- or space-separated organizations. User should be a member of at least one organization to log in.
`org_mapping`	No	List of comma- or space-separated Organization:OrgId mappings
`role_values_editor`	No	List of comma- or space-separated roles which will be mapped into the Editor role
`role_values_admin`	No	List of comma- or space-separated roles which will be mapped into the Admin role
`role_values_grafana_admin`	No	List of comma- or space-separated roles which will be mapped into the Grafana Admin (Super Admin) role

Enable SAML authentication

To use the SAML integration, in the auth.saml section of in the Grafana custom configuration file, set enabled to true.

Refer to Configuration for more information about configuring Grafana.

Certificate and private key

The SAML SSO standard uses asymmetric encryption to exchange information between the SP (Grafana) and the IdP. To perform such encryption, you need a public part and a private part. In this case, the X.509 certificate provides the public part, while the private key provides the private part.

Grafana supports two ways of specifying both the certificate and private_key.

Without a suffix (certificate or private_key), the configuration assumes you’ve supplied the base64-encoded file contents.
With the _path suffix (certificate_path or private_key_path), then Grafana treats the value entered as a file path and attempts to read the file from the file system.

You can only use one form of each configuration option. Using multiple forms, such as both certificate and certificate_path, results in an error.

IdP metadata

You also need to define the public part of the IdP for message verification. The SAML IdP metadata XML defines where and how Grafana exchanges user information.

Grafana supports three ways of specifying the IdP metadata.

Without a suffix idp_metadata, Grafana assumes base64-encoded XML file contents.
With the _path suffix, Grafana assumes a file path and attempts to read the file from the file system.
With the _url suffix, Grafana assumes a URL and attempts to load the metadata from the given location.

Maximum issue delay

Prevents SAML response replay attacks and internal clock skews between the SP (Grafana) and the IdP. You can set a maximum amount of time between the IdP issuing a response and the SP (Grafana) processing it.

The configuration options is specified as a duration, such as max_issue_delay = 90s or max_issue_delay = 1h.

Metadata valid duration

SP metadata is likely to expire at some point, perhaps due to a certificate rotation or change of location binding. Grafana allows you to specify for how long the metadata should be valid. Leveraging the validUntil field, you can tell consumers until when your metadata is going to be valid. The duration is computed by adding the duration to the current time.

The configuration option is specified as a duration, such as metadata_valid_duration = 48h.

Identity provider (IdP) registration

For the SAML integration to work correctly, you need to make the IdP aware of the SP.

The integration provides two key endpoints as part of Grafana:

The /saml/metadata endpoint, which contains the SP metadata. You can either download and upload it manually, or youmake the IdP request it directly from the endpoint. Some providers name it Identifier or Entity ID.
The /saml/acs endpoint, which is intended to receive the ACS (Assertion Customer Service) callback. Some providers name it SSO URL or Reply URL.

Assertion mapping

During the SAML SSO authentication flow, Grafana receives the ACS callback. The callback contains all the relevant information of the user under authentication embedded in the SAML response. Grafana parses the response to create (or update) the user within its internal database.

For Grafana to map the user information, it looks at the individual attributes within the assertion. You can think of these attributes as Key/Value pairs (although, they contain more information than that).

Grafana provides configuration options that let you modify which keys to look at for these values. The data we need to create the user in Grafana is Name, Login handle, and email.

An example is assertion_attribute_name = "givenName" where Grafana looks within the assertion for an attribute with a friendly name or name of givenName. Both, the friendly name (e.g. givenName) or the name (e.g. urn:oid:2.5.4.42) can be used interchangeably as the value for the configuration option.

Configure team sync

Team sync support for SAML only available in Grafana v7.0+

To use SAML Team sync, set assertion_attribute_groups to the attribute name where you store user groups. Then Grafana will use attribute values extracted from SAML assertion to add user into the groups with the same name configured on the External group sync tab.

Learn more about Team Sync

Configure role sync

Only available in Grafana v7.0+

Role sync allows you to map user roles from an identity provider to Grafana. To enable role sync, configure role attribute and possible values for Editor, Admin and Grafana Admin roles.

In the configuration file, set assertion_attribute_role option to the attribute name where the role information will be extracted from.
Set the role_values_editor option to the values mapped to the Editor role.
Set the role_values_admin option to the values mapped to the organization Admin role.
Set the role_values_grafana_admin option to the values mapped to the Grafana Admin role.

If a user role doesn’t match any of configured values, then the Viewer role will be assigned.

Refer to Organization roles for more information about roles and permissions in Grafana.

Example configuration:

[auth.saml]
assertion_attribute_role = role
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin

Important: When role sync is configured, any changes of user roles and organization membership made manually in Grafana will be overwritten on next user login. Assign user organizations and roles in the IdP instead.

Configure organization mapping

Only available in Grafana v7.0+

Organization mapping allows you to assign users to particular organization in Grafana depending on attribute value obtained from identity provider.

In configuration file, set assertion_attribute_org to the attribute name you store organization info in.
Set org_mapping option to the comma-separated list of Organization:OrgId pairs to map organization from IdP to Grafana organization specified by id.

For example, use following config to assign users from Engineering organization to the Grafana organization with id 2 and users from Sales - to the org with id 3, based on Org assertion attribute value:

[auth.saml]
assertion_attribute_org = Org
org_mapping = Engineering:2, Sales:3

You can specify multiple organizations both for the IdP and Grafana:

org_mapping = Engineering:2, Sales:2 to map users from Engineering and Sales to 2 in Grafana.
org_mapping = Engineering:2, Engineering:3 to assign Engineering to both 2 and 3 in Grafana.

Configure allowed organizations

Only available in Grafana v7.0+

With the allowed_organizations option you can specify a list of organizations where the user must be a member of at least one of them to be able to log in to Grafana.

Example SAML configuration

[auth.saml]
enabled = true
certificate_path = "/path/to/certificate.cert"
private_key_path = "/path/to/private_key.pem"
metadata_path = "/my/metadata.xml"
max_issue_delay = 90s
metadata_valid_duration = 48h
assertion_attribute_name = displayName
assertion_attribute_login = mail
assertion_attribute_email = mail

assertion_attribute_groups = Group
assertion_attribute_role = Role
assertion_attribute_org = Org
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin
org_mapping = Engineering:2, Sales:3
allowed_organizations = Engineering, Sales

Set up SAML with Okta

This guide will follow you through the steps of configuring SAML authentication in Grafana with Okta. You need to be an admin in your Okta organization to access Admin Console and create SAML integration. You also need permissions to edit Grafana config file and restart Grafana server.

Configure the SAML integration in Okta

To configure SAML integration with Okta, create integration inside the Okta organization first.

Log in to the Okta portal.
Go to the Admin Console in your Okta organization by clicking Admin in the upper-right corner. If you are in the Developer Console, then click Developer Console in the upper-left corner and then click Classic UI to switch over to the Admin Console.
In the Admin Console, navigate to Applications > Applications.
Click Add Application.
Click Create New App to start the Application Integration Wizard.
Choose Web as a platform.
Select SAML 2.0 in the Sign on method section.
Click Create.
On the General Settings tab, enter a name for your Grafana integration. You can also upload a logo.

On the Configure SAML tab, enter the SAML information related to your Grafana instance:

In the Single sign on URL field, use the /saml/acs endpoint URL of your Grafana instance, for example, https://grafana.example.com/saml/acs.
In the Audience URI (SP Entity ID) field, use the /saml/metadata endpoint URL, for example, https://grafana.example.com/saml/metadata.
Leave the default values for Name ID format and Application username.

In the ATTRIBUTE STATEMENTS (OPTIONAL) section, enter the SAML attributes to be shared with Grafana, for example:

Attribute name (in Grafana)	Value (in Okta profile)
Login	`user.login`
Email	`user.email`
DisplayName	`user.firstName + " " + user.lastName`

In the GROUP ATTRIBUTE STATEMENTS (OPTIONAL) section, enter a group attribute name (for example, Group) and set filter to Matches regex .* to return all user groups.

Click Next.
On the final Feedback tab, fill out the form and then click Finish.

Edit SAML options in the Grafana config file

Once the application is created, configure Grafana to use it for SAML authentication. Refer to Configuration to get more information about how to configure Grafana.

In the [auth.saml] section in the Grafana configuration file, set enabled to true.
Configure the certificate and private key.
On the Okta application page where you have been redirected after application created, navigate to the Sign On tab and find Identity Provider metadata link in the Settings section.
Set the idp_metadata_url to the URL obtained from the previous step. The URL should look like https://<your-org-id>.okta.com/app/<application-id>/sso/saml/metadata.
Set the following options to the attribute names configured at the step 10 of the SAML integration setup. You can find this attributes on the General tab of the application page (ATTRIBUTE STATEMENTS and GROUP ATTRIBUTE STATEMENTS in the SAML Settings section).
Save the configuration file and and then restart the Grafana server.

When you are finished, the Grafana configuration might look like this example:

[server]
root_url = https://grafana.example.com

[auth.saml]
enabled = true
private_key_path = "/path/to/private_key.pem"
certificate_path = "/path/to/certificate.cert"
idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata"
assertion_attribute_name = DisplayName
assertion_attribute_login = Login
assertion_attribute_email = Email
assertion_attribute_groups = Group

Troubleshoot SAML authentication

To troubleshoot and get more log information, enable SAML debug logging in the configuration file. Refer to Configuration for more information.

[log]
filters = saml.auth:debug

Team sync

Fri, 07 Mar 2025 11:34:44 +0100

Team sync

Team sync lets you set up synchronization between your auth providers teams and teams in Grafana. This enables LDAP, OAuth, or SAML users who are members of certain teams or groups to automatically be added or removed as members of certain teams in Grafana.

Only available in Grafana Enterprise.

Grafana keeps track of all synchronized users in teams, and you can see which users have been synchronized in the team members list, see LDAP label in screenshot. This mechanism allows Grafana to remove an existing synchronized user from a team when its group membership changes. This mechanism also enables you to manually add a user as member of a team, and it will not be removed when the user signs in. This gives you flexibility to combine LDAP group memberships and Grafana team memberships.

Currently the synchronization only happens when a user logs in, unless LDAP is used with the active background synchronization that was added in Grafana 6.3.

Supported providers

Synchronize a Grafana team with an external group

If you have already grouped some users into a team, then you can synchronize that team with an external group.

In Grafana, navigate to Configuration > Teams.
Select a team.
On the External group sync tab, and click Add group.
Insert the value of the group you want to sync with. This becomes the Grafana GroupID. Examples:
- For LDAP, this is the LDAP distinguished name (DN) of LDAP group you want to synchronize with the team.
- For Auth Proxy, this is the value we receive as part of the custom Groups header.
Click Add group to save.

Usage-insights

Fri, 07 Mar 2025 11:34:44 +0100

Usage insights

Usage insights allow you to have a better understanding of how your Grafana instance is used. The collected data are the number of:

Dashboard views (aggregated and per user)
Data source errors
Data source queries

Only available in Grafana Enterprise v7.0+.

Presence indicator

The presence indicator is visible to all signed-in users on all dashboards. It shows the avatars of users who interacted with the dashboard recently (last 10 minutes by default). You can see the user’s name by hovering your cursor over the user’s avatar. The avatars come from Gravatar based on the user’s email.

When more users are active on a dashboard than can fit in the presence indicator section, click on the +X icon that opens dashboard insights to see more details about recent user activity.

You can choose your own definition of “recent” by setting it in the configuration file.

[analytics.views]
# Set age for recent active users
recent_users_age = 10m

Dashboard insights

You can see dashboard usage information by clicking on the Dashboard insights button in the top bar.

It shows two kinds of information:

Stats: Shows the daily query count and error count for the last 30 days.
Users & activity: Shows the daily view count for the last 30 days; last activities on the dashboard and recent users (with a limit of 20).

Improved dashboard search

In the search view, you can sort dashboards using these insights data. It helps you find unused or broken dashboards or discover most viewed ones.

Vault

Fri, 07 Mar 2025 11:34:44 +0100

Vault integration

Only available in Grafana Enterprise v7.1+.

If you manage your secrets with Hashicorp Vault, you can use them for Configuration and Provisioning.

Note: If you have Grafana set up for high availability, then we advise not to use dynamic secrets for provisioning files. Each Grafana instance is responsible for renewing its own leases. Your data source leases might expire when one of your Grafana servers shuts down.

Configuration

Before using Vault, you need to activate it by providing a URL, authentication method (currently only token), and a token for your Vault service. Grafana automatically renews the service token if it is renewable and set up with a limited lifetime.

If you’re using short-lived leases, then you can also configure how often Grafana should renew the lease and for how long. We recommend keeping the defaults unless you run into problems.

[keystore.vault]
# Location of the Vault server
;url =
# Vault namespace if using Vault with multi-tenancy
;namespace =
# Method for authenticating towards Vault. Vault is inactive if this option is not set
# Possible values: token
;auth_method =
# Secret token to connect to Vault when auth_method is token
;token =
# Time between checking if there are any secrets which needs to be renewed.
;lease_renewal_interval = 5m
# Time until expiration for tokens which are renewed. Should have a value higher than lease_renewal_interval
;lease_renewal_expires_within = 15m
# New duration for renewed tokens. Vault may be configured to ignore this value and impose a stricter limit.
;lease_renewal_increment = 1h

Example for vault server -dev:

[keystore.vault]
url = http://127.0.0.1:8200 # HTTP should only be used for local testing
auth_method = token
token = s.sAZLyI0r7sFLMPq6MWtoOhAN # replace with your key

Using the Vault expander

After you configure Vault, you must set the configuration or provisioning files you wish to use Vault. Vault configuration is an extension of configuration’s variable expansion and follows the $__vault{<argument>} syntax.

The argument to Vault consists of three parts separated by a colon:

The first part specifies which secrets engine should be used.
The second part specifies which secret should be accessed.
The third part specifies which field of that secret should be used.

For example, if you place a Key/Value secret for the Grafana admin user in secret/grafana/admin_defaults the syntax for accessing it’s password field would be $__vault{kv:secret/grafana/admin_defaults:password}.

Secrets engines

Vault supports many secrets engines which represents different methods for storing or generating secrets when requested by an authorized user. Grafana supports a subset of these which are most likely to be relevant for a Grafana installation.

Key/Value

Grafana supports Vault’s K/V version 2 storage engine which is used to store and retrieve arbitrary secrets as kv.

$__vault{kv:secret/grafana/smtp:username}

Databases

The Vault databases secrets engines is a family of secret engines which shares a similar syntax and grants the user dynamic access to a database. You can use this both for setting up Grafana’s own database access and for provisioning data sources.

$__vault{database:database/creds/grafana:username}

Examples

The following examples show you how to set your configuration or provisioning files to use Vault to retrieve configuration values.

Configuration

The following is a partial example for using Vault to set up a Grafana configuration file’s email and database credentials. Refer to Configuration for more information.

[smtp]
enabled = true
host = $__vault{kv:secret/grafana/smtp:hostname}:587
user = $__vault{kv:secret/grafana/smtp:username}
password = $__vault{kv:secret/grafana/smtp:password}

[database]
type = mysql
host = mysqlhost:3306
name = grafana
user = $__vault{database:database/creds/grafana:username}
password = $__vault{database:database/creds/grafana:password}

Provisioning

The following is a full examples of a provisioning YAML file setting up a MySQL data source using Vault’s database secrets engine. Refer to Provisioning for more information.

provisioning/custom.yaml

apiVersion: 1

datasources:
  - name: statistics
    type: mysql
    url: localhost:3306
    database: stats
    user: $__vault{database:database/creds/ro/stats:username}
    secureJsonData:
      password: $__vault{database:database/creds/ro/stats:password}

White-labeling

Fri, 07 Mar 2025 11:34:44 +0100

White labeling

White labeling allows you to replace the Grafana brand and logo with your own corporate brand and logo.

Only available in Grafana Enterprise v6.6+.

Grafana Enterprise has white labeling options in the grafana.ini file. As with all configuration options, you can also set them with environment variables.

You can change the following elements:

Application title
Login background
Login logo
Side menu top logo
Footer and help menu links
Fav icon (shown in browser tab)
Login title (will not appear if a login logo is set, Grafana v7.0+)
Login subtitle (will not appear if a login logo is set, Grafana v7.0+)
Login box background (Grafana v7.0+)

You will have to host your logo and other images used by the white labeling feature separately. Make sure Grafana can access the URL where the assets are stored.

The configuration file in Grafana Enterprise contains the following options. Each option is defined in the file. For more information about configuring Grafana, refer to Configuration.

# Enterprise only
[white_labeling]
# Set to your company name to override application title
;app_title =

# Set to main title on the login page (Will not appear if a login logo is set)
;login_title =

# Set to login subtitle (Will not appear if a login logo is set)
;login_subtitle =

# Set to complete URL to override login logo
;login_logo =

# Set to complete CSS background expression to override login background
# example: login_background = url(http://www.bhmpics.com/wallpapers/starfield-1920x1080.jpg)
;login_background =

# Set to complete CSS background expression to override login box background
;login_box_background =

# Set to complete URL to override menu logo
;menu_logo =

# Set to complete URL to override fav icon (icon shown in browser tab)
;fav_icon =

# Set to complete URL to override apple/ios icon
;apple_touch_icon =

Below is an example for how to replace the default footer and help links with two custom links.

footer_links = support guides
footer_links_support_text = Support
footer_links_support_url = http://your.support.site
footer_links_guides_text = Guides
footer_links_guides_url = http://your.guides.site

Here is the same example using environment variables instead of the custom.ini or grafana.ini file.

GF_WHITE_LABELING_FOOTER_LINKS=support guides
GF_WHITE_LABELING_FOOTER_LINKS_SUPPORT_TEXT=Support
GF_WHITE_LABELING_FOOTER_LINKS_SUPPORT_URL=http://your.support.site
GF_WHITE_LABELING_FOOTER_LINKS_GUIDES_TEXT=Guides
GF_WHITE_LABELING_FOOTER_LINKS_GUIDES_URL=http://your.guides.site