Skip to content

N
nexpie-grafana-theme
Commit d7a5f3ef by Alexander Zobnin Committed by GitHub
Options

Docs: SAML role and team sync (#23986) 

* SAML: add docs for config options

* SAML: role and org mapping docs

* SAML: team sync docs

* Docs: add SAML to the team sync providers list

* Apply suggestions from code review

Co-Authored-By: Leonard Gram <leo@xlson.com>

* SAML: add `assertion_attribute_org` option to the org mapping example config

* SAML: write config sections as steb-by-step tasks

* SAML: docs tweaks

* SAML docs: minor style fixes

* SAML docs: update availability note

* Docs: add enterprise config page

* Docs: link saml options to the config page

* Apply suggestions from code review

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Docs: rename configuration to enterprise-configuration

* Docs: user's -> user

Co-authored-by: Leonard Gram <leo@xlson.com>
Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
parent bd3ca551
Showing with 273 additions and 2 deletions
docs/sources/enterprise/_index.md
......@@ -45,6 +45,7 @@ Supported auth providers:
* [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" >}})
* [SAML]({{< relref "saml.md#configure-team-sync" >}})
## Reporting
......
docs/sources/enterprise/enterprise-configuration.md 0 → 100644
+++
title = "Enterprise configuration"
description = "Enterprise configuration documentation"
keywords = ["grafana", "configuration", "documentation", "enterprise"]
type = "docs"
[menu.docs]
name = "Enterprise configuration"
identifier = "enterprise-config"
parent = "enterprise"
weight = 300
+++
# 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]({{< relref "../installation/configuration.md" >}}) 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:
```bash
[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 links IDs to use here. Grafana will look for matching links 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 gets 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.
docs/sources/enterprise/saml.md
......@@ -52,6 +52,14 @@ The table below describes all SAML configuration options. Continue reading below
| `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
......@@ -109,6 +117,69 @@ 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.
### Configure team sync
> Team sync support for SAML only available in Grafana v7.0+
To use SAML Team sync, set [`assertion_attribute_groups`]({{< relref "./enterprise-configuration.md#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]({{< relref "../enterprise/team-sync.md" >}})
### 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]({{< relref "../permissions/organization_roles.md#editor-role" >}}), [Admin]({{< relref "../permissions/organization_roles.md#admin-role" >}}) and [Grafana Admin]({{< relref "../permissions/overview.md#grafana-admin" >}}) roles.
1. In the configuration file, set [`assertion_attribute_role`]({{< relref "./enterprise-configuration.md#assertion-attribute-role" >}}) option to the attribute name where the role information will be extracted from.
1. Set the [`role_values_editor`]({{< relref "./enterprise-configuration.md#role-values-editor" >}}) option to the values mapped to the `Editor` role.
1. Set the [`role_values_admin`]({{< relref "./enterprise-configuration.md#role-values-admin" >}}) option to the values mapped to the organization `Admin` role.
1. Set the [`role_values_grafana_admin`]({{< relref "./enterprise-configuration.md#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]({{< relref "../permissions/organization_roles.md" >}}) for more information about roles and permissions in Grafana.
Example configuration:
```bash
[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.
1. In configuration file, set [`assertion_attribute_org`]({{< relref "./enterprise-configuration.md#assertion-attribute-org" >}}) to the attribute name you store organization info in.
1. Set [`org_mapping`]({{< relref "./enterprise-configuration.md#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:
```bash
[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`]({{< relref "./enterprise-configuration.md#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
```bash
......@@ -122,6 +193,15 @@ 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
```
## Troubleshoot SAML authentication
......
docs/sources/enterprise/team-sync.md
......@@ -14,8 +14,7 @@ weight = 600
{{< docs-imagebox img="/img/docs/enterprise/team_members_ldap.png" class="docs-image--no-shadow docs-image--right" max-width= "600px" >}}
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.
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.
......@@ -50,3 +49,4 @@ If you have already grouped some users into a team, then you can synchronize tha
* [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" >}})
* [SAML]({{< relref "saml.md#configure-team-sync" >}})
docs/sources/menu.yaml
......@@ -261,6 +261,8 @@
children:
- name: Overview
link: /enterprise/
- name: Configuration
link: /enterprise/enterprise-configuration/
- name: Data source permissions
link: /enterprise/datasource_permissions/
- name: Enhanced LDAP
......
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