Canvas

Helper routines for authorizing against Canvas instances.

Note

Provisioned dev-key requires support for includes to built section groups.

Basic configuration to pull groups from Canvas courses, and Canvas user groups is as follows:

from jupyterhub_oauthenticator_authz_helpers.canvas import get_user_groups, get_course_groups, build_auth_urls

canvas_url = "<CANVAS-URL>"

async def auth_state_hook(authenticator, auth_state):
  if auth_state is None:
    return None

  access_token = auth_state["access_token"]
  auth_state[authenticator.auth_state_groups_key] = [
    # Populate groups from Canvas courses, using the scheme defined in get_course_groups
    *await get_course_groups(canvas_url, access_token, "course_code"),
    # Populate groups from Canvas groups, using the scheme defined in get_user_groups
    *await get_user_groups(canvas_url, access_token),
  ]
  return auth_state

cfg = c.GenericOAuthenticator
# Inject auth state
cfg.modify_auth_state_hook = auth_state_hook
# Define a custom key for auth groups
cfg.auth_state_groups_key = "custom-groups"
# Configure auth and other URLs
cfg.authorize_url, cfg.token_url, cfg.userdata_url = build_auth_urls(canvas_url)
# Scopes that this token will need, pulled from functions that we've used above
cfg.scope = [*build_auth_urls.scopes, *get_user_groups.scopes, *get_course_groups.scopes]
class jupyterhub_oauthenticator_authz_helpers.canvas.AuthURLs(authorize, token, userdata)
authorize: str

Alias for field number 0

token: str

Alias for field number 1

userdata: str

Alias for field number 2

jupyterhub_oauthenticator_authz_helpers.canvas.build_auth_urls(canvas_url: str) → AuthURLs

Return a named tuple of the (auth, token, userdata) URLs for the given Canvas instance.

Examples

>>> cfg = c.GenericOAuthenticator
>>> cfg.authorize_url, cfg.token_url, cfg.userdata_url = build_auth_urls(canvas_url)
Parameters:

canvas_url – URL to Canvas instance

jupyterhub_oauthenticator_authz_helpers.canvas.build_jupyterhub_group(*terms) → str

Return a group name assembled from provided terms.

jupyterhub_oauthenticator_authz_helpers.canvas.escape_group_segment(segment: str) → str

Escape a group segment to protect against separators used in the group names

Parameters:

segment – segment to escape

async jupyterhub_oauthenticator_authz_helpers.canvas.fetch_canvas_resource(token: str, url: str, includes: list[str] = None) → list

Get paginated items from Canvas.

https://developerdocs.instructure.com/services/canvas/basics/file.pagination

async jupyterhub_oauthenticator_authz_helpers.canvas.get_course_groups(canvas_url: str, token: str, canvas_course_key: str) → list

Return a list of

course::<course-id>

and

course::<course-id>::enrollment_type::<enrollment-type>

group names generated from the courses and course enrollments that the user authenticated by the given token has access to.

Parameters:

  • canvas_url – URL to Canvas instance

  • token – authentication token granted by OAuth

  • canvas_course_key – key in Course response that provides the course ID

async jupyterhub_oauthenticator_authz_helpers.canvas.get_courses(canvas_url: str, token: str) → list

Get list of active courses for the current user.

Parameters:

  • canvas_url – URL to Canvas instance

  • token – Bearer token for authorization

See https://canvas.instructure.com/doc/api/courses.html#method.courses.index.

async jupyterhub_oauthenticator_authz_helpers.canvas.get_self_groups(canvas_url: str, token: str) → list

Get list of active groups for the current user.

Parameters:

  • canvas_url – URL to Canvas instance

  • token – Bearer token for authorization

See https://canvas.instructure.com/doc/api/groups.html#method.groups.index.

async jupyterhub_oauthenticator_authz_helpers.canvas.get_user_groups(canvas_url: str, token: str) → list

Return a list of

<context-type>::<context-id>::group::<name>

group names generated from the groups associated with the user authenticated by the given token.

Access the .scopes attribute of this function to obtain the token scopes necessary to fulfil this request.

Parameters:

  • canvas_url – URL to Canvas instance

  • token – authentication token granted by OAuth

jupyterhub_oauthenticator_authz_helpers.canvas.groups_from_canvas_courses(canvas_courses: Iterable, canvas_course_key: str) → list

Create group identifiers of the form

course::<course-id>

and

course::<course-id>::enrollment_type::<enrollment-type>

for each canvas group the user is a member of.

Parameters:

  • canvas_groups – list of Canvas Course resources

  • canvas_course_key – key within Course response that defines the course ID

jupyterhub_oauthenticator_authz_helpers.canvas.groups_from_canvas_groups(canvas_groups: Iterable) → list

Create group identifiers of the form

<context-type>::<context-id>::group::<name>

for each canvas group the user is a member of.

See https://developerdocs.instructure.com/services/canvas/resources/groups.

Parameters:

canvas_groups – list of Canvas Group resources

async jupyterhub_oauthenticator_authz_helpers.canvas.get_user_groups(canvas_url: str, token: str) → list

Return a list of

<context-type>::<context-id>::group::<name>

group names generated from the groups associated with the user authenticated by the given token.

Access the .scopes attribute of this function to obtain the token scopes necessary to fulfil this request.

Parameters:

  • canvas_url – URL to Canvas instance

  • token – authentication token granted by OAuth

async jupyterhub_oauthenticator_authz_helpers.canvas.get_course_groups(canvas_url: str, token: str, canvas_course_key: str) → list

Return a list of

course::<course-id>

and

course::<course-id>::enrollment_type::<enrollment-type>

group names generated from the courses and course enrollments that the user authenticated by the given token has access to.

Parameters:

  • canvas_url – URL to Canvas instance

  • token – authentication token granted by OAuth

  • canvas_course_key – key in Course response that provides the course ID

jupyterhub_oauthenticator_authz_helpers.canvas.build_auth_urls(canvas_url: str) → AuthURLs

Return a named tuple of the (auth, token, userdata) URLs for the given Canvas instance.

Examples

>>> cfg = c.GenericOAuthenticator
>>> cfg.authorize_url, cfg.token_url, cfg.userdata_url = build_auth_urls(canvas_url)
Parameters:

canvas_url – URL to Canvas instance

class jupyterhub_oauthenticator_authz_helpers.canvas.AuthURLs(authorize, token, userdata)