Stormpath Rails Gem

Stormpath is the first easy, secure user management and authentication service for developers. This is the Rails gem to ease integration of its features with any Rails-based application.

Assumptions

The bulk of this guide assumes that you are creating a new Rails application from scratch and want to user Stormpath for user management out of the box. If you have an existing application into which you want to integrate Stormpath, and that application already has the notion of a user in it, skip to the "Sign Up For A Stormpath Account" section.

Setup

Create A New Rails Application

1. Navigate to where you'd like to start your new app.

2. Use Rails to create a new application and cd into it:

   rails new myApp
   cd myApp
   

3. Initialize your application's database and create a "User" object

   rake db:create
   rails generate scaffold User username:string email:string given_name:string middle_name:string surname:string password:string
   rake db:migrate
   

4. Delete the public HTML file (public/index.html) if it exists and modify your "routes.rb" file (app/config) to point to your user controller:

   root :to => 'users#index'
   

Sign Up For A Stormpath Account

1. Create a Stormpath developer account and create your API Keys downloading the "apiKey.properties" file into a ".stormpath" folder under your local home directory. So that the Rails gem knows where to find this file, add an environment variable called STORMPATH_API_KEY_FILE_LOCATION whose value is the full path to this new .properties file:

   export STORMPATH_API_KEY_FILE_LOCATION="/Users/john/.stormpath/apiKey.properties"
   

2. Within Stormpath's Admin Console, create an application and a directory to store your users' accounts through the Stormpath Admin interface. Make sure to add the newly-created directory as a Account Store for your newly-created application.

3. Through the Stormpath Admin interface, note your application's REST URL. You'll want to create an environment variable called "STORMPATH_APPLICATION_URL" whose value is this URL. For example, add into your ~/.bashrc file on OS X:

   export STORMPATH_APPLICATION_URL="https://api.stormpath.com/v1/applications/YOUR_APP_ID"
   

Integrate Stormpath Rails

1. Navigate to your application's directory.

2. Install the stormpath-rails gem, either via the command line...

   $ gem install stormpath-rails --pre
   

   ...or adding the gem to your application's Bundler Gemspec.

   gem "stormpath-rails", "~> 1.0.0.beta.2"
   

   If you're running Rails > 4.0, you'll also need to add the following gem:

   gem "protected_attributes"
   

   Then, run bundle install.

3. Generate and run the migration script in the root of your application directory. Skip this step if you've configured your app to use Mongoid instead of ActiveRecord.

   rails g stormpath:rails:migration user
   rake db:migrate
   

4. Update your "user" model file (e.g., user.rb) under app/models/ as follows:

   require 'stormpath-rails'
   class User < ActiveRecord::Base
     include Stormpath::Rails::Account
   end
   

5. Modify any views that interact with the user controller and model (e.g., create, edit, etc.) to use the specific fields specific to Stormpath's notion of a user:

   • username
   • email
   • given_name
   • middle_name
   • surname
   • password

For example, if you have a form for your editing your user object, you'll need to change the view (e.g., app/views/users/_form.html.erb) to include something like the following:

  <div class="field">
    <%= f.label :username %><br />
    <%= f.text_field :username %>
  </div>
  <div class="field">
    <%= f.label :email %><br />
    <%= f.text_field :email %>
  </div>
  <div class="field">
    <%= f.label :given_name %><br />
    <%= f.text_field :given_name %>
  </div>
  <div class="field">
    <%= f.label :middle_name %><br />
    <%= f.text_field :middle_name %>
  </div>
  <div class="field">
    <%= f.label :surname %><br />
    <%= f.text_field :surname %>
  </div>  
  <div class="field">
    <%= f.label :password %><br />
    <%= f.password_field :password %>
  </div>
  <div class="actions">
    <%= f.submit %>
  </div>

Now, start your local server with rails s and try to create a user (e.g., http://0.0.0.0:3000/users/new). You'll need to create a user in your application before you can authenticate it via your Ruby application.

Voila! Your application is now connected to Stormpath.

Contributing

You can make your own contributions by forking the development branch, making your changes, and issuing pull-requests on the development branch.

Building the Gem

To build and install the development branch yourself from the latest source:

$ git clone git@github.com:stormpath/stormpath-rails.git
$ cd stormpath-rails
$ gem build stormpath-rails.gemspec
$ gem install stormpath-rails-{version}.gem

TODO

• Automatic directory layout (test, development, production) creation.
• Preventive validation to not send invalid data to stormpath.
• Preventive validation to not send invalid data to stormpath.
• Solve n+1 request problem when requesting account collection.
• Get rake spec working properly with environment variables.

Copyright & Licensing

Copyright © 2013 Stormpath, Inc. and contributors.

This project is licensed under the Apache 2.0 Open Source License.

For additional information, please see the full Project Documentation.