Doc cleanup

Author: brandwe

README.md

@@ -1,53 +1,22 @@
 #Windows Azure Active Directory Sample REST API Service for Node.js using MongoDB and Restify
 
-This Node.js server will give you with a quick and easy way to set up a REST API Service that's integrated with Windows Azure Active Directory for API protection using the OAuth2 protocol using bearer tokens. The sample server included in the download are designed to run on any platform.
+This Node.js server will give you with a quick and easy way to set up a REST API Service that's integrated with Azure Active Directory for API protection using the OAuth2 protocol with bearer tokens. The sample server included in the download are designed to run on any platform.
 
 This REST API server is built using Restify and MongoDB with the following features:
 
 * A node.js server running an REST API interface with JSON using MongoDB as persistent storage
 * REST APIs leveraging OAuth2 API protection for endpoints using Windows Azure Active Directory
 
-[Refer to our Wiki](https://github.com/AzureADSamples/WebAPI-Nodejs/wiki) for detailed walkthroughs on how to use this server.
-
 We've released all of the source code for this example in GitHub under an Apache 2.0 license, so feel free to clone (or even better, fork!) and provide feedback on the forums.
 
-## How to Use The Service
-
-This is a simple TODO Server that takes JSON requests through REST and responds with the appropriate JSON objects.
-
-#### To use this without Authentication (for testing the endpoints without Authentication)
-
-	$ node server.js
-
-	$ curl -isS http://127.0.0.1:8888 | json
-	HTTP/1.1 200 OK
-	Connection: close
-	Content-Type: application/x-www-form-urlencoded
-	Content-Length: 145
-	Date: Wed, 29 Jan 2014 03:41:24 GMT
-
-	[
-  	"GET     /",
-  	"POST    /tasks/:name/:task",
-		"POST		 /tasks (for JSON body)",
-  	"GET     /tasks",
-  	"DELETE  /tasks",
-  	"PUT     /tasks/:name",
-  	"GET     /tasks/:name",
-  	"DELETE  /tasks/:task"
-	]
-
-#### To invoke with OAuth2 Authentication (for use with Windows Azure AD)
-
-	$ node server.js -m oauth2
 
 ## Quick Start
 
 Getting started with the sample is easy. It is configured to run out of the box with minimal setup.
 
 ### Step 1: Register a Windows Azure AD Tenant
 
-To use this sample you will need a Windows Azure Active Directory Tenant. If you're not sure what a tenant is or how you would get one, read [What is a Windows Azure AD tenant](http://technet.microsoft.com/library/jj573650.aspx)? or [Sign up for Windows Azure as an organization](http://azure.microsoft.com/en-us/documentation/articles/sign-up-organization/). These docs should get you started on your way to using Windows Azure AD.
+To use this sample you will need a Windows Azure Active Directory Tenant. If you're not sure what a tenant is or how you would get one, read [What is an Azure AD tenant](http://technet.microsoft.com/library/jj573650.aspx)? or [Sign up for Azure as an organization](http://azure.microsoft.com/en-us/documentation/articles/sign-up-organization/). These docs should get you started on your way to using Windows Azure AD.
 
 ### Step 2: Register your Web API with your Windows Azure AD Tenant
 
@@ -73,7 +42,7 @@ Next, clone the sample repo and install the NPM.
 
 From your shell or command line:
 
-* `$ git clone git@github.com:WindowsAzureAD/Azure-AD-TODO-Server-Sample-For-Node.git`
+* `$ git clone git@github.com:AzureADSamples/WebAPI-Nodejs.git`
 * `$ npm install`
 
 ### Step 6: Run the application
@@ -92,6 +61,7 @@ We would like to acknowledge the folks who own/contribute to the following proje
 - [Restify](http://mcavage.me/node-restify/) - Restify is a node.js module built specifically to enable you to build correct REST web services. ``` node-restify```
 - [Restify-OAuth2](https://github.com/domenic/restify-oauth2) - This package provides a very simple OAuth 2.0 endpoint for the Restify framework. ``` restify-oauth2```
 - [node-jwt-simple](https://github.com/hokaccha/node-jwt-simple) - Library for parsing JSON Web Tokens (JWT) ```node-jwt-simple```
+- [http-bearer-strategy](https://github.com/jaredhanson/passport-http-bearer) - HTTP Bearer authentication strategy for Passport and Node.js.
 
 
 

node-server/config.js

@@ -1,4 +1,4 @@
- // Don't commit this file to your public repos
+ // Don't commit this file to your public repos. This config is for first-run
     exports.creds = {
     mongoose_auth_local: 'mongodb://localhost/tasklist', // Your mongo auth uri goes here
     openid_configuration: 'https://login.microsoftonline.com/hypercubeb2c.onmicrosoft.com/.well-known/openid-configuration?p=b2c_1_B2CSI', // For using Microsoft you should never need to change this.

node-server/lib/oidc_strategy.js

@@ -1,5 +1,5 @@
 /*
- Copyright (c) Microsoft Open Technologies, Inc.
+ Copyright (c) Microsoft Corporation
  All Rights Reserved
  Apache License 2.0
 
@@ -59,7 +59,7 @@ var log = bunyan.createLogger({name: 'Microsoft OpenID Connect: Passport Strateg
 *
 * Examples:
 *
-*     passport.use(new JwtBearerStrategy(
+*     passport.use(new OIDCBearerStrategy(
 *       secretOrPublicKey
 *       function(token, done) {
 *         User.findById(token.sub, function (err, user) {
@@ -135,10 +135,12 @@ var decoded = jws.decode(token);
       done(null, false, "Invalid JWT token.");
     }
 
- log.info(decoded, 'was token decrypted. But is it valid?');
+ log.info('token decoded. But is it valid?: ', decoded);
 
 
-// We have two different types of token signatures we have to validate here. One provides x5t and the other a kid. We need to call the right one.
+// We have two different types of token signatures we have to validate here. One provides x5t and the other a kid. 
+// We need to call the right one.
+
        if (decoded.header.x5t) {
          var PEMkey = this.metadata.generateOidcPEM(decoded.header.x5t);
          }

node-server/server.js

@@ -1,5 +1,5 @@
 /*
- Copyright (c) Microsoft Open Technologies, Inc.
+ Copyright (c) Microsoft Corporation
  All Rights Reserved
  Apache License 2.0
 
@@ -32,6 +32,9 @@
     var getopt = require('posix-getopt');
     var config = require('./config');
 
+
+    // We pass these options in to the ODICBearerStrategy.
+
     var options = {
    // The URL of the metadata document for your app. We will put the keys for token validation from the URL found in the jwks_uri tag of the in the metadata.
   metadataurl: config.creds.openid_configuration
@@ -54,49 +57,36 @@
 
 
 // MongoDB setup
-
-/**
-* Setup some configuration
-*/
-
+// Setup some configuration
 var serverPort = process.env.PORT || 8888;
 var serverURI = (process.env.PORT) ? config.creds.mongoose_auth_mongohq : config.creds.mongoose_auth_local;
 
-
-/**
-*
-* Connect to MongoDB
-*/
-
+// Connect to MongoDB
 global.db = mongoose.connect(serverURI);
 var Schema = mongoose.Schema;
 log.info('MongoDB Schema loaded');
 
-
-/**
-/ Here we create a schema to store our tasks and users. Pretty simple schema for now.
-*/
-
+// Here we create a schema to store our tasks and users. Pretty simple schema for now.
 var TaskSchema = new Schema({
   owner: String,
   task: String,
   completed: Boolean,
   date: Date
 });
 
-
 // Use the schema to register a model
-
 mongoose.model('Task', TaskSchema);
 var Task = mongoose.model('Task');
 
 
 
 /**
  *
- * APIs
+ * APIs for our REST Task server
  */
 
+ // Create a task
+
 function createTask(req, res, next) {
 
     // Resitify currently has a bug which doesn't allow you to set default headers
@@ -133,9 +123,8 @@ function createTask(req, res, next) {
 }
 
 
-/**
- * Deletes a Task by name
- */
+ // Delete a task by name
+
 function removeTask(req, res, next) {
 
         Task.remove( { task:req.params.task }, function (err) {
@@ -151,21 +140,17 @@ function removeTask(req, res, next) {
         });
 }
 
-/**
- * Deletes all Tasks. A wipe
- */
+ // Delete all tasks
+
 function removeAll(req, res, next) {
         Task.remove();
         res.send(204);
         return next();
 }
 
 
-/**
- *
- *
- *
- */
+// Get a specific task based on name
+
 function getTask(req, res, next) {
 
   log.info('getTask was called');
@@ -182,12 +167,8 @@ function getTask(req, res, next) {
         return next();
 }
 
-
-/**
- * Simple returns the list of TODOs that were loaded.
- *
- */
-
+ /// Simple returns the list of TODOs that were loaded.
+ 
 function listTasks(req, res, next) {
   // Resitify currently has a bug which doesn't allow you to set default headers
   // This headers comply with CORS and allow us to mongodbServer our response to any origin
@@ -272,7 +253,7 @@ util.inherits(TaskNotFoundError, restify.RestError);
 
 var server = restify.createServer({
         name: "Windows Azure Active Directroy TODO Server",
-    version: "1.0.0"
+    version: "2.0.1"
 });
 
         // Ensure we don't drop data on uploads
@@ -299,15 +280,23 @@ var server = restify.createServer({
         server.use(restify.dateParser());
         server.use(restify.queryParser());
         server.use(restify.gzipResponse());
-        server.use(restify.bodyParser({ mapParams: true}));
-        server.use(restify.authorizationParser());
+        server.use(restify.bodyParser({ mapParams: true})); // Allows for JSON mapping to REST
+        server.use(restify.authorizationParser()); // Looks for authorization headers
 
         // Let's start using Passport.js
 
-         server.use(passport.initialize());
-         server.use(passport.session());
+         server.use(passport.initialize()); // Starts passport
+         server.use(passport.session()); // Provides session support
 
-        // Passport stuff
+        /**
+        /*
+        /* Calling the OIDCBearerStrategy and managing users
+        /* 
+        /* Passport pattern provides the need to manage users and info tokens
+        /* with a FindorCreate() method that must be provided by the implementor.
+        /* Here we just autoregister any user and implement a FindById().
+        /* You'll want to do something smarter.
+        **/
 
         var findById = function (id, fn) {
           for (var i = 0, len = users.length; i < len; i++) {
@@ -342,6 +331,17 @@ var server = restify.createServer({
 
         /// Now the real handlers. Here we just CRUD
 
+        /**
+        /*
+        /* Each of these handlers are protected by our OIDCBearerStrategy by invoking 'oidc-bearer'
+        /* in the pasport.authenticate() method. We set 'session: false' as REST is stateless and 
+        /* we don't need to maintain session state. You can experiement removing API protection
+        /* by removing the passport.authenticate() method like so:
+        /*
+        /* server.get('/tasks', listTasks);
+        /*
+        **/
+
         server.get('/tasks', passport.authenticate('oidc-bearer', { session: false }), listTasks);
         server.get('/tasks', passport.authenticate('oidc-bearer', { session: false }), listTasks);
         server.get('/tasks/:owner', passport.authenticate('oidc-bearer', { session: false }), getTask);