From 24ea8299f2ebaec8002f30e3f76d4359a5e31b2e Mon Sep 17 00:00:00 2001 From: Saad Rhoulam Date: Mon, 14 Dec 2015 16:53:34 -0500 Subject: [PATCH 1/6] Add documentation for the required `name` instance attribute. --- README.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f655acd..ef6e317 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ subclassed when implementing concrete authentication strategies. Once implemented, such strategies can be used by applications that utilize Passport middleware for authentication. -#### Subclass Strategy +### Subclass Strategy Create a new `CustomStrategy` constructor which inherits from `Strategy`: @@ -36,7 +36,33 @@ function CustomStrategy(...) { util.inherits(CustomStrategy, Strategy); ``` -#### Implement Authentication +#### Set instance attributes + +Passport will identify mounted strategies by the instance's `name` attribute, +so be sure to set one in the constructor: + +```javascript +var util = require('util') + , Strategy = require('passport-strategy'); + +function CustomStrategy(...) { + Strategy.call(this); + + this.name = 'custom'; // set instance name +} + +util.inherits(CustomStrategy, Strategy); +``` + +Later, when a user calls `passport.authenticate` to acquire +the authentication middleware, the value of this `name` attribute +is what must be passed in as the first argument: + +```javascript +var authMiddleware = passport.authenticate('custom'); +``` + +### Implement Authentication Implement `autheticate()`, performing the necessary operations required by the authentication scheme or protocol being implemented. From 2488247857c4540681d876d933afc2e755088995 Mon Sep 17 00:00:00 2001 From: Saad Rhoulam Date: Mon, 14 Dec 2015 17:54:45 -0500 Subject: [PATCH 2/6] Document methods supplied by augmentation. --- README.md | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ef6e317..3f4e4bd 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ util.inherits(CustomStrategy, Strategy); #### Set instance attributes -Passport will identify mounted strategies by the instance's `name` attribute, +Passport will identify mounted strategies by the instance's `name` attribute, so be sure to set one in the constructor: ```javascript @@ -55,7 +55,7 @@ util.inherits(CustomStrategy, Strategy); ``` Later, when a user calls `passport.authenticate` to acquire -the authentication middleware, the value of this `name` attribute +the authentication middleware, the value of this `name` attribute is what must be passed in as the first argument: ```javascript @@ -64,7 +64,7 @@ var authMiddleware = passport.authenticate('custom'); ### Implement Authentication -Implement `autheticate()`, performing the necessary operations required by the +Implement the `authenticate` method, performing the necessary operations required by the authentication scheme or protocol being implemented. ```javascript @@ -73,6 +73,40 @@ CustomStrategy.prototype.authenticate = function(req, options) { } ``` +Upon mounting a strategy instance on passport, it will be augmented with several methods. +These methods are essential to writing a working `authenticate` method: + +* `error(err)`, indicates to passport that an error occurred in authenticating the request. +* `fail()`, indicates to passport that the request failed authentication. +* `success(userObj)`, indicates to passport that the request was successfully authenticated and provides the user object with which to associate the new authenticated session. + +Since the strategy instance is augmented with these methods, they can be accessed as +properties of `this` within the `authenticate` method. + +#### Examples + +```javascript +AlwaysSucceedStrategy.prototype.authenticate = function(req, options) { + this.success({ + username : 'bogus', + userId : NaN + }); +} +``` + +```javascript +AlwaysFailStrategy.prototype.authenticate = function(req, options) { + this.fail(); +} +``` + +```javascript +AlwaysErrorStrategy.prototype.authenticate = function(req, options) { + var err = new Error("Strategy: working as intended") + this.error(err); +} +``` + ## Related Modules - [chai-passport-strategy](https://github.com/jaredhanson/chai-passport-strategy) — helpers for testing strategies with the Chai assertion library From 11d6b67f72b7efcbc9bbe7246bab39bbab3a98c1 Mon Sep 17 00:00:00 2001 From: Saad Rhoulam Date: Mon, 14 Dec 2015 18:28:38 -0500 Subject: [PATCH 3/6] Add `authenticate` example --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 3f4e4bd..2deb475 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,19 @@ AlwaysErrorStrategy.prototype.authenticate = function(req, options) { } ``` +```javascript +CoinFlipStrategy.prototype.authenticate = function(req, options) { + if(Math.random() < .5) { + this.success({ + username : "George Washington", + userId : 25 + }); + } else { + this.fail(); + } +} +``` + ## Related Modules - [chai-passport-strategy](https://github.com/jaredhanson/chai-passport-strategy) — helpers for testing strategies with the Chai assertion library From 81be2cce20a36f61c71c6783f2dacc0c4d62be07 Mon Sep 17 00:00:00 2001 From: Saad Rhoulam Date: Mon, 14 Dec 2015 18:32:04 -0500 Subject: [PATCH 4/6] Clarify wording --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2deb475..81d6fbc 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,8 @@ util.inherits(CustomStrategy, Strategy); ``` Later, when a user calls `passport.authenticate` to acquire -the authentication middleware, the value of this `name` attribute -is what must be passed in as the first argument: +the authentication middleware that employs this strategy, the value +of this `name` attribute is what must be passed in as the first argument: ```javascript var authMiddleware = passport.authenticate('custom'); From 5e86b92fd267e73767ae735b3cfeaf38dbf9a090 Mon Sep 17 00:00:00 2001 From: Saad Rhoulam Date: Mon, 14 Dec 2015 18:33:52 -0500 Subject: [PATCH 5/6] Make number literal more explicit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 81d6fbc..b1191de 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ AlwaysErrorStrategy.prototype.authenticate = function(req, options) { ```javascript CoinFlipStrategy.prototype.authenticate = function(req, options) { - if(Math.random() < .5) { + if(Math.random() < 0.5) { this.success({ username : "George Washington", userId : 25 From 8557805853240dc4c4fe6a33f43daff81c74ccac Mon Sep 17 00:00:00 2001 From: Saad Rhoulam Date: Mon, 28 Dec 2015 20:54:57 -0500 Subject: [PATCH 6/6] Correct `fail` method signature and example usage. --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b1191de..7076624 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Upon mounting a strategy instance on passport, it will be augmented with several These methods are essential to writing a working `authenticate` method: * `error(err)`, indicates to passport that an error occurred in authenticating the request. -* `fail()`, indicates to passport that the request failed authentication. +* `fail(options, statusCode)`, indicates to passport that the request failed authentication. * `success(userObj)`, indicates to passport that the request was successfully authenticated and provides the user object with which to associate the new authenticated session. Since the strategy instance is augmented with these methods, they can be accessed as @@ -96,7 +96,9 @@ AlwaysSucceedStrategy.prototype.authenticate = function(req, options) { ```javascript AlwaysFailStrategy.prototype.authenticate = function(req, options) { - this.fail(); + this.fail({ + message : "working as intended" + }, 200); } ```