How do I install Sakai Plus in my enterprise LMS?

This page contains documentation on how to install Sakai Plus into a number of LMS systems. The exact steps may vary depending on the system and version you are using. Please consult your enterprise LMS documentation for more information on setting up and configuring LTI tools.

To access this tool, select Plus Admin from the left menu in the Administration Workspace.

Select the Add Tenant button to create a new tenant.

A Sakai Plus server can support many "tenants." Each Learning System that you are plugging Sakai Plus into should have its own tenant. In Sakai Plus, all data within a tenant is isolated (each tenant is a "silo"). This way you can have a multi-tenant Sakai Plus server to serve many different learning systems. However it is also a quite typical use case to have one Enterprise LMS - say Canvas and one Sakai Plus server for the same school and to have a single Tenant entry in Sakai Plus for the Canvas system.

You can create a "draft" tenant with a Title and Issuer and optionally a Registration Lock. Once you have created a draft tenant, you can view the tenant to either start the LTI Dynamic Registration process or provide tool configuration to your calling learning system.

You can view the documentation for LTI Dynamic Registration at:

Enter the information for your new tenant into the fields provided.

  1. Title: Give your tenant an easily recognizable title, such as the name of your enterprise LMS. If you have more than one tenant in your system, you may also want to specify the version or group associated with a given tenant. This field is required.
  2. Issuer: Issuer is different for each LMS, but it is usually a URL like "https://plus.sakailms.org" - with no trailing slash. Sometimes this will be the domain where the LMS is hosted. For some cloud-hosted providers, they use one issuer across all customers. This field is required.
  3. Allowed Tools: This field is a colon-separated list of Sakai tool IDs, such as "sakai.resources:sakai.conversations" etc. There is a special "sakai.site" tool id which controls the availability of the "entire site" launch. A simple default for this is "sakai.site" or "sakai.site:sakai.resources: ...". This field is required.
  4. Trust Email: If the LMS that is calling Sakai Plus for this tenant sends email, you should trust the email address to avoid creating multiple user records for each user in each site. If you mark this tenant as "trust email," and the calling system provides the email address of the user, multiple launches from multiple contexts will all be linked to the same user within this Tenant in Sakai Plus.
  5. Time Zone: This is the timezone (for example, US/Eastern) for the controlling LMS. Sakai Plus will shift due dates into this timezone before creating or updating line items.
  6. Registration Lock: You set this field to "unlock" LTI Dynamic Registration for this tenant. It should only be set while performing dynamic registration and should be cleared after dynamic registration is complete. If the launching system does not support dynamic registration you will set these manually.
  7. Client ID: The client ID is provided by the launching LMS as part of tool registration. If the LMS supports LTI Dynamic Registration it will automatically populate this field.
  8. Deployment ID: The Deployment ID may vary depending upon your enterprise LMS. For some systems, the deployment ID is the same for an entire system and is provided as part of Dynamic Registration. For other systems, a new Deployment ID is generated by each course. You can set the Deployment ID to * if you can accept any Deployment ID for a particular Client ID.
  9. New Window Tools: This field is a colon-separated list of Sakai tool IDs which will be forced to always open in a new window. The "sakai.site" is always launched in a new window. This is typically left blank unless it is known that a particular tool just does not work well in an iframe. Or perhaps you are setting up a single tool server and want it to always be in a new window.
  10. Site Template: This specifies an existing site in your Sakai system (for example, !plussite) which will be copied to make a new site when Sakai Plus receives an incoming site. This template site determines the default tools that are added to the new Sakai Plus site. The default is !plussite unless it is changed using the plus.new.site.template Sakai property.
    1. You may go to the !plussite and add or remove tools in that site if you wish to make a custom set of tools available.
  11. Realm Template: This specifies an existing Sakai realm (for example, !site.template.lti) which will be copied to set the roles and permissions used when creating a new site when Sakai Plus receives an incoming site. The default is !site.template.lti unless it is changed using the plus.new.site.realm Sakai property.
  12. Inbound Role Map: This field allows for overriding the default mapping from incoming LTI roles to Sakai roles. See this documentation for detail on how role mapping works and the format for role mapping entries.
    1. Sakai to LTI Role Mapping
  13. Verbose Debugging: Turning verbose debugging on upgrades many of the debugging errors in the SakaiPlus code from debug.log to debug.info so they are placed in the normal Sakai log. In general this is useful for developers or during testing but will fill the log up if left on in production.
  14. The LMS Keyset URL, LMS Authorization URL, LMS Token URL, and LMS Token Audience fields are set up as part of tool registration with the calling learning system. If the system supports LTI Dynamic Registration these values should be set automatically.
    1. Note: The LMS Token Audience is left blank for most systems except for Desire2Learn.

