Superagent D2L Session Authentication

2.0.1 · active · verified Wed Apr 22

superagent-d2l-session-auth is a JavaScript plugin designed to integrate D2L (Brightspace) session authentication with `superagent` HTTP requests. It acts as a `superagent` middleware, automatically adding the necessary D2L authentication headers to outbound requests by leveraging the `frau-jwt` library internally. The current stable version is 2.0.1, which includes a fix for `trustedHost` casing sensitivity. While specific release cadence is not explicitly stated, the project appears to be actively maintained by Brightspace, with updates addressing functionality and compatibility. Its primary differentiator is its specialized function within the Brightspace ecosystem, providing a streamlined way to handle D2L session-based authentication for applications using `superagent`, particularly within iframed contexts.

Common errors

```
Error: Cannot find module 'superagent'
```
cause `superagent` is a peer dependency and was not installed in the project.

fix Run `npm install superagent` or `yarn add superagent` to add `superagent` to your project's dependencies.
```
TypeError: auth is not a function
```
cause The main export of `superagent-d2l-session-auth` is a factory function that must be called to produce the actual plugin.

fix Call the imported `auth` function to get the plugin instance: `const auth = require('superagent-d2l-session-auth')()` or `import createAuth from 'superagent-d2l-session-auth'; const auth = createAuth();`.
```
ReferenceError: require is not defined
```
cause Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment (e.g., Node.js with `type: module` or a browser).

fix Use ESM `import` syntax: `import createAuth from 'superagent-d2l-session-auth'; const auth = createAuth();`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ESM `import` syntax in a CommonJS environment (e.g., Node.js without `type: module` in `package.json`).

fix Use CommonJS `require()` syntax: `const auth = require('superagent-d2l-session-auth')();`.

Warnings

breaking Starting from version `0.12.0`, `superagent` was changed to a peer dependency. Users must explicitly install `superagent` in their project, as it is no longer bundled.
Fix: Ensure `superagent` is installed as a direct dependency in your project: `npm install superagent` or `yarn add superagent`.
deprecated The use of the `X-D2L-App-Id` header for authentication was deprecated starting from version `0.1.0`. Relying on this header may lead to authentication failures in newer D2L environments.
Fix: Transition to using the standard D2L session authentication flow provided by the plugin, which leverages `frau-jwt` for token management.
gotcha Prior to version `1.0.1`, the `trustedHost` option in the plugin configuration was case-sensitive. Incorrect casing could prevent tokens from being sent to the specified host.
Fix: Upgrade to version `1.0.1` or newer. If upgrading is not possible, ensure the `trustedHost` option exactly matches the case of the target D2L host.
gotcha The library primarily uses and demonstrates CommonJS `require()` syntax. While bundlers can handle ESM `import` in many environments, direct `import` might fail in older Node.js versions or certain browser contexts without proper module configuration.
Fix: For CommonJS environments, use `const auth = require('superagent-d2l-session-auth')()`. For ESM, ensure your project is configured for `type: module` in `package.json` or use a bundler.

Install

npm install superagent-d2l-session-auth npm
yarn add superagent-d2l-session-auth yarn
pnpm add superagent-d2l-session-auth pnpm

Imports

auth
wrong:
```
const auth = require('superagent-d2l-session-auth')
```
correct:
```
import auth from 'superagent-d2l-session-auth'
```
The primary export is a factory function. While the README shows CommonJS, ESM is the modern approach.
authFactory
wrong:
```
const auth = require('superagent-d2l-session-auth')
```
correct:
```
const auth = require('superagent-d2l-session-auth')()
```
The default export is a factory function that must be called to create the plugin instance.
framedAuthFactory
wrong:
```
const auth = require('superagent-d2l-session-auth/framed')
```
correct:
```
const auth = require('superagent-d2l-session-auth/framed')()
```
For strictly iframed applications, import from the 'framed' path and call it as a factory function.

Quickstart

Demonstrates how to initialize the `superagent-d2l-session-auth` plugin and attach it to a `superagent` request for D2L API interaction.

const request = require('superagent');
const auth = require('superagent-d2l-session-auth')({
    scope: '*:*:*',
    trustedHost: 'school.brightspace.com' // Replace with your D2L domain
});

// Example using a placeholder D2L API endpoint
request
    .get('https://school.brightspace.com/d2l/api/lp/1.5/users/whoami')
    .use(auth)
    .end(function(err, res) {
        if(err) {
           console.error('Failed to fetch user info: ' + err.status + ' ' + (err.response ? err.response.text : ''));
           return;
        }
        const user = res.body;
        console.log('Hello, ' + user.FirstName + ' ' + user.LastName);
    });

view raw JSON →