Update 5/12/2016:Β We’re excited to announce the 3.0 release of our Express-Stormpath library! For the technical breakdown of authentication in Express, you should see the 3.0 Changelog and the 3.0 Upgrade Guide.

When building full-stack JavaScript applications, it’s all too easy to defer the user authentication until some later date. With the power of frameworks like Angular.js and Express.js, you can “just get going” with your core application functionality, without really needing to invest effort in figuring out the “user login part”.

But if you’ve worked this way, you’ve likely discovered that adding in user authentication can be a real pain once your development picks up and the deadline suddenly turns into tomorrow πŸ™‚

In this post, I’ll show you how we can include user authentication up front, as part of your boilerplate. We’ll be using Stormpath as our authentication service, and you’ll be up and running in 15 minutes – *promise*.

What Is Stormpath?

Stormpath is an authentication and user management service that allows developers to create, edit, and securely store user accounts and user account data. Our API enables you to:

Getting Started

To get started with our example application, you will need to sign up for a Stormpath tenant. It’s free to use and quick to create your tenant account.

After you sign in, you will have the opportunity to get an API Key and Secret. These are secure credentials that your example application will use to communicate with the Stormpath API. You should also find the default Stormpath Application, called “My Application”. This application has an HREF that you will need to use as well.

Here is a screenshot that shows you were to find these items:

Stormpath Admin Console

Fetch The Angular.js-Express.js Example Code

All of the code for our example project can be found in this repository:


Please download this code to your computer, then open your terminal and enter the folder. We need to install the node modules by running this command:

You should see a list of installed modules when the operation completes. Then we can move on to configuration.

Configure Stormpath

We need to create a properties file in this folder, this file will be used to store our secure API credentials that we gathered from the Stormpath Admin Console. Please create the file stormpath.yml and place the following inside it:

That's it! The server should now be usable, we'll start it up in the next section.

Start The Node Server

You should now be able to start the server by running the server script:

If all is well you should see the following logged to your console after a few seconds:

The server should now be available! Visit http://localhost:3000 in your browser, you should now see the Angular application:

Angular App Home

Woot! It’s been about 15 minutes, right? Maybe less? What you’re looking at is a basic, but complete Angular + Express application that has a user management system built in. Give it a try! You can use the registration screen to sign up for an account, then you can login and view your user profile. #awesome

Play around with the app, then continue reading. We’ll discuss how this application works, and what you can do to modify it – or how you can steal pieces of it for your own application.

Server-Side: Stormpath Express.js Integration

The heavy worker in this fullstack application is our express-stormpath library. This library wires up your Express application to Stormpath’s API, and helps with serving the Angular application.

Behind the scenes it is using our lower-level Stormpath Node SDK to communicate directly with the Stormpath REST API. It then ties in with the Express API to provide you an experience that feels very much like an Express middleware experience, but backed by Stormpath authentication services.

If you take a peek inside server.js, you’ll see where we setup this integration:

These options are telling express-stormpath how it should integrate with our fullstack application. We’ve told it where our Angular application is (spaRoot), that we’re building a website (rather than a pure API service), and that we want to expand the account’s custom data and groups (a convenience feature to provide our Angular application with all the user data that it needs).
For more information on how you can configure our express-stormpath library, please see the Express-Stormpath Library Guide.

Front-End: Stormpath Angular.js SDK

The Angular application is also leveraging a Stormpath module, the [Stormpath Angular.js SDK][]. This module has some more nuanced configuration than the server side component, so I’ll walk you through each bit and discuss what it does.

How Authentication Works – Tokens!

This is where it gets really cool. The Stormpath API provides OAuth2 Token Management, which is a very powerful feature if you’re building a web application. In a nutshell, it is sessions as a service. I’ll explain how we use this in our fullstack application, but don’t worry: all this is handled for you automatically by the Stormpath modules.

