21 June, 2011

OpenID for Node.js v0.2.0 released

I am pleased to announce the release of OpenID for Node.js v0.2.0. It deserves a blog post since the new version is a bump of the minor version number. What does this mean to the users of the library?

API changes

The API of the entire thing has changed. All callbacks exposed and used by the library are now on the form callback(error, args). This convention is familiar to Node.js developers, and gives us the advantage of simpler integration with other libraries, as well as a slight increase in the fidelity of error messages.

What has changed?

  • authenticate now expects a callback which will be called with (error, authUrl). Existing code which expects (authUrl) will not get an authUrl (but possibly an error instead), and so authentication won't work after upgrade until you change your code.
  • verifyAssertion also expects a callback of the same form, which will be called with (error, result). Again, existing code depends on receiving a (result) call, and will break.
  • loadAssociation and saveAssociation must now accept a callback on the form (error, result) as an additional parameter. Previously, these functions were synchronous, so existing implementations will have to adapt so they call the callback rather than return.

What is new?

As usual, we have fixed several bugs. The library is gaining a community, and there have been several contributions along the 0.1 release path leading up to 0.2.0. Thank you all for your participation!

Apart from the changes above, 0.2.0 also introduces a discovery cache for caching discovered information. This cache is used to avoid additional HTTP requests when verifying assertions from the OpenID providers. The default cache is an in-memory cache, but you can implement your own by overloading two functions:

  • loadDiscoveredInformation(claimedIdentifier, callback) is expected to look for and load a cached provider for the given claimedIdentifier. It is expected to call callback(error, provider) when finished, with either an error or a provider (duh).
  • saveDiscoveredInformation(provider, callback) is expected to cache the given provider. The key for this object is provider.claimedIdentifier, which loadDiscoveredInformation uses for lookup. After saving, the function is expected to call callback(error) with an error if something failed, or nothing if all went well.

I have been very reluctant to make these significant API changes, but the recent development, reported issues, and feature requests have convinced me that a unified API, and a more familiar API for Node.js developers, is the right way. Also, adapting to the new API is a pretty easy process. I hope you agree with me that the introduction of these changes is best in the long run.


  1. Excellent work! I'm so pleased to have found this, especially so soon after you released it! Consider me grateful.

  2. Nice package. But it would be even nicer, if you could include some simple code examples on the github project page, like how to use it with Google for federated login.

  3. @Jacob But there are lots of examples! There is an example in README.md, which is what you're reading when you visit the OpenID for Node.js GitHub site. That example is the simplest you can do, and it is a stripped-down version of what you find in sample.js. And if that doesn't cut it, look at the tests for even more deep-dives.