moneypenny-client - npm Package Compare versions

Comparing version 0.0.5 to 0.0.6

app/moneypenny-client/index.js

@@ -5,2 +5,44 @@ var passport = require('passport');
 
+/**
+ * Client for authentication against a moneypenny server.
+ * @see https://github.com/blueflag/moneypenny
+ * @example
+ * var express = require('express');
+ * var app = express();
+ * // Create and configure Moneypenny authetication client.
+ * var authClient = new AuthClient({
+ * 		jwtSecret: JWT_SECRET,
+ * 		providerHost: AUTH_HOST,
+ * 		providerPort: AUTH_PORT,
+ * 		serverHost: SERVER_HOST,
+ * 		serverPort: SERVER_PORT,
+ * 		oAuthClientSecret : CLIENT_SECRET,
+ * 		oAuthClientID: CLIENT_ID
+ * });
+ * //Initialize Authentication Routes.
+ * authClient.initialize(app);
+ * //Check authentication before other routes
+ * app.use(authClient.checkAuthenticated);
+ * 
+ * @module moneypenny-client
+ */
+
+/**
+ * @typedef {Options} Options
+ * Options required for creating a moneypenny client.
+ * @property {String} jwtSecret Secret to use to decode JWT.
+ * @property {String} providerHost __required__ web accessable host name for the location of the authentication server.
+ * @property {Number} providerPort _default:443_ web accessable port for the location of the authentication server.
+ * @property {String} providerName _default:moneypenny-server_ name given to the oAuth passport stratergy
+ * @property {String} serverHost __required__ web accessable hostname of the service running the moneypennny-client
+ * @property {Number} serverPort _default:443_ web accessable port of the service running the moneypennny-client
+ * @property {String} oAuthClientSecret __required__ shared secret setup in the authentication service for the service
+ * @property {String} oAuthClientID __required__ client id that corresponds to this service on the authentication service
+ * @property {String} authorizationURI _default:/oauth2/authorization_ url on the authentication server where the authentication endpoint can be found.
+ * @property {String} tokenURI _default:/oauth2/token_ uri that this server will use to get the token.
+ * @property {String} callbackURI _default:/auth/provider/callback_ uri that will be added to this server using the `initialize()` method that will be used for the oAuth2 callback
+ * @property {String} loginUri _default:/login_ uri that is used to login to the service, this will be added to this server using the `initalize()` method.
+ */
+
+
 /* Used for authenticating against remote authentication server */
@@ -35,11 +77,14 @@ var OAuth2Strategy = require('passport-oauth').OAuth2Strategy;
 /***
- * options
-* 		* loginUrl - URL on the local service to direct people to for login.
-* 		* authorizationUrl - URL on the remote authentication server where the user requests authentication
-*       * tokenUrl - URL on the remote autnetication server where this server requests token
-* 		* providerName - name of the provider, unimportant only used internally
-* 		* provithanksderHost - web accessable host name of the authentication server.
-* 		*
+* @function
+* @exports
+* Sets up client authentication using moneypenny.
+* 
+* @param {object} options - options to create moneypenny client with.
+* @property {string} options.loginUrl - URL on the local service to direct people to for login.
+* @property {object} options.authorizationUrl - URL on the remote authentication server where the user requests authentication.
+* @property {object} options.tokenUrl - URL on the remote autnetication server where this server requests token.
+* @property {object} options.providerName - name of the provider, unimportant only used internally.
+* @property {object} options.provithanksderHost - web accessable host name of the authentication server.
+*
  */
