Docs: SAML role and team sync (grafana#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>
kevisong · May 8, 2020 · d7a5f3e · d7a5f3e
1 parent bd3ca55
commit d7a5f3e
Show file tree

Hide file tree

Showing 5 changed files with 282 additions and 11 deletions.
diff --git a/docs/sources/enterprise/_index.md b/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
 

diff --git a/docs/sources/enterprise/enterprise-configuration.md b/docs/sources/enterprise/enterprise-configuration.md
@@ -0,0 +1,188 @@
++++
+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.
diff --git a/docs/sources/enterprise/saml.md b/docs/sources/enterprise/saml.md
@@ -43,15 +43,23 @@ The table below describes all SAML configuration options. Continue reading below
 
 | 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`        |
+| `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
 
@@ -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

diff --git a/docs/sources/enterprise/team-sync.md b/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" >}})
diff --git a/docs/sources/menu.yaml b/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