Populate rdt pages (#144)

* Populate rdt pages * Update README
jupyterhub · Mar 30, 2023 · 5dce90f · 5dce90f
1 parent 1299ab8
commit 5dce90f
Show file tree

Hide file tree

Showing 15 changed files with 560 additions and 444 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -62,6 +62,7 @@ def setup(app):
 # Rediraffe redirects to ensure proper redirection
 rediraffe_redirects = {}
 
+myst_heading_anchors = 3
 
 # -- Options for linkcheck builder -------------------------------------------
 # ref: http://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder

diff --git a/docs/source/explanation/index.md b/docs/source/explanation/index.md
diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -1,53 +1,17 @@
 # LTI Authenticator for JupyterHub
 
-```{warning} Incomplete documentation
-This website is still under construction, complement its content with [github.com/jupyterhub/ltiauthenticator#readme](https://github.com/jupyterhub/ltiauthenticator#readme) until it is.
-```
-
-This website documents the use of an authenticator plugin for JupyterHub for use
-against [LTI](https://en.wikipedia.org/wiki/Learning_Tools_Interoperability)
-based authentication systems.
-
-## Getting started tutorials
-
-**Tutorials.** A hands-on introduction to using the LTI authentication plugin.
-
-```{toctree}
-:maxdepth: 2
-:caption: Getting started tutorials
-
-tutorials/index
-```
-
-## How-to guides
-
-**Step-by-step guides.** Covers key tasks and common problems.
+This website documents the use of an authenticator plugin for JupyterHub for use against [LTI](https://en.wikipedia.org/wiki/Learning_Tools_Interoperability) based authentication systems.
+The plugin supports the both the [LTI 1.1](https://www.imsglobal.org/specs/ltiv1p1/implementation-guide) and [LTI 1.3](https://www.imsglobal.org/spec/lti/v1p3).
 
-```{toctree}
-:maxdepth: 2
-:caption: How-to guides
-
-how-to/index
+```{note}
+LTI 1.1 is [deprecated](https://www.imsglobal.org/lti-security-announcement-and-deprecation-schedule) and LTI 1.3 should be the preferred choice.
 ```
 
-## Explanation
-
-**Explanation.** Clarification and discussion of key topics.
-
-```{toctree}
-:maxdepth: 2
-:caption: Explanation
-
-explanation/index
-```
-
-## Configuration reference
-
-**Technical reference.** Covers available configuration options.
+## Content
 
 ```{toctree}
 :maxdepth: 2
-:caption: Configuration reference
 
-reference/index
+lti13/index
+lti11/index
 ```
diff --git a/docs/source/lti11/getting-started.md b/docs/source/lti11/getting-started.md
@@ -0,0 +1,107 @@
+# Getting Started
+
+## General Procedure
+
+Due to the fact that LTI 1.1 is an open standard, Learning Management System (LMS) vendors that adhere to the LTI 1.1 standard utilize the same configuration settings when integrating with an external tool.
+Some of these settings are included in a configuration endpoint to facilitate the JupyterHub's as an external tool with your LMS.
+
+Start by following the steps below to configure your JupyterHub setup with the essential settings.
+See the [configuration reference](reference) for a complete list of available configuration options.
+
+After setting up the authenticator plugin navigate to the [integration section of your vendor's LMS](lms-integration) 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.
+```
+
+```{note}
+Throughout this document the terms **Client Key** and **Consumer Key** are used interchangeably to represent the LTI 1.1 `key` and **Client Secret**, **Secret Key**, and **Shared Secret** are used interchangeably to represent the LTI 1.1 `secret`.
+```
+
+## Create Consumer and Key
+
+Create a _`client key`_ and _`client secret`_ for use by the LMS to authenticate your hub. Open a terminal and enter the `openssl` commands below to create these values:
+
+```bash
+# consumer key
+openssl rand -hex 32
+```
+
+```bash
+# shared secret
+openssl rand -hex 32
+```
+
+```{caution}
+Anyone with these two strings will be able to access your hub, so keep them secure!!
+```
+
+```{note}
+These commands will simply generate strings for you, it will not store them anywhere on the computer. Therefore, you _do not_ need to run these commands within the environment where you are launching the JupyterHub server.
+```
+
+It's a good idea to exclude sensitive values from your code, including JupyterHub configuration files.
+You can do that by storing both values from above in environmental variables
+
+```bash
+export LTI_CLIENT_KEY=<YOUR CLIENT KEY PRODUCED BY OPENSSL>
+export LTI_SHARED_SECRET=<YOUR CLIENT SECRET PRODUCED BY OPENSSL>
+```
+
+and read them within the `jupyterhub_config.py` file like this
+
+```python
+import os
+c.LTI11Authenticator.consumers = {
+    os.environ["LTI_CLIENT_KEY"]: os.environ["LTI_SHARED_SECRET"]
+}
+```
+
+The same pattern applies when using containers, for example by using the `ENV` directive with a Dockerfile or a `ConfigMap` when using Kubernetes.
+
+## Set the 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 behaviour 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 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).
+To find out which keys are sent by the LMS, you may register an [LTI test tool emulator](https://saltire.lti.app/tool) and inspect the payload of the LTI Launch request.
+
+## Configuration XML Settings
+
+The LTI 1.1 configuration XML settings are available at the `/lti11/config` endpoint. Some LMS vendors, such as [Canvas](lms-integration.md#canvas) 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 [configuration reference](reference.md#lti11authenticator) 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 client key & shared secret with the `LTI11Authenticator.consumers` key. The example below also demonstrates how customize the `LTI11Authenticator.username_key` to set the user's email as the JupyterHub username and the `LTI11Authenticator.config_icon` to define a custom external tool icon when using the LTI 1.1 configuration XML endpoint:
+
+```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.lti11.auth.LTI11Authenticator # LTI 1.1
+    LTI11Authenticator:
+      consumers: { "client-key": "client-secret" }
+      username_key: "lis_person_contact_email_primary"
+      config_icon: "https://my.static.assets/img/icon.jpg"
+```
+
+```{hint}
+In the helm chart example configuration above `hub.config.LTI11Authenticator.username_key: "lis_person_contact_email_primary"` is equivalent to the standard JupyterHub configuration using `jupyterhub_config.py` with `c.LTI11Authenticator.username_key = "lis_person_contact_email_primary"`.
+```
diff --git a/docs/source/lti11/index.md b/docs/source/lti11/index.md
@@ -0,0 +1,9 @@
+# LTI 1.1
+
+```{toctree}
+:maxdepth: 2
+
+getting-started
+lms-integration
+reference
+```
diff --git a/docs/source/lti11/lms-integration.md b/docs/source/lti11/lms-integration.md
@@ -0,0 +1,157 @@
+# LMS Integration
+
+## Open edX
+
+1. You need access to [Open edX Studio](https://studio.edx.org/) to set up Open edX with LTI 1.1. You might have to contact your Open edX administrator to get access.
+
+1. [Enable LTI Components](http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/lti_component.html#enabling-lti-components-for-a-course) for your course.
+
+1. Pick a name for Open edX to call your JupyterHub server.
+   Then, along with the _`client key`_ and _`client secret`_ you [generated](getting-started.md#create-consumer-and-key), create a `LTI Passport String` in the following format: `your-hub-name:client-key:client-secret`.
+   The `your-hub-name` value can be anything, but you'll be using it throughout Open edX to refer to your JupyterHub instance, so make it something meaningful and unique.
+
+1. Then [add the Passport String](http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/lti_component.html#adding-an-lti-passport-to-the-course-configuration) to Open edX.
+   Remember to save your changes when done!
+
+1. In a Unit where you want there to be a link to the hub, [add an LTI Component](http://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/lti_component.html#adding-an-lti-component-to-a-course-unit).
+
+   You should enter the following information into the appropriate component settings:
+
+   - **LTI ID**: The value you entered for `your-hub-name` above.
+
+   - **LTI URL**: Should be set to `your-hub-url/hub/lti/launch`. So if your hub is accessible at `http://datahub.berkeley.edu`, **LTI URL** should be `http://datahub.berkeley.edu/hub/lti/launch`
+
+   - **LTI Launch Target**: Should be set to **New Window**.
+
+   - **Custom parameters**: The only currently supported custom parameter are `next` and `custom_next`, which can contain the relative URL that the user should be redirected to after authentication. For example, if you are using [`nbgitpuller`](https://github.com/data-8/nbgitpuller) and want the user to see [this file](https://github.com/binder-examples/requirements/blob/master/index.ipynb) after logging in, you could set the field **Custom parameters** to the following string:
+
+   ```js
+   [
+     "next=/hub/user-redirect/git-pull?repo=https://github.com/binder-examples/requirements&subPath=index.ipynb",
+   ];
+   ```
+
+   > **Note**: If you have a `base_url` set in your JupyterHub configuration, that should be prefixed to your next parameter. ([Further explanation](#common-gotchas))
+
+1. Done! You can click the Link to see what the user workflow would look like. You can repeat step 6 in all the units that should have a link to the Hub for the user.
+
+## Canvas
+
+The setup for Canvas is very similar to the process for Open edX.
+
+### Install JupyterHub as an External Tool
+
+[Add a new external app configuration in Canvas](https://community.canvaslms.com/docs/DOC-13135-415257103).
+You can name it anything, but you'll be using it throughout the Canvas course to refer to your JupyterHub instance, so make it something meaningful and unique.
+Note that the right to create applications might be limited by your institution.
+The basic information required to create an application in Canvas' `Manual entry` mode is:
+
+- **Name**: the external tool name, such as `JupyterHub`
+- **Consumer Key**: the [created consumer key](getting-started.md#create-consumer-and-key)
+- **Secret Key**: the [shared secret](getting-started.md#create-consumer-and-key)
+- **Launch URL**: `https://www.example.com/hub/lti/launch`
+- **Domain**: optional
+- **Privacy**: anonymous, email only, name only, or public
+- **Custom Fields**: optional
+
+Canvas also provides the option to add the external tool by selecting either the `Paste XML` or `By URL` items from the `Course --> Settings --> Apps --> +App` section.
+In these cases, use the `/lti11/config` endpoint from your JupyterHub instance to copy/paste the configuration XML or add the URL when defining your external tool configuration with the `Paste XML` or `By URL` options, respectively.
+
+The application can be created at the account level or the course level. If the application is created at the account level, it means that the application is available to all courses under the same account.
+
+**Privacy Setting**:
+
+- If you run the course in public mode, ltiauthenticator will parse the student's canvas ID as the JupyterHub username.
+- If you run the course in anonymous mode, ltiauthenticator will fall back to the LTI user ID, an anonymized version.
+  - Currently, the only method for de-anonymizing the LTI user ID in Canvas is with [the "masquerade" permission](https://canvas.instructure.com/doc/api/file.masquerading.html), which grants the user full access to act as any user account.
+  - Unless you are able to obtain masquerade permissions, it is recommended to run the course in public mode.
+
+### Create a new assignment.
+
+1. Navigate to `Assignments -> Add Assignment`
+1. For `Submission Type`, select `External Tool`
+1. Click on the `Find` button and search for the external tool by name that you added in the step above. Selecting the external tool will prepopulate the URL field with the correct launch URL.
+
+```{important}
+Using the `Find` button to search for your external tool is necessary to ensure the LTI consumer key and shared secret are referenced correctly.
+Else, your launch request will be recognized as unauthorized and responded to with `401 Unauthorized`.
+```
+
+4. (Recommended) Check the `Launch in a new tab` checkbox.
+1. Append any custom parameters you wish (see next step)
+
+   > **Note**: If you are creating assignments via the Canvas API, you need to use [these undocumented external tool fields](https://github.com/instructure/canvas-lms/issues/1315) when creating the assignment.
+
+1. **Custom Parameters**: With Canvas users have the option to set custom fields with the Launch Request URL. Unlike Open edX, there is no method to include these custom parameters in the LTI launch request's form data. However, you can append custom parameters to the launch URL as query strings using proper [character encoding](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) to preserve the query strings as they are passed through JupyterHub. You can perform this encoding manually, [programmatically](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlencode), or via an online tool.
+
+   Before:
+
+   ```
+   https://example.com/hub/lti/launch?custom_next=/hub/user-redirect/git-pull?repo=https://github.com/binder-examples/requirements&subPath=index.ipynb
+   ```
+
+   After:
+
+   ```
+   https://example.com/hub/lti/launch?custom_next=/hub/user-redirect/git-pull%3Frepo%3Dhttps%3A%2F%2Fgithub.com%2Fbinder-examples%2Frequirements%26subPath%3Dindex.ipynb
+   ```
+
+   Note that the _entire_ query string should not need to be escaped, just the portion that will be invoked after JupyterHub processes the `user-redirect` command.
+
+1. Done! You can click the link to see what the user workflow would look like.
+   You can repeat step 7 in all the units that should have a link to the Hub for the user.
+
+## Moodle
+
+### General Requirements
+
+The Moodle setup is very similar to both the Open edX and Canvas setups described above. In addition to completing the steps from the [Getting Started sections](getting-started.md) ensure that:
+
+1. You have access to a user with the Moodle Administrator role, or have another Moodle Role that gives you Permissions to manage `Activity Modules`.
+
+2. You need to have enabled the [External Tool](https://docs.moodle.org/37/en/External_tool) Activity Module in your Moodle environment.
+
+3. If your Moodle environment is using https, you should also use https for your JupyterHub.
+
+### Configuration Steps
+
+1. Navigate to the course where you would like to add JupyterHub as an external tool
+1. Turn on editing and add an instance of the `External Tool Activity Module` (https://docs.moodle.org/37/en/External_tool_settings)
+
+   1. Activity Name: This will be the name that appears in the course for students to click on to initiate the connection to your hub.
+   1. Click 'Show more...' to add additional configuration settings:
+
+   - **Tool name**: the external tool name, such as `JupyterHub`.
+   - **Tool URL**: Should be set to `your-hub-url/hub/lti/launch`. So if your hub is accessible at `https://datahub.berkeley.edu`, _Tool URL_ should be
+     `https://datahub.berkeley.edu/hub/lti/launch`.
+   - **Consumer Key**: _client key_
+   - **Shared secret**: _client secret_
+   - **Custom parameters**: this is an optional field that you could use to fetch additional values from the launch request.
+   - **Default launch container**: This setting will define how the hub is
+     presented to the end user, whether it's embedded within a Moodle, with or
+     without blocks, replaces the current window, or is displayed in a new
+     window.
+
+1. Click `Save and return to course` or `Save and display`, you will either be returned to the course page or create an LTI 1.1 launch request to log into the JupyterHub instance.
+
+## Common Gotchas
+
+1.  If you have a `base_url` set in your JupyterHub configuration, this needs to be reflected in your launch URL and custom parameters. For example, if your `jupyterhub_config.py` file contains:
+
+```python
+c.JupyterHub.base_url = '/jupyter'
+```
+
+then your Launch URL would be:
+
+```
+https://www.example.com/jupyter/hub/lti/launch
+```
+
+A custom next parameter might look like:
+
+```js
+[
+  "next=/jupyter/hub/user-redirect/git-pull?repo=https://github.com/binder-examples/requirements&subPath=index.ipynb",
+];
+```
diff --git a/docs/source/lti11/reference.md b/docs/source/lti11/reference.md
@@ -0,0 +1,31 @@
+# Configuration reference
+
+This section describes the available configuration options for the various classes of the plugin.
+Configuration is defined via `traitlets` of the classes and values are specified either in the [`jupyterhub_config.py`](https://jupyterhub.readthedocs.io/en/stable/getting-started/config-basics.html#configuration-basics) or by some other means depending on the JupyterHub deployment (e.g. the [JupyterHub helm chart](https://z2jh.jupyter.org/en/stable/administrator/authentication.html)).
+For example, to set the `config_title` property of the `LTI11Authenticator` class, your `jupyterhub_config.py` file would contain the lines
+
+```python
+c.JupyterHub.authenticator_class = "ltiauthenticator.lti11.auth.LTI11Authenticator"
+c.LTI11Authenticator.config_title = "Some Title"
+```
+
+or your helm chart `config.yml` would contain
+
+```yaml
+hub:
+  config:
+    JupyterHub:
+      authenticator_class: ltiauthenticator.lti11.auth.LTI13Authenticator
+    LTI11Authenticator:
+      config_title: "Some Title"
+```
+
+## LTI11Authenticator
+
+| Property           | 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`            |