suggest roles instead of admin_users

and make admin link permission check match admin page

it would be nice if this could be consolidated (maybe an `admin:ui` permission?)

docs/source/getting-started/authenticators-users-basics.md

@@ -18,6 +18,13 @@ started.
 
 ## Configure admins (`admin_users`)
 
+```{note}
+As of JupyterHub 2.0, the full permissions of `admin_users`
+should not be required.
+Instead, you can assign [roles][] to users or groups
+with only the scopes they require.
+```
+
 Admin users of JupyterHub, `admin_users`, can add and remove users from
 the user `allowed_users` set. `admin_users` can take actions on other users'
 behalf, such as stopping and restarting their servers.

docs/source/rbac/roles.md

@@ -1,3 +1,5 @@
+(roles)=
+
 # Roles
 
 JupyterHub provides four roles that are available by default:

examples/postgres/hub/jupyterhub_config.py

@@ -2,10 +2,23 @@
 
 c = get_config()  # noqa
 
-# Add some users.
+# Add some users
-c.JupyterHub.admin_users = {'rhea'}
 c.Authenticator.allowed_users = {'ganymede', 'io', 'rhea'}
 
+c.JupyterHub.load_roles = [
+    {
+        "name": "user-admin",
+        "scopes": [
+            "admin:groups",
+            "admin:users",
+            "admin:servers",
+        ],
+        "users": [
+            "rhea",
+        ],
+    }
+]
+
 # These environment variables are automatically supplied by the linked postgres
 # container.
 import os

jupyterhub/app.py

@@ -1866,12 +1866,6 @@ class JupyterHub(Application):
             if not self.authenticator.validate_username(username):
                 raise ValueError("username %r is not valid" % username)
 
-        if not admin_users:
-            self.log.warning("No admin users, admin interface will be unavailable.")
-            self.log.warning(
-                "Add any administrative users to `c.Authenticator.admin_users` in config."
-            )
-
         new_users = []
 
         for name in admin_users:

jupyterhub/auth.py

@@ -88,6 +88,10 @@ class Authenticator(LoggingConfigurable):
         help="""
         Set of users that will have admin rights on this JupyterHub.
 
+        Note: As of JupyterHub 2.0,
+        full admin rights should not be required,
+        and more precise permissions can be managed via roles.
+
         Admin users have extra privileges:
          - Use the admin panel to see list of users logged in
          - Add / remove users in some authenticators
@@ -987,6 +991,10 @@ class PAMAuthenticator(LocalAuthenticator):
         Users not in these groups can still be granted admin status through admin_users.
 
         allowed/blocked rules still apply.
+
+        Note: As of JupyterHub 2.0,
+        full admin rights should not be required,
+        and more precise permissions can be managed via roles.
         """
     ).tag(config=True)
 

jupyterhub/handlers/base.py

@@ -1239,6 +1239,8 @@ class BaseHandler(RequestHandler):
             static_url=self.static_url,
             version_hash=self.version_hash,
             services=self.get_accessible_services(user),
+            parsed_scopes=self.parsed_scopes,
+            expanded_scopes=self.expanded_scopes,
         )
         if self.settings['template_vars']:
             ns.update(self.settings['template_vars'])

jupyterhub/handlers/pages.py

@@ -450,7 +450,8 @@ class AdminHandler(BaseHandler):
     """Render the admin page."""
 
     @web.authenticated
-    @needs_scope('users')  # stacked decorators: all scopes must be present
+    # stacked decorators: all scopes must be present
+    # note: keep in sync with admin link condition in page.html
     @needs_scope('admin:users')
     @needs_scope('admin:servers')
     async def get(self):

share/jupyterhub/templates/page.html

@@ -122,7 +122,7 @@
           {% block nav_bar_left_items %}
             <li><a href="{{base_url}}home">Home</a></li>
             <li><a href="{{base_url}}token">Token</a></li>
-            {% if user.admin %}
+            {% if 'admin:users' in parsed_scopes and 'admin:servers' in parsed_scopes %}
             <li><a href="{{base_url}}admin">Admin</a></li>
             {% endif %}
             {% if services %}