mirror of https://github.com/grafana/grafana
Docs: Refactored Enterprise side menu (#22189)
* Refactored Enterprise side menu * Update menu.yaml * Fixed links * Update menu.yamlpull/22221/head
Diana Payton
5 years ago
committed by
GitHub
parent
d03075b811
commit
0d3d8edb92
@ -0,0 +1,69 @@ |
||||
+++ |
||||
title = "Data source permissions" |
||||
description = "Grafana Datasource Permissions Guide " |
||||
keywords = ["grafana", "configuration", "documentation", "datasource", "permissions", "users", "teams", "enterprise"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Datasource" |
||||
identifier = "datasource-permissions" |
||||
parent = "enterprise" |
||||
weight = 4 |
||||
+++ |
||||
|
||||
# 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 |
||||
|
||||
{{< 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. |
||||
|
||||
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. |
||||
|
||||
**To enable permissions for a data source:** |
||||
|
||||
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. |
||||
|
||||
<div class="clearfix"></div> |
||||
|
||||
## Allow users and teams to query a data source |
||||
|
||||
{{< 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. |
||||
|
||||
**Assign query permission to users and teams:** |
||||
|
||||
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. |
||||
|
||||
<div class="clearfix"></div> |
||||
|
||||
## Restore Default Access - Disable 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. |
||||
|
||||
**Disable permissions for a data source:** |
||||
|
||||
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. |
||||
|
||||
<div class="clearfix"></div> |
||||
@ -0,0 +1,64 @@ |
||||
+++ |
||||
title = "Enhanced LDAP Integration" |
||||
description = "Grafana Enhanced LDAP Integration Guide " |
||||
keywords = ["grafana", "configuration", "documentation", "ldap", "active directory", "enterprise"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Enhanced LDAP" |
||||
identifier = "enhanced-ldap" |
||||
parent = "enterprise" |
||||
weight = 3 |
||||
+++ |
||||
|
||||
# Enhanced LDAP integration |
||||
|
||||
> Only available in Grafana Enterprise. |
||||
|
||||
The enhanced LDAP integration adds additional functionality on top of the existing [LDAP integration]({{< relref "../auth/ldap.md" >}}). |
||||
|
||||
## 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. |
||||
|
||||
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. |
||||
|
||||
[Learn more about Team Sync]({{< relref "team-sync.md">}}) |
||||
|
||||
<div class="clearfix"></div> |
||||
|
||||
## Active LDAP Synchronization |
||||
|
||||
> Only available in Grafana Enterprise v6.3+ |
||||
|
||||
In the open source version of Grafana, user data from LDAP will be synchronized only during the login process when authenticating using LDAP. |
||||
|
||||
With this feature you can configure Grafana to actively sync users with LDAP servers in the background. Role and team membership will be updated, removed users will be disabled and logged out. Only users that have logged into Grafana at least once will be synchronized. |
||||
|
||||
```bash |
||||
[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 |
||||
``` |
||||
|
||||
### 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. |
||||
@ -0,0 +1,52 @@ |
||||
+++ |
||||
title = "Reporting" |
||||
description = "" |
||||
keywords = ["grafana", "reporting"] |
||||
type = "docs" |
||||
aliases = ["/docs/grafana/latest/administration/reports"] |
||||
[menu.docs] |
||||
parent = "enterprise" |
||||
weight = 8 |
||||
+++ |
||||
|
||||
# Reporting |
||||
|
||||
> Only available in Grafana Enterprise v6.4+. |
||||
|
||||
Reporting allows you to generate PDFs from any of your Dashboards and have them sent out to interested parties on a schedule. |
||||
|
||||
{{< 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. |
||||
|
||||
## Setup |
||||
|
||||
> SMTP must be configured for reports to be sent |
||||
|
||||
|
||||
### Rendering |
||||
|
||||
> 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 |
||||
|
||||
{{< 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 | |
||||
|
||||
## Debugging errors |
||||
|
||||
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" >}}). |
||||
@ -0,0 +1,173 @@ |
||||
+++ |
||||
title = "SAML Authentication" |
||||
description = "Grafana SAML Authentication" |
||||
keywords = ["grafana", "saml", "documentation", "saml-auth"] |
||||
aliases = ["/docs/grafana/latest/auth/saml/"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "SAML" |
||||
parent = "authentication" |
||||
weight = 5 |
||||
+++ |
||||
|
||||
# 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 |
||||
|
||||
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. |
||||
|
||||
Grafana supports: |
||||
|
||||
* 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, we currently support signed and encrypted Assertions. However, signed or encrypted requests are not supported. |
||||
|
||||
* In terms of initiation, only SP-initiated requests are supported. There's no support for 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: |
||||
|
||||
| Setting | Required | Description | Default | |
||||
| ----------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | ------------- | |
||||
| `enabled` | No | Whenever 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 | | |
||||
| `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` | |
||||
|
||||
### Cert 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. |
||||
|
||||
### 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. |
||||
|
||||
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. |
||||
|
||||
### Max 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. |
||||
|
||||
The configuration options is specified as a duration e.g. `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. |
||||
|
||||
The configuration option is specified as a duration e.g. `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'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/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, 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. |
||||
|
||||
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. |
||||
|
||||
## Troubleshooting |
||||
|
||||
To troubleshoot and get more log info enable saml debug logging in the [main config file]({{< relref "../installation/configuration.md" >}}). |
||||
|
||||
```bash |
||||
[log] |
||||
filters = saml.auth:debug |
||||
``` |
||||
@ -0,0 +1,47 @@ |
||||
+++ |
||||
title = "Team sync" |
||||
description = "Grafana Team Sync" |
||||
keywords = ["grafana", "auth", "documentation"] |
||||
aliases = ["/docs/grafana/latest/auth/saml/"] |
||||
type = "docs" |
||||
[menu.docs] |
||||
name = "Team sync" |
||||
parent = "enterprise" |
||||
weight = 5 |
||||
+++ |
||||
|
||||
# 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. |
||||
|
||||
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. |
||||
|
||||
<div class="clearfix"></div> |
||||
|
||||
### Enable synchronization for a team |
||||
|
||||
{{< 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`. |
||||
|
||||
- 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. |
||||
|
||||
5. Click on `Add group` button to save. |
||||
|
||||
### Supported Providers |
||||
|
||||
* [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">}}) |
||||
Loading…
Reference in new issue