Sakai LMS Integration

Integrate Qriib Virtual Classrooms into Sakai LMS using the LTI 1.3 / LTI Advantage protocol. This guide is written for system administrators, DevOps engineers, and developers responsible for registering the tool, wiring up grade/roster services, and operating the integration in production.

1. Overview & Prerequisites

LTI 1.3 replaces the old OAuth 1.0a launch signing used by LTI 1.1 with an OpenID Connect (OIDC) third-party initiated login flow and signed JWTs. Sakai acts as the Platform, and Qriib acts as the Tool. Once registered, the integration enables:

• Single sign-on (SSO) launches from any Sakai site.
• Deep Linking — instructors pick and embed a Qriib activity directly from Lessons/Resources.
• Assignment and Grade Services (AGS) — scores sync back to the Sakai Gradebook.
• Names and Role Provisioning Services (NRPS) — course roster and roles sync automatically.

Prerequisites

2. Sakai LTI 1.3 Tool Registration & Deployment

Sakai registers external tools through Administration Workspace → External Tools. This is a two-way handshake: you give Sakai the Qriib tool's endpoints, save, and Sakai then generates platform credentials you register back into Qriib.

Step 1: Get the LTI Tool Credentials

Log in to the [Your App Name] Developer Portal and copy the three URLs generated for your environment:

Step 2: Locate and Edit the Tool in Sakai

