Question regarding API Token Scopes when using nbgrader with JupyterHub

[christina-seegers]

The documentation (https://nbgrader.readthedocs.io/en/stable/configuration/jupyterhub_config.html#jupyterhub-authentication) states "The course service additionally needs to have an API token set that is from a JupyterHub admin (see JupyterHub documentation)."
But does not specify what scopes are necessary for the token.
It would be good if it was known what the minimal scopes (https://jupyterhub.readthedocs.io/en/stable/rbac/scopes.html#available-scopes) are to run nbgrader.
The best would be to include that information into the documentation.

Operating system

nbgrader --version

0.9.2

jupyterhub --version (if used with JupyterHub)

= 2.x

Expected behavior

Minimal rights for grader-course-entities with nbgrader still capabale to run

Actual behavior

grader-course-entities gets some form of admin access

[lahwaacz]

Note that JupyterHub 4 does not have a UI for creating tokens with limited scopes. This was added in jupyterhub/jupyterhub#4578

[jeflem]

scopes ['read:users:groups', 'list:services', 'list:users', 'groups', 'admin:users', 'admin:groups'] suffice for the course service, but maybe this isn't the minimal set of scopes

[lahwaacz]

@jeflem It works for me with just ['read:users:groups', 'groups'], or I'm missing some functionality which needs more scopes

[jeflem]

@lahwaacz Depends on your usecase and your overall JHub configuration. If you enrole a student via formgrader, the formgrader wants to add this student to a group, for instance, which is not possible with your set of scopes. And if you enrole a student not yet known to the hub, then formgrader needs to add this user to JHub's user list. As far as I remember, all scopes listed in my comment above stem from fixing some formgrader errors. In this sense they are required by formgrader (but of course might by slightly to wide).

[lahwaacz]

If you enrole a student via formgrader, the formgrader wants to add this student to a group

This works with the groups scope which is read and write. The group needs to already exist as documented. There is actually some code which creates the group, but the documentation says it must be created beforehand.

And if you enrole a student not yet known to the hub, then formgrader needs to add this user to JHub's user list.

You need admin:users for this, but I would argue nbgrader should not create users in JupyterHub. I also don't see any code that would do this 🤔

Overall, I think that nbgrader should not require any admin scope. Remember that people using nbgrader essentially get the same permission scopes and they can run any code on JupyterHub, not just nbgrader.

[jeflem]

Remember that people using nbgrader essentially get the same permission scopes and they can run any code on JupyterHub, not just nbgrader.

That's true and maybe a problem in my setup. Will check this soon...