stormpath-rails 2.2.0 → 2.3.0

data/docs/conf.py

@@ -0,0 +1,346 @@
+# -*- coding: utf-8 -*-
+#
+# Stormpath Rails Documentation documentation build configuration file, created by
+# sphinx-quickstart on Tue Sep 20 12:56:07 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.imgmath',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Stormpath Rails Documentation'
+copyright = u'2016, Stormpath, Inc.'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'0.1'
+# The full version, including alpha/beta/rc tags.
+release = u'0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#
+# today = ''
+#
+# Else, today_fmt is used as the format for a strftime call.
+#
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+# todo_include_todos = True
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'stormpath'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = ['_themes']
+
+# The name for this set of Sphinx documents.
+# "<project> v<release> documentation" by default.
+#
+# html_title = u'Stormpath Rails Documentation v0.1'
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#
+# html_logo = None
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#
+# html_extra_path = []
+
+# If not None, a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+# The empty string is equivalent to '%b %d, %Y'.
+#
+# html_last_updated_fmt = None
+highlight_language = 'javascript'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#
+html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+#
+# html_domain_indices = True
+
+# If false, no index is generated.
+#
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
+#
+# html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# 'ja' uses this config value.
+# 'zh' user can custom change `jieba` dictionary path.
+#
+# html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#
+# html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Rails-Stormpathdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'Rails-Stormpath.tex', u'Rails-Stormpath Documentation',
+     u'Stormpath, Inc.', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+#
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#
+# latex_appendices = []
+
+# It false, will not define \strong, \code, 	itleref, \crossref ... but only
+# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
+# packages.
+#
+# latex_keep_old_macro_names = True
+
+# If false, no module index is generated.
+#
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'rails-stormpath', u'Rails-Stormpath Documentation',
+     [u'Stormpath, Inc.'], 1)
+]
+
+# If true, show URL addresses after external links.
+#
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  (master_doc, 'Rails-Stormpath', u'Rails-Stormpath Documentation',
+   u'Stormpath, Inc.', 'Rails-Stormpath', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+#
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#
+# texinfo_no_detailmenu = False

data/docs/configuration.rst

@@ -0,0 +1,151 @@
+.. _configuration:
+
+
+Configuration
+=============
+
+This module provides several options that allow you to customize the authentication
+features of your Rails application. We will cover the major options in this
+section, and more specific options in later sections of this guide.
+
+If you would like a list of all available options, please refer to the
+`Web Configuration Defaults`_ file in the library. This YAML file has comments
+which describe each option and the value represents the option default.
+
+
+Environment Variables
+---------------------
+
+It is a best practice to store confidential information in environment
+variables (*don't hard-code it into your application*). You should store your
+confidential Stormpath information in environment variables.  You can do this
+by running the following commands in the shell:
+
+.. code-block:: bash
+
+    export STORMPATH_API_KEY_ID=YOUR_ID_HERE
+    export STORMPATH_API_KEY_SECRET=YOUR_SECRET_HERE
+    export STORMPATH_APPLICATION_URL=YOUR_APP_HREF
+
+or by using any text editor and adding the environment variables to .bashrc (or .zshrc if you're using ohmyzsh)
+
+.. note::
+    If you're on Windows, the command you need to use to set environment
+    variables is:
+
+    .. code-block:: bash
+
+        set STORMPATH_API_KEY_ID=YOUR_ID_HERE
+        set STORMPATH_API_KEY_SECRET=YOUR_SECRET_HERE
+        set STORMPATH_APPLICATION_URL=YOUR_APP_HREF
+
+The examples above show you the 3 mandatory settings you need to configure to
+make stormpath-rails work.  These settings can be configured via environment
+variables, or in a number of other ways.
+
+.. note::
+
+    If you're using Heroku you don't need to specify the credentials or
+    your application -- these values will be automatically provided for you.
+
+.. tip::
+
+    You might also want to check out
+    `autoenv <https://github.com/kennethreitz/autoenv>`_, a project that makes
+    working with environment variables simpler for Linux/Mac/BSD users.
+
+
+Default Features
+----------------
+
+When you add stormpath_rails_routes to your routes configuration file,
+our module will automatically add the following routes to your application:
+
++--------------+-------------------------------------------------------------+---------------------------+
+| URI          | Purpose                                                     | Documentation             |
++==============+=============================================================+===========================+
+| /forgot      | Request a password reset link.                              | :ref:`password_reset`     |
++--------------+-------------------------------------------------------------+---------------------------+
+| /login       | Login to your application with username and password.       | :ref:`login`              |
++--------------+-------------------------------------------------------------+---------------------------+
+| /logout      | Accepts a POST request, and destroys the login session.     | :ref:`logout`             |
++--------------+-------------------------------------------------------------+---------------------------+
+| /me          | Returns a JSON representation of the current user.          | :ref:`me_api`             |
++--------------+-------------------------------------------------------------+---------------------------+
+| /oauth/token | Issue OAuth2 access and refresh tokens.                     | :ref:`authentication`     |
++--------------+-------------------------------------------------------------+---------------------------+
+| /register    | Create an account within your application.                  | :ref:`registration`       |
++--------------+-------------------------------------------------------------+---------------------------+
+| /reset       | Reset an account password, from a password reset link.      | :ref:`password_reset`     |
++--------------+-------------------------------------------------------------+---------------------------+
+| /verify      | Verify a new account, from a email verification link.       | :ref:`email_verification` |
++--------------+-------------------------------------------------------------+---------------------------+
+
+Each feature has its own options, please refer to the documentation of each
+feature. If you want to disable specific features, continue to the next
+section.
+
+Disabling Features
+------------------
+
+We enable many features by default, but you might not want to use all of them.
+For example, if you wanted to disable all the default features, you would use
+this configuration:
+
+ .. code-block:: yaml
+
+    stormpath:
+      web:
+        login:
+          enabled: false
+        logout:
+          enabled: false
+        me:
+          enabled: false
+        oauth2:
+          enabled: false
+        register:
+          enabled: false
+
+
+
+Stormpath Client Options
+------------------------
+
+By using this gem you are able to instantiate a client object.
+The Stormpath client is responsible for communicating with the Stormpath REST
+API and is provided by the `Stormpath Ruby SDK`_. If you would like to work directly with the client in your Rails application,
+you can fetch it from the app object like this:
+
+ .. code-block:: ruby
+
+    client = Stormpath::Rails::Client.client
+
+The `client` object is also highly configurable through the use of the Ruby SDK. You can set how it is instantiated, custom caching options and the base URL for your enterprise application.
+For more detail concerning the `client` object, please visit the `Ruby SDK Documentation`_.
+
+Stormpath Application
+---------------------
+
+When you configured Stormpath, you specified the Stormpath Application that you
+want to use (you did this by providing the HREF of the application).  This gem
+will fetch the application and use it to perform all login, registration,
+verification and password reset functions.
+
+The Stormpath Application allows you to do a lot of other work, such as manually
+creating accounts and modifying your OAuth policy - plus much more!  If you want
+to work with the Stormpath Application, you can reference its object like this:
+
+.. code-block:: ruby
+
+    client = Stormpath::Rails::Client.client
+    application = client.applications.get(app_href)
+    application.accounts.create(account_attributes)
+
+where *app_href* is your application URL from Stormpath that you stored in a environment variable.
+
+.. _Web Configuration Defaults: https://github.com/stormpath/stormpath-rails/blob/master/lib/generators/stormpath/install/templates/default_config.yml
+.. _Stormpath applications: https://api.stormpath.com/v#!applications
+.. _Stormpath dashboard: https://api.stormpath.com/ui/dashboard
+.. _Stormpath Ruby SDK: https://github.com/stormpath/stormpath-sdk-ruby
+.. _Ruby SDK Documentation: https://docs.stormpath.com/ruby/product-guide/latest/configuration.html

data/docs/contributors.rst

@@ -0,0 +1,56 @@
+.. _contributors:
+
+
+Contributors
+============
+
+This project is written by various people at `Stormpath`_, and many lovely
+contributors.
+
+Without contributors, this project would look vastly different from the glorious
+project you see before you.  At Stormpath, we *love* our contributors, and you
+should too!
+
+The fabulous, smart, beautiful, and absurdly intelligent people below are
+directly responsible for making this project as awesome as it is today.
+
+**NOTE**: If you are contributing code to this project, please add yourself to
+the list below.  Then send us `an email`_ with a link to your contribution and
+your mailing address so we can ship you a swag bag!  Thank you for your hard
+work!
+
+
+Developers
+----------
+
+The people below have all contributed code to the project.
+
+
+Nenad Nikolić
+*************
+
+Nenad worked on the project since the beginning and has contributed major features to the project.
+
+- Github: https://github.com/nikone
+
+
+Damir Svrtan
+************
+
+Damir worked on the project since the beginning and has contributed major features to the project.
+
+- Website: http://damir.svrtan.me/
+- Github: https://github.com/DamirSvrtan
+- Twitter: https://twitter.com/damirsvrtan
+
+
+Marko Ćilimković
+****************
+
+Marko has contributed major features and is currently working on the development of the project.
+
+- Github: https://github.com/cilim
+- Twitter: https://twitter.com/MarkoCilimkovic
+
+.. _Stormpath: https://stormpath.com/
+.. _an email: info@stormpath.com

data/docs/devise_import.rst

@@ -0,0 +1,112 @@
+.. _devise_import:
+
+
+Import Data from Devise
+=======================
+
+If you already have a Rails application that uses devise and need to transfer all users, accounts, or however you named your model there's a nifty rake task that you can create in your codebase by running:
+
+.. code-block:: sh
+
+    rails generate stormpath:migration
+
+This will create a rake task that has the most common use cases for transferring user data into Stormpath that you can configure:
+
+.. code-block:: sh
+
+  lib/tasks/stormpath.rake
+
+
+Default Configuration
+----------------------
+
+This configuration is for the simplest migrations, where the goal is to just transfer all account information from devise's User model into one existing directory:
+
+.. code-block:: ruby
+
+  namespace :stormpath do
+    desc 'Migrate devise data to Stormpath'
+    task migrate: :environment do
+      directory_href = 'https://api.stormpath.com/v1/directories/4BjHtySIVQ8iwz96rguEE1'
+      directory = Stormpath::Rails::Client.client.directories.get(directory_href)
+
+      User.all.find_each do |user|
+        directory.accounts.create(
+          { username: "rex#{user.id}",
+            email: user.email,
+            given_name: 'Captain',
+            middle_name: '12345',
+            surname: 'Rex',
+            password: user.encrypted_password },
+          password_format: 'mcf'
+        )
+        puts "#{user.email} migrated to Stormpath directory: #{directory.name}"
+      end
+    end
+  end
+
+This is the minimal configuration needed to execute the migration successfully. All you need to do is set your `directory_href` which you can find by logging into the `Stormpath Admin Console`_ and viewing the directory you want to transfer your users into.
+Of course, make sure you use the correct name of the model for your users, accounts, members etc.
+
+
+New Application and Directory
+------------------------------
+
+You can also create a new application and directory in which you'll be storing your accounts, or, depending on account attributes, you could modify the script and migrate some accounts to one directory, and the rest to another.
+
+.. code-block:: ruby
+
+  application = Stormpath::Rails::Client.client.applications.create(name: 'Devise import',
+                                                                    description: 'Devise')
+
+  directory = Stormpath::Rails::Client.client.directories.create(name: 'devise import',
+                                                                 description: 'devise import'
+
+  # =>  Map the two together
+  Stormpath::Rails::Client.client.account_store_mappings.create(
+    application: application,
+    account_store: directory,
+    list_index: 0,
+    is_default_account_store: true,
+    is_default_group_store: false
+  )
+
+
+Custom Account Data
+--------------------
+
+If you have any custom user data that you need to keep stored on Stormpath, here's an example of how you can do that too:
+
+.. code-block:: ruby
+
+  User.all.find_each do |user|
+    account = directory.accounts.create(
+      { username: "rex{user.id}",
+        email: user.email,
+        given_name: 'Jean-Luc',
+        surname: 'Picard',
+        password: user.encrypted_password,
+        custom_data: {
+          rank: 'Captain',
+          favorite_drink: 'Earl Grey Tea'
+        } },
+      password_format: 'mcf'
+    )
+    puts "#{user.email} with custom data #{account.custom_data['favorite_drink']} migrated."
+  end
+
+For more information on account management, visit the `Account Management Chapter`_ or `Multitenancy Chapter`_.
+
+Migration Process
+---------------------
+
+When you're finished modifying the rake task execute it with:
+
+.. code-block:: sh
+
+  rake stormpath:migrate
+
+
+.. _Stormpath Admin Console: https://api.stormpath.com/login
+.. _Account Management Chapter: https://docs.stormpath.com/ruby/product-guide/latest/accnt_mgmt.html
+.. _Multitenancy Chapter: https://docs.stormpath.com/ruby/product-guide/latest/multitenancy.html

data/docs/help.rst

@@ -0,0 +1,24 @@
+.. _help:
+
+
+Getting Help
+============
+
+Have a question you can't find an answer to?  Things not working as expected?
+We can help!
+
+All of the official Stormpath client libraries (*including this one!*) are
+officially supported by Stormpath's incredibly amazing-and-hip support team!
+
+If you have a question, or need in-depth technical help, you can drop us an
+email anytime: support@stormpath.com
+
+If you visit our website (https://stormpath.com/), you can also click the "Chat
+with us!" button near the bottom right of the page to chat with us live, in
+real-time!
+
+And lastly, we're always available via Twitter as well!  We're `@gostormpath`_
+on Twitter.
+
+
+.. _@gostormpath: https://twitter.com/gostormpath