Update 2/29/16: These code examples have been updated to reflect the 3.0 release of the express-stormpath integration.
It’s no secret that if you’re building an Express web app, adding in user authentication is quite difficult. If you google “Express Authentication”, you’ll be directed to the Passport website.
While both Passport is a really great tool, as a relatively new Node developer, I had a difficult time figuring out how to actually use them in a real application.
I honestly don’t want to setup / configure my own session management stuff, or worry about creating my own login / registration views securely.
After a lot of discussion internally at Stormpath, we decided it would be awesome to build a really simple, powerful, and elegant authentication system for Express.
Which brings me to…
express-stormpath
For the past week, I’ve been working on building an authentication library that would abstract away all the details, and make adding user authentication to Express apps drop-dead easy.
With that said, I’m really happy to introduce express-stormpath! Visit the official docs here: https://docs.stormpath.com/nodejs/express/latest/
NOTE: If you aren’t a Stormpath user already, Stormpath is an API service that makes managing users simple. It’s completely free for small apps.
express-stormpath allows you to painlessly add complete user authentication (including registration, login, and logout) into your Express apps in just a few lines of code.
First, install the library (and express, too!):
|
1 2 |
$ npm install --save express express-stormpath |
Next, open up your editor and create an app.js file:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
var express = require('express'); var stormpath = require('express-stormpath'); var app = express(); app.use(stormpath.init(app, { client: { apiKey: { id: 'xxx', secret: 'xxx', } }, application: { href: 'xxx' } })); app.on('stormpath.ready', function () { console.log('Stormpath Ready'); }); app.listen(3000); |
NOTE: In this example we’ve put the API keys into the code, but this is only for example purposes. When you move to production, you should use a more secure solution such as environment variables or config files. Our post on building a simple app with Node.js, Express, Passport, and Stormpath shows how to configure these as environment variables.
For more information on setting up a Stormpath account, you can check out the Setup section of our docs.
The above code sample is a fully functional Express app which has three pre-configured routes:
A registration route (/register), which looks like this:
A login route (/login), which looks like this:
And a logout route (/logout) which logs users out of their account.
Out of the box you get user registration, login, and logout!
Just to demonstrate how easy it actually is, here’s a 90 second screencast I made in which I’ll create a brand new Express app from scratch with full user registration and login!
Customization
With express-stormpath, you can also customize essentially every part of the library very easily.
Let’s say, for instance, that after a user creates a new account or logs in, you’d like to redirect them to a dashboard page (/dashboard), you can easily do this by specifying the nextUri setting when initializing the middleware, like so:
|
1 2 3 4 5 6 7 8 9 10 |
app.use(stormpath.init(app, { // .. web: { register: { nextUri: '/dashboard' } } // .. })); |
What if you want to change the login and registration urls? It’s also a single setting:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
app.use(stormpath.init(app, { // .. web: { login: { uri: '/user/login' }, register: { uri: '/user/register' } } // .. })); |
Or, what if you want to change the view code to add in your own styles / etc? It’s incredibly simple! I wrote a guide which explains how to do it in explicit detail.
You can easily change / remove / modify any part of the express-stormpath library by modifying middleware settings — it really is that simple.
Exploring express-stormpath
If you’d like to give express-stormpath a try, here are some code samples which illustrate how to use the library in a bit more depth.
Let’s say you want to write a route which requires a user to be logged in. You can do this easily by using the stormpath.loginRequired tooling:
|
1 2 3 4 |
app.get('/dashboard', stormpath.loginRequired, function(req, res) { res.send('If you can see this page, you must be logged into your account!'); }); |
When a user visits /dashboard, we’ll automatically check to ensure the user is logged in before allowing them to continue. If the user isn’t logged in, they’ll be redirected to /login?next=%2Fdashboard, so once they log into their account, they’ll be immediately sent back to the dashboard page!
Furthermore, you can also require a user to be a member of one or more groups in order to access a route. For instance, if you’d like to build an admin panel that’s exclusively available to users in the ‘admins’ group, you could do:
|
1 2 3 4 |
app.get('/admin', stormpath.groupsRequired(['admins']), function(req, res) { res.send('You are an admin!'); }); |
To assert that a user is a member of multiple groups, you can simply list multiple groups, ex:
|
1 2 3 4 |
app.get('/admin', stormpath.groupsRequired(['admins, developers']), function(req, res) { res.send('You are an admin and developer!'); }); |
You can also assert that a user is a member of one or more groups by passing an optional flag:
|
1 2 3 4 |
app.get('/hmm', stormpath.groupsRequired(['admins, developers', 'dudes'], false), function(req, res) { res.send('You are either an admin, developer, dude, or some combination of them all!'); }); |
In your route code, you can also access the current user object by calling res.locals.user like so:
|
1 2 3 4 |
app.get('/dashboard', stormpath.loginRequired, function(req, res) { res.send('Welcome back: ' + res.locals.user.email); }); |
If you’re inside of a template, you can access the user object directly, here’s an example in Pug:
|
1 2 3 4 |
html body p Hi #{user.email} |
Making Authentication Easier
Thanks for reading this far!
If you’d like to get started with express-stormpath, now would be a great time to check out the official documentation!
I’m super excited to launch the very first release of express-stormpath, and plan on adding lots of new features to it in the coming weeks:
- Social login support.
- API authentication support.
- Password reset support.
- etc.
If any of you give express-stormpath a try, I’d love to hear from you, please drop me a line: [email protected] — or tweet us @gostormpath!