Skip to content

Configuring LTI 1.3

Jump to bottom
Code Hugger (Matthew Jones) edited this page Nov 8, 2024 · 34 revisions

ngrok/proxy Setup

This app previously had two ngrok URL's, but now only has one. You can use it with or without an Auth Token. You can also use the similar service like Loophole to create this proxy.

Instructions for ngrok with auth token (optional now):

  • Go to https://ngrok.com/ and Click Login
  • You can just login with your Github account for easier connection
  • After this is done click your authtoken. You'll need this in a few seconds.
  • In the code there is an example file called ngrok.yml.sample. Copy this file to ngrok.yml and fill in your auth token on the first line
  • Optional: You may need to install ngrok. There are a few ways of doing this but you can also download the binary
  • Start ngrok with the command ngrok start --config=ngrok.yml backend. It should start with 1 URLs on port 5000. If you leave this process running it should persist even though sleep with the same URL. If you have a paid ngrok account you should get static URLs. You will need both front and backend URL's for future steps.

Loophole has a similar setup without the configuration. Just follow the documentation and then run it with loophole http 5000

Canvas Setup

Instructor Productivity Tools local setup

  • Before you can run and build Instructor Productivity Tools with LTI changes you'll need to copy .env.sample to .env and fill in the required fields. For easier dev it's recommended to set LTI_CONFIG_DISABLE_DEPLOYMENT_ID_VALIDATION=True and you have to set CSRF_COOKIE_SECURE=True

**In the following steps replace https://f1079d9f08c8.ngrok.io with whatever your proxy is. **

Create Canvas OAuth Token

  • Go to your Canvas Admin for your instance -> Developer Keys and select +API Key
  • Give the key a name and email
  • In the Redirect URL enter https://f1079d9f08c8.ngrok.io/oauth/oauth-callback with no trailing slash
  • Enable "Enforce Scopes", and check the checkboxes for the following three scopes:
    • under Tabs: url:GET|/api/v1/courses/:course_id/tabs
    • under Tabs: url:PUT|/api/v1/courses/:course_id/tabs/:tab_id
    • under Courses: url:GET|/api/v1/courses/:id,
  • Now in the .env above fill in the values
  • CANVAS_OAUTH_CLIENT_ID=<ID of the key from canvas like 12300000000023>
  • CANVAS_OAUTH_CLIENT_SECRET=<Value when you click Show Key>
  • CANVAS_OAUTH_CANVAS_DOMAIN=<Domain of your canvas instance like canvas.umich.edu>

Create Canvas LTI Key (You need to have the app accessible at this point to get the LTI config)

  • Go to your Canvas Admin for your instance -> Developer Keys and select +LTI key
  • Select "Enter URL" from the Dropdown list. For the JSON URL field, enter https://f1079d9f08c8.ngrok.io/lti/config/
  • In the "Key Name" field, fill in an App Name like "Instructor Productivity Tools "
  • In the "Owner Email" field, enter your email
  • In the "Redirect URIs", use the URL of the ngrok with /lti/launch/ like https://f1079d9f08c8.ngrok.io/lti/launch/ with a trailing slash
  • Click "Save"
  • You can go back in and edit the name if you'd like at any time. You can also change the URLs
  • You are now in the list view of "Developer Keys". Note the newly added developer key has ID like 85530000000000126, you'll need this a few places later
  • Click the button to turn this on

Enable this LTI tool in a site

  • Go to your Canvas Site or Account, choose Settings->Apps->View App Configuration-> +Apps
  • Select "By Client ID" and use the ID above then click Submit and Install.
  • Refresh the page, then go into Navigation and enable the tool that was added.

Configure on LTI on server to work with Canvas

Initial setup

Initially there's no way to login so a management utility was created to add the first LTI key. Run the command below, substituting the LTI client ID above here. Locally you'd run through Docker, or be in a shell on the container.

