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:

import { AbstractPublicKeyStore } from 'brightspace-auth-keys';

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:

import { KeyGenerator } from 'brightspace-auth-keys';

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).

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:

import AuthTokenProvision from '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
});