Use Cases#
To determine which scopes a role should have, one can follow these steps:
Determine what actions the role holder should have/have not access to
Match the actions against the JupyterHub’s APIs
Check which scopes are required to access the APIs
Combine scopes and subscopes if applicable
Customize the scopes with filters if needed
Define the role with required scopes and assign to users/services/groups/tokens
Below, different use cases are presented on how to use the RBAC framework
Service to cull idle servers#
Finding and shutting down idle servers can save a lot of computational resources. We can make use of jupyterhub-idle-culler to manage this for us. Below follows a short tutorial on how to add a cull-idle service in the RBAC system.
Install the cull-idle server script with
pip install jupyterhub-idle-culler
.Define a new service
idle-culler
and a new role for this service:# in jupyterhub_config.py c.JupyterHub.services = [ { "name": "idle-culler", "command": [ sys.executable, "-m", "jupyterhub_idle_culler", "--timeout=3600" ], } ] c.JupyterHub.load_roles = [ { "name": "idle-culler", "description": "Culls idle servers", "scopes": ["read:users:name", "read:users:activity", "servers"], "services": ["idle-culler"], } ]
Important
Note that in the RBAC system the
admin
field in theidle-culler
service definition is omitted. Instead, theidle-culler
role provides the service with only the permissions it needs.If the optional actions of deleting the idle servers and/or removing inactive users are desired, change the following scopes in the
idle-culler
role definition:servers
toadmin:servers
for deleting serversread:users:name
,read:users:activity
toadmin:users
for deleting users.
Restart JupyterHub to complete the process.
API launcher#
A service capable of creating/removing users and launching multiple servers should have access to:
POST and DELETE /users
POST and DELETE /users/:name/server or /users/:name/servers/:server_name
Creating/deleting servers
The scopes required to access the API enpoints:
admin:users
servers
admin:servers
From the above, the role definition is:
# in jupyterhub_config.py
c.JupyterHub.load_roles = [
{
"name": "api-launcher",
"description": "Manages servers",
"scopes": ["admin:users", "admin:servers"],
"services": [<service_name>]
}
]
If needed, the scopes can be modified to limit the permissions to e.g. a particular group with !group=groupname
filter.
Group admin roles#
Roles can be used to specify different group member privileges.
For example, a group of students class-A
may have a role allowing all group members to access information about their group. Teacher johan
, who is a student of class-A
but a teacher of another group of students class-B
, can have additional role permitting him to access information about class-B
students as well as start/stop their servers.
The roles can then be defined as follows:
# in jupyterhub_config.py
c.JupyterHub.load_groups = {
'class-A': ['johan', 'student1', 'student2'],
'class-B': ['student3', 'student4']
}
c.JupyterHub.load_roles = [
{
'name': 'class-A-student',
'description': 'Grants access to information about the group',
'scopes': ['read:groups!group=class-A'],
'groups': ['class-A']
},
{
'name': 'class-B-student',
'description': 'Grants access to information about the group',
'scopes': ['read:groups!group=class-B'],
'groups': ['class-B']
},
{
'name': 'teacher',
'description': 'Allows for accessing information about teacher group members and starting/stopping their servers',
'scopes': [ 'read:users!group=class-B', 'servers!group=class-B'],
'users': ['johan']
}
]
In the above example, johan
has privileges inherited from class-A-student
role and the teacher
role on top of those.
Note
The scope filters (!group=
) limit the privileges only to the particular groups. johan
can access the servers and information of class-B
group members only.