Release of third-party authentication tutorial.

Author: Fosco Marotto

cloud/main.js

@@ -0,0 +1,327 @@
+/**
+ * Login With GitHub
+ *
+ * An example web application implementing OAuth2 in Cloud Code
+ *
+ * There will be four routes:
+ * / - The main route will show a page with a Login with GitHub link
+ *       JavaScript will detect if it's logged in and navigate to /main
+ * /authorize - This url will start the OAuth process and redirect to GitHub
+ * /oauthCallback - Sent back from GitHub, this will validate the authorization
+ *                    and create/update a Parse User before using 'become' to
+ *                    set the user on the client side and redirecting to /main
+ * /main - The application queries and displays some of the users GitHub data
+ *
+ * @author Fosco Marotto (Facebook) <[email protected]>
+ */
+
+/**
+ * Load needed modules.
+ */
+var express = require('express');
+var querystring = require('querystring');
+var _ = require('underscore');
+var Buffer = require('buffer').Buffer;
+
+/**
+ * Create an express application instance
+ */
+var app = express();
+
+/**
+ * GitHub specific details, including application id and secret
+ */
+var githubClientId = 'your-github-client-id-here';
+var githubClientSecret = 'your-github-client-secret-here';
+
+var githubRedirectEndpoint = 'https://github.com/login/oauth/authorize?';
+var githubValidateEndpoint = 'https://github.com/login/oauth/access_token';
+var githubUserEndpoint = 'https://api.github.com/user';
+
+/**
+ * In the Data Browser, set the Class Permissions for these 2 classes to
+ *   disallow public access for Get/Find/Create/Update/Delete operations.
+ * Only the master key should be able to query or write to these classes.
+ */
+var TokenRequest = Parse.Object.extend("TokenRequest");
+var TokenStorage = Parse.Object.extend("TokenStorage");
+
+/**
+ * Create a Parse ACL which prohibits public access.  This will be used
+ *   in several places throughout the application, to explicitly protect
+ *   Parse User, TokenRequest, and TokenStorage objects.
+ */
+var restrictedAcl = new Parse.ACL();
+restrictedAcl.setPublicReadAccess(false);
+restrictedAcl.setPublicWriteAccess(false);
+
+/**
+ * Global app configuration section
+ */
+app.set('views', 'cloud/views');  // Specify the folder to find templates
+app.set('view engine', 'ejs');    // Set the template engine
+app.use(express.bodyParser());    // Middleware for reading request body
+
+/**
+ * Main route.
+ *
+ * When called, render the login.ejs view
+ */
+app.get('/', function(req, res) {
+  res.render('login', {});
+});
+
+/**
+ * Login with GitHub route.
+ *
+ * When called, generate a request token and redirect the browser to GitHub.
+ */
+app.get('/authorize', function(req, res) {
+
+  var tokenRequest = new TokenRequest();
+  // Secure the object against public access.
+  tokenRequest.setACL(restrictedAcl);
+  /**
+   * Save this request in a Parse Object for validation when GitHub responds
+   * Use the master key because this class is protected
+   */
+  tokenRequest.save(null, { useMasterKey: true }).then(function(obj) {
+    /**
+     * Redirect the browser to GitHub for authorization.
+     * This uses the objectId of the new TokenRequest as the 'state'
+     *   variable in the GitHub redirect.
+     */
+    res.redirect(
+      githubRedirectEndpoint + querystring.stringify({
+        client_id: githubClientId,
+        state: obj.id
+      })
+    );
+  }, function(error) {
+    // If there's an error storing the request, render the error page.
+    res.render('error', { errorMessage: 'Failed to save auth request.'});
+  });
+
+});
+
+/**
+ * OAuth Callback route.
+ *
+ * This is intended to be accessed via redirect from GitHub.  The request
+ *   will be validated against a previously stored TokenRequest and against
+ *   another GitHub endpoint, and if valid, a User will be created and/or
+ *   updated with details from GitHub.  A page will be rendered which will
+ *   'become' the user on the client-side and redirect to the /main page.
+ */
+app.get('/oauthCallback', function(req, res) {
+  var data = req.query;
+  var token;
+  /**
+   * Validate that code and state have been passed in as query parameters.
+   * Render an error page if this is invalid.
+   */
+  if (!(data && data.code && data.state)) {
+    res.render('error', { errorMessage: 'Invalid auth response received.'});
+    return;
+  }
+  var query = new Parse.Query(TokenRequest);
+  /**
+   * Check if the provided state object exists as a TokenRequest
+   * Use the master key as operations on TokenRequest are protected
+   */
+  Parse.Cloud.useMasterKey();
+  Parse.Promise.as().then(function() {
+    return query.get(data.state);
+  }).then(function(obj) {
+    // Destroy the TokenRequest before continuing.
+    return obj.destroy();
+  }).then(function() {
+    // Validate & Exchange the code parameter for an access token from GitHub
+    return getGitHubAccessToken(data.code);
+  }).then(function(access) {
+    /**
+     * Process the response from GitHub, return either the getGitHubUserDetails
+     *   promise, or reject the promise.
+     */
+    var githubData = access.data;
+    if (githubData && githubData.access_token && githubData.token_type) {
+      token = githubData.access_token;
+      return getGitHubUserDetails(token);
+    } else {
+      return Parse.Promise.error("Invalid access request.");
+    }
+  }).then(function(userDataResponse) {
+    /**
+     * Process the users GitHub details, return either the upsertGitHubUser
+     *   promise, or reject the promise.
+     */
+    var userData = userDataResponse.data;
+    if (userData && userData.login && userData.id) {
+      return upsertGitHubUser(token, userData);
+    } else {
+      return Parse.Promise.error("Unable to parse GitHub data");
+    }
+  }).then(function(user) {
+    /**
+     * Render a page which sets the current user on the client-side and then
+     *   redirects to /main
+     */
+    res.render('store_auth', { sessionToken: user.getSessionToken() });
+  }, function(error) {
+    /**
+     * If the error is an object error (e.g. from a Parse function) convert it
+     *   to a string for display to the user.
+     */
+    if (error && error.code && error.error) {
+      error = error.code + ' ' + error.error;
+    }
+    res.render('error', { errorMessage: JSON.stringify(error) });
+  });
+
+});
+
+/**
+ * Logged in route.
+ *
+ * JavaScript will validate login and call a Cloud function to get the users
+ *   GitHub details using the stored access token.
+ */
+app.get('/main', function(req, res) {
+  res.render('main', {});
+});
+
+/**
+ * Attach the express app to Cloud Code to process the inbound request.
+ */
+app.listen();
+
+/**
+ * Cloud function which will load a user's accessToken from TokenStorage and
+ * request their details from GitHub for display on the client side.
+ */
+Parse.Cloud.define('getGitHubData', function(request, response) {
+  if (!request.user) {
+    return response.error('Must be logged in.');
+  }
+  var query = new Parse.Query(TokenStorage);
+  query.equalTo('user', request.user);
+  query.ascending('createdAt');
+  Parse.Promise.as().then(function() {
+    return query.first({ useMasterKey: true });
+  }).then(function(tokenData) {
+    if (!tokenData) {
+      return Parse.Promise.error('No GitHub data found.');
+    }
+    return getGitHubUserDetails(tokenData.get('accessToken'));
+  }).then(function(userDataResponse) {
+    var userData = userDataResponse.data;
+    response.success(userData);
+  }, function(error) {
+    response.error(error);
+  });
+});
+
+/**
+ * This function is called when GitHub redirects the user back after
+ *   authorization.  It calls back to GitHub to validate and exchange the code
+ *   for an access token.
+ */
+var getGitHubAccessToken = function(code) {
+  var body = querystring.stringify({
+    client_id: githubClientId,
+    client_secret: githubClientSecret,
+    code: code
+  });
+  return Parse.Cloud.httpRequest({
+    method: 'POST',
+    url: githubValidateEndpoint,
+    headers: {
+      'Accept': 'application/json',
+      'User-Agent': 'Parse.com Cloud Code'
+    },
+    body: body
+  });
+}
+
+/**
+ * This function calls the githubUserEndpoint to get the user details for the
+ * provided access token, returning the promise from the httpRequest.
+ */
+var getGitHubUserDetails = function(accessToken) {
+  return Parse.Cloud.httpRequest({
+    method: 'GET',
+    url: githubUserEndpoint,
+    params: { access_token: accessToken },
+    headers: {
+      'User-Agent': 'Parse.com Cloud Code'
+    }
+  });
+}
+
+/**
+ * This function checks to see if this GitHub user has logged in before.
+ * If the user is found, update the accessToken (if necessary) and return
+ *   the users session token.  If not found, return the newGitHubUser promise.
+ */
+var upsertGitHubUser = function(accessToken, githubData) {
+  var query = new Parse.Query(TokenStorage);
+  query.equalTo('githubId', githubData.id);
+  query.ascending('createdAt');
+  // Check if this githubId has previously logged in, using the master key
+  return query.first({ useMasterKey: true }).then(function(tokenData) {
+    // If not, create a new user.
+    if (!tokenData) {
+      return newGitHubUser(accessToken, githubData);
+    }
+    // If found, fetch the user.
+    var user = tokenData.get('user');
+    return user.fetch({ useMasterKey: true }).then(function(user) {
+      // Update the accessToken if it is different.
+      if (accessToken !== tokenData.get('accessToken')) {
+        tokenData.set('accessToken', accessToken);
+      }
+      /**
+       * This save will not use an API request if the token was not changed.
+       * e.g. when a new user is created and upsert is called again.
+       */
+      return tokenData.save(null, { useMasterKey: true });
+    }).then(function(obj) {
+      // Return the user object.
+      return Parse.Promise.as(user);
+    });
+  });
+}
+
+/**
+ * This function creates a Parse User with a random login and password, and
+ *   associates it with an object in the TokenStorage class.
+ * Once completed, this will return upsertGitHubUser.  This is done to protect
+ *   against a race condition:  In the rare event where 2 new users are created
+ *   at the same time, only the first one will actually get used.
+ */
+var newGitHubUser = function(accessToken, githubData) {
+  var user = new Parse.User();
+  // Generate a random username and password.
+  var username = new Buffer(24);
+  var password = new Buffer(24);
+  _.times(24, function(i) {
+    username.set(i, _.random(0, 255));
+    password.set(i, _.random(0, 255));
+  });
+  user.set("username", username.toString('base64'));
+  user.set("password", password.toString('base64'));
+  // Sign up the new User
+  return user.signUp().then(function(user) {
+    // create a new TokenStorage object to store the user+GitHub association.
+    var ts = new TokenStorage();
+    ts.set('githubId', githubData.id);
+    ts.set('githubLogin', githubData.login);
+    ts.set('accessToken', accessToken);
+    ts.set('user', user);
+    ts.setACL(restrictedAcl);
+    // Use the master key because TokenStorage objects should be protected.
+    return ts.save(null, { useMasterKey: true });
+  }).then(function(tokenStorage) {
+    return upsertGitHubUser(accessToken, githubData);
+  });
+}

cloud/views/error.ejs

@@ -0,0 +1,4 @@
+<% include head %>
+<p>An error has occurred: <%= errorMessage %></p>
+<p><a href="/authorize">Login with GitHub</a></p>
+<% include foot %>

cloud/views/foot.ejs

@@ -0,0 +1,3 @@
+</div>
+</body>
+</html>

cloud/views/head.ejs

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width" />
+  
+  <title>GitHub Authentication Example</title>
+
+  <script src="//code.jquery.com/jquery-2.0.3.min.js"></script>
+  <script src="//www.parsecdn.com/js/parse-1.2.13.min.js"></script>
+  <script src="/js/base-app.js"></script>
+  <script type="text/javascript">
+  Parse.initialize(
+    "your-parse-application-id-here",
+    "your-parse-javascript-key-here"
+  );
+<body>
+  <div class="container">
+    <h1 class="intro">GitHub Authentication Example</h1>

cloud/views/login.ejs

@@ -0,0 +1,8 @@
+<% include head %>
+<p><a href="/authorize">Login with GitHub</a></p>
+<script type="text/javascript">
+if (Parse.User.current()) {
+	window.location.href='/main';
+}
+</script>
+<% include foot %>