stormpath-rails 2.2.0 → 2.3.0

data/docs/index.rst

@@ -0,0 +1,31 @@
+Stormpath Rails Gem Guide
+=============================
+
+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.
+
+Stormpath makes it incredibly simple to add users and user data to your application. It aims to completely abstract away all user registration, login, authentication, and authorization problems, and make building secure websites painless.
+And the best part? **You don't even need a database!**
+
+User Guide
+----------
+
+This part of the documentation will show you how to get started with the Stormpath Rails Gem. If you're new to the gem, start here!
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   quickstart
+   configuration
+   user_data
+   authentication
+   registration
+   login
+   social_login
+   logout
+   password_reset
+   devise_import
+   templates
+   help
+   contributors
+   changelog

data/docs/login.rst

@@ -0,0 +1,242 @@
+.. _login:
+
+
+Login
+=====
+
+By default this gem will serve an HTML login page at ``/login``.  You can
+change this URI with the ``web.login.uri`` option.  You can disable this feature
+entirely by setting ``web.login.enabled`` to ``false``.
+
+To view the default page in your example application, navigate to this URL:
+
+http://localhost:3000/login
+
+If the login attempt is successful, we will send the user to the Next URI and
+create the proper session cookies.
+
+
+Next URI
+--------
+
+The form will render with two fields for login and password, and this form
+will be posted to ``/login``.  If login is successful, we will redirect the user
+to ``/``.  If you wish to change this, use the ``nextUri`` config option::
+
+.. code-block:: yaml
+
+      web:
+        login:
+          enabled: true,
+          nextUri: "/dashboard"
+
+
+Form Customization
+------------------
+
+The label and placeholder values can be changed by modifying the login form
+field configuration:
+
+.. code-block:: yaml
+
+    web:
+      login:
+        form:
+          fields:
+            login:
+              label: 'Your Username or Email',
+              placeholder: 'email@trustyapp.com'
+            password:
+              label: 'Your super-secure PAssw0rd!'
+
+
+Controller private & helper methods
+-----------------------------------
+
+The Application Controller gets the ``Stormpath::Rails::Controller`` module included by default. The module provides 4 private controller methods:
+
+- ``current_account`` - get the current account
+- ``signed_in?`` - check if the user is signed in.
+- ``require_authentication!`` - a before action to stop unauthenticated access.
+- ``require_no_authentication!`` - a before action to stop authenticated access (a logged in user shouldn't be able to see the login form).
+
+By default, the ``current_account`` and ``signed_in?`` are marked as helper_methods and you can use them in your views.
+
+If you wish to add these methods to a controller that doesn't inherit from the ApplicationController, just include the ``Stormpath::Rails::Controller`` module in that controller as well.
+
+
+.. _json_login_api:
+
+JSON Login API
+--------------
+
+If you want to make a login attempt from a front-end application (Angular, React),
+simply post a JSON body to the ``/login`` endpoint, with the following format::
+
+    {
+      "login": "foo@bar.com",
+      "password": "myPassword"
+    }
+
+If the login attempt is successful, you will receive a 200 OK response and the
+session cookies will be set on the response.  If there is an error we will
+send a 400 status with an error message in the body.
+
+If you make a GET request to the login endpoint, with ``Accept:
+application/json``, we will send you a JSON view model that describes the login
+form and the social account stores that are mapped to your Stormpath
+Application.  Here is an example view model that shows you an application that
+has a default login form, and a mapped Google directory:
+
+.. code-block:: javascript
+
+  {
+    "accountStores": [
+      {
+        "name": "stormpath-rails google",
+        "href": "https://api.stormpath.com/v1/directories/gc0Ty90yXXk8ifd2QPwt",
+        "provider": {
+          "providerId": "google",
+          "href": "https://api.stormpath.com/v1/directories/gc0Ty90yXXk8ifd2QPwt/provider",
+          "clientId": "422132428-9auxxujR9uku8I5au.apps.googleusercontent.com",
+          "scope": "email profile"
+        }
+      }
+    ],
+    "form": {
+      "fields": [
+        {
+          "label": "Username or Email",
+          "placeholder": "Username or Email",
+          "required": true,
+          "type": "text",
+          "name": "login"
+        },
+        {
+          "label": "Password",
+          "placeholder": "Password",
+          "required": true,
+          "type": "password",
+          "name": "password"
+        }
+      ]
+    }
+  }
+
+
+Overriding Login
+----------------
+
+Controllers
+...........
+
+Since Stormpath controllers are highly configurable, they have lots of configuration code and are not written in a traditional way.
+
+A LoginController would usually have two actions - new & create, however in Stormpath-Rails they are separated into two single action controllers - ``Stormpath::Rails::Login::NewController`` and ``Stormpath::Rails::Login::CreateController``.
+They both respond to a ``call`` method (action).
+
+To override a Stormpath controller, first you need to subclass it:
+
+.. code-block:: ruby
+
+    class CreateSessionController < Stormpath::Rails::Login::CreateController
+    end
+
+
+and update the routes to point to your new controller:
+
+.. code-block:: ruby
+
+    Rails.application.routes.draw do
+      stormpath_rails_routes(actions: {
+        'login#create' => 'create_session#call'
+      })
+    end
+
+
+Routes
+------
+
+To override routes (while using Stormpath default controllers), please use the configuration file ``config/stormpath.yml`` and override them there.
+As usual, to see what the routes are, run *rake routes*.
+
+Views
+-----
+
+You can use the Stormpath views generator to copy the default views to your application for modification:
+
+.. code-block:: ruby
+
+    rails generate stormpath:views
+
+
+which generates these files::
+
+    stormpath/rails/layouts/stormpath.html.erb
+
+    stormpath/rails/login/new.html.erb
+    stormpath/rails/login/_form.html.erb
+
+    stormpath/rails/register/new.html.erb
+    stormpath/rails/register/_form.html.erb
+
+    stormpath/rails/change_password/new.html.erb
+
+    stormpath/rails/forgot_password/new.html.erb
+
+    stormpath/rails/shared/_input.html.erb
+
+    stormpath/rails/verify_email/new.html.erb
+
+
+Using ID Site
+----------------------------------------------------------------------
+
+Stormpath provides a hosted login application, known as ID Site.  This feature
+allows you to redirect the user to our hosted application.  When the user
+authenticates, they will be redirected back to your application with an identity
+assertion.
+
+This feature is useful if you don't want to modify your application to serve
+web pages or single page apps, and would rather have that hosted somewhere else.
+
+ID site looks like this:
+
+.. image:: /_static/id-site-login.png
+
+
+ID Site Configuration
+.....................
+
+If you wish to use the ID Site feature, you will need to log in to the
+`Stormpath Admin Console`_ and configure the settings.  You need to change the
+**Authorized Redirect Uri** setting and set it to
+``http://localhost:3000/id_site_result`` in order to instruct Stormpath about the resource that
+handles all ID Site requests from Stormpath to your application. For example, if you want to support logging out
+of your application via ID Site, then you need to set the route to which you want to be redirected after a successful logout:
+
+.. image:: /_static/id-site-stormpath-config.png
+
+Then you want to enable ID Site in your rails stormpath configuration:
+
+.. code-block:: yaml
+
+      web:
+        idSite:
+          enabled: true
+          loginUri: ""
+          forgotUri: "/#/forgot"
+          registerUri: "/#/register"
+
+
+When ID Site is enabled, any request for ``/login`` or ``/register`` will cause a
+redirect to ID Site.  When the user is finished at ID Site they will be
+redirected to `/id_site_result` on your application.  Our gem will handle
+this request, and then redirect the user to the ``nextUri``.
+
+For more information about how to use and customize the ID site, please see
+this documentation:
+
+http://docs.stormpath.com/guides/using-id-site/
+
+.. _Stormpath Admin Console: https://api.stormpath.com

data/docs/logout.rst

@@ -0,0 +1,73 @@
+.. _logout:
+
+
+Logout
+======
+
+If you are using browser-based sessions, you'll need a way for the user to
+logout and destroy their session cookies.
+
+By default this library will automatically provide a POST route at ``/logout``.
+Simply make a POST request to this URL and the session cookies will be
+destroyed.
+
+On a Rails application, this can usually be achieved with the following snippet in a view file:
+
+.. code-block:: ruby
+
+    <% if signed_in? %>
+      <p>Logged in as: <%= current_account.given_name %></p>
+      <%= link_to "Log out", logout_path, method: :post %>
+    <% end %>
+
+
+Configuration Options
+---------------------
+
+If you wish to change the logout URI or the redirect url, you can provide the
+following configuration:
+
+.. code-block:: yaml
+
+    web:
+      logout:
+        enabled: true,
+        uri: '/log-me-out',
+        nextUri: '/goodbye'
+
+
+Overriding Logout
+-----------------
+
+Controllers
+...........
+
+Since Stormpath controllers are highly configurable, they have lots of configuration code and are not written in a traditional way.
+
+Logging out users is usually done with just a destroy method in some kind of SessionController, but in Stormpath we strive for high configuration so we
+are handling this with a LogoutController that has one method ``create`` which responds to the ``call`` method.
+
+To override a Stormpath controller, first you need to subclass it:
+
+.. code-block:: ruby
+
+    class DestroySessionController < Stormpath::Rails::Logout::CreateController
+    end
+
+
+and update the routes to point to your new controller:
+
+.. code-block:: ruby
+
+    Rails.application.routes.draw do
+      stormpath_rails_routes(actions: {
+        'logout#create' => 'destroy_session#call'
+      })
+    end
+
+
+Routes
+------
+
+To override routes (while using Stormpath default controllers), please use the configuration file ``config/stormpath.yml`` and override them there.
+As usual, to see what the routes are, run *rake routes*.

data/docs/password_reset.rst

@@ -0,0 +1,85 @@
+.. _password_reset:
+
+
+Password Reset
+==============
+
+Stormpath provides a self-service password reset flow for your users, allowing
+them to request a link that lets them reset their password.  This is a very
+secure feature and we highly suggest it for your application.
+
+
+Enable the Workflow
+-------------------
+
+To use the password reset workflow, you need to enable it on the directory
+that your application is using.  Login to the `Stormpath Admin Console`_ and
+find your directory, then navigate to the workflows section of that directory.
+
+Enable the password reset email if it is disabled.
+
+You should also set the **Link Base Url** to be the following URL if you want the password reset form to be hosted on your domain:
+
+ .. code-block:: sh
+
+    http://localhost:3000/change
+
+You can leave the default URL if you want the user to be redirected to the Stormpath password reset page with the reset form: ``https://api.stormpath.com/passwordReset``
+
+
+Adjust Workflow in Config File
+------------------------------
+
+Make sure that you enable the workflow in your ``stormpath.yml`` configuration file
+
+.. code-block:: yaml
+
+    web:
+      forgotPassword:
+        enabled: true
+        uri: "/forgot"
+        view: "stormpath/rails/forgot_password/new"
+        nextUri: "/login?status=forgot"
+      changePassword:
+        enabled: true
+        autoLogin: false
+        uri: "/change" # make sure the URI matches the one you stored in the Stormpath dashboard as the Link Base Url
+        nextUri: "/login?status=reset"
+        view: "stormpath/rails/change_password/new"
+        errorUri: "/forgot?status=invalid_sptoken"
+
+
+You may also change the URLs of the pages in this workflow, as well as the redirect URLs that we use during the workflow.
+If so, just make sure that you apply the changes to the **Link Base Url** in the Stormpath dashboard, and restart your server.
+
+Using the Workflow
+------------------
+
+After enabling the workflow, restart your Rails application.  You can now
+complete a password reset workflow by doing the following steps:
+
+* The login form at ``/login`` will show a "Forgot Password?" link.
+* Clicking that link will take you to ``/forgot``, where you can ask for a password reset email
+* After you receive the email, clicking on the link will take you to ``/change``
+* You'll see a form that allows you to change your password
+* After changing your password, you are taken to the login form
+
+
+
+Auto Login
+----------
+
+Our gem implements the most secure workflow by default: the user must
+request a password reset link, then login again after changing their password.
+We recommend these settings for security purposes, but if you wish to automatically
+log the user in after they reset their password you can enable that functionality
+with this option:
+
+ .. code-block:: yaml
+
+      web:
+        changePassword:
+          autoLogin: false
+
+
+.. _Stormpath Admin Console: https://api.stormpath.com

data/docs/quickstart.rst

@@ -0,0 +1,179 @@
+.. _quickstart:
+
+
+Quickstart
+=============================
+
+This section walks you through the basic setup for Stormpath Rails gem, by the end
+of this page you'll have setup the login and registration features for your
+Rails application!
+
+Create a Stormpath Account
+--------------------------
+
+Now that you've decided to use Stormpath, the first thing you'll want to do is
+create a new Stormpath account: https://api.stormpath.com/register
+
+
+Create an API Key Pair
+----------------------
+
+Once you've created a new account you need to create a new API key pair. A new
+API key pair is easily created by logging into your dashboard and clicking the
+"Create an API Key" button. This will generate a new API key for you, and
+prompt you to download your key pair.
+
+.. note::
+    Please keep the API key pair file you just downloaded safe!  These two keys
+    allow you to make Stormpath API requests, and should be properly protected,
+    backed up, etc.
+
+Once you've downloaded your `apiKey.properties` file, save it and be sure to set up the following environment variables:
+
+ - STORMPATH_API_KEY_ID
+ - STORMPATH_API_KEY_SECRET
+
+Environment variables should be set up in you .bashrc file (or .zshrc if you use myzsh).
+
+Example setup:
+
+.. code-block:: sh
+
+    export STORMPATH_API_KEY_ID=6U4HZMHGVHN0U765BGW
+    export STORMPATH_API_KEY_SECRET=0e0TuVZKYiPiLTDLNnswEwpPpa5nPv
+
+Find Your Stormpath Application
+-------------------------------
+
+All new Stormpath Tenants will have a Stormpath Application, called
+"My Application". You'll generally want one application per project, and we can
+use this default application to get started.
+
+An application has a HREF, and it looks like this:
+
+.. code-block:: sh
+
+    https://api.stormpath.com/v1/applications/24kkU5XOz4tQlZ7sBtPUN6
+
+From inside the `Admin Console`_, you can find the HREF by navigating to the
+Application in the Application's list.
+
+To learn more about Stormpath Applications, please see the
+`Application Resource`_ and
+`Setting up Development and Production Environments`_
+
+.. note::
+    Your default Application will also have a directory mapped to it. The
+    Directory is where Stormpath stores accounts. To learn more, please see
+    `Directory Resource`_ and `Modeling Your User Base`_.
+
+- Make sure your application has a default account directory.
+
+Now that you have your application HREF, make sure to set up another environment variable:
+
+.. code-block:: sh
+
+    export STORMPATH_APPLICATION_URL=https://api.stormpath.com/v1/applications/24kkU5XOz4tQlZ7sBtPUN6
+
+
+You're ready to bundle Stormpath Rails gem into your project!
+
+Install the Gem
+-------------------
+
+Now that you've got a Stormpath account all setup and ready to go, all that's
+left to do before we can dive into the code is install the gem.
+
+Stormpath Rails officially supports Ruby versions over 2.1.0 and Rails over 4.0.
+
+Add the stormpath-rails integration gem to your Gemfile.
+
+Stormpath is currently in beta so it is necessary to include the gem version:
+
+.. code-block:: ruby
+
+    gem 'stormpath-rails', '~> 2.0.0'
+
+Bundle the Gemfile
+
+.. code-block:: ruby
+
+    bundle install
+
+Run the generator to insert the config yaml file and the neccessary controller module.
+
+.. code-block:: sh
+
+    rails generate stormpath:install
+
+
+Routes configuration
+----------------------------
+
+Make sure that you have the `root_path` defined in your rails `routes.rb`
+
+Then, add `stormpath_rails_routes` to your routes.rb file.
+
+.. code-block:: ruby
+
+    Rails.application.routes.draw do
+      root 'home#index'
+      stormpath_rails_routes
+      ...
+    end
+
+
+Start your server
+----------------------------
+
+Yes, that's it.
+
+With this minimal configuration, our library will do the following:
+
+- Fetch your Stormpath Application and all the data about its configuration and
+  account stores.
+
+- Attach the default features to your Rails application, such as the
+  login page and registration page.
+
+- Hold any requests that require authentication, until Stormpath is ready.
+
+That's it, you're ready to go! Try navigating to these URLs in your application:
+
+- http://localhost:3000/login
+- http://localhost:3000/register
+
+You should be able to register for an account and log in. The newly created
+account will be placed in the directory that is mapped to "My Application".
+
+.. note::
+
+    By default, we don't require email verification for new accounts, but we
+    highly recommend you use this workflow. You can enable email verification
+    by logging into the `Admin Console`_ and going to the the Workflows tab
+    for the directory of your Stormpath Application.
+
+There are many more features than login and registration, please continue to the
+next section to learn more!
+
+
+Example Applications
+--------------------
+
+Looking for some example applications?  We provide the following examples
+applications to get you up and running quickly.  They show you how to setup
+Stormpath, and implement a profile page for the logged-in user:
+
+- `Stormpath-Rails Sample Project`_
+
+- `Stormpath Angular + Rails Sample Project`_
+
+.. _Admin Console: https://api.stormpath.com/login
+.. _Application Resource: https://docs.stormpath.com/rest/product-guide/latest/reference.html#application
+.. _Active Directory: http://en.wikipedia.org/wiki/Active_Directory
+.. _Directory Resource: https://docs.stormpath.com/rest/product-guide/latest/reference.html#directory
+.. _Stormpath-Rails Sample Project: https://github.com/stormpath/stormpath-rails-sample
+.. _LDAP: http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol
+.. _Modeling Your User Base: https://docs.stormpath.com/rest/product-guide/latest/accnt_mgmt.html#modeling-your-user-base
+.. _Setting up Development and Production Environments: https://docs.stormpath.com/guides/dev-test-prod-environments/
+.. _Stormpath Angular + Rails Sample Project: https://github.com/stormpath/stormpath-angular-rails-sample