allow custom scopes

defined with

    c.JupyterHub.custom_scopes = {
        'custom:scope': {'description': "text shown on oauth confirm"}
    }

Allows injecting custom scopes to roles,
allowing extension of granular permissions to service-defined custom scopes.

Custom scopes:

- MUST start with `custom:`
- MUST only contain ascii lowercase, numbers, colon, hyphen, asterisk, underscore
- MUST define a `description`
- MAY also define `subscopes` list(s), each of which must also be explicitly defined

HubAuth can be used to retrieve and check for custom scopes to authorize requests.

examples/custom-scopes/jupyterhub_config.py

@@ -0,0 +1,43 @@
+import sys
+
+c = get_config()  # noqa
+
+c.JupyterHub.services = [
+    {
+        'name': 'grades',
+        'url': 'http://127.0.0.1:10101',
+        'command': [sys.executable, './grades.py'],
+        'oauth_roles': ['grader'],
+    },
+]
+
+c.JupyterHub.custom_scopes = {
+    "custom:grades:read": {
+        "description": "read-access to all grades",
+    },
+    "custom:grades:write": {
+        "description": "Enter new grades",
+        "subscopes": ["custom:grades:read"],
+    },
+}
+
+c.JupyterHub.load_roles = [
+    {
+        "name": "user",
+        # grant all users access to services
+        "scopes": ["access:services", "self"],
+    },
+    {
+        "name": "grader",
+        # grant graders access to write grades
+        "scopes": ["custom:grades:write"],
+        "users": ["grader", "instructor"],
+    },
+]
+
+c.JupyterHub.allowed_users = {"instructor", "grader", "student"}
+# dummy spawner and authenticator for testing, don't actually use these!
+c.JupyterHub.authenticator_class = 'dummy'
+c.JupyterHub.spawner_class = 'simple'
+c.JupyterHub.ip = '127.0.0.1'  # let's just run on localhost while dummy auth is enabled
+c.JupyterHub.log_level = 10