1. Log in to Sakai with an admin account.
2. Navigate to Administration Workspace → External Tools.
3. Search for the tool (or click Register New Tool if it doesn't exist yet), then click Edit to open it for editing.

Step 3: Fill in the Tool Configuration

If your Sakai instance offers only a single Redirect URI(s) field, enter the Launch URL above — it doubles as the redirect target after OIDC authentication succeeds.

Step 4: Configure Privacy & Services

These settings control what data Sakai is allowed to hand the tool on every launch — required for interactive features like roster display, attendance, and grade passback to work:

Privacy Settings

• Enable Send User Names to External Tool.
• Enable Send Email Addresses to External Tool.

Services

• Enable Allow External Tool to return grades — required for AGS.
• Enable Provide Roster to External Tool — required for NRPS.

Step 5: Save and Collect Platform Credentials

Click Save. Sakai will generate the platform-side credentials at the bottom of the same page — copy these into the Qriib DevKit Portal's LMS Integration form:

Paste these into the Qriib DevKit Portal's Register New LMS form:

Click Register LMS Integration. The tool now appears in Sakai's External Tools table as an active LTI 1.3 tool:

3. LTI Advantage Services Setup (Sakai-Specific)

Deep Linking (LTI DL)

Deep Linking lets an instructor open a content-selection UI inside Qriib (from Sakai Lessons or Resources) and have the selected item embedded back into the course automatically, instead of manually configuring a placement.

• Deep Linking is negotiated automatically once the tool registration in Section 2 is saved with LTI 1.3 enabled — no extra endpoint is needed beyond the shared Launch URL.
• In Sakai, Deep Linking is triggered from Lessons → Add Content → Add Learning App, or from Resources when adding an external tool item.
• Qriib returns a Deep Linking Response JWT (ltiResourceLink or contentItems) that Sakai uses to create the placement — verify in your tool logs that the response is signed with the same key referenced in your JWKS.

Assignment and Grade Services (AGS)

AGS lets Qriib post scores, attendance, and commentary directly into the Sakai Gradebook via the https://purl.imsglobal.org/spec/lti-ags/scope/* scopes.

1. Confirm Allow External Tool to return grades is enabled on the tool registration (Section 2, Step 4).
2. Sakai automatically creates a Gradebook column for the tool placement the first time a score is posted (line item auto-creation), or you can pre-create the line item from the Gradebook if strict column control is required.
3. Qriib requests an access token from the Access Token URL using the client_credentials grant with a signed JWT assertion, then calls the AGS Line Item and Score endpoints returned in the launch's endpoint claim.
4. Scores appear in the Sakai Gradebook shortly after the session ends — check Gradebook → column settings if a score doesn't map to the expected assignment.

Names and Role Provisioning Services (NRPS)

NRPS lets Qriib pull the enrolled roster (names, emails, LTI roles) for a course context, powering features like pre-populated attendee lists and role-based UI (instructor vs. student controls).

1. Confirm Provide Roster to External Tool is enabled on the tool registration.
2. Sakai exposes the roster at the namesroleservice URL returned in the launch's https://purl.imsglobal.org/spec/lti-nrps/claim/namesroleservice claim — no separate registration step is required beyond enabling the service.
3. Roles are returned as LTI standard role URNs (e.g. http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor); map these on the Qriib side rather than relying on Sakai-specific role names.

4. Sakai Lesson Tool & Course Placement

Once registered by an admin, instructors add the tool to their own course sites — no further admin involvement is needed per-course.

Optional: Creating a Test Course Site

If you don't already have a course site to test against, create one from Administration Workspace → Worksite Setup → Create New Site, choose the Project Site (or Course Site) type, and give it a title on the Edit Site Information screen:

Once created, the site appears in the worksite list with a confirmation banner:

Adding the Tool via Lessons

1. Open the course site and go to Lessons in the site's tool menu (or create one via Site Info → Manage Tools if not yet added to the site).
2. Click Add Content + in the page toolbar.
3. Select Add Learning App from the dropdown.

4. Choose Qriib Virtual Classrooms from the list of registered external tools.
5. Choose a target placement:
   • Embed in page — the tool renders inline within the Lessons page (best for launch-and-join flows).
   • New Window — opens the tool in a separate browser tab (recommended if the session uses camera/microphone permissions or screen sharing, which can be restricted inside nested iframes).
6. Save the page. Students launch the tool by clicking the item on the Lessons page.

Adding the Tool via External Tools Menu

Alternatively, add the tool directly as a top-level site tool:

1. Go to Site Info → Manage Tools.
2. Select the registered Qriib Virtual Classrooms tool from the external tools list and add it to the site.
3. Save — the tool now appears in the site's left-hand tool menu for all site members.

5. Security & Authentication Flow

OIDC Third-Party Initiated Login

Every launch follows the standard LTI 1.3 / OIDC flow between Sakai (Platform) and Qriib (Tool):

1. Initiation — Sakai redirects the browser to the Qriib OIDC Initiation Endpoint with iss, login_hint, and target_link_uri.
2. Auth request — Qriib redirects the browser back to Sakai's Authentication Request URL (/imsoidc/lti13/oidc_auth) with a generated state and nonce.
3. Authentication — Sakai authenticates the request (the user is already logged in) and redirects to the tool's Launch URL with a signed id_token (JWT) and the original state.
4. Launch — Qriib validates the state matches what it issued, validates the JWT (see below), consumes the nonce exactly once, and renders the session.

JWT Validation Checklist

Qriib validates every id_token against:

• Signature — verified using the public key fetched from Sakai's JWKS (/imsblis/lti13/keyset), matched by the kid in the JWT header.
• Issuer (iss) — must exactly match the registered Platform Issuer.
• Audience (aud) — must match the Client ID issued for this registration.
• Nonce — must be unique and unused; replayed nonces are rejected.
• Expiry (exp) / issued-at (iat) — rejected if expired or issued outside an acceptable clock-skew window (requires NTP-synced servers).
• Deployment ID claim (https://purl.imsglobal.org/spec/lti/claim/deployment_id) — must match the registered Deployment ID exactly; mismatches are the most common cause of rejected launches after a Sakai site is cloned or the tool is re-registered.

Key Rotation Guidance

• Rotate the Qriib tool's signing keys periodically. Publish both the old and new public key in the JWKS response during a rotation window so in-flight tokens signed with the old key still validate.
• Sakai caches the JWKS response for a period of time — after rotating keys, allow for cache expiry (or restart the relevant Sakai service) before retiring the old key entirely.
• Never remove a key from the JWKS the moment you stop signing with it — keep it published until you are confident no cached/queued token still references its kid.

6. Environment Configuration Reference

Example configuration for the LTI tool's backend/frontend. Adjust variable names to match your framework's convention; values below correspond to the fields collected in Section 2, Step 5.

# --- Sakai Platform (per-tenant, one set per Sakai instance registered) ---
SAKAI_ISSUER=https://sakai.example.edu
SAKAI_CLIENT_ID=<client-id-from-sakai-tool-registration>
SAKAI_DEPLOYMENT_ID=<deployment-id-from-sakai-tool-registration>

# --- Sakai Endpoints ---
SAKAI_KEYSET_URL=https://sakai.example.edu/imsblis/lti13/keyset
SAKAI_AUTH_TOKEN_URL=https://sakai.example.edu/imsblis/lti13/token/<id>
SAKAI_AUTH_LOGIN_URL=https://sakai.example.edu/imsoidc/lti13/oidc_auth

# --- Your LTI Tool's own endpoints (copy the dynamic values shown in Section 2, Step 1) ---
LTI_TOOL_LAUNCH_URL=<launch-url-from-your-lti-tool>
LTI_TOOL_LOGIN_URL=<oidc-initiation-url-from-your-lti-tool>
LTI_TOOL_JWKS_URL=<jwks-url-from-your-lti-tool>

# --- Tool Signing Keys ---
LTI_TOOL_PRIVATE_KEY_PATH=/etc/<your-app>/keys/lti-signing-key.pem
LTI_TOOL_KID=<key-id-matching-jwks-entry>

Store one SAKAI_ISSUER / SAKAI_CLIENT_ID / SAKAI_DEPLOYMENT_ID triple per Sakai tenant you integrate with — multi-tenant deployments must key their credential lookup off all three values together, since client_id alone is not guaranteed globally unique across platforms.

7. Troubleshooting & Common Sakai Edge Cases

Debugging LTI Launches in Sakai

• Sakai Admin Logs: check sakai.log (or your configured log appender) for entries under org.sakaiproject.lti13 and org.sakaiproject.basiclti — these log OIDC state/nonce mismatches and JWT validation failures with the specific claim that failed.
• Raise log verbosity: temporarily set the org.sakaiproject.lti13 logger to DEBUG via Sakai's admin logging console (Administration Workspace → Logging) to capture the full outgoing/incoming JWT payloads during a test launch.
• Inspect the launch payload: use browser devtools' Network tab on the redirect to the tool's Launch URL — the id_token is a standard JWT and can be decoded (without verifying the signature) at any JWT debugger to confirm claims like deployment_id, roles, and the AGS/NRPS service URLs are present as expected.
• Test in isolation: reproduce the launch with a minimal LTI 1.3 test tool (e.g. the IMS Global reference implementation) against the same Sakai registration to confirm whether an issue is Sakai-side or Qriib-side before escalating.