added documentation for serving as lti

Author: bradley-erickson

VERSION

@@ -1 +1 @@
-0.1.0+2025.10.01T17.50.57.101Z.d6047986.master
+0.1.0+2025.10.01T21.16.15.146Z.8b205d0c.master

autodocs/concepts.rst

@@ -21,6 +21,8 @@ implementation details:
   aggregated into the state our experiences depend on.
 - :doc:`Communication Protocol <docs/concepts/communication_protocol>` - discusses how
   the system queries data from reducers for dashboards.
+- :doc:`Student Identity Mapping <docs/concepts/student_identity_mapping>` - explain
+  how learners information is mapped across integrations.
 - :doc:`Scaling <docs/concepts/scaling>` - covers strategies for growing the
   system once the fundamentals are in place.
 - :doc:`Auth <docs/concepts/auth>` - describes authentication considerations
@@ -41,6 +43,7 @@ implementation details:
    docs/concepts/events
    docs/concepts/reducers
    docs/concepts/communication_protocol
+   docs/concepts/student_identity_mapping
    docs/concepts/scaling
    docs/concepts/auth
    docs/concepts/privacy

autodocs/how-to.rst

@@ -6,6 +6,7 @@ Practical instructions for achieving specific goals within Learning Observer. Us
 - :doc:`Communication Protocol <docs/how-to/communication_protocol>` - How to query data from reducers or system endpoints for dashboards.
 - :doc:`Configure Learning Observer <docs/how-to/config>` - Set up credentials, environment variables, and other configuration details required for a smooth deployment.
 - :doc:`Build Dashboards <docs/how-to/dashboards>` - Walk through creating dashboards from reducer outputs, including layout choices and data wiring.
+- :doc:`LTI <docs/how-to/lti>` - Cover how to install Learning Observer as an LTI application.
 - :doc:`Run with Docker <docs/how-to/docker>` - Learn how to containerize the stack, manage images, and operate the project using Docker Compose.
 - :doc:`Writing Observer Extension <docs/how-to/extension>` - Install, configure, and validate the Writing Observer browser extension for capturing events.
 - :doc:`Interactive Environments <docs/how-to/interactive_environments>` - Connect Learning Observer to Jupyter and other live coding setups for iterative development.
@@ -18,6 +19,7 @@ Practical instructions for achieving specific goals within Learning Observer. Us
    docs/how-to/communication_protocol.md
    docs/how-to/config.md
    docs/how-to/dashboards.md
+   docs/how-to/lti.md
    docs/how-to/docker.md
    docs/how-to/extension.md
    docs/how-to/interactive_environments.md

docs/concepts/student_identity_mapping.md

@@ -0,0 +1,36 @@
+# Student Identity Mapping
+
+This document describes the current approach for reconciling a student's identity across the Google Workspace context used by Writing Observer and external platforms that only surface an email address (for example when the application is launched as an LTI tool).
+
+## Why the mapping exists
+
+When Writing Observer runs inside Google Workspace we naturally have access to the Google user identifier that shows up in event payloads. However, when the product is embedded as an LTI application we receive the learner's email address but do not receive the Google identifier. Many downstream reducers and dashboards expect to look students up by the Google identifier that is emitted by Google Docs events. Without an explicit bridge between those two identifiers we would be unable to join activity data with roster or profile information for LTI launches.
+
+## Data sources involved
+
+Two pieces of infrastructure cooperate to keep an email-to-Google-ID lookup table available:
+
+1. **`student_profile` reducer** – The `student_profile` KVS pipeline in `writing_analysis.py` stores the latest email address and Google identifier (`safe_user_id`) observed for each student. The reducer only updates its state when either value changes. The resulting records live in the reducer's internal key-value namespace and therefore need to be copied to a place where other services can access them. 【F:modules/writing_observer/writing_observer/writing_analysis.py†L233-L253】
+2. **`map_emails_to_ids_in_kvs.py` script** – This maintenance script scans the reducer's internal keys, extracts any records that contain both `email` and `google_id`, and writes a dedicated `email-studentID-mapping:{email}` entry to the key-value store. The explicit mapping gives any service that only knows the email address a way to recover the Google identifier. 【F:scripts/map_emails_to_ids_in_kvs.py†L1-L29】
+
+This flow is intentionally simple: the reducer captures whatever the client reports, and the script copies the data to keys that other components already know how to query.
+
+## Operating the script
+
+The email mapping script is normally run in the same environment as other KVS maintenance tasks. It requires access to the same credentials file that reducers use. A manual run looks like this:
+
+```bash
+python scripts/map_emails_to_ids_in_kvs.py
+```
+
+The script performs a full scan every time it runs, so it is safe to execute multiple times or to schedule as a recurring job.
+
+## Limitations and future direction
+
+The current reducer-plus-script approach fills an immediate gap but remains a stopgap solution:
+
+* **Tight coupling to Google identity** – The reducer only records the Google identifier surfaced by Google Docs. If we ingest events from another platform, there is no canonical place to persist its identifiers.
+* **No user object abstraction** – Each consumer must know which KVS keys to query. A shared user object (or identity service) would allow the system to attach multiple external identifiers, roles, and profile attributes to a learner and to expose them through a stable API.
+* **Operational overhead** – Because the mapping lives in the KVS, we must remember to run the maintenance script anywhere we expect the lookup table to be fresh.
+
+In the future we plan to introduce a formal user object that encapsulates identifiers, roles, and cross-system metadata. That abstraction would make this lookup process unnecessary by giving every component a single source of truth for student identity. Until then, this document serves as a reference for the current mapping workflow.

