Skip to content

N
nexpie-grafana-theme
Commit 800431bc by Diana Payton Committed by GitHub
Options

Docs: Edited Enterprise docs (#22602) 

* Update white-labeling.md

* Update team-sync.md

* Update saml.md

* Update saml.md

* Update menu.yaml

* Update reporting.md

* Update saml.md

* Update reporting.md

* Update reporting.md

* Update enhanced_ldap.md

* Update _index.md

* content updates

content updates

* Update menu.yaml

* Update datasource_permissions.md

* Update _index.md

* Minor edits

* Update _index.md

* Update docs/sources/enterprise/_index.md

Co-Authored-By: Emil Tullstedt <sakjur@gmail.com>

* Update _index.md

* Update saml.md

* Update reporting.md

Co-authored-by: Emil Tullstedt <sakjur@gmail.com>
parent 763fb3bc
Showing with 223 additions and 256 deletions
docs/sources/enterprise/_index.md
......@@ -6,7 +6,7 @@ type = "docs"
[menu.docs]
name = "Grafana Enterprise"
identifier = "enterprise"
weight = 30
weight = 100
+++
# Grafana Enterprise
......@@ -17,58 +17,62 @@ Building on everything you already know and love about Grafana, Grafana Enterpri
Grafana Enterprise includes all of the features found in the open source edition and more.
## Enhanced LDAP Integration
[Learn more about Grafana Enterprise.](https://grafana.com/enterprise)
With Grafana Enterprise you can set up synchronization between LDAP Groups and Teams. [Learn More]({{< relref "../auth/enhanced_ldap.md" >}}).
## Enhanced security features
## SAML Authentication
Grafana Enterprise includes integrations with more ways to authenticate your users and enhanced authorization capabilities.
Enables your Grafana Enterprise users to authenticate with SAML. [Learn More]({{< relref "saml.md" >}}).
### Data source permissions
## Team Sync
[Data source permissions]({{< relref "datasource_permissions.md" >}}) allow you to restrict query access to only specific teams and users.
Team Sync allows you to setup synchronization between teams in Grafana and teams in your auth provider so that your users automatically end up in the right team. [Learn More]({{< relref "team-sync.md" >}}).
### Enhanced LDAP integration
Supported auth providers:
With Grafana Enterprise [enhanced LDAP]({{< relref "enhanced_ldap.md" >}}), you can set up synchronization between LDAP groups and Grafana teams.
* [LDAP]({{< relref "enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
* [GitHub OAuth]({{< relref "../auth/github.md#team-sync-enterprise-only" >}})
* [GitLab OAuth]({{< relref "../auth/gitlab.md#team-sync-enterprise-only" >}})
* [Auth Proxy]({{< relref "../auth/auth-proxy.md#team-sync-enterprise-only">}})
### SAML authentication
## White labeling
[SAML authentication]({{< relref "saml.md" >}}) enables your Grafana Enterprise users to authenticate with SAML.
White labeling makes it possible to customize the logos and footer links of Grafana. [Learn More]({{< relref "white-labeling.md" >}}).
### Team sync
## Data source permissions
[Team sync]({{< relref "team-sync.md" >}}) allows you to set up synchronization between teams in Grafana and teams in your auth provider so that your users automatically end up in the right team.
Data source permissions allow you to restrict query access to only specific Teams and Users. [Learn More]({{< relref "datasource_permissions.md" >}}).
Supported auth providers:
* [Auth Proxy]({{< relref "../auth/auth-proxy.md#team-sync-enterprise-only">}})
* [GitHub OAuth]({{< relref "../auth/github.md#team-sync-enterprise-only" >}})
* [GitLab OAuth]({{< relref "../auth/gitlab.md#team-sync-enterprise-only" >}})
* [LDAP]({{< relref "enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
## Reporting
Reporting makes it possible to take any dashboard, generate a PDF report, and set up a schedule to have it delivered. [Learn More]({{< relref "reporting.md" >}}).
[Reporting]({{< relref "reporting.md" >}}) allows you to take any dashboard, generate a PDF report, and set up a schedule to have it emailed to whoever you choose.
## Enterprise Plugins
## White labeling
With a Grafana Enterprise license you will get access to enterprise plugins, including:
[White labeling]({{< relref "white-labeling.md" >}}) allows you to replace the Grafana brand and logo with your own corporate brand and logo. You can also change footer links to point to your custom resources.
* [Splunk](https://grafana.com/plugins/grafana-splunk-datasource)
## Enterprise plugins
With a Grafana Enterprise license, you get access to premium plugins, including:
* [Amazon Timestream](https://grafana.com/plugins/grafana-timestream-datasource)
* [AppDynamics](https://grafana.com/plugins/dlopes7-appdynamics-datasource)
* [DataDog](https://grafana.com/plugins/grafana-datadog-datasource)
* [Dynatrace](https://grafana.com/plugins/grafana-dynatrace-datasource)
* [New Relic](https://grafana.com/plugins/grafana-newrelic-datasource)
* [Amazon Timestream](https://grafana.com/plugins/grafana-timestream-datasource)
* [Oracle Database](https://grafana.com/plugins/grafana-oracle-datasource)
* [Splunk](https://grafana.com/plugins/grafana-splunk-datasource)
## Try Grafana Enterprise
You can learn more about Grafana Enterprise [here](https://grafana.com/enterprise). To purchase or obtain a trial license contact the Grafana Labs [Sales Team](https://grafana.com/contact?about=support&topic=Grafana%20Enterprise).
To purchase or obtain a trial license contact the Grafana Labs [Sales Team](https://grafana.com/contact?about=support&topic=Grafana%20Enterprise).
## License file management
To download your Grafana Enterprise license log in to your [Grafana.com](https://grafana.com) account and go to your **Org
Profile**. In the side menu there is a section for Grafana Enterprise licenses. At the bottom of the license
details page there is **Download Token** link that will download the *license.jwt* file containing your license.
To download your Grafana Enterprise license log in to your [Grafana.com](https://grafana.com) account and go to your **Org Profile**. In the side menu there is a section for Grafana Enterprise licenses. At the bottom of the license details page there is **Download Token** link that will download the *license.jwt* file containing your license.
Place the *license.jwt* file in Grafana's data folder. This is usually located at `/var/lib/grafana/data` on Linux systems.
......@@ -79,6 +83,4 @@ You can also configure a custom location for the license file via the ini settin
license_path = /company/secrets/license.jwt
```
This setting can also be set via ENV variable which is useful if you're running Grafana via docker and have a custom
volume where you have placed the license file. In this case set the ENV variable `GF_ENTERPRISE_LICENSE_PATH` to point
to the location of your license file.
This setting can also be set with an environment variable, which is useful if you're running Grafana with Docker and have a custom volume where you have placed the license file. In this case, set the environment variable `GF_ENTERPRISE_LICENSE_PATH` to point to the location of your license file.
docs/sources/enterprise/datasource_permissions.md
......@@ -7,31 +7,29 @@ type = "docs"
name = "Datasource"
identifier = "datasource-permissions"
parent = "enterprise"
weight = 4
weight = 200
+++
# Data source permissions
> Only available in Grafana Enterprise.
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**.
## Restricting Access - Enable Permissions
> Only available in Grafana Enterprise.
## Enable data source permissions
{{< docs-imagebox img="/img/docs/enterprise/datasource_permissions_enable_still.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" animated-gif="/img/docs/enterprise/datasource_permissions_enable.gif" >}}
By default, permissions are disabled for data sources and a data source in an organization can be queried by any user in
that organization. For example a user with `Viewer` role can still issue any possible query to a data source, not just
those queries that exist on dashboards he/she has access to.
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 will restrict admin and query access for that
data source to [admin users]({{< relref "../permissions/organization_roles/#admin-role" >}}) in that organization.
When permissions are enabled for a data source in an organization, you restrict admin and query access for that data source to [admin users]({{< relref "../permissions/organization_roles/#admin-role" >}}) in that organization.
**To enable permissions for a data source:**
**Enable permissions for a data source:**
1. Navigate to Configuration / Data Sources.
1. Navigate to **Configuration > Data Sources**.
2. Select the data source you want to enable permissions for.
3. Select the Permissions tab and click on the `Enable` button.
3. On the Permissions tab, click **Enable**.
<div class="clearfix"></div>
......@@ -39,31 +37,30 @@ data source to [admin users]({{< relref "../permissions/organization_roles/#admi
{{< docs-imagebox img="/img/docs/enterprise/datasource_permissions_add_still.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" animated-gif="/img/docs/enterprise/datasource_permissions_add.gif" >}}
After you have [enabled permissions](#restricting-access-enable-permissions) for a data source you can assign query
permissions to users and teams which will allow access to query the 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:**
1. Navigate to Configuration / Data Sources.
1. Navigate to **Configuration > Data Sources**.
2. Select the data source you want to assign query permissions for.
3. Select the Permissions tab.
4. click on the `Add Permission` button.
5. Select Team/User and find the team/user you want to allow query access and click on the `Save` button.
3. On the Permissions tab, click **Add Permission**.
4. Select **Team** or **User**.
5. Select the entity you want to allow query access and then click **Save**.
<div class="clearfix"></div>
## Restore Default Access - Disable Permissions
## Disable data source permissions
{{< docs-imagebox img="/img/docs/enterprise/datasource_permissions_disable_still.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" animated-gif="/img/docs/enterprise/datasource_permissions_disable.gif" >}}
If you have enabled permissions for a data source and want to return data source permissions to the default, i.e.
data source can be queried by any user in that organization, you can disable permissions with a click of a button.
Note that all existing permissions created for data source will be deleted.
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:**
1. Navigate to Configuration / Data Sources.
1. Navigate to **Configuration > Data Sources**.
2. Select the data source you want to disable permissions for.
3. Select the Permissions tab and click on the `Disable Permissions` button.
3. On the Permissions tab, click **Disable Permissions**.
<div class="clearfix"></div>
docs/sources/enterprise/enhanced_ldap.md
......@@ -7,40 +7,39 @@ type = "docs"
name = "Enhanced LDAP"
identifier = "enhanced-ldap"
parent = "enterprise"
weight = 3
weight = 300
+++
# Enhanced LDAP integration
> Only available in Grafana Enterprise.
The enhanced LDAP integration adds additional functionality on top of the [LDAP integration]({{< relref "../auth/ldap.md" >}}) available in the open source edition of Grafana.
The enhanced LDAP integration adds additional functionality on top of the existing [LDAP integration]({{< relref "../auth/ldap.md" >}}).
> Enhanced LDAP integration is only available in Grafana Enterprise.
## LDAP Group Synchronization for Teams
## LDAP group synchronization for teams
{{< docs-imagebox img="/img/docs/enterprise/team_members_ldap.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" >}}
With the enhanced LDAP integration it's possible to setup synchronization between LDAP groups and teams. This enables LDAP users which are members
of certain LDAP groups to automatically be added/removed as members to certain teams in Grafana. Currently the synchronization will only happen every
time a user logs in, unless Grafana v6.3 (or later) is used with active background synchronization enabled.
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 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.
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]({{< relref "team-sync.md">}})
[Learn more about team sync.]({{< relref "team-sync.md">}})
<div class="clearfix"></div>
## Active LDAP Synchronization
## Active LDAP synchronization
> Only available in Grafana Enterprise v6.3+
In the open source version of Grafana, user data from LDAP is synchronized only during the login process when authenticating using LDAP.
In the open source version of Grafana, user data from LDAP will be 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.
With this feature you can configure Grafana to actively sync users with LDAP servers in the background. Only users that have logged into Grafana at least once will be synchronized.
Users with updated role and team membership will need to refresh the page to get access to the new features.
Removed users will be automatically logged out and their account disabled. They will be displayed in the Server Admin / Users page with a `disabled` label. Disabled users will keep their custom permissions on dashboards, folders and datasources so if you add them back in your LDAP database, they will have access to the application with the same custom permissions as before.
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.
```bash
[auth.ldap]
......@@ -61,6 +60,4 @@ sync_cron = "0 0 1 * * *" # This is default value (At 1 am every day)
active_sync_enabled = true # enabled by default
```
### Not compatible with Single Bind
Single Bind configuration (as in the [Single Bind Example]({{< relref "../auth/ldap.md#single-bind-example">}})) is not supported with active LDAP synchronization because Grafana needs user information to perform LDAP searches.
Single bind configuration (as in the [Single bind example]({{< relref "../auth/ldap.md#single-bind-example">}})) is not supported with active LDAP synchronization because Grafana needs user information to perform LDAP searches.
docs/sources/enterprise/license-expiration.md
......@@ -14,7 +14,7 @@ If your license has expired most of Grafana keeps working as normal. Some enterp
> Replace your license as soon as possible. Running Grafana Enterprise with an expired license is unsupported and can lead to unexpected consequences.
## Replacing your license
## Update your license
1. 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](https://grafana.com/docs/grafana/latest/installation/configuration/)
```
......@@ -31,19 +31,19 @@ The configuration file's location may also be overridden by the `GF_ENTERPRISE_L
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.
## Reporting
## LDAP authentication
- You're unable to configure new reports or generate previews.
- Scheduled reports are not generated or sent.
* LDAP synchronization is not affected by an expired license.
* Enhanced LDAP debugging is unavailable.
## SAML authentication
SAML is not affected by an expired license.
SAML authentication is not affected by an expired license.
## LDAP authentication
## Reporting
- LDAP synchronization is not affected by an expired license.
- Enhanced LDAP debugging is unavailable.
* You're unable to configure new reports or generate previews.
* Scheduled reports are not generated or sent.
## Enterprise plugins
......
docs/sources/enterprise/reporting.md
......@@ -6,47 +6,46 @@ type = "docs"
aliases = ["/docs/grafana/latest/administration/reports"]
[menu.docs]
parent = "enterprise"
weight = 8
weight = 400
+++
# Reporting
> Only available in Grafana Enterprise v6.4+.
Reporting allows you to automatically generate PDFs from any of your dashboards and have Grafana email them to interested parties on a schedule.
Reporting allows you to generate PDFs from any of your Dashboards and have them sent out to interested parties on a schedule.
> Only available in Grafana Enterprise v6.4+.
{{< docs-imagebox img="/img/docs/enterprise/reports_list.png" max-width="500px" class="docs-image--no-shadow" >}}
## Dashboard as a Report
With Reports there are a few things to keep in mind, most importantly, any changes you make to the Dashboard used in a report will be reflected in the report. If you change the time range in the Dashboard the time range will be the same in the report as well.
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.
## Setup
## Requirements
> SMTP must be configured for reports to be sent
* SMTP must be configured for reports to be sent. Refer to [SMTP]({{< relref "../installation/configuration.md#smtp" >}}) in [Configuration]({{< relref "../installation/configuration.md" >}}) for more information.
* The Image Renderer plugin must be installed or the remote rendering service must be set up. Refer to [Image rendering]({{< relref "../administration/image_rendering.md" >}}) for more information.
## Create or update a report
### Rendering
Currently only Organization Admins can create reports.
> Reporting requires the [rendering plugin]({{< relref "../administration/image_rendering.md#grafana-image-renderer-plugin" >}}).
Reporting with the built-in image rendering is not supported. We recommend installing the image renderer plugin.
## Usage
1. Click on the reports icon in the side menu. The Reports tab allow you to view, create, and update your reports.
1. 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.
1. **Preview** the report to make sure it appears as you expect. Update if necessary.
1. Enter scheduling information. Options vary depending on the frequency you select.
1. **Save** the report.
{{< docs-imagebox img="/img/docs/enterprise/reports_create_new.png" max-width="500px" class="docs-image--no-shadow" >}}
Currently only Organisation Admins can create reports. To get to report click on the reports icon in the side menu. This will allow you to list, create and update your reports.
| Setting | Description |
| --------------|------------------------------------------------------------------ |
| Name | name of the Report |
| Dashboard | what dashboard to generate the report from |
| Recipients | emails of the people who will receive this report |
| ReplyTo | your email address, so that the recipient can respond |
| Message | message body in the email with the report |
| Schedule | how often do you want the report generated and sent |
## Troubleshoot reporting
## Debugging errors
To troubleshoot and get more log information, enable debug logging in the configuration file. Refer to [Configuration]({{< relref "../installation/configuration.md#filters" >}}) for more information.
If you have problems with the reporting feature you can enable debug logging by switching the logger to debug (`filters = report:debug`). Learn more about making configuration changes [here]({{< relref "../installation/configuration.md#filters" >}}).
```bash
[log]
filters = saml.auth:debug
```
docs/sources/enterprise/saml.md
......@@ -7,155 +7,101 @@ type = "docs"
[menu.docs]
name = "SAML"
parent = "authentication"
weight = 5
weight = 500
+++
# SAML authentication
> Only available in Grafana Enterprise v6.3+.
The SAML authentication integration allows your Grafana users to log in by using an external SAML Identity Provider (IdP). To enable this, Grafana becomes a Service Provider (SP) in the authentication flow, interacting with the IdP to exchange user information.
## Supported SAML
SAML authentication integration allows your Grafana users to log in by using an external SAML 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.
> Should you encounter any problems with our implementation, please don't hesitate to contact us.
> Only available in Grafana Enterprise v6.3+. If you encounter any problems with our implementation, please don't hesitate to contact us.
Grafana supports:
## Supported SAML
* From the Service Provider (SP) to the Identity Provider (IdP)
Grafana supports the following SAML integrations.
* 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)
* From the Identity Provider (IdP) to the Service Provider (SP):
- `HTTP-POST` binding
* In terms of security, we currently support signed and encrypted Assertions. However, signed or encrypted requests are not supported.
In terms of security:
* Grafana supports signed and encrypted assertions.
* Grafana does not support signed or encrypted requests.
* In terms of initiation, only SP-initiated requests are supported. There's no support for IdP-initiated request.
In terms of initiation:
* Grafana supports SP-initiated requests.
* Grafana does not support IdP-initiated request.
## Set up SAML authentication
To use the SAML integration, you need to enable SAML in the [main config file]({{< relref "../installation/configuration.md" >}}).
```bash
[auth.saml]
# Defaults to false. If true, the feature is enabled
enabled = true
# Base64-encoded public X.509 certificate. Used to sign requests to the IdP
certificate =
# Path to the public X.509 certificate. Used to sign requests to the IdP
certificate_path =
# Base64-encoded private key. Used to decrypt assertions from the IdP
private_key =
# Path to the private key. Used to decrypt assertions from the IdP
private_key_path =
# Base64-encoded IdP SAML metadata XML. Used to verify and obtain binding locations from the IdP
idp_metadata =
# Path to the SAML metadata XML. Used to verify and obtain binding locations from the IdP
idp_metadata_path =
# URL to fetch SAML IdP metadata. Used to verify and obtain binding locations from the IdP
idp_metadata_url =
# Duration, since the IdP issued a response and the SP is allowed to process it. Defaults to 90 seconds
max_issue_delay =
# Duration, for how long the SP's metadata should be valid. Defaults to 48 hours
metadata_valid_duration =
# Friendly name or name of the attribute within the SAML assertion to use as the user's name
assertion_attribute_name = displayName
# Friendly name or name of the attribute within the SAML assertion to use as the user's login handle
assertion_attribute_login = mail
# Friendly name or name of the attribute within the SAML assertion to use as the user's email
assertion_attribute_email = mail
```
Important to note:
- Like any other Grafana configuration, use of [environment variables for these options is supported]({{< relref "../installation/configuration.md#using-environment-variables" >}})
- Only one form of configuration option is required. Using multiple forms, e.g. both `certificate` and `certificate_path` will result in an error
## Grafana configuration
Example working configuration:
```bash
[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
```
Available options:
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]({{< relref "../installation/configuration.md#configure-with-environment-variables" >}}).
| Setting | Required | Description | Default |
| ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | ------------- |
| `enabled` | No | Whenever SAML authentication is allowed | `false` |
| `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` or `idp_metadata_path` or `idp_metadata_url` | Yes | Base64-encoded string, Path or URL for the IdP SAML metadata XML | |
| `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's metadata should be valid | `48h` |
| `assertion_attribute_name` | No | Friendly name or name of the attribute within the SAML assertion to use as the user's name | `displayName` |
| `assertion_attribute_login` | No | Friendly name or name of the attribute within the SAML assertion to use as the user's login handle | `mail` |
| `assertion_attribute_email` | No | Friendly name or name of the attribute within the SAML assertion to use as the user's email | `mail` |
| `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` |
### Cert and private key
### 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]({{< relref "../installation/configuration.md" >}}) 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 (e.g. `certificate=`), the configuration assumes you've supplied the base64-encoded file contents. However, if specified with the `_path` suffix (e.g. `certificate_path=`) Grafana will treat it as a file path and attempt to read the file from the file system.
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 attempt 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
Expanding on the above, we'll also need the public part from our IdP for message verification. The SAML IdP metadata XML tells us where and how we should exchange the user information.
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.
Currently, we support three ways of specifying the IdP metadata. Without a suffix `idp_metadata=` Grafana assumes base64-encoded XML file contents, with the `_path` suffix assumes a file path and attempts to read the file from the file system and with the `_url` suffix assumes an URL and attempts to load the metadata from the given location.
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.
### Max issue delay
### Maximum issue delay
Prevention of SAML response replay attacks and internal clock skews between the SP (Grafana), and the IdP is covered. You can set a maximum amount of time between the IdP issuing a response and the SP (Grafana) processing it.
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 e.g. `max_issue_delay = 90s` or `max_issue_delay = 1h`
The configuration options is specified as a duration, such as `max_issue_delay = 90s` or `max_issue_delay = 1h`.
### Metadata valid duration
As an SP, our metadata is likely to expire at some point, e.g. 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 standard's `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.
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 e.g. `metadata_valid_duration = 48h`
The configuration option is specified as a duration, such as `metadata_valid_duration = 48h`.
## Identity provider (IdP) registration
### 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's metadata. You can either download and upload it manually or make the IdP request it directly from the endpoint. Some providers name it Identifier or Entity ID.
* 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.
- 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
## Assertion mapping
During the SAML SSO authentication flow, we receive the ACS (Assertion Customer Service) 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.
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).
......@@ -163,9 +109,24 @@ Grafana provides configuration options that let you modify which keys to look at
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.
## Troubleshooting
## Example SAML configuration
```bash
[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
```
## Troubleshoot SAML authentication
To troubleshoot and get more log info enable saml debug logging in the [main config file]({{< relref "../installation/configuration.md" >}}).
To troubleshoot and get more log information, enable SAML debug logging in the configuration file. Refer to [Configuration]({{< relref "../installation/configuration.md#filters" >}}) for more information.
```bash
[log]
......
docs/sources/enterprise/team-sync.md
......@@ -7,41 +7,45 @@ type = "docs"
[menu.docs]
name = "Team sync"
parent = "enterprise"
weight = 5
weight = 600
+++
# Team sync
> Only available in Grafana Enterprise.
{{< docs-imagebox img="/img/docs/enterprise/team_members_ldap.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" >}}
With the Team Sync it's possible to setup synchronization between your auth providers teams and teams in Grafana. This enables LDAP or GitHub OAuth users which are members
of certain teams/groups to automatically be added/removed as members to certain teams in Grafana. Currently the synchronization will only happen every
time a user logs in, unless LDAP is used together with active background synchronization that was added in Grafana 6.3.
Team sync lets you set up synchronization between your auth providers teams and teams in Grafana. This enables LDAP or GitHub OAuth 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.
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 LDAP group membership (for example) 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.
<div class="clearfix"></div>
### Enable synchronization for a team
## 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.
{{< docs-imagebox img="/img/docs/enterprise/team_add_external_group.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" >}}
1. Navigate to Configuration / Teams.
2. Select a team.
3. Select the External group sync tab and click on the `Add group` button.
4. Insert the value of the group you want to sync with. This becomes what Grafana denominates as a `GroupID`.
1. In Grafana, navigate to **Configuration > Teams**.
1. Select a team.
1. On the External group sync tab, and click **Add group**.
1. Insert the value of the group you want to sync with. This becomes the Grafana `GroupID`.
Examples:
- Using LDAP as an example, this is the LDAP distinguished name (DN) of LDAP group you want to synchronize with the team.
- Using Auth Proxy as an example, this is the value we receive as part of the custom `Groups` header.
- 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.
5. Click on `Add group` button to save.
1. Click `Add group` to save.
### Supported Providers
## Supported providers
* [LDAP]({{< relref "enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
* [Auth Proxy]({{< relref "../auth/auth-proxy.md#team-sync-enterprise-only">}})
* [GitHub OAuth]({{< relref "../auth/github.md#team-sync-enterprise-only" >}})
* [GitLab OAuth]({{< relref "../auth/gitlab.md#team-sync-enterprise-only" >}})
* [Auth Proxy]({{< relref "../auth/auth-proxy.md#team-sync-enterprise-only">}})
* [LDAP]({{< relref "enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
docs/sources/enterprise/white-labeling.md
......@@ -7,27 +7,31 @@ type = "docs"
[menu.docs]
name = "White-labeling"
parent = "enterprise"
weight = 5
weight = 700
+++
# White labeling
> Only available in Grafana Enterprise v6.6+.
White labeling allows you to replace the Grafana brand and logo with your own corporate brand and logo.
{{< docs-imagebox img="/img/docs/v66/whitelabeling_1.png" max-width="800px" caption="White labeling example" >}}
> Only available in Grafana Enterprise v6.6+.
Grafana Enterprise has white labeling options in the `grafana.ini` file (can also be set via ENV variables).
Grafana Enterprise has white labeling options in the `grafana.ini` file. As with all configuration options, you can also be set set them with environment variables.
You can change the following elements:
- Application Title
- Login Background
- Login Logo
- Application title
- Login background
- Login logo
- Side menu top logo
- Footer & Help menu links
- Footer and help menu links
- Fav icon (shown in browser tab)
> You will have to host your logo and other images used by the white labeling feature separately.
> 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.
{{< docs-imagebox img="/img/docs/v66/whitelabeling_1.png" max-width="800px" caption="White labeling example" >}}
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]({{< relref "../installation/configuration.md">}}).
```ini
# Enterprise only
......@@ -50,21 +54,24 @@ You can change the following elements:
# Set to complete URL to override apple/ios icon
;apple_touch_icon =
```
# Below is an example for how to replace the default footer & help links with 2 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
Below is an example for how to replace the default footer and help links with two custom links.
```ini
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.
ENV Variables:
```
- 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
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
```
docs/sources/menu.yaml
......@@ -14,15 +14,15 @@
children:
- name: Requirements
link: /installation/requirements/
- name: Install on Ubuntu / Debian
- name: Install on Ubuntu/Debian
link: /installation/debian/
- name: Install on Centos / Redhat
- name: Install on Centos/RedHat/SUSE
link: /installation/rpm/
- name: Install on Windows
link: /installation/windows/
- name: Install on macOS
link: /installation/mac/
- name: Install using Docker
- name: Run Docker image
link: /installation/docker/
- name: Upgrade Grafana
link: /installation/upgrading/
......@@ -109,7 +109,7 @@
name: Dashboard list
- link: /features/panels/text/
name: Text
- name: Dashboard Features
- name: Dashboard features
link: /features/dashboard/
children:
- link: /features/dashboard/dashboards/
......@@ -140,7 +140,7 @@
name: JSON Model
- link: /reference/scripting/
name: Scripted dashboards
- name: Data Sources
- name: Data sources
link: /features/datasources/
children:
- link: /features/datasources/add-data-source/
......@@ -192,7 +192,7 @@
link: /features/reporting/
- name: Navigation links
link: /features/navigation-links/
- name: What's New In Grafana
- name: What's new In Grafana
link: /whatsnew/
children:
- name: Version 6.6
......@@ -245,12 +245,12 @@
children:
- name: Overview
link: /enterprise/
- name: Reporting
link: /enterprise/reporting/
- name: Data source permissions
link: /enterprise/datasource_permissions/
- name: Enhanced LDAP
link: /enterprise/enhanced_ldap/
- name: Reporting
link: /enterprise/reporting/
- name: SAML authentication
link: /enterprise/saml/
- name: Team sync
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment