Express-Stormpath is an extension for Express.js that makes it incredibly simple to add user authentication to your application, such as login, signup, authorization, and social login.
Stormpath is a User Management API that reduces development time with instant-on, scalable user infrastructure. Stormpath's intuitive API and expert support make it easy for developers to authenticate, manage and secure users and roles in any application.
Follow these steps to add Stormpath user authentication to your Express.js app.
- Download Your Key File
Downlaod your API Key file by logging in to https://api.stormpath.com/login and clicking the “Create API Key” button under the “Developer Tools” section.
- Store Your Key As Environment Variables
Open your key file and grab the API Key ID and API Key Secret, then run these commands to save them as environment variables:
$ export STORMPATH_CLIENT_APIKEY_ID=<YOUR-ID-HERE>
$ export STORMPATH_CLIENT_APIKEY_SECRET=<YOUR-SECRET-HERE>On Windows, use the set or setx command instead of export.
- Get Your Stormpath App HREF
Login to the Stormpath Console and grab the HREF (called REST URL in the UI) of your Application. It should look something like this:
https://api.stormpath.com/v1/applications/q42unYAj6PDLxth9xKXdL
- Store Your Stormpath App HREF In an Environment Variable
$ export STORMPATH_APPLICATION_HREF=<YOUR-STORMPATH-APP-HREF>On Windows, use the set or setx command instead of export.
- Install The SDK
$ npm install --save express-stormpath- Include It In Your App
var stormpath = require('express-stormpath');- Initialize It
You need to initialize the middlware and use it with your application. We have options for various use cases.
If your app is a traditional website:
Initialize the Stormpath module, and pass an empty set of options:
app.use(stormpath.init(app, { }));This will enable the default features, such as login and registration pages.
If your app is a single page application (Angular, React)
You will need to tell our library where the root file is. For example, if
your Angular app is in the client/ folder in your project:
app.use(stormpath.init(app, {
web: {
spa: {
enabled: true,
view: path.join(__dirname, 'client', 'index.html')
}
}
}));Read more about the initialization in the documentation →
- Wait For The SDK
Wait for the SDK to get ready, then start the web server:
app.on('stormpath.ready', function () {
app.listen(3000, function () {
//...
});
});- Protect Your Routes
For websites and Single-Page Apps, use stormpath.authenticationRequired as a
middleware to protect your routes:
app.get('/secret', stormpath.authenticationRequired, function (req, res) {
//...
});For API services that use HTTP Basic Auth, use
stormpath.apiAuthenticationRequired:
app.get('/secret', stormpath.apiAuthenticationRequired, function (req, res) {
//...
});If the user tries to access this route without being logged in, they will be redirected to the login page.
- Login
To access a protected route, the user must first login.
Traditional Websites:
You can login by visiting the /login URL and submitting the login form.
Single Page Apps:
Your front-end client should POST this data to the /login endpoint:
{
"username": "[email protected]",
"password": "myPassword"
}Note: make sure that your client is setting the Accept: application/json
header on the request.
Using AngularJS? Try our Stormpath Angular SDK
API Services
If your app is an API service that uses our client_credentials workflow, your API consumers can obtain access tokens by making this POST to your server:
POST /oauth/token
Authorization: Basic <Base64Endoded(ACCOUNT_API_KEY_ID:ACCOUNT_API_KEY_SECRET)>;
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
Read more about login in the documentation →
- Register
To be able to login, your users first need an account.
Traditional Websites:
Users can register by visiting the /register URL and submitting the
registration form.
Single Page Applications:
Your front-end client should POST this data to the /register endpoint:
{
"email": "[email protected]",
"password": "mySuper3ecretPAssw0rd"
}If the user was created successfully, you will receive a 200 response and the body will contain the account that was created. If an error occurred, we will send a 400 status with an error message in the body.
Note: make sure that your client is setting the Accept: application/json
header on the request.
Using AngularJS? Try our Stormpath Angular SDK
Read more about registration in the documentation →
- That's It!
You just added user authentication to your app with Stormpath. See the documentation for further information on how Stormpath can be used with your Express.js app.
For a full documentation of this library, see the documentation.
Contact us via email at [email protected] or visit our support center.
For an example app, see the Stormpath SPA Development Server.
Below are some resources you might find useful.
- 15-Minute Tutorial: A Simple Web App With Node.js, Express, Bootstrap & Stormpath
- Stormpath Node.js SDK
Apache 2.0, see LICENSE.