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.
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.
-
Navigate to where you'd like to start your new app.
-
Use Rails to create a new application and cd into it:
rails new myApp cd myApp
-
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
-
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'
-
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"
-
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.
-
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"
-
Navigate to your application's directory.
-
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
. -
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
-
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
-
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
- 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.
You can make your own contributions by forking the development
branch, making your changes, and issuing pull-requests on the
development
branch.
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
- 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 © 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.