OAuth: Allow role mapping from GitHub and GitLab groups (#52407)

* OAuth: Add extract role support to github

OAuth: correct github errors

Oauth: add github tests

Oauth: Allow mapping via group memberships

Oauth: Add markdown instructions to the new mappers

fix lint

* Apply suggestions from code review

Co-authored-by: Gabriel MABILLE <gamab@users.noreply.github.com>
Co-authored-by: Vardan Torosyan <vardants@gmail.com>

* Apply suggestions from code review

Co-authored-by: Gabriel MABILLE <gamab@users.noreply.github.com>
Co-authored-by: Vardan Torosyan <vardants@gmail.com>

docs/sources/setup-grafana/configure-security/configure-authentication/github.md

@@ -101,6 +101,35 @@ allow_sign_up = true
 allowed_organizations = github google
 ```
 
+### Map roles
+
+You can use GitHub OAuth to map roles. During mapping, Grafana checks for the presence of a role using the [JMESPath](http://jmespath.org/examples.html) specified via the `role_attribute_path` configuration option.
+
+For the path lookup, Grafana uses JSON obtained from querying GitHub's API [`/api/user`](https://docs.github.com/en/rest/users/users#get-the-authenticated-user=) endpoint and a `groups` key containing all of the user's teams (retrieved from `/api/user/teams`).
+
+The result of evaluating the `role_attribute_path` JMESPath expression must be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../administration/roles-and-permissions/" >}}).
+
+An example Query could look like the following:
+
+```bash
+role_attribute_path = [login==octocat] && 'Admin' || 'Viewer'
+```
+
+This allows the user with login "octocat" to be mapped to the `Admin` role,
+but all other users to be mapped to the `Viewer` role.
+
+#### Map roles using teams
+
+Teams can also be used to map roles. For instance,
+if you have a team called 'example-group' you can use the following snippet to
+ensure those members inherit the role 'Editor'.
+
+```bash
+role_attribute_path = contains(groups[*], '@github/example-group') && 'Editor' || 'Viewer'
+```
+
+Note: If a match is found in other fields, teams will be ignored.
+
 ### Team Sync (Enterprise only)
 
 > Only available in Grafana Enterprise v6.3+

docs/sources/setup-grafana/configure-security/configure-authentication/gitlab.md

@@ -122,7 +122,7 @@ role_attribute_path = is_admin && 'Admin' || 'Viewer'
 
 You can use GitLab OAuth to map roles. During mapping, Grafana checks for the presence of a role using the [JMESPath](http://jmespath.org/examples.html) specified via the `role_attribute_path` configuration option.
 
-For the path lookup, Grafana uses JSON obtained from querying GitLab's API [`/api/v4/user`](https://docs.gitlab.com/ee/api/users.html#list-current-user-for-normal-users) endpoint. The result of evaluating the `role_attribute_path` JMESPath expression must be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../administration/roles-and-permissions/" >}}).
+For the path lookup, Grafana uses JSON obtained from querying GitLab's API [`/api/v4/user`](https://docs.gitlab.com/ee/api/users.html#list-current-user-for-normal-users) endpoint and a `groups` key containing all of the user's teams. The result of evaluating the `role_attribute_path` JMESPath expression must be a valid Grafana role, for example, `Viewer`, `Editor` or `Admin`. For more information about roles and permissions in Grafana, refer to [Roles and permissions]({{< relref "../../../administration/roles-and-permissions/" >}}).
 
 An example Query could look like the following:
 
@@ -132,6 +132,19 @@ role_attribute_path = is_admin && 'Admin' || 'Viewer'
 
 This allows every GitLab Admin to be an Admin in Grafana.
 
+#### Map roles using groups
+
+Groups can also be used to map roles. Group name (lowercased and unique) is used instead of display name for identifying groups
+
+For instance, if you have a group with display name 'Example-Group' you can use the following snippet to
+ensure those members inherit the role 'Editor'.
+
+```bash
+role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'
+```
+
+Note: If a match is found in other fields, groups will be ignored.
+
 ### Team Sync (Enterprise only)
 
 > Only available in Grafana Enterprise v6.4+