#Stormpath is Joining Okta We are incredibly excited to announce that Stormpath is joining forces with Okta. Please visit the Migration FAQs for a detailed look at what this means for Stormpath users.

We're available to answer all questions at [email protected].

stormpath-restify

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.

Installation

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:

You will need a free Developer account, available at api.stormpath.com/register. Once you have logged in, click on the "Node.js" quickstart on the home screen of the Admin Console. You will see your API Keys and Stormpath Application href, you will need to provide those to your Restify project.

You can export them to your environment:

export STORMPATH_API_KEY_SECRET=XXX
export STORMPATH_API_KEY_ID=XXX
export STORMPATH_APP_HREF=XXX

Or you can create stormpath.yaml in the root of your project, and define them like this:

client:
  apiKey:
    id: YOUR_STORMPATH_API_KEY
    secret: YOUR_STORMPATH_API_SECRET
application:
  href: https://api.stormpath.com/v1/applications/YOUR_STORMPATH_APP_HREF

Now that you have configured your settings, you can require the module in your project. This will usually go in your main server file:

var stormpathRestify = require('stormpath-restify')

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).

Now you can generate a filter set for that application:

var stormpathFilters = stormpathRestify.createFilterSet();

This will create an internal Stormpath Client that is bound to the Stormpath application that you configured. Any options that the Stormpath Client accepts can be passed into the this function. For example, if you wanted to configure redis:

var clientOptions = {
  cacheOptions: {
    store: 'redis'
  }
}

var stormpathFilters = stormpathRestify.createFilterSet(clientOptions);

Using the Filters

Oauth Filter

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 account object, which is the Stormpath Account object from the Stormpath Node SDK

Configure the filter and use it like so:

var oauthFilter = stormpathFilters.createOauthFilter({/* options */});

server.post('/oauth/token',oauthFilter);

server.get('/me',[oauthFilter,function(req,res){
  res.json(req.account);
}]);

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.

Group Filter

Use this filter to assert group membership of the authenticated account:

var trustedFilter = stormpathFilters.createGroupFilter({
  inGroup: 'trusted'
});

server.del('/things/:id',[oauthFilter,trustedFilter,function(req,res,next){
  // handle resource delete request
}]);

Registration Filter

This filter will accept a JSON POST, which must have the following properties:

• surname
• givenName
• email
• password

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.newAccountFilter();

server.post('/accounts',newAccountFilter);

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.accountVerificationFilter();

server.get('/verifyAccount',accountVerificationFilter);

Error Handling

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 errorHandler 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: (err,req,res,next)

Example usage:

var trustedFilter = stormpathFilters.createGroupFilter({
  inGroup: 'trusted',
  errorHandler: function(err,req,res,next){
    res.json(403,{
      message:'You must apply for access to the Trusted users group'
    });
  }
});

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.createFilterSet({
  errorHandler: function(err,req,res,next){
    // all your error are belong to me
  }
});