further emphasize that admin_users config only grants permission

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

@@ -93,6 +93,25 @@ A set of initial admin users, `admin_users` can be configured as follows:
 c.Authenticator.admin_users = {'mal', 'zoe'}
 ```
 
+:::{warning}
+`admin_users` config can only be used to _grant_ admin permissions.
+Removing users from this set **does not** remove their admin permissions,
+which must be done via the admin page or API.
+
+Role assignments via `load_roles` are the only way to _revoke_ past permissions from configuration:
+
+```python
+c.JupyterHub.load_roles = [
+    {
+        "name": "admin",
+        "users": ["admin1", "..."],
+    }
+]
+```
+
+or, better yet, [specify your own roles](define-role-target) with only the permissions your admins actually need.
+:::
+
 Users in the admin set are automatically added to the user `allowed_users` set,
 if they are not already present.
 

jupyterhub/auth.py

@@ -102,18 +102,37 @@ class Authenticator(LoggingConfigurable):
 
     admin_users = Set(
         help="""
-        Set of users that will have admin rights on this JupyterHub.
+        Set of users that will be granted admin rights on this JupyterHub.
 
-        Note: As of JupyterHub 2.0,
+        Note:
-        full admin rights should not be required,
-        and more precise permissions can be managed via roles.
 
-        Admin users have extra privileges:
+            As of JupyterHub 2.0,
-         - Use the admin panel to see list of users logged in
+            full admin rights should not be required,
-         - Add / remove users in some authenticators
+            and more precise permissions can be managed via roles.
-         - Restart / halt the hub
+
-         - Start / stop users' single-user servers
+        Caution:
-         - Can access each individual users' single-user server (if configured)
+
+            Adding users to `admin_users` can only *grant* admin rights,
+            removing a username from the admin_users set **DOES NOT** remove admin rights previously granted.
+
+            For an authoritative, restricted set of admins,
+            assign explicit membership of the `admin` *role*::
+            
+                c.JupyterHub.load_roles = [
+                    {
+                        "name": "admin",
+                        "users": ["admin1", "..."],
+                    }
+                ]
+
+        Admin users can take every possible action on behalf of all users,
+        for example:
+
+        - Use the admin panel to see list of users logged in
+        - Add / remove users in some authenticators
+        - Restart / halt the hub
+        - Start / stop users' single-user servers
+        - Can access each individual users' single-user server
 
         Admin access should be treated the same way root access is.