Waterlock is an all encompassing user authentication/json web token management tool for Sails
What does it provide
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:
it is a great tool if you're looking to grant user access to your api.
How does it work
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.
How do I use it
Glad you asked! If you're on a fresh install of a Sails app first run
npm install waterlocknpm 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.
How can I customize it?
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: modelsuserattributes/* e.g.nickname: 'string'*/
you can add any custom attributes you wish to your user model by just dropping them in like normal.
What if I want to control my own User model
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 urls
autheMethod- the npm package name for the chosen authentication method or array of methods
jsonWebTokens- object containing information on how the jwt's should be constructed
secret- the secret used to encrypt the token, CHANGE THIS VALUE!
expiry- object containing information on expiry these are passed to moment.js add function
length- length of time
audience- the jwt aud claim a good choice is the name of your app
tokenProperty- customize the name of the property returning the token value
expiresProperty- customize the name of the property returning the expires value
includeUserInJwtResponse- 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 tripsg
subject- 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
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)