#ah-passport-plugin

##Status This plugin is a draft - please test it but it is not advisable for production usage (yet)

##Version Master: v1.0.0

##Semver This project aims to maintain the semver version numbering scheme.

##Changelog See the changelog file

##Overview ah-passport-plugin is a plugin for the actionhero API framework/system which allows usage of passport authentication middleware in actionhero projects. There are a large number of passport strategies available which provide authentication backends for various websites/social networks/backends etc. - for example, Github, Twitter, Facebook, Google, Youtube...

##Challenges Passport does not impose strict constraints over strategy implementations - this unfortunately means that this plugin cannot abstract strategies into simple key/value configuration parameters. This is most likely due in the main to the lack of consistency in authentication services/backends, thus this is not in any way a criticism of passport, merely a statement of fact to explain the implementation of this plugin.

##Requirements/dependencies ###Production requirements

• passport - the core passport module which this plugin lightly wraps/implements for actionhero specifics

###Development/test requirements/dependencies I use some requirements/dependencies for testing etc. which are:

• mocha
• should
• coveralls
• mocha-lcov-reporter
• istanbul

###Peer dependencies

• actionhero - the framework for which this is a plugin

Note: You can avoid installing these by running npm install ah-passport-plugin --production if you wish.

##Installation The simplest installation method is via npm as per below:

npm install ah-passport-plugin

alternatively, you could use a git clone to create a new instance of actionhero with this plugin installed, as per below:

cd /destination/path
git clone https://github.com/neilstuartcraig/ah-passport-plugin.git
npm install

##Usage To use ah-passport-plugin you will need to install it (as per above or via your package.json file, in the dependencies object) into your actionhero project. You'll also need to install (ideally via your package.json file, in dependencies) the strategies you want to use - this plugin cannot easily do that for you (yet).

##Configuration You will need to add the strategies you want to use in the config file file (which will be copied into your actionhero project: /config/plugins/ah-passport-plugin-config.js) and you'll also need to provide the actions you require (e.g. authenticate, callback (for oAuth/2 style logins at least), failed, logout etc.) - these will be specific to your requirements and strategies but you can see some examples which should allow for simple modification in actions

##To do/roadmap

• Consider some method of moving the oAuth (etc.) IDs/secrets into a config file which won't be overwritten with new versions of this plugin
• Test with web-facing installation to verify:
  • Logins/auth properly
  • Sessions
• Test functionality and add default config/actions for several stragies - at least:
  • Github
  • Twitter
  • Facebook
  • Google
  • Youtube
  • Instagram
  • Weibo
  • ...?
• Add some tests (using the above actions/config)
• Test/fix for 2FA/MFA
• Ideally, add some 'local' auth mechanisms - perhaps ah-tdp-auth-plugin and any others which are sensible
• Audit security
• Optimise performance as far as possible

##Tests Tests use mocha and the actiohero test facilties and are run via Travis CI.

##License ah-passport-plugin is issued under a Creative Commons attribution share-alike license. This means you can share and adapt the code provided you attribute the original author(s) and you share your resulting source code. If, for some specific reason you need to use this library under a different license then please contact me and i'll see what I can do - though I should mention that I am committed to all my code being open-source so closed licenses will almost certainly not be possible.