When a user posts the login form, we send their username and password to the Stormpath API. If the credentials are valid, we exchange them for an access token and refresh token. These tokens are then stored in secure, HTTPS-only cookies in the browser. On subsequent requests, these access tokens will be provided for authentication. Stormpath authenticates the tokens for you without any extra effort on your part.

Should you ever need to revoke tokens, you can easily do so by finding the user in the Stormpath Admin Console and revoking their issued tokens. Again, this is like sessions as a service: you never have to build your own database for this! mic drop

For more information, please see Using Stormpath for OAuth 2.0 and Access/Refresh Token Management.

The Stormpath Module, and Its Templates

The very first thing that must be done is to depend on the Stormpath module and the templates. That is done with the standard Angular module system:

Our Stormpath Angular SDK has broken out the templates from the core code, because you may find that you want to supply your own templates. If you go this route you can simply omit this dependency.

Each of our directives that need a template will allow you to supply your own template. Please see the individual directives for more information, such as these common ones:

UI-Router Integration

In this example we are using the UI-Router module, but please note that support for ngRoute will be coming very soon.

To configure UI-Router, we tell it what our default state should be (where users go after login) and the name of the state where our login page can be found. You will find this in the main Angular script, client/app.js:

Please see the documentation of the $stormpath service for the more advanced UI Router configuration options.

Login and Registration Forms

The Stormpath Angular SDK provides default forms for Login and Registration, via directives. These directives need to be placed in the appropriate location in your Angular application.

This example application has the structure of one folder per major view, so you will find the login view in client/login/login.html:

This is where we’ve placed the sp-login-form directive. The Stormpath Angular SDK will replace this element with the default form.

You will find a similar directive, for registration, in client/register/register.html.

Handling Logout

When a user wants to logout, we need to revoke their access tokens. This is done by making a request to the /logout endpoint on your express server. What should happen in your UI after logout? We leave that in your control, as UI Router represents everything as view states.

As such, you’ll find that in client/app.js we listen for the session end event and then redirect the user back to the login page. This event is emitted once the tokens have been revoked:

To trigger the deletion of the tokens, we add the sp-logout directive to our logout link in client/navbar/navbar.html:

Please see sp-logout and $sessionEnd for more information on how to use these together.

More Features!

In the previous section I went into detail about the core features of login and registration. But there are many more features in this example that I’ll cover quickly, so that you can get on with building the rest of your application πŸ™‚

Email Verification

Stormpath provides an email verification feature that allows you to send a verification email to users when they register. Their account is not activated until they click on this link. The Stormpath Angular SDK provides the landing pages that users will come to when they click on this link. You will see this code in client/email-verification.

To configure email verification and the related emails, please login to the Stormpath Admin Console and find the Directory that is attached to your default Stormpath Application. In there you will find the Workflows section, where you can configure this feature.

Password Reset

Stormpath provides a password reset feature that allows users to request a password reset email. When they click on the link in the email, they will arrive at your angular application and be prompted to enter a new password. You will see the code for this feature in client/forgot-password and client /change-password.

To configure the password reset feature, please login to the Stormpath Admin Console and find the Directory that is attached to your default Stormpath Application. In there you will find the Workflows section, where you can configure this feature.

Social Login

Would you like to provide Google Login and Facebook Login for your users? No problem! This is super easy to setup. Simply login to the Stormpath Admin Console and create two new directories, one for Google and one for Facebook. During the setup you will have to enter the associated information for your Google App and Facebook App.

After you have created the directories, go back to your default Stormpath Application and map these directories to your application. Then restart your Express server and you should see the buttons on your login page:

Angular App Home


Custom Profile Data

All accounts in Stormpath can have arbitrary custom data assigned to them. In this example we show you how to create a custom profile editing form, and how you can post to your Express server and save the data onto the user object. You can find the Angular code in client/profile and the server code in server/routes/profile.js

Go Forth and Develop!

While this is an example application, you can definitely use it as the base for your own project. So go ahead, start building your next awesome app on top of it! Or just steal the good parts for your existing application πŸ™‚

As always, we’re here to help! Hit us up via [email protected], or leave a comment below.

-robert out