{"id":16782,"library":"brightspace-auth-provisioning","title":"Brightspace Auth Token Provisioning","description":"The `brightspace-auth-provisioning` library facilitates the creation and assertion of access tokens against a Brightspace authentication service. It abstracts the complexities of token generation, allowing developers to provision tokens with specific claims such as scopes, tenant IDs, user IDs, impersonator IDs, and Caliper FSIDs. The current stable version is `9.0.1`, which requires Node.js version `20.x` or higher. The package sees active development with major versions released periodically (e.g., v7, v8, v9) and more frequent patch and minor releases. Its key differentiator is its tight integration with the Brightspace authentication ecosystem, providing a specific API for generating tokens that adhere to Brightspace's assertion requirements, including a flexible `keyLookup` mechanism for signing keys and support for caching mechanisms.","status":"active","version":"9.0.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/Brightspace/node-auth","tags":["javascript"],"install":[{"cmd":"npm install brightspace-auth-provisioning","lang":"bash","label":"npm"},{"cmd":"yarn add brightspace-auth-provisioning","lang":"bash","label":"yarn"},{"cmd":"pnpm add brightspace-auth-provisioning","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for looking up and managing authentication keys, as indicated by the peer dependency.","package":"brightspace-auth-keys","optional":false}],"imports":[{"note":"While the README shows CommonJS `require`, modern Node.js projects (especially with `node >=20.x`) typically use ES Modules. Both are generally supported, but `import` is preferred for new code.","wrong":"const AuthTokenProvisioner = require('brightspace-auth-provisioning');","symbol":"AuthTokenProvisioner","correct":"import { AuthTokenProvisioner } from 'brightspace-auth-provisioning';"},{"note":"This is an abstract class intended for extension, available as a named export. Ensure you import it correctly for type hinting or extension.","wrong":"const AbstractProvisioningCache = require('brightspace-auth-provisioning').AbstractProvisioningCache;","symbol":"AbstractProvisioningCache","correct":"import { AbstractProvisioningCache } from 'brightspace-auth-provisioning';"},{"note":"The primary class is a named export, not a default export. Using `require` directly on the package returns an object with named exports.","wrong":"import AuthTokenProvisioner from 'brightspace-auth-provisioning';","symbol":"AuthTokenProvisioner","correct":"const { AuthTokenProvisioner } = require('brightspace-auth-provisioning');"}],"quickstart":{"code":"import { AuthTokenProvisioner } from 'brightspace-auth-provisioning';\nimport { KeyObject, generateKeyPairSync } from 'node:crypto';\n\nasync function provisionExampleToken() {\n  // Generate a dummy key pair for demonstration purposes\n  // In a real application, you would load this securely\n  const { privateKey } = generateKeyPairSync('ec', {\n    namedCurve: 'P-256',\n    publicKeyEncoding: { type: 'spki', format: 'pem' },\n    privateKeyEncoding: { type: 'pkcs8', format: 'pem' }\n  });\n\n  const provisioner = new AuthTokenProvisioner({\n    issuer: 'ece083bc-e6ac-11e4-8e1b-54ee750fffa4', // Replace with your service's issuer GUID\n    keyLookup: async () => {\n      return {\n        kid: '0a9e68f6-e6ad-11e4-8ab6-54ee750fffa4', // Replace with your key ID\n        key: privateKey, // Must be a node:crypto KeyObject\n        alg: 'ES256'\n      };\n    }\n  });\n\n  try {\n    const token = await provisioner.provisionToken({\n      user: '32647',\n      impersonator: '30882',\n      tenant: '5492ff8a-e6ad-11e4-84d6-54ee750fffa4',\n      scopes: ['updates:feed-items:read', 'core:*:*'],\n      fsid: 'eyJhbGciOiJIUzI1Ni...' // Optional Caliper FSID\n    });\n    console.log('Successfully provisioned token:', token);\n    return token;\n  } catch (error) {\n    console.error('Error provisioning token:', error);\n    throw error;\n  }\n}\n\nprovisionExampleToken();","lang":"typescript","description":"This quickstart demonstrates how to instantiate `AuthTokenProvisioner`, provide a `keyLookup` function returning a `KeyObject`, and then use it to provision an access token with specified claims."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.x or newer. Use `nvm install 20 && nvm use 20` or similar version management tools.","message":"Version 9.x (and potentially prior major versions) requires Node.js runtime version 20.x or higher. Running on older Node.js versions will result in errors.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Ensure that your `keyLookup` function correctly loads and returns a `KeyObject` (e.g., from a PEM string using `crypto.createPrivateKey`).","message":"The `keyLookup` option for `AuthTokenProvisioner` must return a Promise resolving to an object where the `key` property is a `node:crypto.KeyObject`, not a raw key string or buffer. Incorrect key types will lead to signing errors.","severity":"gotcha","affected_versions":">=6.0.0"},{"fix":"Review the specific release notes or changelog for the version you are upgrading to and adapt your code accordingly. Pay close attention to constructor options and method signatures.","message":"Major version updates (e.g., v6.x to v7.x, v7.x to v8.x, v8.x to v9.x) typically introduce breaking changes in the API or required options. Always consult the release notes when upgrading between major versions.","severity":"breaking","affected_versions":">=6.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the peer dependency: `npm install brightspace-auth-keys` or `yarn add brightspace-auth-keys`.","cause":"The `brightspace-auth-keys` package is a peer dependency but was not installed in your project.","error":"Cannot find package 'brightspace-auth-keys' imported from ..."},{"fix":"For CommonJS, use `const { AuthTokenProvisioner } = require('brightspace-auth-provisioning');`. For ES Modules, use `import { AuthTokenProvisioner } from 'brightspace-auth-provisioning';`.","cause":"Attempting to use `require('brightspace-auth-provisioning')` and then calling it as a default export, or using `import AuthTokenProvisioner from '...'`. The class is a named export.","error":"TypeError: AuthTokenProvisioner is not a constructor"},{"fix":"Ensure that the `key` property in the object returned by `keyLookup` is a properly instantiated `KeyObject`. Use `crypto.createPrivateKey()` to convert PEM strings or other formats.","cause":"The object returned by `keyLookup` has a `key` property that is not an instance of `node:crypto.KeyObject`.","error":"Error: privateKey is not a KeyObject"}],"ecosystem":"npm","meta_description":null}