Canvas#

Helper routines for authorizing against Canvas instances.

Note

Provisioned dev-keys require the includes scope if building from Canvas sections is required. Without this scope, the get_course_groups() function will succeed but groups derived from sections will not be returned.

Basic configuration to pull groups from Canvas courses, user groups, and sections, 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, canvas_course_key="course_code", canvas_section_key="id"),
    # Populate groups from Canvas groups, using the scheme defined in get_user_group
    *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]
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 = 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 = 'name', canvas_section_key: str = 'name') → 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: URL, 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: URL, 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, canvas_section_key: str) → list#

Create group identifiers of the form

course::<course>

and

course::<course>::role::<enrollment-role>

and

course::<course>::section::<section>

and

course::<course>::section::<section>::role::<enrollment-role>

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

  • canvas_section_key – key within Section response that defines the section 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::<group>

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 = 'name', canvas_section_key: str = 'name') → 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)#