Skip to content

Commit

Permalink
Remove LTI13 from docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@martinclaus
martinclaus committed Feb 22, 2023
1 parent 7517caa commit 735cbc3
Show file tree
Hide file tree
Showing 3 changed files with 0 additions and 186 deletions.
118 changes: 0 additions & 118 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -264,121 +264,3 @@ The Moodle setup is very similar to both the Open edX and Canvas setups describe
```

1. [401 Unauthorized] - [Canvas] Make sure you added your JupyterHub link by first specifying the tool via the 'Find' button (Step 4.2). Otherwise your link will not be sending the appropriate key and secret and your launch request will be recognized as unauthorized.

### LTI 1.3

#### Common Configuration Settings

Like LTI 1.1, LTI 1.3 is an open standard. Many Learning Management System (LMS) vendors support the LTI 1.3 standard and as such vendors are able to integrate with various LMS's as External Tools.

Start by following the steps below to configure your JupyterHub setup with the basic settings. Then, navigate to your LMS vendor's section to complete the installation and configuration steps.

> **Note**: if your LMS is not listed feel free to send us a PR with instructions for this new LMS.
The table below describes the configuration options available with the LTI v1.1 authenticator:

| LTI Authenticator Configuration Setting | Required | Description | Default |
| --------------------------------------- | -------- | ------------------------------------------------------------------------ | ---------------------------------- |
| config_description | No | The LTI 1.1 external tool description | `JupyterHub LTI 1.1 external tool` |
| config_icon | No | The http/s URL with the LTI 1.1 icon | `nil` |
| config_title | No | The LTI 1.1 external tool Title | `JupyterHub` |
| consumers | Yes | The key/value pair that represents the client key and shared secret | `{}` |
| username_key | No | The LTI 1.1 launch parameter that contains the JupyterHub username value | `canvas_custom_user_id` |

#### The Username Key Setting (LTI11Authenticator.username_key)

Regardless of the LMS vendor you are using (Canvas, Moodle, Open edX, etc), the user's name will default to use the `custom_canvas_user_id`. (This is due to legacy behavior and will default to a more generic LTI 1.1 parameter in a future release). Change the `username_key` setting if you would like to use another value from the LTI 1.1 launch request.

The example below illustrates how to fetch the user's email to set the JupyterHub username by specifying the `lis_person_contact_email_primary` LTI 1.1 launch request parameter:

```python
# Set the user's email as their user id
c.LTIAuthenticator.username_key = 'lis_person_contact_email_primary'
```

A [partial list of keys in an LTI request](https://www.edu-apps.org/code.html#params) is available as a reference if you would like to use another value to set the JupyterHub username. As a general rule of thumb, Personally Identifiable Information (PII) values are represented with the `lis_person_*` arguments in the launch request. Your LMS provider might also implement custom keys you can use, such as with the use of [custom parameter substitution](https://www.imsglobal.org/specs/ltiv1p1p1/implementation-guide).

#### LTI 1.3 Configuration JSON Settings

The LTI 1.3 configuration XML settings are available at `/lti11/config` endpoint. Some LMS vendors accept XML and/or URLs that render the configuration XML to simplify the LTI 1.1 External Tool installation process.

You may customize these settings with the `config_*` configuration options described in the [common configuration settings](#common-configuration-settings) section.

#### Custom Configuration with JupyterHub's Helm Chart

If you are running **JupyterHub within a Kubernetes Cluster**, deployed using helm, you need to supply the LTI 1.3 (OIDC/OAuth2) endpoints. The example below also demonstrates how customize the `lti13.username_key` to set the user's give name:

```yaml
# Custom config for JupyterHub's helm chart
hub:
config:
# Additional documentation related to authentication and authorization available at
# https://zero-to-jupyterhub.readthedocs.io/en/latest/administrator/authentication.html
JupyterHub:
authenticator_class: ltiauthenticator.lti13.auth.LTI13Authenticator
LTI13Authenticator:
# Use an LTI 1.3 claim to set the username. You can use and LTI 1.3 claim that
# identifies the user, such as email, last_name, etc.
username_key: "given_name"
# The LTI 1.3 authorization url
authorize_url: "https://canvas.instructure.com/api/lti/authorize_redirect"
# The external tool's client id as represented within the platform (LMS)
# Note: the client id is not required by some LMS's for authentication.
client_id: "125900000000000329"
# The LTI 1.3 endpoint url, also known as the OAuth2 callback url
endpoint: "http://localhost:8000/hub/oauth_callback"
# The LTI 1.3 token url used to validate JWT signatures
token_url: "https://canvas.instructure.com/login/oauth2/token"
```

#### Configuration of LTI 1.3 with the Learning Management System

#### Canvas

The setup for the Canvas LMS.

##### Configure the JupyterHub as as a Developer Key

1. [To install the JupyterHub as an External Tool](https://community.canvaslms.com/t5/Canvas-Releases-Board/Canvas-Release-LTI-1-3-and-LTI-Advantage-2019-06-22/td-p/246652) admin users need to create a `Developer Key`. (More detailed instructions and screen shots on how to access this section are provided in the link above).

1. Once the Developer Key configuration for is open then select the `Enter URL` method within the `Configure` -> `Method` dropdown. This allows admin users to add the JupyterHub configuration by referring to a JupyterHub endpoint that renders the LTI 1.3 Developer Key configuration in JSON. By default the configuration URL is structured with the `https://<my-hub.domain.com>/hub/lti13/config` format.

