store scopes on oauth clients, too

rather than roles, matching tokens

because oauth clients are mostly involved with issuing tokens,
they don't have roles themselves (their owners do).

This deprecates the `oauth_roles` config on Spawners and Services, in favor of `oauth_allowed_scopes`.

The ambiguously named `oauth_scopes` is renamed to `oauth_access_scopes`.

docs/source/_static/rest-api.yml

@@ -564,7 +564,7 @@ paths:
                     A list of role names from which to derive scopes.
                     This is a shortcut for assigning collections of scopes;
                     Tokens do not retain role assignment.
-                    (Changed in 2.3: roles are immediately resolved to scopes
+                    (Changed in 2.4: roles are immediately resolved to scopes
                     instead of stored on roles.)
                   items:
                     type: string
@@ -572,7 +572,7 @@ paths:
                   type: array
                   description: |
                     A list of scopes that the token should have.
-                    (new in JupyterHub 2.3).
+                    (new in JupyterHub 2.4).
                   items:
                     type: string
         required: false

docs/source/rbac/scopes.md

@@ -231,7 +231,12 @@ async def write_something(request):
 
 If you use {class}`~.HubOAuthenticated`, this check is performed automatically
 against the `.hub_scopes` attribute of each Handler
-(the default is populated from `$JUPYTERHUB_OAUTH_SCOPES` and usually `access:services!service=myservice`).
+(the default is populated from `$JUPYTERHUB_OAUTH_ACCESS_SCOPES` and usually `access:services!service=myservice`).
+
+:::{versionchanged} 2.4
+The JUPYTERHUB_OAUTH_SCOPES environment variable is deprecated and renamed to JUPYTERHUB_OAUTH_ACCESS_SCOPES,
+to avoid ambiguity with JUPYTERHUB_OAUTH_ALLOWED_SCOPES
+:::
 
 ```python
 from tornado import web

docs/source/reference/services.md

@@ -116,7 +116,10 @@ JUPYTERHUB_BASE_URL:       Base URL of the Hub (https://mydomain[:port]/)
 JUPYTERHUB_SERVICE_PREFIX: URL path prefix of this service (/services/:service-name/)
 JUPYTERHUB_SERVICE_URL:    Local URL where the service is expected to be listening.
                            Only for proxied web services.
-JUPYTERHUB_OAUTH_SCOPES:   JSON-serialized list of scopes to use for allowing access to the service.
+JUPYTERHUB_OAUTH_SCOPES:   JSON-serialized list of scopes to use for allowing access to the service
+                           (deprecated in 2.4, use JUPYTERHUB_OAUTH_ACCESS_SCOPES).
+JUPYTERHUB_OAUTH_ACCESS_SCOPES: JSON-serialized list of scopes to use for allowing access to the service (new in 2.4).
+JUPYTERHUB_OAUTH_ALLOWED_SCOPES: JSON-serialized list of scopes that can be requested on behalf of users (new in 2.4).
 ```
 
 For the previous 'cull idle' Service example, these environment variables
@@ -376,7 +379,7 @@ The `scopes` field can be used to manage access.
 Note: a user will have access to a service to complete oauth access to the service for the first time.
 Individual permissions may be revoked at any later point without revoking the token,
 in which case the `scopes` field in this model should be checked on each access.
-The default required scopes for access are available from `hub_auth.oauth_scopes` or `$JUPYTERHUB_OAUTH_SCOPES`.
+The default required scopes for access are available from `hub_auth.oauth_scopes` or `$JUPYTERHUB_OAUTH_ACCESS_SCOPES`.
 
 An example of using an Externally-Managed Service and authentication is
 in [nbviewer README][nbviewer example] section on securing the notebook viewer,

docs/source/reference/spawners.md

@@ -308,6 +308,9 @@ The process environment is returned by `Spawner.get_env`, which specifies the fo
   This is also the OAuth client secret.
 - JUPYTERHUB_CLIENT_ID - the OAuth client ID for authenticating visitors.
 - JUPYTERHUB_OAUTH_CALLBACK_URL - the callback URL to use in oauth, typically `/user/:name/oauth_callback`
+- JUPYTERHUB_OAUTH_ACCESS_SCOPES - the scopes required to access the server (called JUPYTERHUB_OAUTH_SCOPES prior to 2.4)
+- JUPYTERHUB_OAUTH_ALLOWED_SCOPES - the scopes the service is allowed to request.
+  If no scopes are requested explicitly, these scopes will be requested.
 
 Optional environment variables, depending on configuration: