Merge pull request #267 from DentonGentry/master

Add gitlab scope documentation

github_scope.md

@@ -5,7 +5,7 @@ be used to extend the GitHub OAuthenticator. By overriding the scope
 list in the authenticator, additional features can be enabled for
 specific deployment needs.
 
-## Example GiHub scopes
+## Example GitHub scopes
 
 The following GitHub scopes may be suitable for certain use cases:
 

gitlab_scope.md

@@ -0,0 +1,39 @@
+Scopes may be added to the GitLab OAuthenticator by overriding the
+scope list, like so:
+
+    c.GitLabOAuthenticator.scope = ['read_user']
+
+
+The following scopes are implemented in GitLab 11.x:
+
+`api`: Grants complete read/write access to the API, including all
+groups and projects. If no other scope is requested, this is the default.
+This is a *very* powerful set of permissions, it is recommended to limit
+the scope of authentication to something other than API.
+
+`read_user`: Grants read-only access to the authenticated user's
+profile through the /user API endpoint, which includes username,
+public email, and full name. Also grants access to read-only
+API endpoints under /users.
+
+`read_repository`: Grants read-only access to repositories on
+private projects using Git-over-HTTP (not using the API).
+
+`write_repository`: Grants read-write access to repositories
+on private projects using Git-over-HTTP (not using the API).
+
+`read_registry`: Grants read-only access to container registry
+images on private projects.
+
+`sudo`: Grants permission to perform API actions as any user
+in the system, when authenticated as an admin user.
+
+`openid`: Grants permission to authenticate with GitLab using
+OpenID Connect. Also gives read-only access to the user's
+profile and group memberships.
+
+`profile`: Grants read-only access to the user's profile data
+using OpenID Connect.
+
+`email`: Grants read-only access to the user's primary email
+address using OpenID Connect.

oauthenticator/gitlab.py

@@ -68,6 +68,9 @@ class GitLabLoginHandler(OAuthLoginHandler, GitLabMixin):
 
 
 class GitLabOAuthenticator(OAuthenticator):
+    # see gitlab_scopes.md for details about scope config
+    # set scopes via config, e.g.
+    # c.GitLabOAuthenticator.scope = ['read_user']
 
     login_service = "GitLab"