docs: team sync (#18239)

* docs: team sync

* docs: update team sync with regards to auth proxy

* Add a footnote on server-side session cache

* Docs: minor edits.

docs/sources/auth/auth-proxy.md

@@ -218,3 +218,80 @@ ProxyPassReverse / http://grafana:3000/
 ### Use grafana.
 
 With our Grafana and Apache containers running, you can now connect to http://localhost/ and log in using the username/password we created in the htpasswd file.
+
+### Team Sync (Enterprise only)
+
+> Only available in Grafana Enterprise v6.3+
+
+With Team Sync, it's possible to set up synchronization between teams in your authentication provider and Grafana. You can send Grafana values as part of an HTTP header and have Grafana map them to your team structure. This allows you to put users into specific teams automatically.
+
+To support the feature, auth proxy allows optional headers to map additional user attributes. The specific attribute to support team sync  is `Groups`.
+
+```bash
+# Optionally define more headers to sync other user attributes
+headers = "Groups:X-WEBAUTH-GROUPS"
+```
+
+You use the `X-WEBAUTH-GROUPS` header to send the team information for each user. Specifically, the set of Grafana's group IDs that the user belongs to.
+
+First, we need to set up the mapping between your authentication provider and Grafana. Follow [these instructions]({{< relref "auth/team-sync.md#enable-synchronization-for-a-team" >}}) to add groups to a team within Grafana.
+
+Once that's done. You can verify your mappings by querying the API.
+
+```bash
+# First, inspect your teams and obtain the corresponding ID of the team we want to inspect the groups for.
+curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/teams/search
+{
+  "totalCount": 2,
+  "teams": [
+    {
+      "id": 1,
+      "orgId": 1,
+      "name": "Core",
+      "email": "core@grafana.com",
+      "avatarUrl": "/avatar/327a5353552d2dc3966e2e646908f540",
+      "memberCount": 1,
+      "permission": 0
+    },
+    {
+      "id": 2,
+      "orgId": 1,
+      "name": "Loki",
+      "email": "loki@grafana.com",
+      "avatarUrl": "/avatar/102f937d5344d33fdb37b65d430f36ef",
+      "memberCount": 0,
+      "permission": 0
+    }
+  ],
+  "page": 1,
+  "perPage": 1000
+}
+
+# Then, query the groups for that particular team. In our case, the Loki team which has an ID of "2".
+curl -H "X-WEBAUTH-USER: admin" http://localhost:3000/api/teams/2/groups
+[
+  {
+    "orgId": 1,
+    "teamId": 2,
+    "groupId": "lokiTeamOnExternalSystem"
+  }
+]
+```
+
+Finally, whenever Grafana receives a request with a header of `X-WEBAUTH-GROUPS: lokiTeamOnExternalSystem`, the user under authentication will be placed into the specified team. Placement in multiple teams is supported by using comma-separated values e.g. `lokiTeamOnExternalSystem,CoreTeamOnExternalSystem`.
+
+```bash
+curl -H "X-WEBAUTH-USER: leonard" -H "X-WEBAUTH-GROUPS: lokiteamOnExternalSystem" http://localhost:3000/dashboards/home
+{
+  "meta": {
+    "isHome": true,
+    "canSave": false,
+    ...
+}
+```
+
+With this, the user `leonard` will be automatically placed into the Loki team as part of Grafana authentication.
+
+Please note that by default server-side session caching is enabled. If a user has previously authenticated via Auth Proxy, team synchronization only happens once the sessions expire.
+
+[Learn more about Team Sync]({{< relref "auth/team-sync.md" >}})

docs/sources/auth/enhanced_ldap.md

@@ -22,23 +22,13 @@ The enhanced LDAP integration adds additional functionality on top of the [exist
 
 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, but an active background synchronization is currently being developed.
+time a user logs in, unless Grafana 6.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.
 
-<div class="clearfix"></div>
-
-### Enable LDAP group 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 LDAP distinguished name (DN) of LDAP group you want to synchronize with the team.
-5. Click on `Add group` button to save.
+[Learn more about Team Sync]({{< relref "auth/team-sync.md">}})
 
 <div class="clearfix"></div>
 

docs/sources/auth/github.md

@@ -108,9 +108,9 @@ the correct teams.
 
 Your GitHub teams can be referenced in two ways:
 
-- `https://github.com/orgs/<org>/teams/<team name>`
-- `@<org>/<team name>`
+- `https://github.com/orgs/<org>/teams/<slug>`
+- `@<org>/<slug>`
 
 Example: `@grafana/developers`
 
-[Learn more about Team Sync]({{< relref "auth/enhanced_ldap.md" >}})
+[Learn more about Team Sync]({{< relref "auth/team-sync.md" >}})

docs/sources/auth/team-sync.md

@@ -0,0 +1,47 @@
++++
+title = "Team Sync"
+description = "Grafana Team Sync"
+keywords = ["grafana", "auth", "documentation"]
+aliases = ["/auth/saml/"]
+type = "docs"
+[menu.docs]
+name = "Team Sync"
+parent = "authentication"
+weight = 5
++++
+
+# Team Sync
+
+> Team Sync is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "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 "auth/enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
+* [GitHub OAuth]({{< relref "auth/github.md#team-sync-enterprise-only" >}})
+* [Auth Proxy]({{< relref "auth/auth-proxy.md#team-sync-enterprise-only">}})

docs/sources/enterprise/_index.md

@@ -25,13 +25,24 @@ ___
 
 With Grafana Enterprise you can set up synchronization between LDAP Groups and Teams. [Learn More]({{< relref "auth/enhanced_ldap.md" >}}).
 
+### SAML Authentication
+
+Enables your Grafana Enterprise users to authenticate with SAML. [Learn More]({{< relref "auth/saml.md" >}}).
+
+### Team Sync
+
+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 "auth/team-sync.md" >}}).
+
+Supported auth providers:
+
+* [LDAP]({{< relref "auth/enhanced_ldap.md#ldap-group-synchronization-for-teams" >}})
+* [GitHub OAuth]({{< relref "auth/github.md#team-sync-enterprise-only" >}})
+* [Auth Proxy]({{< relref "auth/auth-proxy.md#team-sync-enterprise-only">}})
+
 ### Datasource Permissions
 
 Datasource permissions allow you to restrict query access to only specific Teams and Users. [Learn More]({{< relref "permissions/datasource_permissions.md" >}}).
 
-### SAML Authentication
-
-Enables your Grafana Enterprise users to authenticate with SAML. [Learn More]({{< relref "auth/saml.md" >}}).
 
 ### Premium Plugins