Added support for scopes

Readme.md

@@ -124,15 +124,36 @@ Note: see https://github.com/thomseddon/node-oauth2-server/tree/master/examples/
  - *boolean* **allowed**
      - Indicates whether the grantType is allowed for this clientId
 
-#### saveAccessToken (accessToken, clientId, expires, user, callback)
+#### saveAccessToken (accessToken, clientId, expires, user, scope, callback)
 - *string* **accessToken**
 - *string* **clientId**
 - *date* **expires**
 - *object* **user**
+- *string* **scope**
 - *function* **callback (error)**
  - *mixed* **error**
      - Truthy to indicate an error
 
+#### authoriseScope (accessToken, scope, callback)
+- *string* **accessToken**
+- *mixed* **scope**
+- *function* **callback (error, invalid)**
+ - *mixed* **error**
+     - Truthy to indicate an error
+ - *boolean|string* **invalid**
+     - Falsey to indicate token possesses required scope; truthy (boolean or string) as invalid scope error message
+
+### validateScope (scope, client, user, callback)
+- *string* **scope**
+- *object* **client**
+- *object* **user**
+- *function* **callback (error, validScope, invalid)**
+ - *mixed* **error**
+     - Truthy to indicate an error
+ - *mixed* **validScope**
+     - Validated/sanitized scope string
+ - *boolean|string* **invalid**
+     - Falsey to indicate solicited scope was granted; truthy (boolean or string) as invalid scope error message
 
 ### Required for `authorization_code` grant type
 
@@ -151,12 +172,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
@@ -178,11 +200,12 @@ Note: see https://github.com/thomseddon/node-oauth2-server/tree/master/examples/
 
 ### Required for `refresh_token` grant type
 
-#### saveRefreshToken (refreshToken, clientId, expires, user, callback)
+#### saveRefreshToken (refreshToken, clientId, expires, user, scope, callback)
 - *string* **refreshToken**
 - *string* **clientId**
 - *date* **expires**
 - *object* **user**
+- *string* **scope**
 - *function* **callback (error)**
  - *mixed* **error**
      - Truthy to indicate an error
@@ -275,21 +298,21 @@ 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)
+ - saveAccessToken (accessToken, clientId, expires, user, scope, callback)
  - saveRefreshToken (refreshToken, clientId, expires, user, callback) **(if using)**
 
 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 +327,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-delimited scope string
       });
       done();
     });
@@ -48,7 +49,7 @@ model.getClient = function (clientId, clientSecret, callback) {
   pg.connect(connString, function (err, client, done) {
     if (err) return callback(err);
 
-    client.query('SELECT client_id, client_secret, redirect_uri FROM oauth_clients WHERE ' +
+    client.query('SELECT client_id, client_secret, redirect_uri, valid_scopes, default_scope FROM oauth_clients WHERE ' +
       'client_id = $1', [clientId], function (err, result) {
       if (err || !result.rowCount) return callback(err);
 
@@ -59,7 +60,9 @@ model.getClient = function (clientId, clientSecret, callback) {
       // This object will be exposed in req.oauth.client
       callback(null, {
         clientId: client.client_id,
-        clientSecret: client.client_secret
+        clientSecret: client.client_secret,
+        validScopes: client.valid_scopes,
+        defaultScope: client.default_scope
       });
       done();
     });
@@ -69,12 +72,11 @@ 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);
+    client.query('SELECT refresh_token, scope, client_id, expires, user_id FROM oauth_refresh_tokens ' +
+      'WHERE refresh_token = $1', [bearerToken], function(err, result) {
+	  callback(err, result.rowCount ? result.rows[0] : false);
       done();
-    });
+	});
   });
 };
 
@@ -89,37 +91,70 @@ model.grantTypeAllowed = function (clientId, grantType, callback) {
   callback(false, true);
 };
 
-model.saveAccessToken = function (accessToken, clientId, expires, userId, callback) {
+model.saveAccessToken = function (accessToken, clientId, expires, userId, scope, callback) {
   pg.connect(connString, function (err, client, done) {
     if (err) return callback(err);
-    client.query('INSERT INTO oauth_access_tokens(access_token, client_id, user_id, expires) ' +
-        'VALUES ($1, $2, $3, $4)', [accessToken, clientId, userId, expires],
+    client.query('INSERT INTO oauth_access_tokens(access_token, client_id, user_id, scope, expires) ' +
+        'VALUES ($1, $2, $3, $4, $5)', [accessToken, clientId, userId, scope, expires],
         function (err, result) {
       callback(err);
       done();
     });
   });
 };
 
-model.saveRefreshToken = function (refreshToken, clientId, expires, userId, callback) {
+model.saveRefreshToken = function (refreshToken, clientId, expires, userId, scope, callback) {
   pg.connect(connString, function (err, client, done) {
     if (err) return callback(err);
-    client.query('INSERT INTO oauth_refresh_tokens(refresh_token, client_id, user_id, ' +
-        'expires) VALUES ($1, $2, $3, $4)', [refreshToken, clientId, userId, expires],
+
+    client.query('INSERT INTO oauth_refresh_tokens(refresh_token, client_id, ' +
+        'user_id, scope, expires) VALUES ($1, $2, $3, $4, $5)',
+        [refreshToken, clientId, userId, scope, expires],
         function (err, result) {
-      callback(err);
-      done();
-    });
+          callback(err);
+          done();
+        });
   });
 };
 
+model.authoriseScope = function (accessToken, scope, callback) {
+  var hasScope = accessToken.scope.indexOf(scope) !== -1;
+
+  // You may pass anything from a simple string, as this example illustrates,
+  // to representations including scopes and subscopes such as
+  // { "account": [ "edit" ] }
+  return callback(false, hasScope ? false : 'Missing scope: ' + scope);
+};
+
+model.validateScope = function (scope, client, user, callback) {
+  // Sanitize the requested scope string against a client-specific set of valid scope keys
+  // and the scopes the user actually is allowed to use (if any).
+  // You could choose to strip invalid keys, or return an error message
+  var requestedScope = scope || client.defaultScope || '';
+  var requestedScopes = requestedScope.split(' ');
+  var validScopes = client.validScopes.split(' ');
+  var isValid = !requestedScope || requestedScopes.every(function(key) {
+        return validScopes.indexOf(key) !== -1;
+      });
+
+  if (user.allowedScopes) {
+    var userAllowedScopes = user.allowedScopes.split(' ');
+    var userScopes = validScopes.filter(function(key) {
+      return (!scope || requestedScopes.indexOf(key) !== -1) && userAllowedScopes.indexOf(key) !== -1;
+    });
+    requestedScope = userScopes.join(' ');
+  }
+
+  return callback(false, requestedScope, isValid ? false : 'Invalid scope request');
+};
+
 /*
  * Required to support password grant type
  */
 model.getUser = function (username, password, callback) {
   pg.connect(connString, function (err, client, done) {
     if (err) return callback(err);
-    client.query('SELECT id FROM users WHERE username = $1 AND password = $2', [username,
+    client.query('SELECT id, allowed_scopes AS allowedScopes FROM users WHERE username = $1 AND password = $2', [username,
         password], function (err, result) {
       callback(err, result.rowCount ? result.rows[0] : false);
       done();

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
@@ -47,7 +48,9 @@ CREATE TABLE oauth_access_tokens (
 CREATE TABLE oauth_clients (
     client_id text NOT NULL,
     client_secret text NOT NULL,
-    redirect_uri text NOT NULL
+    redirect_uri text NOT NULL,
+    valid_scopes text NULL,
+    default_scope text NULL
 );
 
 
@@ -57,6 +60,7 @@ CREATE TABLE oauth_clients (
 
 CREATE TABLE oauth_refresh_tokens (
     refresh_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
@@ -70,7 +74,8 @@ CREATE TABLE oauth_refresh_tokens (
 CREATE TABLE users (
     id uuid NOT NULL,
     username text NOT NULL,
-    password text NOT NULL
+    password text NOT NULL,
+    allowed_scopes text 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

@@ -26,21 +26,26 @@ module.exports = Authorise;
  */
 var fns = [
   getBearerToken,
-  checkToken
+  checkToken,
+  checkScope
 ];
 
 /**
  * Authorise
  *
- * @param {Object}   config Instance of OAuth object
+ * @param {Object}   config  Instance of OAuth object
  * @param {Object}   req
  * @param {Object}   res
+ * @param {Object}   options
  * @param {Function} next
  */
-function Authorise (config, req, next) {
+function Authorise (config, req, options, next) {
+  options = options || {};
+
   this.config = config;
   this.model = config.model;
   this.req = req;
+  this.options = options;
 
   runner(fns, this, next);
 }
@@ -128,3 +133,22 @@ function checkToken (done) {
     done();
   });
 }
+
+/**
+ * Check scope
+ *
+ * @param {Function} done
+ * @this  OAuth
+ */
+
+function checkScope (done) {
+  if (!this.options.scope) return done();
+
+  this.model.authoriseScope(this.req.oauth.bearerToken, this.options.scope,
+      function (err, invalid) {
+    if (err) return done(error('server_error', false, err));
+    if (invalid) return done(error('invalid_scope', invalid));
+
+    done();
+  });
+}

lib/error.js

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