docs/how-to/lti.md

@@ -0,0 +1,87 @@
+# Serve Learning Observer as an LTI 1.3 tool
+
+Learning Observer ships with an IMS LTI 1.3 implementation that relies on the platform's OpenID Connect (OIDC) handshake to authenticate users and obtain scoped API access tokens from the learning management system (LMS). Use this guide to register the tool in an LMS and connect it to a course shell.
+
+## Prerequisites
+
+* A deployment of Learning Observer reachable by the LMS (typically via HTTPS).
+* An LMS that supports LTI 1.3 with dynamic registration or manual developer keys (e.g., Canvas or Schoology).
+* Administrative access in that LMS to create a developer key / external tool.
+
+## 1. Generate and share a signing key
+
+Learning Observer signs client assertions with an RSA private key when it exchanges OIDC launch data for an LMS access token. Generate a keypair, store the private key somewhere on the application host, and upload the public key to the LMS when you create the developer key.
+
+```bash
+# create a 4096-bit RSA keypair
+openssl genrsa -out secrets/lti-tool-private.pem 4096
+openssl rsa -in secrets/lti-tool-private.pem -pubout > secrets/lti-tool-public.pem
+```
+
+Record the filesystem path to the private key; you'll reference it in the application configuration in the next step.
+
+## 2. Configure `creds.yaml`
+
+Enable the LTI provider in `learning_observer/creds.yaml` by adding an entry under `auth.lti.<provider>`. Each provider requires the LMS endpoints, the Learning Observer redirect URL, and the private key location. A Canvas example looks like this:
+
+```yaml
+auth:
+  lti:
+    sample-canvas:
+      client_id: "10000000000000"
+      auth_uri: "https://canvas.example.edu/api/lti/authorize_redirect"
+      jwks_uri: "https://canvas.example.edu/api/lti/security/jwks"
+      token_uri: "https://canvas.example.edu/login/oauth2/token"
+      redirect_uri: "https://lo.example.edu/lti/sample-canvas/launch"
+      private_key_path: "secrets/lti-tool-private.pem"
+      api_domain: "https://canvas.example.edu"  # Canvas-specific
+```
+
+Set `redirect_uri` to the public URL that will receive the POST launch request (`/lti/<provider>/launch`). The login initiation URL for the LMS is the matching `/lti/<provider>/login` route.
+
+Restart the application after updating configuration so the new provider registration is loaded.
+
+## 3. Enable LMS API routes
+
+Learning Observer only exposes the IMS Names & Roles (NRPS) and Assignment & Grade Service (AGS) proxy routes when the matching feature flag is turned on. Add the appropriate flag to `creds.yaml` so the application registers the routes during startup:
+
+```yaml
+feature_flags:
+  canvas_routes: true          # Canvas NRPS/AGS proxy endpoints
+  # schoology_routes: true     # Schoology NRPS/AGS proxy endpoints
+```
+
+## 4. Map the roster source with PMSS
+
+LTI launches identify the LMS provider in the session so roster lookups can decide which backend to call. Create a PMSS overlay that maps the provider to the correct roster source (see [System settings](../concepts/system_settings.md) for more on PMSS). For Canvas, create a file such as `config/roster_source.pmss` alongside `creds.yaml` with the following contents:
+
+```pmss
+roster_data[provider="sample-canvas"] {
+    source: sample-canvas;
+}
+```
+
+If you support multiple LMS tenants, add additional selector blocks for their email domains or provider names and point them at `schoology`, `filesystem`, or any other supported roster backend.
+
+## 5. Register the tool in the LMS
+
+When you create the LTI developer key/external tool inside the LMS:
+
+1. Supply the **OIDC login initiation URL** as `https://<your-domain>/lti/<provider>/login`.
+2. Supply the **redirect/launch URL** as `https://<your-domain>/lti/<provider>/launch`.
+3. Paste the **public key** generated earlier so the LMS can validate the signed client assertions.
+4. Copy the LMS-issued **client ID** and the platform endpoints (authorize, JWKS, token) into `creds.yaml` if you have not done so already.
+
+Publish the developer key and install the tool in the desired course/context. The LMS will send the context identifiers in the launch claims so Learning Observer can associate sessions with the right course.
+
+## 6. Verify the launch
+
+* Add the external tool link to a module or assignment inside the LMS course.
+* Launch the tool from within the LMS. Learning Observer should redirect the browser to the LMS's authorize endpoint, validate the launch state and nonce, and then create a session for the user when the LMS returns.
+* Successful launches land on the root of the application with LMS-specific authorization headers stored in the session for follow-up roster and grade sync operations.
+
+If the launch fails, inspect the Learning Observer logs for messages beginning with `LTI Launch`—they include detailed context whenever state validation, token exchange, or JWT verification fails. Once the LMS recognizes the tool, you can remove or hide other authentication methods; Learning Observer will automatically expose the LTI login routes whenever `auth.lti` providers are configured.
+
+## 7. Plan student identity mapping
+
+LTI launch data only includes the learner's email address, while Writing Observer's Google Workspace integrations emit a Google-specific user identifier. To keep downstream reducers and dashboards working for LTI cohorts, plan to run the maintenance workflow that maps emails to Google IDs. Refer to the [Student Identity Mapping guide](../concepts/student_identity_mapping.md) for an overview of how the reducer and maintenance script cooperate and how to operate the sync in production.