README.md

OAuth 2 Server with OpenID Connect support

This is a fully functional OAuth 2 server implementation, with support for OpenID Connect specification. Based on https://github.com/ammmir/node-oauth2-provider.

News

Major rewrite. Now we use modelling for Model part.

Install

Install via npm:

npm install --save openid-connect

You can add it to your Connect or Express application as another middleware. Be sure to enable the bodyParser and query middleware.

To use it inside your project, just do:

var oidc = require('openid-connect').oidc(options);

and then, for example, with express

app.get('/authorization', oidc.auth());

Options

When you require openid-connect, you may specify options. If you specify them, it must be with a json object with the following properties (all of them are optional):

• login_url

  URL where login form can be found. Defaults to "/login".

• consent_url

  URL where consent form can be found. Defaults to "/consent".

• scopes

  Json object of type { scope name: scope description, ... } used to define custom scopes.

• models

  Models as described in modelling.

  Actually OpenIDConnect defines 6 models:

  • user: Where user data is stored (email, password, etc).
  • client: Where user can register a client app that will use your project for authentication/authorization.
  • consent: Where user consent of certain scopes for a particular client is stored.
  • auth: Where authorization data is stored (token, expiration date, etc).
  • access: Where access data is stored (token, expiration date, etc).
  • refresh: Where refresh data is stored (token, expiration date, etc).

  You can overwrite any part of any model of OpenIDConnect, or overwrite all of them.

  If you overwrite user model, the new model should conform with OpenID Connect Standard Claims, in order to comply with the spec.

• adapters

  Adapters as described in modelling.

• connections

  Connections as described in modelling.

• policies

  Policies as described in modelling.

• alien

  You can use your own Waterline collections with OpenIDConnect.

  If you define an alien collection with the same name of one of the models in OpenIDConnect, the last one will be replaced.

  For example:

  var orm = new Waterline();
  
  var MyUserModel = Waterline.collection.extend({
  	identity: 'user',
  	//Collection definition here.
  });
  
  var MyUsersCarModel = Waterline.collection.extend({
  	identity: 'car',
  	//Collection definition here.
  });
  
  var config = {
    collections: {
    	user: MyUserModel, //replace OpenIDConnect user model. 
    	car: MyUsersCarModel //add new model
    }
  }
  
  orm.initialize(config, function(err, result) {
  	var options = {
  		alien: result.collections
  	}
  
  	var oidc = require('openid-connect').oidc(options);
  
  	app.get('/cars', oidc.use(['user', 'car']), function(req, res, next) {
  		...
  	});
  });
  

  Beware that if you replace an OpenIDConnect model, you won't be able to use populate with other OpenIDConnect models.

  If you replace user model, the new model should conform with OpenID Connect Standard Claims, in order to comply with the spec.

• orm

  You can replace the whole OpenIDConnect modelling instance with your own.

  Beware that you must implement at least all models and exept for user model, all attributes.

  If in your models, you set autoPK to false, they must have an id attribute that is primary key.

  Notice that you can get OpenIDConnect's default models with require('openid-connect').defaults().models.

  var orm = new modelling(options);
  
  var oidc = require('openid-connect').oidc({orm: orm});
  

API

• auth()

  returns a function to be placed as middleware in connect/express routing methods. For example:

  app.get('/authorization', oidc.auth());
  

  This is the authorization endpoint, as described in http://tools.ietf.org/html/rfc6749#section-3.1

• consent()

  returns a function to be placed as middleware in connect/express routing methods. For example:

  app.post('/consent', oidc.consent());
  

  This method saves the consent of the resource owner to a client request, or returns an access_denied error.

• token()

  returns a function to be placed as middleware in connect/express routing methods. For example:

  app.get('/token', oidc.token());
  

  This is the token endpoint, as described in http://tools.ietf.org/html/rfc6749#section-3.2

• check(scope, ...)

  returns a function to be placed as middleware in connect/express routing methods. For example:

  app.get('/api/user', oidc.check('openid', /profile|email/), function(req, res, next) { ... });
  

  If no arguments are given, checks if user is logged in.

  Arguments may be of type string or regexp.

  This function is used to check if user logged in, if an access_token is present, and if certain scopes where granted to it.

• removetokens()

  returns a function to be placed as middleware in connect/express routing methods. For example:

  app.get('/logout', oidc.removetokens(), function(req, res, next) { ... });
  

  This function removes all tokens that were issued to the user.

  access_token is required either as a parameter or as a Bearer token.

• userInfo()

  returns a function to be placed as middleware in connect/express routing methods. For example:

  app.get('/api/user', oidc.userInfo());
  

  This function returns the user info in a json object. Checks for scope and login are included.

• use([name])

  Same description as in modelling. If you defined alien models or your own orm you can call those models as well.

• getOrm()

  Retrieves current orm of instance.

Example

There is a complete example here.

Help!

Any suggestions, bug reports, bug fixes, pull requests, etc, are very wellcome (here).

Thanks for reading!.