brightspace-auth-keys

Library for generating, storing, and retrieving keypairs for use in Brightspace's auth framework.

Install

npm install brightspace-auth-keys --save

Usage

Step 1. Implement the interface defined by AbstractPublicKeyStore:

const AbstractPublicKeyStore = require('brightspace-auth-keys').AbstractPublicKeyStore;

class RedisPublicKeyStore extends AbstractPublicKeyStore {
	constructor (redisClient) {
		super();
		// initialization
	}

	_storePublicKey (key, expiry) {
		// "key" is an opaque String representing the public JWK
		// "expiry" is the "seconds since unix epoch", after which
		// the key should not longer be returned in results

		// returns a Promise, resolving after the key is successfully stored
	}

	_lookupPublicKeys() {
		// returns a Promise, resolving with an Array of the stored opaque strings
	}
}

Step 2. Instantiate KeyGenerator:

const KeyGenerator = require('brightspace-auth-keys').KeyGenerator;
const publicKeyStore = new RedisPublicKeyStore(...);

const keyGenerator = new KeyGenerator({
	signingKeyType: 'EC',
	// other settings
	publicKeyStore
});

Step 3. Expose a route for public key retrieval using a routing framework of your choice. The route will be called by D2L Auth Service. Note that your service must be known by the Auth service (present in its DB).

const router = require('koa-router')();

router.get('/auth/.well-known/jwks', function() {
	return publicKeyStore
		.lookupPublicKeys()
		.then(keys => this.body = { keys });
});

router.get('/auth/jwk/:kid', function(kid) {
	return publicKeyStore
		.lookupPublicKey(kid)
		.then(key => this.body = key);
});

app.use(router.routes());

Step 4. Instantiate AuthTokenProvisioner providing keyGenerator.getCurrentPrivateKey as a keyLookup function:

const AuthTokenProvisioner = require('brightspace-auth-provisioning');

const provisioner = new AuthTokenProvisioner({
	...
	keyLookup: keyGenerator.getCurrentPrivateKey.bind(keyGenerator),
	...
});

Now you are able to call provisioner.provisionToken(...).

Supported options:

const keyGenerator = new KeyGenerator({
	signingKeyType: 'EC',				// A type of signing keys to generate. 'RSA' or 'EC'. REQUIRED

	lifetimes: {
		keyUse: 3600,					// Length of time, in seconds, for a private key to remain in use
		token: 300						// Max length of time, in seconds, that a signed token will remain valid
	},

	// EC-specific settings:
	ec: {
		crv: 'P-256'					// one of 'P-256', 'P-384', 'P-521'
	},

	// RSA-specific settings:
	rsa: {
		signingKeySize: 2048			// RSA key size, in bits
	},

	publicKeyStore: new RedisPublicKeyStore(...)	// A backend for storing public keys.
													// Can be anything: Redis, MSSQL, PostgreSQL, etc.
													// REQUIRED
});