# passport-oauth2-password-grant

[![Build](https://travis-ci.org/leftmostcat/passport-oauth2-password-grant.svg?branch=master)](https://travis-ci.org/leftmostcat/passport-oauth2-password-grant)
[![Quality](https://codeclimate.com/github/leftmostcat/passport-oauth2-password-grant/badges/gpa.svg)](https://codeclimate.com/github/leftmostcat/passport-oauth2-password-grant)

This module allows authentication through OAuth2 on servers which permit the
'password' grant type. It makes use of the [Passport](http://passportjs.org/)
authentication framework to allow easy use by any
[Express](http://expressjs.com/)-based application. Like the module on which it
is based, [passport-oauth2](https://github.com/jaredhanson/passport-oauth2), its
functionality is designed to be generic enough for use with any OAuth2-compliant
implementation which accepts password grants and can be subclassed for
provider-specific functionality, including user profile.

## Installation

	$ npm install passport-oauth2-password-grant

## Usage

#### Generic Configuration

Like passport-oauth2, the token grant endpoint and OAuth2 client ID are
passed as options to the strategy constructor. It also requires a `verify()`
callback, which is called when authentication has succeeded and must call the
`done()` callback when it has finished. `verify()` accepts one of the following
prototypes:

	function(accessToken, refreshToken, profile, done);
	function(accessToken, refreshToken, requestParams, profile, done);

The following demonstrates how to construct and use a PasswordGrantStrategy
object:

	var PasswordGrantStrategy = require('passport-oauth2-password-grant');

	passport.use(new PasswordGrantStrategy({
		tokenURL: 'https://www.example.com/oauth2/token',
		clientID: EXAMPLE_CLIENT_ID
	},
	function(accessToken, refreshToken, profile, done) {
		done(null, profile);
	});

Additionally, the `passReqToCallback` and `skipUserProfile` options may be used,
which function identically to the same options for passport-oauth2.

#### Authentication

This is accomplished through the use of `passport.authenticate()` with the
`password-grant` strategy. The username and password to be used for
authentication are to be passed to `passport.authenticate()` as the `username`
and `password` options, respectively. This may be done as in the following
example:

	function authenticate() {
		return function(req, res, next) {
			var username = req.body.username;
			var password = req.body.password;

			passport.authenticate('password-grant', {
				username: username,
				password: password
			})(req, res, next);
		};
	}

	app.get('/auth/handler', authenticate(), function(req, res) {
		res.redirect('/');
	});

#### User Profile Retrieval

In order to retrieve profile information for the authenticating user, a subclass
of PasswordGrantStrategy must be provided which overrides the
`PasswordGrantStrategy.userProfile()` function with prototype
`userProfile(accessToken, done)`. `done()` should be called as
`done(err, profile)`, and `profile` is then passed to the `verify()` callback
provided during configuration.

## Related Modules

* [passport-oauth2](https://github.com/jaredhanson/passport-oauth2)
  – OAuth 2.0 authentication strategy, upon which this module is based
* [passport-http-bearer](https://github.com/jaredhanson/passport-http-bearer)
  – Bearer token authentication strategy for APIs

## Testing

	$ npm install
	$ npm test

## Credits

- [Sean Burke](https://github.com/leftmostcat/) — Module author
- [Jared Hanson](https://github.com/jaredhanson/) – Author of passport-oauth2,
  from which this module was adapted and upon which this module relies

## License

[The MIT License](http://opensource.org/licenses/MIT)