Select Add Tenant.

Once you have finished entering the tenant information, select the Add Tenant button at the bottom of the screen to save the new draft tenant in the system. (Remember that many of the fields may be left empty if you are using dynamic registration to auto-fill the information when you register Sakai Plus with your enterprise LMS.)

Click on the title of your new draft tenant to view the configuration information.

The draft tenant information will display.

You will use the draft tenant information displayed on this screen to register Sakai Plus in your enterprise LMS.

Go to your enterprise LMS to complete the installation.

We have documentation below on how to install Sakai Plus into a number of LMS systems. If you have additional questions or need more detail on configuring Sakai Plus as an LTI tool, please see your enterprise LMS documentation for more information.

Canvas

Canvas does not support LTI Dynamic Registration but has their own JSON-based automatic Registration process that is supported by Sakai Plus.

https://canvas.instructure.com/doc/api/file.lti_dev_key_config.html

To use this process, create a Tenant in Sakai Plus with a title and the following information:

Issuer: https://canvas.instructure.com

OIDC Auth: https://canvas.instructure.com/api/lti/authorize_redirect

OIDC KeySet: https://canvas.instructure.com/api/lti/security/jwks

OIDC Token: https://canvas.instructure.com/login/oauth2/token

Make sure to check "Trust Email" - this needs to be set in the SakaiPlus Tenant from the beginning.

This is a partially complete tenant, to get the remaining data, go into the Tenant detail page and find the Canvas URL that looks like:

https://dev1.sakaicloud.com/plus/sakai/canvas-config.json?guid=1234567

Use this URL in the Canvas Admin -> Developer Keys -> + Developer Key -> + LTI Key. Set Key Name, Title, and your email address. Then Choose "Enter URL" from the drop-down and paste the URL for your Tenant in Sakai. Make sure not to have any spaces in the URL. Then press "Save". The go back in to edit the key and make sure the key is marked as "Public" in "Additional Settings", changing and saving if necessary.

to create an integration. This integration creates a Client Id similar to the following:

Client Id: 85730000000000147

Then to install Sakai Plus into a course or set of courses, you must use the Client Id to add the tool and it then gives you a Deployment ID. For a single course, go to Settings -> View App Configurations -> + App. Then choose "By Client ID" from the drop down and enter the ClientID from the previous step and press "Submit".

Deployment Id: 327:a17deed8f179b120bdd14743e67ca7916eaea622

Come back to Sakai Plus and update the Tenant to include both values and your integration should start working.

For Canvas, sometimes it generates lots of Deployment Id values, so you can make authorization of SakaiPlus based only on Client Id by leaving the Deployment Id blank/empty in the Tenant. SakaiPlus will track Deployment Id on a per-context basis for AccessToken calls to the the LMSs.

D2L Brightspace

BrightSpace supports LTI Dynamic Registration. Create a Tenant with a title, issuer, and registration unlock code. Then go to the SakaiPlus Tenant detail page and find the LTI Dynamic Registration URL and use that in the auto-provisioning screen of BrightSpace.

The issuer for a D2L system is the base URL of the system without a trailing slash:

https://school.brightspacedemo.com

While Dynamic Registration is the easiest approach, you can create a draft Tenant in Sakai Plus, then paste all the Sakai Plus URLs into Brightspace manually, save the tool in Brightspace, then get copy the Brightspace URLs and edit your Sakai Plus Tenant. Here are what typical values look like for Brightspace:

Client ID:           04a7d304-477d-401a-b701-5a58f54772d6

Deployment ID:       7862b2ce-79a0-77da-b2dd-7c77c4bb6e39

LMS Authorization:   https://school.brightspacedemo.com/d2l/lti/authenticate

LMS KeySet:          https://school.brightspacedemo.com/d2l/.well-known/jwks

LMS Token:           https://auth.brightspace.com/core/connect/token

LMS Token Audience:  https://api.brightspace.com/auth/token

Some of the values are local to the Brightspace school's URL and others are global for all schools.

The basic outline in Brightspace is to

  • Install an LTI Advantage Tool
  • Create a Deployment for the tool
  • Create a Link for the tool (this is what most LMS's call "Placement")

Make sure to enable the security settings for Org Unit Information, User Information, Link Information. If you do not send Org Unit Information Sakai Pus will not know anything about the course it is being launched from. And sending email is important because otherwise all the SakaiPlus accounts will use the "subject" as the logical key for user accounts. SakaiPlus can function without email - but it makes it a lot harder to re-connect user accounts later.

For Dynamic Registration to work, Sakai Plus demands that the issuer in Sakai Plus match the issuer provided by the LMS during the LTI Dynamic Registration process. The registration lock is single use and must be reset in Sakai Plus to re-run the Dynamic Registration process.

Here are some helpful URLs:

https://documentation.brightspace.com/EN/integrations/ipsis/LTI%20Advantage/intro_to_LTI.htm

https://documentation.brightspace.com/EN/integrations/ipsis/LTI%20Advantage/LTI_register_external_learning_tool.htm

https://success.vitalsource.com/hc/en-gb/articles/360052454313-Brightspace-D2L-LTI-1-3-Tool-Setup

https://documentation.brightspace.com/EN/integrations/ipsis/LTI%20Advantage/deploy_external_learning_tool_for_LTI_A.htm

Blackboard

Blackboard is planning on supporting LTI Dynamic Registration, but until they do, you need to do a bit of cutting and pasting of URLs between the systems.

To use this process, create a Tenant in Administration Workspace -> Plus Admin, with a title and the following information:

Issuer: https://blackboard.com

OIDC Auth: https://developer.blackboard.com/api/v1/gateway/oidcauth

OIDC Token: https://developer.blackboard.com/api/v1/gateway/oauth2/jwttoken

Then go into the Sakai Plus Registration for the tenant and grab the "Manual Configuration" URLs so you can create an LTI 1.3 clientID in the Blackboard Developer Portal. Here are some sample Sakai Plus URLs you will need for the Blackboard Developer portal:

OIDC Login: https://dev1.sakaicloud.com/plus/sakai/oidc_login/654321

OIDC Redirect: https://dev1.sakaicloud.com/plus/sakai/oidc_launch

OIDC KeySet: https://dev1.sakaicloud.com/imsblis/lti13/keyset

Note that the OIDC Login value for Sakai Plus includes the Tenant ID for your newly created Sakai Plus Tenant so it is unique for each Sakai Plus Tenant. The Redirect and Keyset values are the same for all tenants.

Use these Sakai Plus values in the Blackboard Developer portal to create an LTI 1.3 integration. The developer portal will give you a Client Id and per-client KeySet URL similar to the following:

OIDC KeySet: https://developer.blackboard.com/api/vl/management/applications/fe3ebd13-39a4-42c4-8b83-194f08e77f8a/jwks.json

Client Id: fe3ebd13-39a4-42c4-8b83-194f08e77f8a

The value in the KeySet is the same as the Client Id. You will need to update these values in your Sakai Plus Tenant.

Once you place Sakai Plus into a Blackboard instance you will be given a Deployment Id for that integration.

Deployment Id: ea4e4459-2363-348e-bd38-048993689aa0

Once you have updated your Sakai Plus tenant with the Client ID, Keyset URL, and Deployment ID your security arrangement should be set up.

Once the Tenant has all the necessary security set up, there a number of target_link_uri values that you can use. You can send a Deep Link.

Moodle

For recent versions of Moodle you can use LTI Dynamic Registration.

In Administration Workspace -> Plus Admin, create a Tenant with a title, issuer, and registration unlock code. Then go to the Tenant detail page and find the LTI Dynamic Registration URL and use that in the auto-provisioning screen of Moodle.

The issuer for a Moodle system is the base URL of the system without a trailing slash:

https://moodle.school.edu

For testing you might use and issuer like:

http://localhost:8888/moodle

In both cases do not include a trailing slash.

For Dynamic Registration to work, Sakai Plus demands that the issuer in Sakai Plus match the issuer provided by the LMS during the LTI Dynamic Registration process. The registration lock is single use and must be reset in Sakai Plus to re-run the Dynamic Registration process.

Sakai

Installing Sakai Plus into a Sakai installation is most often used for "loop back" QA testing. It may also be used to allow access to a more recent release (for example, Sakai 23.x) with new and enhanced features within a Sakai instance that is running a prior version (for example, Sakai 22.x).

The issuer for a Sakai system is the base URL of the system without a trailing slash:

For loop-back testing you might use an issuer like:

https://trunk-mysql.nightly.sakaiproject.org

http://localhost:8080   (for a local instance of Sakai)

In both cases do not include a trailing slash.

Adding A Tenant to Sakai

Log in under a Sakai admin account, and then go to Administration Workspace > Plus Admin.

For fresh installs, Plus Admin is automatically added to Administration Workspace. If this is an upgraded server, you may need to add the Plus Admin (sakai.plus) tool to the Administration Workspace using the Sites tool.

Add a tenant, give it a title and set the issuer, set "Trust Email," set "Verbose Debugging," set Allowed Tools to "sakai.resources:sakai.site," and Registration Lock to "42."

Save the Tenant - it is "draft" because it is missing a lot of fields that will be set when LTI Dynamic Provisioning runs.

If you don't set "trust email," each plus launch will log you out of the window you launched from. However, this is only a problem when running both the main site and the plus site on the same server (i.e. loop back testing). If these are different Sakai servers and URLs, the logout at launch will not be a problem.

Once the draft tenant is saved, view the tenant and grab the Dynamic Registration URL, for example:

http://localhost:8080/plus/sakai/dynamic/8efcdee4-96c3-44bf-92fd-1d901ad593a3?unlock_token=42

Adding A Sakai Plus Placement to Sakai

Go into Administration Workspace > External Tools > LTI Advantage Auto Provision.

Give the new tool a title like "LMS End of Sakai Plus" and press "Auto-Provision."

Then press "Use LTI Advantage Auto Configuration" and paste in the Dynamic Registration URL from the Tenant, and run the process. Make sure to enable the following before saving the external tool:

  • Send email
  • Send name
  • Give access to services
  • Choose the various placements (Lessons, etc.)
  • Tool Supports LTI 1.3
  • Allow popup to be changed

You can select both of the types of launches (and even the privacy placement) as long as the tool url is something like "http../plus/sakai/" with no suffix like sakai.site or sakai.resources.

  • The tool URL can receive an LTI launch
  • The tool can receive a Content-Item or Deep-Link launch

Once the tool (or tools) are configured, save the tool.

Testing SakaiPlus

We have a simple outline of how to testing Sakai Plus from Sakai. Please keep in mind that you end up with two tabs - one tab from the "main site" and another tab for the "plus site". The easiest way to keep them separate is to have different tools in the sites or edit the Overview message in each site so that you can easily tell which is which.