docker exec -it canvas_app_explorer ./manage.py manage_pylti --tool_key="LTI Key" --title="Canvas Test" --client_id=85530000000000126

You can additionally specify

  • --platform (Defaults to canvas.instructure.com)
  • --deployment_ids (Needs to be set unless the .env value LTI_CONFIG_DISABLE_DEPLOYMENT_ID_VALIDATION=True is set)
    • You can specify multiple like --deployment_ids "303:43090cc0c11063fdf5b270094da05ed6e23ea6ad" "100:43090cc0c11063fdf5b270094da05ed6e23ea6ad" These are obtained from the External Apps Page on Canvas

After this is setup, you should be able to launch into the app from Canvas. You can add other LTI keys through the admin or with this command. Once you launch with a user, you should promote someone to admin with this command, filling in "UPDATE_USERNAME=" with the user email that you want to promote. This will make that first user staff so you can get into the admin UI.

UPDATE_USERNAME="[email protected]";docker exec -it canvas_app_explorer ./manage.py shell -c "from django.contrib.auth.models import User; User.objects.update_or_create(username='$UPDATE_USERNAME', defaults=dict(is_superuser=True, is_staff=True))"

Manual setup via Admin

Click LTI 1.3 tools under PYLTI 1.3 Tool Config

Fill in these fields

  • Title:
  • Issuer: https://canvas.instructure.com (This may not match your instance host name)
  • Client ID: This was the numeric again from the above configuration

I believe these settings below for URL should match the hostname that you're using, rather than be canvas.instructure.com.

  • Auth Login URL: https://canvas.instructure.com/api/lti/authorize_redirect
  • Auth Token URL: https://canvas.instructure.com/login/oauth2/token
  • Auth audience: Leave Blank
  • Key set URL: https://canvas.instructure.com/api/lti/security/jwks
  • Key set: Leave Blank
  • Tool Key: Press the + button to add a config if you don't have one or select one.
  • Deployment IDs: You need to get these from the platform (go to Canvas->Admin->Settings->Apps, click on the Settings dropdown list and select Deployment Id), or have deployment ID check disabled

Troubleshooting tips

Error: {"status":"bad_request","message":"Invalid redirect_uri"}
Solution: Check that you have a trailing slash in the Redirect URI in Canvas

Error: Server Error 500
Solution: Make sure you've added the correct information in the app PyLTI config

Error: iss https://canvas.instructure.com [client_id=12340000000000126] not found in settings
Solution: Check that the Issuer and client id in the PyLTI admin table match the values that are failing. These are the first two settings. Also if you haven't done the steps in this document it would explain this message and you need to add a PyLTI client ID.

Error: OAuth error invalid_request or Forbidden: /oauth/oauth-callback
Solution: You might need to clear out the database table canvas_oauth_canvasoauth2token until #175 is fixed as it could have outdated tokens. Also check your settings.

Error: LtiException: Unable to find deployment
Solution: Either set the .env variable LTI_CONFIG_DISABLE_DEPLOYMENT_ID_VALIDATION=True or configure the correct deployment Id in [Lti 1.3 tools] in the admin interface.

Error: refresh_token request failed to get a token: Error: invalid_grant
Solution: This is due to the Canvas OAuth refresh_token is no longer valid inside canvas_oauth_canvasoauth2token table for the user. Clean/purge the user row in the canvas_oauth_canvasoauth2token and auth_user, then continue with OAuth authentication to establish new OAuth refresh_token.
docker exec -it canvas_app_explorer_mysql mysql -u cae_user --password=cae_pw
mysql> use canvas_app_explorer_local
mysql> delete from canvas_oauth_canvasoauth2token where user_id ='<user_id>'
mysql> delete from auth_user where id='<user_id>'

You can also delete this from the Django Admin in the Canvas OAuth2 Tokens table. Just delete the row for the problematic user or all users. This is referenced as an issue #208 which may be fixed.

Clone this wiki locally