-
 module.exports = function(options){
@@ -164,2 +209,9 @@
 
+    /**
+     * Checks that a user is autenticated for a request, returns user to the login page if they are not.
+     * 
+     * @param {Request} req express request object.
+     * @param {Response} res express response object
+     * @param {callback} next express next callback, next function to call after success.
+     */
 	this.checkAuthenticated = function(req, res, next){
@@ -178,2 +230,8 @@ if(req.isAuthenticated()){
 
+    /**
+     * Initalizes the passport and sets up oAuth routes.
+     * 
+     * @param {App} app express js application ojbect.
+     */
+
 	this.initialize = function(app){
@@ -180,0 +238,0 @@ app.use(passport.initialize());

Gruntfile.js

@@ -68,2 +68,9 @@ module.exports = function(grunt){
         },
+        
+        jsdoc2md: {
+            oneOutputFile: {
+                src: 'app/moneypenny-client/**/*.js',
+                dest: 'api/documentation.md'
+            }
+        }
     });
@@ -73,2 +80,4 @@ grunt.loadNpmTasks('grunt-mocha-istanbul');
     grunt.loadNpmTasks('grunt-contrib-jshint');
+    grunt.loadNpmTasks('grunt-jsdoc-to-markdown');
+    grunt.registerTask('doc', 'jsdoc2md');
     grunt.registerTask('test', ['jshint' ,'mocha_istanbul:coverage', 'coveralls:post_lcov']);
@@ -75,0 +84,0 @@

package.json

 {
   "name": "moneypenny-client",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Moneypenny authentication client, allows node js applications to authenticate using moneypenny",
@@ -20,2 +20,3 @@ "main": "app.js",
     "grunt-coveralls": "^1.0.0",
+    "grunt-jsdoc-to-markdown": "^1.2.0",
     "grunt-karma": "^0.12.1",
@@ -47,3 +48,4 @@ "grunt-mocha": "^0.4.13",
   "scripts": {
-    "test": "grunt test"
+    "test": "grunt test",
+    "doc": "jsdoc2md -l js -t jsdoc2md/README.hb  app/moneypenny-client/index.js  > README.md"
   },
@@ -50,0 +52,0 @@ "author": "Blueflag",

README.md

 ![moneypenny-client](https://upload.wikimedia.org/wikipedia/en/9/9b/Miss_Moneypenny_by_Lois_Maxwell.jpg)
 
-# moneypenny - Authentication Client
+# Moneypenny - Authentication Client
 
@@ -8,19 +8,118 @@ [![Circle CI](https://circleci.com/gh/blueflag/moneypenny-client.svg?style=shield)](https://circleci.com/gh/blueflag/moneypenny-client)
 
-Moneypenny acts as an authentication service that offers multiple authentication strategies to a backend service and sends a [JSON web token](http://jwt.io/)(JWT) encripted using a shared secret as a response.
+##Introduction
 
-Other services in the architecture should also know the shared secret allowing the token to be passed around in API calls to provide user information related to the request.
+Moneypenny acts as an authentication service that supports single sign-on and sign-off using oAuth and [JSON web tokens](http://jwt.io/)(JWT).
 
-##Autenticated User.
+Backend services unencrypt the JWT to know who the authenticated user is.
 
-After a user is authenticated with moneypenny, the user will be attached to the expressjs request as `req.user` and the users token attached to the user in `req.user.token`.
+###Related Projects
 
-For the sake of security a developer using this service should endevor to not pass the token outside their controlled ecosystem, for example, remove the token from the object if you wish to send the user to the browser.
+* [moneypenny server](https://github.com/blueflag/moneypenny)
+* [moneypenny server mongodb store](https://github.com/blueflag/moneypenny-mongo-storage)
 
-##Authenticating next Request
+###Sample
 
-To autenticate a request against another moneypenny server forward the token to that service, moneypenny-client uses [passport-localapikey](https://github.com/cholalabs/passport-localapikey) for this.
+[Sample Implementation Code](https://github.com/blueflag/moneypenny/tree/master/samples/sample-client)
 
-You can either attach a query parameter `apikey` or a header `apikey` the next service will then attempt to decript that user using either the public key or shared secret, if it has success that user will be autenticated for that request.
+##Authenticating a Request
 
+To authenticate a request against another service running moneypenny client the server can forward the token to that service, moneypenny-client uses [passport-localapikey](https://github.com/cholalabs/passport-localapikey) to allow requests to other services to be authenticated.
+
+The token is passed by adding the query parameter `apikey` or a header `apikey`to the request, service running moneypenny-client will then attempt to decript that user using either the public key or shared secret, if it has success that user will be authenticated for that request.
+
 This project connects to the [moneypenny server](https://github.com/blueflag/moneypenny)
 
+###Methods
+
+`checkAuthenticated(req, res, next)` middlewhere to check the authentication of the client, redirects the user to the moneypenny server for login, if they are not authenticated.
+
+`initialize(app)` initalizes express to use routes required by moneypenny for the oauth flow.
+
+##Authenticated User.
+
+After a user is authenticated with the moneypenny server and the oAuth flow is complete, the user will be attached to the expressjs request as `req.user` and the users token attached to the user in `req.user.token`.
+
+For the sake of security a developer using this service should endevor to not pass the token outside their controlled ecosystem, for example, remove the token from the object if you wish to send the user to the browser.
+
+##API documentation.
+
+<a name="module_moneypenny-client"></a>
+
+## moneypenny-client
+Client for authentication against a moneypenny server.
+
+**See**: https://github.com/blueflag/moneypenny  
+**Example**  
+```js
+var express = require('express');
+var app = express();
+// Create and configure Moneypenny authetication client.
+var authClient = new AuthClient({
+		jwtSecret: JWT_SECRET,
+		providerHost: AUTH_HOST,
+		providerPort: AUTH_PORT,
+		serverHost: SERVER_HOST,
+		serverPort: SERVER_PORT,
+		oAuthClientSecret : CLIENT_SECRET,
+		oAuthClientID: CLIENT_ID
+});
+//Initialize Authentication Routes.
+authClient.initialize(app);
+//Check authentication before other routes
+app.use(authClient.checkAuthenticated);
+```
+
+* [moneypenny-client](#module_moneypenny-client)
+    * _static_
+        * [.checkAuthenticated(req, res, next)](#module_moneypenny-client.checkAuthenticated)
+        * [.initialize(app)](#module_moneypenny-client.initialize)
+    * _inner_
+        * [~Options](#module_moneypenny-client..Options) : <code>Options</code>
+
+<a name="module_moneypenny-client.checkAuthenticated"></a>
+
+### moneypenny-client.checkAuthenticated(req, res, next)
+Checks that a user is autenticated for a request, returns user to the login page if they are not.
+
+**Kind**: static method of <code>[moneypenny-client](#module_moneypenny-client)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| req | <code>Request</code> | express request object. |
+| res | <code>Response</code> | express response object |
+| next | <code>callback</code> | express next callback, next function to call after success. |
+
+<a name="module_moneypenny-client.initialize"></a>
+
+### moneypenny-client.initialize(app)
+Initalizes the passport and sets up oAuth routes.
+
+**Kind**: static method of <code>[moneypenny-client](#module_moneypenny-client)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| app | <code>App</code> | express js application ojbect. |
+
+<a name="module_moneypenny-client..Options"></a>
+
+### moneypenny-client~Options : <code>Options</code>
+Options required for creating a moneypenny client.
+
+**Kind**: inner typedef of <code>[moneypenny-client](#module_moneypenny-client)</code>  
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| jwtSecret | <code>String</code> | Secret to use to decode JWT. |
+| providerHost | <code>String</code> | __required__ web accessable host name for the location of the authentication server. |
+| providerPort | <code>Number</code> | _default:443_ web accessable port for the location of the authentication server. |
+| providerName | <code>String</code> | _default:moneypenny-server_ name given to the oAuth passport stratergy |
+| serverHost | <code>String</code> | __required__ web accessable hostname of the service running the moneypennny-client |
+| serverPort | <code>Number</code> | _default:443_ web accessable port of the service running the moneypennny-client |
+| oAuthClientSecret | <code>String</code> | __required__ shared secret setup in the authentication service for the service |
+| oAuthClientID | <code>String</code> | __required__ client id that corresponds to this service on the authentication service |
+| authorizationURI | <code>String</code> | _default:/oauth2/authorization_ url on the authentication server where the authentication endpoint can be found. |
+| tokenURI | <code>String</code> | _default:/oauth2/token_ uri that this server will use to get the token. |
+| callbackURI | <code>String</code> | _default:/auth/provider/callback_ uri that will be added to this server using the `initialize()` method that will be used for the oAuth2 callback |
+| loginUri | <code>String</code> | _default:/login_ uri that is used to login to the service, this will be added to this server using the `initalize()` method. |
+

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

46108

increased by27.77%

Lines of code

757

increased by9.08%

Number of lines in readme file

125

increased by380.77%

Worsened metrics

Dev dependency count

32

increased by3.23%

Number of package files

18

decreased by-10%

No dependency changes