Added support for scopes

Readme.md

@@ -133,6 +133,20 @@ Note: see https://github.com/thomseddon/node-oauth2-server/tree/master/examples/
  - *mixed* **error**
      - Truthy to indicate an error
 
+#### checkScope (scope, accessToken, callback)
+- *mixed* **scope**
+  - String, array, or object indicating which scope(s) a token must possess
+- *string* **accessToken**
+- *function* **callback (error)**
+ - *mixed* **error**
+     - Truthy to indicate an error
+
+#### saveScope (scope, accessToken, callback)
+- *string* **scope**
+- *object* **accessToken**
+- *function* **callback (error)**
+ - *mixed* **error**
+     - Truthy to indicate an error
 
 ### Required for `authorization_code` grant type
 
@@ -151,12 +165,13 @@ Note: see https://github.com/thomseddon/node-oauth2-server/tree/master/examples/
          - *string|number* **userId**
              - The userId
 
-#### saveAuthCode (authCode, clientId, expires, user, callback)
+#### saveAuthCode (authCode, clientId, expires, user, scope, callback)
 - *string* **authCode**
 - *string* **clientId**
 - *date* **expires**
 - *mixed* **user**
    - Whatever was passed as `user` to the codeGrant function (see example)
+- *string* **scope**
 - *function* **callback (error)**
  - *mixed* **error**
      - Truthy to indicate an error
@@ -275,22 +290,23 @@ First you must insert client id/secret and user into storage. This is out of the
 
 To obtain a token you should POST to `/oauth/token`. You should include your client credentials in
 the Authorization header ("Basic " + client_id:client_secret base64'd), and then grant_type ("password"),
-username and password in the request body, for example:
+username, password, and optionally a scope in the request body, for example:
 
 ```
 POST /oauth/token HTTP/1.1
 Host: server.example.com
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
 Content-Type: application/x-www-form-urlencoded
 
-grant_type=password&username=johndoe&password=A3ddj3w
+grant_type=password&username=johndoe&password=A3ddj3w&scope=readonly
 ```
 This will then call the following on your model (in this order):
  - getClient (clientId, clientSecret, callback)
  - grantTypeAllowed (clientId, grantType, callback)
  - getUser (username, password, callback)
  - saveAccessToken (accessToken, clientId, expires, user, callback)
  - saveRefreshToken (refreshToken, clientId, expires, user, callback) **(if using)**
+ - saveScope (scope, accessToken, callback)
 
 Provided there weren't any errors, this will return the following (excluding the `refresh_token` if you've not enabled the refresh_token grant type):
 
@@ -304,7 +320,8 @@ Pragma: no-cache
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"bearer",
   "expires_in":3600,