1. Add the `Redirect URIs`. By default, the redirect URI is equivalent to the callback URL. As such the default URL for the Redirect URIs field should be `https://<my-hub.domain.com>/hub/oauth_callback`.

1. Add a `Key Name` to identify the `Developer Key`.

1. (Optional) Enter owner's email and developer key notes.

1. Save the `Developer Key` settings by clicking on the `Save` button.

##### Enable the Developer Key and copy Client ID

1. You should now see the new `Developer Key` in the `Admin` -> `Developer Keys` -> `Accounts` tab. By default the Developer Key is disabled. Enable the JupyterHub installation by clicking on the On/Off toggler in the `State` column to `ON`.

1. Copy the value that represents the `Client ID` in the `Datails` column. This value should look something like `125900000000000318`.

##### Install the JupyterHub as an External Tool in your Canvas Course

1. Navigate to the course where you would like to enable the JupyterHub.

1. Click on the course's `Settings` link.

1. Click on the `Apps` tab and then on `View App Configurations`.

1. Click on the `+App` button to add a new application. Select `By Client ID` from the `Configuration Type` dropdown and paste the `Client ID` value that you copied from the `Developer Keys` -> `<Your Developer Key Name>` -> `Details` column.

1. Save the application.

Once the application is saved you will see the option to launch the JupyterHub from the Course navigation menu. You will also have the option to add `Assignments` as an `External Tool`.

**Privacy Settings**:

Like the Privacy Settings for LTI 1.1, the LTI 1.3 External Tool application in [Canvas may be configured with privacy enabled](https://community.canvaslms.com/t5/Canvas-Developers-Group/LTI-1-3-Configuration-Claims-Course-Placement-Privacy/td-p/229252). The user ID in these cases will fetch the value from the LTI 1.3 subject (`sub` claim) which is a unique and opaque identifier for the student.

##### Create a new assignment as an External Tool

To configure an assignment with LTI 1.3 as an External Tool [follow the instructions from the LTI 1.1 -> Create a new assignment section](#create-a-new-assignment-as-an-external-tool).

#### Common Gotchas

Refer to the [common gotchas](#common-gotchas) section in the LTI 1.1 section.
22 changes: 0 additions & 22 deletions examples/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,28 +66,6 @@ jupyterhub --config /path/to/jupyterhub_config_lti11.py

If the actual username value is different from the expected username value, then view the JupyterHub logs in `debug` (the provided examples have `c.Application.log_level = "DEBUG"`) mode to confirm that the original launch request keys/values are correct.

### LTI 1.3

#### Validate Platform Settings

Ensure the `authorization_url`, `client_id`, `token_url`, `endpoint`, and `callback_url` have the correct values. The provided example has standard settings for the Canvas LMS.

#### Test the `username_key` settings with LTI 1.3 launches

This example demonstrates how users can change the `username_key` to fetch values from the LTI 1.3 login initiation flows that can be used to set the username.

1. Confirm the `username_key` value in the provided `jupyterhub_config_lti13.py` example:

Edit the provided `jupyterhub_config_lti13.py` to change the `username_key` to another value to represent the user's username. You can basically use any LTI 1.3 claims that represent Personably Identifiable Information (PII).

You could also use a parameter substitution to extract PII values from your LMS. To obtain a full list of possible parameter substitution settings refer to the IMS Global LTI 1.3 [implementation guide](https://www.imsglobal.org/spec/lti/v1p3/) -> Apendix B: Custom parameter substitution.

1. Start the JupyterHub with the example configuration for LTI 1.3:

```bash
jupyterhub --config /path/to/jupyterhub_config_lti13.py
```

### Trouble Shooting

#### The username_key does not fetch the correct value from the launch requests
Expand Down
46 changes: 0 additions & 46 deletions examples/jupyterhub_config_lti13.py
View file

This file was deleted.

0 comments on commit 735cbc3

Please sign in to comment.