Stormpath User Management

This add-on is operated by Stormpath

User Management for Developers

Stormpath User Management

Last Updated: 19 March 2014

Table of Contents

Stormpath is a REST+JSON API service that automates authentication, access control and common security workflows (such as Password Reset and Account Email Verification) for your applications. The Stormpath Heroku add-on allows you to use Stormpath easily in a Heroku application. Stormpath provides the following for your applications:

  • Account registration, complete with sending welcome emails.
  • Account email verification (send email -> user clicks a link -> their account is verified and they can login).
  • Secure password storage with continuously updated cryptography best practices.
  • Password reset (send email -> user clicks a link -> sets new password -> account password encrypted and stored securely).
  • Account login (aka authentication).
  • Seamless integration with LDAP and Active Directory - you’ll never have to worry about integrating your application with them again.
  • A complete administrative user interface to allow you to manage your applications, directories, accounts and groups.
  • And more

When building your applications in the past, how much time have you spent writing some or all of this functionality? It is quite a large amount of work, and this logic has nothing to do with why you’re writing your application! But you need it, and you need it to be secure. By offloading all of this effort to Stormpath, a service with deep security roots, you can quickly get back to writing your actual application and never worry about password attacks again.

Stormpath is a highly-available and secure service accessible via a web UI administration console or REST/JSON API. While any REST-client can use Stormpath, Stormpath also provides pre-built client libraries for Ruby, Java, Python and PHP.

Installing the Stormpath Heroku Add-On

You can add Stormpath to a Heroku application via the CLI:

A list of all plans available can be found here.
$ heroku addons:add stormpath --app YOUR_APPLICATION_NAME
-----> Adding stormpath to sharp-mountain-4005... done, v18 (free)

Once Stormpath has been added, the following settings will be available in the app configuration:

  • STORMPATH_URL: the canonical URL used to access Stormpath for your application
  • STORMPATH_API_KEY_ID: the REST API key ID (aka username) to use when communicating with the Stormpath REST API
  • STORMPATH_API_KEY_SECRET: the REST API key secret value (aka password) to use when communicating with the Stormpath REST API

You can confirm this using the heroku config:get command.

$ heroku config:get STORMPATH_URL
https://api.stormpath.com/v1/applications/YoUrStOrMPaThApPlICAtiOnId

$ heroku config:get STORMPATH_API_KEY_ID
5IFE9WD86423ZPOV8IEXAMPLE

$ heroku config:get STORMPATH_API_KEY_SECRET
0Fx+Ebqns9OWBO5lbHce6FAYTUtnSpYwcQ+DEXAMPLE

After provisioning Stormpath the application should be configured to fully integrate with the add-on.

Local workstation setup

After provisioning the Stormpath add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export STORMPATH_URL=value, export STORMPATH_API_KEY_ID=value and export STORMPATH_API_KEY_SECRET=value.

Use Foreman to reliably configure and run the process formation specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the STORMPATH_* values retrieved from heroku config to .env.

$ heroku config --app YOUR_APPLICATION_NAME -s | grep STORMPATH_URL >> .env
$ heroku config --app YOUR_APPLICATION_NAME -s | grep STORMPATH_API_KEY_ID >> .env
$ heroku config --app YOUR_APPLICATION_NAME -s | grep STORMPATH_API_KEY_SECRET >> .env
$ more .env

Credentials and other sensitive configuration values (such as the STORMPATH_API_KEY_* values) should NOT be committed to source-control! In Git exclude the .env file with: echo .env >> .gitignore.

Use with Ruby

Stormpath has created an excellent Ruby Stormpath SDK

Ruby applications will need to add the following entry into their Gemfile specifying the Stormpath client library.

gem 'stormpath-sdk', '>=1.0.0.beta.2'

Update application dependencies with bundler. Specify the latest version available.

$ bundle install
Installing stormpath-sdk (X.Y.Z)

Connect your application

When you add Stormpath to your Heroku application, Stormpath creates a record of the application so it can secure users for it. You need to access that Stormpath Application record to perform further actions:

require "stormpath-sdk"
...

api_key = Stormpath::ApiKey.new(ENV['STORMPATH_API_KEY_ID'], ENV['STORMPATH_API_KEY_SECRET'])
client = Stormpath::Client.new(api_key: api_key)

application = client.applications.get ENV['STORMPATH_URL']

The Client and Application instances should be shared across your code where needed. Avoid creating multiple client instances as this will eliminate caching and performance enhancements made by the client implementation.

You will work mostly with the application instance, but sometimes you’ll need to the client instance for general-purpose work, like instantiating new objects and other ‘meta’ tasks.

Now that you have a reference for your Application, you can easily authenticate users, reset passwords, and more. See the sections below for examples.

Register a new user account

When you want to create a new user for your application, you create an Account resource. Set (at a minimum) a first name, last name, email and password. For example, you might have a web-based registration form that an end-user visits and populates:

account = application.accounts.create({
  given_name: 'John',
  surname: 'Smith',
  email: 'john.smith@example.com',
  username: 'johnsmith', # this isn't strictly necessary.  Defaults to email if not provided.
  password: 'ChangeMe0!'
})

Also, it is very important to store the newly created Account’s HREF in your application’s data model so you can look up the account later. You can think of Stormpath HREFs as IDs. For example:

my_user = User.new username, email, given_name, surname
my_user.stormpath_href = account.href
my_user.save

Authenticate a user account

When your user tries to login to your application, you forward that attempt to Stormpath:

# get the user account's submitted username and password however you need to
# BUT ONLY OVER SSL/TLS!  Keep your logins secure!

authc_request = Stormpath::Authentication::UsernamePasswordRequest.new 'johnsmith', 'ChangeMe0!'

begin
  authc_result = application.authenticate_account authc_request
  account = authc_result.account
rescue Stormpath::Error => e
  #If credentials are invalid or account doesn't exist
end

Retrieve a user account

If you need to lookup an Account, you can access it using the Account’s HREF property that you store in your application’s data model after account registration:

account_href = my_user.stormpath_href
account = application.accounts.get account_href

Update a user account

If you need to change properties on the Account (e.g. surname, email, etc), just set the values and call save():

account.given_name = 'Joe'
account.save

Heroku sample application

There is a simple Heroku sample application that you can see and get a good idea on how to set things up.

You can find it here: stormpath-heroku-ruby-sample

Next steps

What you’ve seen here is just a small introduction to Stormpath’s full offering using the Ruby SDK. There are many more features available to the SDK (and the backing REST API), such as querying, group management for access control, LDAP integration, and much more.

Now that you have your Heroku application working with Stormpath, please see the complete Stormpath Ruby Product Guide to learn about everything you can do with the Stormpath Ruby SDK.