-  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
+  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
+  "scope": "readonly"
 }
 ```
 

examples/postgresql/index.js

@@ -75,6 +75,12 @@ app.get('/secret', app.oauth.authorise(), function (req, res) {
   res.send('Secret area');
 });
 
+app.get('/scoped', app.oauth.authorise(), app.oauth.scope('demo'),
+    function (req, res) {
+  // Will require that the access_token possesses the 'demo' scope key
+  res.send('Secret and scope-controlled area');
+});
+
 app.get('/public', function (req, res) {
   // Does not require an access_token
   res.send('Public area');

examples/postgresql/model.js

@@ -25,7 +25,7 @@ var pg = require('pg'),
 model.getAccessToken = function (bearerToken, callback) {
   pg.connect(connString, function (err, client, done) {
     if (err) return callback(err);
-    client.query('SELECT access_token, client_id, expires, user_id FROM oauth_access_tokens ' +
+    client.query('SELECT access_token, scope, client_id, expires, user_id FROM oauth_access_tokens ' +
         'WHERE access_token = $1', [bearerToken], function (err, result) {
       if (err || !result.rowCount) return callback(err);
       // This object will be exposed in req.oauth.token
@@ -37,7 +37,8 @@ model.getAccessToken = function (bearerToken, callback) {
         accessToken: token.access_token,
         clientId: token.client_id,
         expires: token.expires,
-        userId: token.userId
+        userId: token.userId,
+		scope: token.scope.split(' ') // Assumes a flat, space-separated scope string 
       });
       done();
     });
@@ -69,12 +70,14 @@ model.getClient = function (clientId, clientSecret, callback) {
 model.getRefreshToken = function (bearerToken, callback) {
   pg.connect(connString, function (err, client, done) {
     if (err) return callback(err);
-    client.query('SELECT refresh_token, client_id, expires, user_id FROM oauth_refresh_tokens ' +
-        'WHERE refresh_token = $1', [bearerToken], function (err, result) {
-      // The returned user_id will be exposed in req.user.id
-      callback(err, result.rowCount ? result.rows[0] : false);
-      done();
-    });
+	// Note: To avoid replicating the scope string in both token tables, the old
+	// access token's scope string must be retrieved and passed along from here.
+	client.query('SELECT rt.refresh_token, rt.client_id, rt.expires, rt.user_id, at.scope FROM ' +
+        'oauth_refresh_tokens AS rt, oauth_access_tokens AS at WHERE rt.user_id = ' +
+		'at.user_id AND rt.client_id = at.client_id AND rt.refresh_token = $',
+		[bearerToken], function (err, result) {
+	  callback(err, result.rowCount ? result.rows[0] : false);
+	});
   });
 };
 
@@ -113,6 +116,34 @@ model.saveRefreshToken = function (refreshToken, clientId, expires, userId, call
   });
 };
 
+model.saveScope = function (scope, accessToken, callback) {
+  // Here you will want to validate that what the client is soliciting
+  // makes sense. You might then proceed by storing the validated scope.
+  // In this example, the scope is simply stored as a string in the
+  // oauth_access_tokens table, but you could also handle them as entries
+  // in a connection table.
+  var acceptedScope = scope;
+
+  pg.connect(connString, function (err, client, done) {
+    if (err) return callback(err);
+	client.query('UPDATE oauth_access_tokens SET scope=$1 WHERE access_token = $2',
+        [acceptedScope, accessToken], function (err, result) {
+     callback(err, acceptedScope); 
+	 done();
+  });
+};
+
+model.checkScope = function (accessToken, requiredScope, callback)
+  // requiredScope is set through the scope middleware.
+  // You may pass anything from a simple string, as this example illustrates,
+  // to representations including scopes and subscopes such as
+  // { "account": [ "edit" ] }
+  if(accessToken.scope.indexOf(requiredScope) === -1) {
+    return callback('Required scope: ' + requiredScope);
+  }
+  callback();
+};
+
 /*
  * Required to support password grant type
  */

examples/postgresql/schema.sql

@@ -34,6 +34,7 @@ SET default_with_oids = false;
 
 CREATE TABLE oauth_access_tokens (
     access_token text NOT NULL,
+    scope text NOT NULL,
     client_id text NOT NULL,
     user_id uuid NOT NULL,
     expires timestamp without time zone NOT NULL

lib/authCodeGrant.js

@@ -137,7 +137,7 @@ function checkClient (done) {
  */
 function checkUserApproved (done) {
   var self = this;
-  this.check(this.req, function (err, allowed, user) {
+  this.check(this.req, function (err, allowed, user, scope) {
     if (err) return done(error('server_error', false, err));
 
     if (!allowed) {
@@ -146,6 +146,8 @@ function checkUserApproved (done) {
     }
 
     self.user = user;
+    self.scope = scope;
+
     done();
   });
 }
@@ -175,7 +177,7 @@ function saveAuthCode (done) {
   expires.setSeconds(expires.getSeconds() + this.config.authCodeLifetime);
 
   this.model.saveAuthCode(this.authCode, this.client.clientId, expires,
-      this.user, function (err) {
+      this.user, this.scope, function (err) {
     if (err) return done(error('server_error', false, err));
     done();
   });

lib/authorise.js

@@ -32,15 +32,17 @@ var fns = [
 /**
  * Authorise
  *
- * @param {Object}   config Instance of OAuth object
+ * @param {Object}   config  Instance of OAuth object
  * @param {Object}   req
  * @param {Object}   res
+ * @param {Object}   options May indicate required scope(s)
  * @param {Function} next
  */
-function Authorise (config, req, next) {
+function Authorise (config, req, scope, next) {
   this.config = config;
   this.model = config.model;
   this.req = req;
+  this.scope = scope;
 
   runner(fns, this, next);
 }
@@ -125,6 +127,13 @@ function checkToken (done) {
     self.req.oauth = { bearerToken: token };
     self.req.user = token.user ? token.user : { id: token.userId };
 
-    done();
+    if(self.scope) {
+	  self.model.checkScope(self.scope, token, function (err) {
+	    if (err) { return done(new error('invalid_scope', err)); }
+	    done();
+	  });
+    } else {
+      done();
+    }
   });
 }

lib/error.js

@@ -46,6 +46,7 @@ function OAuth2Error (error, description, err) {
         'WWW-Authenticate': 'Basic realm="Service"'
       };
       /* falls through */
+	case 'invalid_scope':
     case 'invalid_grant':
     case 'invalid_request':
       this.code = 400;

lib/grant.js

@@ -36,6 +36,7 @@ var fns = [
   saveAccessToken,
   generateRefreshToken,
   saveRefreshToken,
+  saveScope,
   sendResponse
 ];
 
@@ -193,6 +194,7 @@ function useAuthCodeGrant (done) {
     }
 
     self.user = authCode.user || { id: authCode.userId };
+    self.scope = authCode.scope || '';
     if (!self.user.id) {
       return done(error('server_error', false,
         'No user/userId parameter returned from getauthCode'));
@@ -257,6 +259,7 @@ function useRefreshTokenGrant (done) {
     }
 
     self.user = refreshToken.user || { id: refreshToken.userId };
+    self.scope = refreshToken.scope || '';
 
     if (self.model.revokeRefreshToken) {
       return self.model.revokeRefreshToken(token, function (err) {
@@ -449,14 +452,32 @@ function saveRefreshToken (done) {
 }
 
 /**
- * Create an access token and save it with the model
+ * Pass the scope string to the model for saving
+ *
+ * @param  {Function} done
+ * @this   OAuth
+ */
+function saveScope (done) {
+  var scope = this.scope || this.req.body.scope;
+
+  var self = this;
+  this.model.saveScope(scope, self.accessToken, function (err, acceptedScope) {
+    if (err) return done(error('server_error', false, err));
+	self.scope = acceptedScope;
+    done();
+  });
+}
+
+/**
+ * Sends the resulting token(s) and related information to the client
  *
  * @param  {Function} done
  * @this   OAuth
  */
 function sendResponse (done) {
   var response = {
     token_type: 'bearer',
+    scope: this.scope,
     access_token: this.accessToken
   };
 

lib/oauth2server.js

@@ -17,7 +17,8 @@
 var error = require('./error'),
   AuthCodeGrant = require('./authCodeGrant'),
   Authorise = require('./authorise'),
-  Grant = require('./grant');
+  Grant = require('./grant'),
+  Scope = require('./scope');
 
 module.exports = OAuth2Server;
 
@@ -63,11 +64,11 @@ function OAuth2Server (config) {
  *
  * @return {Function} middleware
  */
-OAuth2Server.prototype.authorise = function () {
+OAuth2Server.prototype.authorise = function (scope) {
   var self = this;
 
   return function (req, res, next) {
-    return new Authorise(self, req, next);
+    return new Authorise(self, req, scope, next);
   };
 };
 
@@ -104,6 +105,24 @@ OAuth2Server.prototype.authCodeGrant = function (check) {
   };
 };
 
+/**
+ * Scope Check Middleware
+ *
+ * Returns middleware that allows the specification of required
+ * scope(s) for routers and/or routes, which is validated by the model.
+ *
+ * @param  {Mixed}    requiredScope String or list of scope keys
+ *                                  required to access the route.
+ * @return {Function} 
+ */
+OAuth2Server.prototype.scope = function(requiredScope) {
+  var self = this;
+
+  return function(req, res, next) {
+    return new Scope(self, req, next, requiredScope);
+  };
+};
+
 /**
  * OAuth Error Middleware
  *