Stormpath-Restify is a filter ("middleware") provider for the Restify API framework. It helps you secure your API by making it easy to create accounts for your API users and provision API keys for them.
Stormpath is a User Management API that reduces development time for any application with scalable user infrastructure.
This module provides a set of filters which allow you to add the following to your API:
- Register new API accounts
- Verify new API accounts (via email)
- Provision API keys for new API accounts
- API Key Authentication using JWT Bearer tokens
- Oauth2 Client-credentials worklow for generating Bearer tokens
- Access control based on the group membership of an account
For a walk through of how to enable these features, please see our blog post (TBD) or view the examples section of this repo.
To get started, you need to install this package via npm:
$ npm install stormpath-restify
You can then require it in your Restify server application:
var stormpathRestify =
HTTPS - You MUST use it
Warning: You MUST use HTTPS in production
Oauth itself does NOT make your authentication strategies secure. Sensitive information is still sent over the wire, and you MUST use HTTPS on your sever. Failing to do this will compromise your entire API.
Creating a filter set
To make use of the filters you must first create a filter set which is bound to your Stormpath Application (this is how we use Stormpath to manage all the state about your API accounts).
You will need a free Developer account, available at api.stormpath.com/register. Once you have obtained your Stormpath credentials and Application Href you can generate a filter set for that application:
var stormpathConfig =apiKeyId: 'YOUR_STORMPATH_API_KEY'apiKeySecret: 'YOUR_STORMPATH_API_SECRET'appHref: 'YOUR_STORMPATH_APP_HREF';var stormpathFilters = stormpathRestify;
Alternatively you can export those values as these environment variables, and they will be automatically read (you do not have to pass in a config object to createFilterSet):
export STORMPATH_API_KEY_SECRET=XXXexport STORMPATH_API_KEY_ID=XXXexport STORMPATH_APP_HREF=XXX
Using the Filters
This filter can be used to handle the Oauth2 Client Credential workflow,
it can issue tokens or authenticate users if they already have a token.
If the user is authenticated the
req object will have an
which is the Stormpath Account object from the Stormpath Node SDK
Configure the filter and use it like so:
var oauthFilter = stormpathFilters;server;server;
The options object can be used to configure the expiration of the token, as well as the given scopes. The options object is the same object that you would pass to authenticateApiRequest if you were using the Stormpath Node SDK directly. Please refer to that link for documentation of the options.
Use this filter to assert group membership of the authenticated account:
var trustedFilter = stormpathFilters;server;
This filter will accept a JSON POST, which must have the following properties:
This data will be used to create a new account for the API user. Email conflicts and password strength rules will be followed, based on the configuration of the Stormpath Directory that is attached to the Stormpath Application that you used when configuring the filter set.
Warning: You should enable the email verification workflow for your Stormpath Directory, so that arbitrary API accounts cannot be generated at will. Please read Cloud Directory Workflow Automations
Create and use the filter like this:
var newAccountFilter = stormpathFilters;server;
Account Verification Filter
You should require account verification for newly created API accounts. Stormpath will send an email to the new account, containing a link that they must click on. Use the Stormpath Admin Console to configure this email template and modify the link in the email to direct the user to your server.
Then configure this filter to accept requests at the specified URL:
var accountVerificationFilter = stormpathFilters;server;
If an error occurs within any filter they will, by default, send an HTTP response with appropriate status codes and error message as a JSON body. This ends the request handling chain.
Should you need to do custom error handling, all filters will accept an
function as an option. If you supply this function you will receive control of
the request chain and it is your responsibility to end the request.
The error handler will receive these arguments:
var trustedFilter = stormpathFilters;
If you wish to catch all errors from the filter set, you can specify the error handler when you create the filter set:
var stormpathFilters = stormpathRestify;