passport-oauth2-password-grant
Version:
OAuth 2.0 password grant authentication strategy for Passport.
102 lines (74 loc) • 3.73 kB
Markdown
# passport-oauth2-password-grant
[](https://travis-ci.org/leftmostcat/passport-oauth2-password-grant)
[](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)