Waterlock is an all encompassing user authentication/json web token management tool for Sails >= 0.10
Waterlock provides predefined routes and models for user authentication and json web token management. Password resets are also handled but we'll cover that below. Authentication is handled via methods. The current supported methods are:
Method | Library |
---|---|
Local Auth | waterlock-local-auth |
Twitter Auth | waterlock-twitter-auth |
Facebook Auth | waterlock-facebook-auth |
Google Auth | waterlock-google-auth |
it is a great tool if you're looking to grant user access to your api.
Since sails currently has no official support for 3rd party libraries like Rails gems; Waterlock works by hooking into your model and controller files adding the functionality needed. When Sails starts officially supporting 3rd party libraries this might change.
Glad you asked! If you're on a fresh install of a Sails app first run
npm install waterlock
npm install waterlock-local-auth
then run on mac/linux
./node_modules/.bin/waterlock generate all
or for windows
node_modules\.bin\waterlock generate all
this will generate all the necessary components, however you do not have strict access yet! The custom policies are generated via the command above but not yet applied. To apply policies crack open your config/policies.js
file and add something like the following:
MyController:{
'*': true,
'myApiAction': ['hasJsonWebToken'],
'mySessionAction': ['sessionAuth']
}
now with your policies applied to your custom controller you're good to go! (given you've actually implemented some login in them e.g. res.view()
)
Waterlock wraps around models and controllers so you can override any of the actions and definition that are predefined. After running waterlock generate all
open up the User.js
file you'll see this:
attributes: require('waterlock').models.user.attributes({
/* e.g.
nickname: 'string'
*/
}),
you can add any custom attributes you wish to your user model by just dropping them in like normal.
Good question! If for whatever reason be it we haven't implemented a certain authentication method or your case it exceptionally complex. You can still take advantage of Waterlocks json web token management, so long as your user model has the following:
jsonWebTokens: {
collection: 'jwt',
via: 'owner'
},
this will keep the user association to the Jwt model and still allow for management of the tokens, which is what Waterlock tries to accomplish first and foremost.
Waterlock generates a config located at config/waterlock.json
this file is used to set various options
baseUrl
- this is the URL your app resides at, used in password reset urlsautheMethod
- the npm package name for the chosen authentication method or array of methodsjsonWebTokens
- object containing information on how the jwt's should be constructedsecret
- the secret used to encrypt the token, CHANGE THIS VALUE!expiry
- object containing information on expiry these are passed to moment.js add functionunit
- y,M,w,d,h,m,s,mslength
- length of time
audience
- the jwt aud claim a good choice is the name of your apptokenProperty
- customize the name of the property returning the token valueexpiresProperty
- customize the name of the property returning the expires valueincludeUserInJwtResponse
- when JWT is the default response for succesfull log-in you can return the user along with the token by setting this to true - cuts down round tripsgsubject
- the jwt sub claim
postActions
- lets waterlock know how to handle various login/logout events, you can read more about this in the docs
We would hope to turn this project into a well oiled jwt management tool for users.
Tests are run through the wonderful mocha so just clone the library run npm install
then npm test
I love to hear all of your feature requests, so if you have any please open an issue here! I'll be more than happy to work it into the roadmap if feasible.
Feel free to contribute as you please, the more the merrier. Just please write test cases for everything you submit, in short you can follow the steps below. Happy coding! ๐
- Fork it ( http://github.com/waterlock/waterlock/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Write test cases!
- Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
MIT (see License)