diff --git a/.gitignore b/.gitignore index a6f0c0b..e3b4ac4 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,4 @@ spec/dummy/db/development.sqlite3 spec/dummy/log/development.log spec/dummy/log/test.log spec/dummy/tmp -docs +docs/_build diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..70f5f19 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs/_themes/stormpath"] + path = docs/_themes/stormpath + url = https://github.com/stormpath/stormpath-sphinx-theme.git diff --git a/.travis.yml b/.travis.yml index 3555950..19cebac 100644 --- a/.travis.yml +++ b/.travis.yml @@ -21,7 +21,7 @@ after_success: - if [ "$CURRENT_HASH" = "$RELEASE_HASH" ]; then DEPLOY_DOCS=true; fi env: global: - - STORMPATH_APPLICATION_URL=https://api.stormpath.com/v1/applications/4BiS1Hc1LuBEbszdDrOwyz + - STORMPATH_APPLICATION_URL=https://api.stormpath.com/v1/applications/4xz3y2Hrid4aqp5YwbNTvk - secure: VMjIMI42vIPTMPTr0fnzSPiIjzuSAnT7iNWjhAXP9WsdaCmxwHp1vOlry4QuX8DzpKHv2MQubeUN/UA227Nk1xn+CVu9mujWOqvvjmL9m20wMJvwT4ctn7zG+FJK76id9TEyx0mCTlH4ZrRoDMGfM9yzhpsg8FtSebBDdHxePaM= - secure: IhR6H9qxmxCDNbLK0ebYuIXQRsGA/JhD6In4V/hnSMJ8lPi2kwRn6eKclNCHGNjcy6QF1V5vddKIfKOkFFZvIyP26reygTX1g5Mfa8SqTGKh3DAW4WP+T+yaE4z4UBDK1zZpbV0Zbkw/HC0xeD8UPnjRzERX1LVZp1qeEjhQrks= - secure: a5woUmOQPRW6FBQBaxKJATfggUD/BVTBfeRaS07u1SQOpMoGJZLY0m29PVx4fHwRD1E7ho31YIeH8wk1vMMrimIHSdE1B4pm4n8bUTi/gDFwavXq9KgTdH8f6Eli37nAXZum78m4NgL9+OlrKeJKCcROdzniZPvFaLrnOwBGzVs= diff --git a/CHANGELOG.md b/CHANGELOG.md index f0a3b83..fc613ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,10 +17,13 @@ Released on Nov 02, 2016 Version 2.0.2 ------------- Released on Aug 29, 2016 + - Render path links depending on the configuration - Use Faker to generate random test data - Rename all user instances to account +Version 2.0.1 +------------- Released on Aug 22, 2016 - Fix error when showing new_register_path on login page when register is disabled. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..159b0eb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Rails-Stormpath.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Rails-Stormpath.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Rails-Stormpath" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Rails-Stormpath" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/docs/_static/facebook-new-project.png b/docs/_static/facebook-new-project.png new file mode 100755 index 0000000..eac5be0 Binary files /dev/null and b/docs/_static/facebook-new-project.png differ diff --git a/docs/_static/facebook-url-settings.png b/docs/_static/facebook-url-settings.png new file mode 100755 index 0000000..5d35a1a Binary files /dev/null and b/docs/_static/facebook-url-settings.png differ diff --git a/docs/_static/forgot-change.png b/docs/_static/forgot-change.png new file mode 100755 index 0000000..b36ff32 Binary files /dev/null and b/docs/_static/forgot-change.png differ diff --git a/docs/_static/forgot-complete.png b/docs/_static/forgot-complete.png new file mode 100755 index 0000000..fa9fb7f Binary files /dev/null and b/docs/_static/forgot-complete.png differ diff --git a/docs/_static/forgot-email-sent.png b/docs/_static/forgot-email-sent.png new file mode 100755 index 0000000..12cff12 Binary files /dev/null and b/docs/_static/forgot-email-sent.png differ diff --git a/docs/_static/forgot-email.png b/docs/_static/forgot-email.png new file mode 100755 index 0000000..2412f57 Binary files /dev/null and b/docs/_static/forgot-email.png differ diff --git a/docs/_static/forgot-init.png b/docs/_static/forgot-init.png new file mode 100755 index 0000000..4c9f62c Binary files /dev/null and b/docs/_static/forgot-init.png differ diff --git a/docs/_static/forgot.png b/docs/_static/forgot.png new file mode 100755 index 0000000..5daf658 Binary files /dev/null and b/docs/_static/forgot.png differ diff --git a/docs/_static/github_create_app.png b/docs/_static/github_create_app.png new file mode 100644 index 0000000..515d98b Binary files /dev/null and b/docs/_static/github_create_app.png differ diff --git a/docs/_static/google-enable-login.png b/docs/_static/google-enable-login.png new file mode 100755 index 0000000..0b78680 Binary files /dev/null and b/docs/_static/google-enable-login.png differ diff --git a/docs/_static/google-new-project.png b/docs/_static/google-new-project.png new file mode 100755 index 0000000..9d82022 Binary files /dev/null and b/docs/_static/google-new-project.png differ diff --git a/docs/_static/google-oauth-settings.png b/docs/_static/google-oauth-settings.png new file mode 100755 index 0000000..f006960 Binary files /dev/null and b/docs/_static/google-oauth-settings.png differ diff --git a/docs/_static/id-site-login.png b/docs/_static/id-site-login.png new file mode 100755 index 0000000..545d30f Binary files /dev/null and b/docs/_static/id-site-login.png differ diff --git a/docs/_static/id-site-settings.png b/docs/_static/id-site-settings.png new file mode 100755 index 0000000..412bc37 Binary files /dev/null and b/docs/_static/id-site-settings.png differ diff --git a/docs/_static/id-site-stormpath-config.png b/docs/_static/id-site-stormpath-config.png new file mode 100644 index 0000000..08e0993 Binary files /dev/null and b/docs/_static/id-site-stormpath-config.png differ diff --git a/docs/_static/linkedin-add-authorized-urls.gif b/docs/_static/linkedin-add-authorized-urls.gif new file mode 100755 index 0000000..dceca37 Binary files /dev/null and b/docs/_static/linkedin-add-authorized-urls.gif differ diff --git a/docs/_static/linkedin-add-permissions.gif b/docs/_static/linkedin-add-permissions.gif new file mode 100755 index 0000000..f811114 Binary files /dev/null and b/docs/_static/linkedin-add-permissions.gif differ diff --git a/docs/_static/linkedin-new-application.gif b/docs/_static/linkedin-new-application.gif new file mode 100755 index 0000000..fcb8a18 Binary files /dev/null and b/docs/_static/linkedin-new-application.gif differ diff --git a/docs/_static/linkedin-permissions-page.png b/docs/_static/linkedin-permissions-page.png new file mode 100755 index 0000000..94eec2a Binary files /dev/null and b/docs/_static/linkedin-permissions-page.png differ diff --git a/docs/_static/login-page-basic.png b/docs/_static/login-page-basic.png new file mode 100755 index 0000000..202b32b Binary files /dev/null and b/docs/_static/login-page-basic.png differ diff --git a/docs/_static/login-page-facebook-permissions.png b/docs/_static/login-page-facebook-permissions.png new file mode 100755 index 0000000..4e6b4c5 Binary files /dev/null and b/docs/_static/login-page-facebook-permissions.png differ diff --git a/docs/_static/login-page-facebook.png b/docs/_static/login-page-facebook.png new file mode 100755 index 0000000..433005a Binary files /dev/null and b/docs/_static/login-page-facebook.png differ diff --git a/docs/_static/login-page-google-account.png b/docs/_static/login-page-google-account.png new file mode 100644 index 0000000..63e7608 Binary files /dev/null and b/docs/_static/login-page-google-account.png differ diff --git a/docs/_static/login-page-google.png b/docs/_static/login-page-google.png new file mode 100755 index 0000000..4359371 Binary files /dev/null and b/docs/_static/login-page-google.png differ diff --git a/docs/_static/login-page-linkedin.png b/docs/_static/login-page-linkedin.png new file mode 100755 index 0000000..b89374d Binary files /dev/null and b/docs/_static/login-page-linkedin.png differ diff --git a/docs/_static/login-page.png b/docs/_static/login-page.png new file mode 100755 index 0000000..c344593 Binary files /dev/null and b/docs/_static/login-page.png differ diff --git a/docs/_static/login_page_with_all_providers.png b/docs/_static/login_page_with_all_providers.png new file mode 100644 index 0000000..842147e Binary files /dev/null and b/docs/_static/login_page_with_all_providers.png differ diff --git a/docs/_static/registration-page-basic.png b/docs/_static/registration-page-basic.png new file mode 100755 index 0000000..42c1e56 Binary files /dev/null and b/docs/_static/registration-page-basic.png differ diff --git a/docs/_static/registration-page-error.png b/docs/_static/registration-page-error.png new file mode 100755 index 0000000..75226b1 Binary files /dev/null and b/docs/_static/registration-page-error.png differ diff --git a/docs/_static/registration-page.png b/docs/_static/registration-page.png new file mode 100755 index 0000000..3fafd71 Binary files /dev/null and b/docs/_static/registration-page.png differ diff --git a/docs/_static/verification-complete.png b/docs/_static/verification-complete.png new file mode 100755 index 0000000..86c63f3 Binary files /dev/null and b/docs/_static/verification-complete.png differ diff --git a/docs/_static/verification-email.png b/docs/_static/verification-email.png new file mode 100755 index 0000000..6541499 Binary files /dev/null and b/docs/_static/verification-email.png differ diff --git a/docs/_static/verification.png b/docs/_static/verification.png new file mode 100755 index 0000000..71ea108 Binary files /dev/null and b/docs/_static/verification.png differ diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..7cce4b0 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,6 @@ +{% extends "!layout.html" %} + +{% block footer %} + {{ super() }} + +{% endblock %} diff --git a/docs/_themes/stormpath b/docs/_themes/stormpath new file mode 160000 index 0000000..65d7663 --- /dev/null +++ b/docs/_themes/stormpath @@ -0,0 +1 @@ +Subproject commit 65d7663dd480d81b5a822b1735a7120cf183d4a0 diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 0000000..891a54f --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,72 @@ +.. _about: + +About +============================= + +Are you building a web app, but not sure if the Stormpath Rails Gem is right for you? This page will help you decide if it is a good fit! + + +What is Stormpath? +------------------ + +`Stormpath`_ is a reliable, scalable API service for managing users, authentication and authorization. Stormpath allows your web application to do things like: + +- Create user accounts. +- Edit user accounts. +- Store custom user data with each account. +- Create groups and roles. +- Automate account email verification and password reset email workflows. +- Assign users various permissions (groups, roles, etc.). +- Handle complex authentication and authorization patterns. +- Log users in via social login with `Facebook`_ and `Google`_ OAuth. +- Cache user information for quick access. +- Scale your application as you get more users. +- Securely store your users and user data in a central location. +- Support token-based authentication for your Single Page Applications (SPAs) +- Allow users to authenticate with your application with OAuth +- and more! + +Stormpath provides a simple REST API for all of the above. For instance, if you wanted to create a new user account given an email address and password, you could send Stormpath an ``HTTP POST`` request and Stormpath would create a new user account for you, securely hash its password using security best practices and and store it securely on Stormpath's cloud service. + +In addition to allowing you to create users and groups, Stormpath also allows you to store custom data with each user account. Let's say you want to store a user's birthday -- you can send Stormpath an ``HTTP POST`` request to the user's account URL and store *any* variable JSON data (birthdays, images, movies, links, etc.). This information is encrypted and authenticated end-to-end, ensuring your user data is secure. + +What is the Stormpath Rails Gem? +------------------------------------------ + +The Stormpath Rails Gem is a gem that makes it *incredibly* simple to add user management and authentication to your Ruby on Rails web application. + +It aims to completely abstract away all user registration, login, authentication and authorization workloads as well as properly secure the web app. It is completely flexible - use only the functionality you need or leverage the entire feature set. + + +Who should use Stormpath? +------------------------- + +Stormpath is a powerful and secure service, but might not be for everyone. + +You might want to use Stormpath if: + +- You want to make user creation, management, and security as simple as possible (you can get started with the Stormpath Rails Gem with ZERO lines of code *excluding settings*) +- User security is a top priority. The Stormpath API, our documents and integrations were built by Java security experts. +- Scaling your userbase is a potential problem (Stormpath handles scaling your users transparently). +- You need to store custom user data along with your user's basic information (email, password). +- You would like to have automatic email verification for new user accounts. +- You would like to configure and customize password strength rules. +- You'd like to keep your user data separate from your other applications to increase platform stability / availability. +- You are building a service oriented application or using a microservices based architecture, in which multiple independent services need access to the same user data. +- You who would like to use Stormpath, but need to host it yourself (Stormpath has private and on-premise editions you can use internally). + +**Stormpath is a great match for applications of any size where security, development speed, and simplicity are top priorities.** + +You might **NOT** want to use Stormpath if: + +- You are building an application that does not need user accounts. +- Your application is meant for internal employee-only usage (not exposed to the public web). +- You aren't worried about user data / security much. +- You aren't worried about application availability / redundancy. +- You want to roll your own custom user authentication. + +Want to use Stormpath? OK, great! Let's get started! + +.. _Stormpath: https://stormpath.com/ +.. _Facebook: https://www.facebook.com/ +.. _Google: https://www.google.com/ diff --git a/docs/authentication.rst b/docs/authentication.rst new file mode 100644 index 0000000..816c77e --- /dev/null +++ b/docs/authentication.rst @@ -0,0 +1,332 @@ +.. _authentication: + +Authentication +============== + +This library offers several options for securing your application and +authenticating your users. Which strategy should you use? The answer depends +on your use case, and we'll discuss each one in detail. But at a high level, +your choices look like this: + + * If you are building a traditional web app or single page application, you + should use **Cookie Authentication**. + + * If you are building a mobile application, you should use the **OAuth2 + Password Grant**. + + * If you are building an API service, you can use + **HTTP Basic Authentication** or **OAuth2 Client Credentials**. + + + +Cookie Authentication +--------------------- + +If you are building a web application that serves traditional HTML pages, or a +Single Page Application (Angular/React), this library will handle the cookies +for you. No special configuration is necessary. + +To use cookie authentication, simply use the ``require_authentication!`` before action: + +.. code-block:: ruby + + class ProfilesController < ApplicationController + before_action :require_authentication! + + def show + end + end + +Behind the scenes we are issuing a OAuth2 Access Token and Refresh Token for +the user, and storing them in secure, HTTPS-Only cookies. After the user has +logged in, these cookies will be supplied on every request. Our library will +assert that the Access Token is valid. If the Access Token is expired, we will +attempt to refresh it with the Refresh Token. + + +.. note:: + Stormpath-Rails's OAuth2 cookie feature will not interfere with any + existing cookie-based session middleware you might have. The cookies that + Stormpath creates are used exclusively for Stormpath's purposes, so it's + safe to create your own separate sessions if needed. + +.. _setting_token_expiration_time: + +Setting Token Expiration Time +............................. + +If you need to change the expiration time of the Access Token or Refresh Token, +please login to the Stormpath Admin Console and navigate to the OAuth policy of +your Stormpath Application. There you will find the settings for each token. + +.. _configuring_cookie_flags: + +Configuring Cookie Flags +........................ + +This library creates two cookies, one for the Access Token and one for the +Refresh Token. There are several options available for controlling the flags +that are set on these cookies. + +Here is an example configuration block, with the default settings: + +.. code-block:: yaml + + web: + accessTokenCookie: + name: "access_token" + httpOnly: true + secure: null + path: null + domain: null + + refreshTokenCookie: + name: "refresh_token" + httpOnly: true + secure: null + path: null + domain: null + + +This table describes each setting in detail: + ++-------------+---------+------------------------------------------------------+ +| Cookie Flag | Default | Description | ++=============+=========+======================================================+ +| domain | null | Set if needed, e.g. "subdomain.mydomain.com". | ++-------------+---------+------------------------------------------------------+ +| httpOnly | true | True by default, do not disable without good reason | +| | | (exposes tokens to XSS | attacks). | ++-------------+---------+------------------------------------------------------+ +| path | "/" | Set if needed, e.g. "/newapp". | ++-------------+---------+------------------------------------------------------+ +| secure | null | Will be ``true`` in HTTPS environments (as detected | +| | | by ``req.protocol``), unless explicitly set to | +| | | ``false`` (not recommended!). | ++-------------+---------+------------------------------------------------------+ + +.. _token_validation_strategy: + +Token Validation Strategy +......................... + +When a request comes to your server, this gem will use the Access Token +and Refresh Token cookies to make an authentication decision. The default +validation strategy (``local``) works like this: + +- If the Access Token signature is valid, and the token is not expired, accept + the request. + +- If the Access Token is expired, attempt to get a new one from the Stormpath + REST API by using the Refresh Token. + +- If a new Access Token cannot be obtained, deny the request. + +With the ``local`` option, our gem only checks the signature and expiration of +the Access Token. It does not check with the Stormpath REST API to assert that +the Access Token hasn't been revoked. + +If you would like to check for Access Token revocation on every request, you +should opt-in to the ``stormpath`` validation strategy. This will make a +network call to the Stormpath REST API. If the Access Token has been revoked, +or the account has been disabled or deleted, the request will be rejected. + +Opt-in to ``stormpath`` validation with this configuration: + +.. code-block:: yaml + + web: + oauth2: + password: + validationStrategy: 'stormpath' + + +.. warning:: + + When using local validation, your server will not be aware of token revocation + or any changes to the associated Stormpath account. **This is a security + trade-off that optimizes for performance.** If you prefer extra security, use + the ``stormpath`` validation option. + + If you prefer local validation, for the performance reasons, you can add more + security by doing one of the following: + + * Use a short expiration time for your Access Tokens (such as five minutes or + less). This will limit the amount of time that the Access Token can be used + for validation, while still reducing the number of times that we need to + make a REST API call, with the refresh token, to get a new access token. + + * Maintain a blacklist of revoked Access Tokens, in your local application + cache. Implement a middleware function that asserts that the Access Token is + not in this cache, and reject the request if true. We may implement this as + a convenience feature in the future. + + +HTTP Basic Authentication +------------------------- + +This strategy makes sense if you are building a simple API service that does +not have complex needs around authorization and resource control. This strategy +is simple because the developer simply supplies their API keys on every request +to your server. + +Once the developer has their API keys, they will use them to authenticate with your +API. For each request they will set the ``Authorization`` header, like this:: + + Authorization: Basic + +How this is done will depend on what tool or library they are using. For example, +if using curl: + +.. code-block:: sh + + curl -v --user apiKeyId:apiKeySecret http://localhost:3000/secret + +You only need to set the *require_authentication!* callback, but behind the curtains another class is going to be invoked, +which will handle the basic authentication. + + +OAuth2 Client Credentials +------------------------- + +If you are building an API service and you have complex needs around +authorization and security, this strategy should be used. In this situation +the developer does a one-time exchange of their API Keys for an Access Token. +This Access Token is time limited and must be periodically refreshed. This adds a +layer of security, at the cost of being more complex than HTTP Basic +Authentication. + +If you're not sure which strategy to use, it's best to start with HTTP Basic +Authentication. You can always switch to OAuth2 at a later time. + +Once a developer has an API Key pair (see above, *Issuing API Keys*), they will +need to use the OAuth2 Token Endpoint to obtain an Access Token. In simple +HTTP terms, that request looks like this:: + + + POST /oauth/token HTTP/1.1 + Host: myapi.com + Content-Type: application/x-www-form-urlencoded + Authorization: Basic + + grant_type=client_credentials + +How you construct this request will depend on your library or tool, but the key +parts you need to know are: + + * The request must be a POST request. + * The content type must be form encoded, and the body must contain + ``grant_type=client_credentials``. + * The Authorization header must be Basic and contain the Base64 Url-Encoded + values of the Api Key Pair. + +If you were doing this request with curl, it would look like this:: + + curl -X POST --user api_key_id:api_key_secret http://localhost:3000/oauth/token -d grant_type=client_credentials + +If the credentials are valid, you will get an Access Token response that looks +like this:: + + { + "access_token": "eyJ0eXAiOiJKV1QiL...", + "token_type": "bearer", + "expires_in": 3600 + } + + +The response is a JSON object which contains: + +- ``access_token`` - Your OAuth Access Token. This can be used to authenticate + on future requests. +- ``token_type`` - This will always be ``"bearer"``. +- ``expires_in`` - This is the amount of seconds (*as an integer*) for which + this token is valid. + +With this token you can now make requests to your API. This request is simpler, +as only thing you need to supply is ``Authorization`` header with the Access +Token as a bearer token. If you are using curl, that request looks like this: + +.. code-block:: sh + + curl -v -H "Authorization: Bearer eyJ0eXAiOiJKV1QiL..." http://localhost:3000/secret + +In order to protect your API endpoint and allow this form of authentication, +you just need to use the *require_authentication!* callback again. + +By default the Access Tokens are valid for one hour. If you want to change +the expiration of these tokens you will need to configure it in the server +configuration, like this: + +.. code-block:: yaml + + web: + oauth2: + client_credentials: + accessToken: + ttl: 3600 // your custom TTL, in seconds, goes here + + +OAuth2 Password Grant +--------------------- + +This is the authentication strategy that you will want to use for mobile clients. +In this situation the end-user supplies their username and password to your +mobile application. The mobile application sends that username and password to +your Rails application, which then verifies the password with Stormpath. + +If the account is valid and the password is correct, Stormpath will generate +an Access Token for the user. Your server gets this Access Token from Stormpath +and then sends it back to your mobile application. + +The mobile application then stores the Access Token in a secure location, and +uses it for future requests to your API. Every time the mobile application uses +this Access Token your server will verify that it's still valid, using Stormpath. + +When a user wants to login to your mobile application, the mobile application +should make this request to your Rails application: + +.. code-block:: sh + + POST /oauth/token HTTP/1.1 + Host: myapi.com + Content-Type: application/x-www-form-urlencoded + + grant_type=password + &username=user@gmail.com + &password=theirPassword + +If the authentication is successful, the Stormpath API will return an Access +Token to your mobile application. The response will look like this:: + + { + "refresh_token": "eyJraWQiOiI2...", + "stormpath_access_token_href": "https://api.stormpath.com/v1/accessTokens/3bBAHmSuTJ64DM574awVen", + "token_type": "Bearer", + "access_token": "eyJraWQiOiI2Nl...", + "expires_in": 3600 + } + +Your mobile application should store the Access Token and Refresh Token. By +default the Access Token is valid for 1 hour and the Refresh Token for 60 days. +When the Access Token expires you can get a new Access Token by using the +Refresh Token, making this request to your Rails application:: + + POST /oauth/token HTTP/1.1 + Host: myapi.com + Content-Type: application/x-www-form-urlencoded + + grant_type=refresh_token + &refresh_token=eyJraWQiOiI2... + +The response will contain a new Access Token. Once the Refresh Token expires, +the user will have to re-authenticate with a username and password. + +You can control the lifetime of the Access Token and Refresh Token by modifying +the OAuth Policy of your Stormpath Application. This can be found by logging +into the Stormpath Admin Console and finding your Application. + +For full documentation on our OAuth2 Access Token features, please see +`Using Stormpath for OAuth 2.0 and Access/Refresh Token Management`_ + +.. _Using Stormpath for API Authentication: https://docs.stormpath.com/guides/api-key-management/ +.. _Using Stormpath for OAuth 2.0 and Access/Refresh Token Management: http://docs.stormpath.com/guides/token-management/ diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 0000000..b834c6a --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1,34 @@ +.. _changelog: + + +Change Log +========== + +Gem changes until version 2.0.1, in descending order. + +Version 2.2.0 +------------- +Released on Nov 07, 2016 + +- Implement Authentication with Social Providers (Facebook, Google, Linkedin, Github) + +Version 2.1.0 +------------- +Released on Nov 02, 2016 + +- Create script for generating a rake task responsible for transferring users from devise to Stormpath +- Implement ID Site Authentication + +Version 2.0.2 +------------- +Released on Aug 29, 2016 + +- Render path links depending on the configuration +- Use Faker to generate random test data +- Rename all user instances to account + +Version 2.0.1 +------------- +Released on Aug 22, 2016 + +- Fix error when showing new_register_path on login page when register is disabled. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..eaf3ef0 --- /dev/null +++ b/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. +# " v 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 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 diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..a09c0fd --- /dev/null +++ b/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 `_, 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 diff --git a/docs/contributors.rst b/docs/contributors.rst new file mode 100644 index 0000000..3673721 --- /dev/null +++ b/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 diff --git a/docs/devise_import.rst b/docs/devise_import.rst new file mode 100644 index 0000000..6b9283b --- /dev/null +++ b/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 diff --git a/docs/help.rst b/docs/help.rst new file mode 100644 index 0000000..33bf29e --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..02be555 --- /dev/null +++ b/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 diff --git a/docs/login.rst b/docs/login.rst new file mode 100644 index 0000000..4a63e5c --- /dev/null +++ b/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 diff --git a/docs/logout.rst b/docs/logout.rst new file mode 100644 index 0000000..4b057b1 --- /dev/null +++ b/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? %> +

Logged in as: <%= current_account.given_name %>

+ <%= 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*. diff --git a/docs/password_reset.rst b/docs/password_reset.rst new file mode 100644 index 0000000..ef8cade --- /dev/null +++ b/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 diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..6c6c4b8 --- /dev/null +++ b/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 diff --git a/docs/registration.rst b/docs/registration.rst new file mode 100644 index 0000000..f3e1748 --- /dev/null +++ b/docs/registration.rst @@ -0,0 +1,364 @@ +.. _registration: + + +Registration +============ + +The registration feature of this gem allows you to use Stormpath to create +new accounts in a Stormpath directory. You can create traditional password- +based accounts, which have a username and a password, or you can create customized accounts with multiple required or optional fields. + +By default this gem will serve an HTML registration page at ``/register``. +You can change this URI with the ``web.register.uri`` option. You can disable +this feature entirely by setting ``web.register.enabled`` to ``false`` in your ``stormpath.yml`` configuration file. + +http://localhost:3000/register + + +Configuration Options +--------------------- + +This feature supports several options. This example shows what is possible, +we will cover them in detail below: + +.. code-block:: yaml + + web: + register: + enabled: true, + uri: '/signup', # Use a different URL + nextUri: '/', # Where to send the user to, if auto login is enabled + form: + fields: # see next section for documentation + fieldOrder: # see next section + + +Modifying Default Fields +------------------------ + +The registration form will render these fields by default, and they will be +required by the user: + +* given_name +* surname +* email +* password + +While email and password will always be required, you do not need to require +first and last name. These can be configured as optional fields, or omitted +entirely. You can also specify your own custom fields. We'll cover each use +case in detail. + +Configure First Name and Last Name as Optional +.............................................. + +If you would like to show the fields for first name and last name, but not +require them, you can set required to false: + +.. code-block:: yaml + + web: + register: + form: + fields: + givenName: + required: false + surname: + required: false + + +Because the Stormpath API requires a first name and last name, we will auto-fill +these fields with `UNKNOWN` if the user does not provide them. + + +Disabling First Name and Last Name +.................................. + +If you want to remove these fields entirely, you can set enabled to false: + +.. code-block:: yaml + + web: + register: + form: + fields: + givenName: + enabled: false + surname: + enabled: false + + +Because the Stormpath API requires a first name and last name, we will auto-fill +these fields with `UNKNOWN` when a user registers. + +.. _custom_form_fields: + +Creating Custom Fields +---------------------- + +You can add your own custom fields to the form. The values will be +automatically added to the user's custom data object when they register +successfully. You can define a custom field by defining a new field object, +like this: + +.. code-block:: yaml + + web: + register: + form: + fields: + favoriteColor: + enabled: true, + label: 'Favorite Color', + placeholder: 'E.g. Red, Blue', + required: true, + type: 'text' + + +All field objects have the following properties, which must be defined: + +- **enabled** - Determines if the field is shown on the form. + +- **label** - The text label that is shown to the left of the input field. + +- **placeholder** - The help text that is shown inside the input field, if the + input field is empty (HTML5 property). + +- **required** - Marks the field as a required field. This uses the HTML5 + required property, to prompt the user to enter the value. The post data will + also be validated to ensure that the field is supplied, and an error will be + returned if the field is empty. + +- **type** - the HTML type of the input, e.g. text, email, or password. + +.. note:: + + The property name of the field definition, in this case ``favoriteColor``, + will be used for the ``name`` attribute in the rendered HTML form, or the key + in the JSON view model for the registration endpoint. + +Changing Field Order +-------------------- + +If you want to change the order of the fields, you can do so by specifying the +``fieldOrder`` array: + +.. code-block:: yaml + + web: + register: + form: + fieldOrder: + - 'givenName' + - 'surname' + - 'email' + - 'password' + - 'confirmPassword' + +Password Strength Rules +----------------------- + +Stormpath supports complex password strength rules, such as number of letters +or special characters required. These settings are controlled on a directory +basis. If you want to modify the password strength rules for your application +you should use the `Stormpath Admin Console`_ to find the directory that is mapped +to your application, and modify it's password policy. + +For more information see `Account Password Strength Policy`_. + +.. _email_verification: + +Email Verification +------------------ + +We **highly** recommend that you use email verification, as it adds a layer +of security to your site (it makes it harder for bots to create spam accounts). + +One of our favorite Stormpath features is email verification. When this workflow +is enabled on the directory, we will send the new account an email with a link +that they must click on in order to verify their account. When they click on +that link they will need to be directed to this URL: + +http://localhost:3000/verify?sptoken=TOKEN + +We have to configure our directory in order for this to happen. Use the +`Stormpath Admin Console`_ to find the directory of your application, then +go into the Workflows section. In there you will find the email verification +workflow, which should be enabled by default (enable it if not). Then modify +the template of the email to use this value for the `Link Base URL`: + +.. code-block:: sh + + http://localhost:3000/verify + +When the user arrives on the verification URL, we will verify that their email +link is valid and hasn't already been used. If the link is valid we will redirect +them to the login page. If there is a problem with the link we provide a form +that allows them to ask for a new link. + + +Auto Login +---------- + +If you are *not* using email verificaion (not recommended) you may log users in +automatically when they register. This can be achieved with this config: + +.. code-block:: yaml + + web: + register: + autoLogin: true, + nextUri: '/' + + +By default the nextUri is to the ``/`` page, but you can modify this. + +Overriding Registration +----------------------- + +Controllers +........... + +Since Stormpath controllers are highly configurable, they have lots of configuration code and are not written in a traditional way. + +A RegisterController would usually have two actions - new & create, however in Stormpath-Rails they are separated into two single action controllers - ``Stormpath::Rails::Register::NewController`` and ``Stormpath::Rails::Register::CreateController``. +They both respond to a ``call`` method (action). + +To override a Stormpath controller, first you need to subclass it: + +.. code-block:: ruby + + class CreateAccountController < Stormpath::Rails::Register::CreateController + end + + +and update the routes to point to your new controller: + +.. code-block:: ruby + + Rails.application.routes.draw do + stormpath_rails_routes(actions: { + 'register#create' => 'create_account#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 + + +JSON Registration API +--------------------- + +If you are using this gem from a SPA framework like Angular or React, you +will want to make a JSON post to register users. Simply post an object to +``/register`` that looks like this, and supply the fields that you wish to +populate on the user:: + + { + "email": "foo@bar.com", + "password": "mySuper3ecretPAssw0rd", + "surname": "optional" + } + +If the user is created successfully you will get a 200 response and the body +will the the account object that was created. If there was an error you +will get an object that looks like ``{ message: 'error message here'}``. + +If you make a GET request to the registration endpoint, with ``Accept: +application/json``, we will send you a JSON view model that describes the +registration 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 registration 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", + "clientId": "441084632428-9au0gijbo5icagep9u79qtf7ic7cc5au.apps.googleusercontent.com", + "scope": "email profile", + "href": "https://api.stormpath.com/v1/directories/gc0Ty90yXXk8ifd2QPwt/provider" + } + } + ], + "form": { + "fields": [ + { + "label": "First Name", + "placeholder": "First Name", + "required": true, + "type": "text", + "name": "givenName" + }, + { + "label": "Last Name", + "placeholder": "Last Name", + "required": true, + "type": "text", + "name": "surname" + }, + { + "label": "Email", + "placeholder": "Email", + "required": true, + "type": "email", + "name": "email" + }, + { + "label": "Password", + "placeholder": "Password", + "required": true, + "type": "password", + "name": "password" + } + ] + } + } + +.. note:: + + You may have to explicitly tell your client library that you want a JSON + response from the server. Not all libraries do this automatically. If the + library does not set the ``Accept: application/json`` header on the request, + you'll get back the HTML registration form - not the JSON response that you + expect. + +.. _Stormpath Admin Console: https://api.stormpath.com +.. _Account Password Strength Policy: https://docs.stormpath.com/rest/product-guide/#account-password-strength-policy diff --git a/docs/social_login.rst b/docs/social_login.rst new file mode 100644 index 0000000..0bb107d --- /dev/null +++ b/docs/social_login.rst @@ -0,0 +1,409 @@ +.. _social_login: + + +Social Login +============ + +Do you want users to authenticate with a social provider, such as Facebook? +Stormpath provides integration with the following services: + +* Facebook +* Google +* Linkedin +* Github + +In this guide we cover all of them step by step. + + +Facebook Login +-------------- + +To use Facebook Login you must create a Facebook Application, this is done +through their Developer site. + + +Create a Facebook App +..................... + +The first thing you need to do is log into the `Facebook Developer Site`_ and +create a new Facebook App. + +You can do this by visiting the `Facebook Developer Site`_ and clicking the "Apps" +menu at the top of the screen, then select the "Create a New App" button. You +should see something like the following: + +.. image:: /_static/facebook-new-project.png + +Go ahead and pick a "Display Name" (usually the name of your app), and choose a +category for your app. Once you've done this, click the "Create App" button. + + +Specify Allowed URLs +.................... + +The next thing we need to do is tell Facebook what URLs we'll be using Facebook +Login from. + +From the app dashboard page you're on, click the "Settings" tab in the left +menu, then click the "Add Platform" button near the bottom of the page. When +prompted, select "Website" as your platform type. + +In the "Site URL" box, enter your private and public root URLs. This should be +something like ``"http://localhost:3000"`` or ``"http://mysite.com"``. *If you +want to allow Facebook Login from multiple URLs (local development, production, +etc.) you can just click the "Add Platform" button again and enter another URL.* + +Lastly, click the "Save Changes" button to save the changes. + +Your settings should now look something like this: + +.. image:: /_static/facebook-url-settings.png + + +Create a Facebook Directory +........................... + +Next, we need to input the Facebook app credentials into Stormpath Directory. +This allows Stormpath to interact with the Facebook API on your behalf, which +automates all OAuth flows. + +To do this, you need to visit the `Stormpath Admin Console`_ and create a new +directory. When you click the "Create Directory" button you will choose +"Facebook" as the provider, and enter the following information about your +Facebook application: + +- For the "Name" field, you can insert whatever name you want. +- For the "Facebook Client ID" field, insert your Facebook App ID which you got + in the previous steps. +- For the "Facebook Client Secret" field, insert your Facebook Client Secret + which you got in the previous steps. + +Make sure to click "Create" to finish creating your directory. + +Next, you need to hook your new Facebook Directory up to your Stormpath +Application. To do this, visit the `Stormpath Admin Console`_, navigate to +Applications, and select your application from the list. + +On your application page, click the "Account Stores" tab, then click the "Add +Account Store" button. From the drop down list, select your newly created +Facebook Directory, then save your changes. + +That's it! + + +Test it Out +........... + +Now that you've plugged your Facebook credentials into stormpath-rails, social +login should already be working! + +Open your Rails app in a browser, and try logging in by visiting the login page +(``/login``). If you're using the default login page included with this +gem, you should see the following: + +.. image:: /_static/login-page-facebook.png + +You now have a fancy new Facebook enabled login button! Try logging in! When +you click the new Facebook button you'll be redirected to Facebook, and +prompted to accept the permissions requested: + +.. image:: /_static/login-page-facebook-permissions.png + +After accepting permissions, you'll be immediately redirected back to your +website at the URL specified by ``redirectUrl`` in your app's config. + + +Google Login +------------ + +Integrating Google Login is very similar to Facebook. You must create an application +in the Google Developer Console, then create a Directory in Stormpath which holds +settings for the Google application that you created. + + +Create a Google Project +....................... + +The first thing you need to do is log into the `Google Developer Console`_ and +create a new Google Project. + +You can do this by visiting the `Google Developer Console`_ and clicking the "Create +Project" button. You should see something like the following: + +.. image:: /_static/google-new-project.png + +Go ahead and pick a "Project Name" (usually the name of your app), and +(*optionally*) a "Project ID". + + +Enable Google Login +................... + +Now that you've got a Google Project -- let's enable Google Login. The way +Google Projects work is that you have to selectively enable what functionality +each Project needs. + +From your `Google Developer Console`_ click on your new Project, then in the +side panel click on the "APIs & auth" menu option. + +Now, scroll through the API list until you see "Google+ API", then click the +"OFF" button next to it to enable it. You should now see the "Google+ API" as +"ON" in your API list: + +.. image:: /_static/google-enable-login.png + + +Create OAuth Credentials +........................ + +The next thing we need to do is create a new OAuth client ID. This is what +we'll use to handle user login with Google. + +From your project, click the "APIs & auth" menu, then click on the "Credentials" +sub-menu. + +You should see a big red button labeled "Create New Client ID" near the top of +the page -- click that. + +You'll want to do several things here: + +1. Select "Web application" for your "Application Type". +2. Remove everything from the "Authorized Javascript Origins" box. +3. Add the callback URI of your site (both publicly and locally) into the + "Authorized Redirect URI" box. This tells Google where to + redirect users after they've logged in with Google. The default callback + URI for this gem is ``/callbacks/google``. + +In the end, your settings should look like this: + +.. image:: /_static/google-oauth-settings.png + +Once you've specified your settings, go ahead and click the "Create Client ID" +button. + +Lastly, you'll want to take note of your "Client ID" and "Client Secret" +variables that should now be displayed on-screen. We'll need these in the next +step. + + +Create a Google Directory +......................... + +Next, we need to input the Google app credentials into Stormpath. This allows +Stormpath to interact with the Google API on your behalf, which automates all +OAuth flows. + +To do this, you need to visit the `Stormpath Admin Console`_ and create a new +directory from the Directories section. When you click "Create Directory", +choose "Google" as the provider, and enter the following information about your +Google application: + +- For the "Name" field, you can insert whatever name you want. +- For the "Google Client ID" field, insert your Google Client ID which you got + in the previous steps. +- For the "Google Client Secret" field, insert your Google Client Secret + which you got in the previous steps. +- For the "Google Authorized Redirect URI" field, insert your Google Redirect + URL from the previous section. Be sure to *only enter the URI you're currently + using*. EG: If you're running your app in development mode, set it to your + local URL, if you're running your app in production mode, set it to your + production URL. + +Lastly, be sure to click the "Save" button at the bottom of the page. + +Next, you need to hook your new Google Directory up to your Stormpath +Application. To do this, visit the Applications section and select your +application from the list. + +On your application page, click the "Account Stores" tab, then click the "Add +Account Store" button. From the drop down list, select your newly created +Google Directory, then save your changes. + + +Test it Out +........... + +Now that you've plugged your Google credentials into stormpath-rails, social +login should already be working! + +Open your Rails app in a browser, and try logging in by visiting the login page +(``/login``). If you're using the default login page included with this +gem, you should see the following: + +.. image:: /_static/login-page-google.png + +You now have a fancy new Google enabled login button! Try logging in! When you +click the new Google button you'll be redirected to Google, and prompted to +select your Google account: + +.. image:: /_static/login-page-google-account.png + +After selecting your account you'll then be prompted to accept any permissions, +then immediately redirected back to your website at the URL specified by +``redirectUrl`` in your app's settings. + + +LinkedIn Login +-------------- + +Integrating LinkedIn Login is very similar to Google. You must create an application +in the LinkedIn Console, then create a Directory in Stormpath which holds +settings for the LinkedIn application that you created. + + +Create a LinkedIn Application +............................. + +The first thing you need to do is log into the `LinkedIn Developer Console`_ and +create a new LinkedIn Application. + +You can do this by visiting the `LinkedIn Developer Console`_ and clicking the "Create +Application" button. You should see something like the following: + +.. image:: /_static/linkedin-new-application.gif + +Continue by filling out all the required fields. + + +Enable LinkedIn Permissions +........................... + +Now that you've got a LinkedIn Application -- let's enable LinkedIn permissions. The way +LinkedIn Applications work is that you have to selectively enable what permissions +each Application requires. + +Under the "Default Application Permissions" section, be sure to enable the "r_basicprofile" +and the "r_emailaddress" permissions. These permissions allow Stormpath to access the basic +profile properties (first, middle, and last name) and email (*these permissions are required*). + +.. image:: /_static/linkedin-add-permissions.gif + +The next thing we need to do is add in all of the allowed Redirect URLs for our application. Well do this by +entering all of our absolute redirect URLs under the "OAuth 2.0" section. For instance, if I was running +my site locally on port 3000, as well as under the "www.example.com" domain, I'd add two redirect URIs: + +- http://localhost:3000/callbacks/linkedin +- https://www.example.com/callbacks/linkedin + +.. image:: /_static/linkedin-add-authorized-urls.gif + + +Create a LinkedIn Directory +........................... + +Next, we need to input the LinkedIn Application credentials into Stormpath. This allows +Stormpath to interact with the LinkedIn API on your behalf, which automates all +OAuth flows. + +To do this, you need to visit the `Stormpath Admin Console`_ and create a new +directory from the Directories section. When you click "Create Directory", +choose "LinkedIn" as the provider, and enter the following information about your +LinkedIn Application: + +- For the "Name" field, you can insert whatever name you want. +- For the "LinkedIn Client ID" field, insert your LinkedIn Client ID which you got + in the previous steps. +- For the "LinkedIn Client Secret" field, insert your LinkedIn Client Secret + which you got in the previous steps. + +Lastly, be sure to click the "Save" button at the bottom of the page. + +Next, you need to hook your new LinkedIn Directory up to your Stormpath +Application. To do this, visit the Applications section and select your +application from the list. + +On your application page, click the "Account Stores" tab, then click the "Add +Account Store" button. From the drop down list, select your newly created +LinkedIn Directory, then save your changes. + + +Test it Out +........... + +Now that you've plugged your LinkedIn credentials into rails-stormpath, social +login should already be working! + +Open your Rails app in a browser, and try logging in by visiting the login page +(``/login``). If you're using the default login page included with this +gem, you should see the following: + +.. image:: /_static/login-page-linkedin.png + +You now have a fancy new LinkedIn enabled login button! Try logging in! When you +click the new LinkedIn button you'll be redirected to LinkedIn, and prompted to +select your LinkedIn account: + +.. image:: /_static/linkedin-permissions-page.png + +After selecting your account you'll then be prompted to accept any permissions, +then immediately redirected back to your website at the URL specified by +``redirectUrl`` in your app's settings. + +Github Login +-------------- + +To use Github Login you must create a Github Application, this is done +through their Developer site. + + +Create a Github App +..................... + +The first thing you need to do is log into the `Github Developer Site`_ and +create a new Github App. + +You can do this by visiting the `Github Developer Site`_ and clicking the "Register a new application" +menu at the top of the screen. You should see something like the following: + +.. image:: /_static/github_create_app.png + +After filling out the form fields click on "Register application" + + +Create a Github Directory +........................... + +Next, we need to input the Github app credentials into Stormpath Directory. +This allows Stormpath to interact with the Github API on your behalf, which +automates all OAuth flows. + +To do this, you need to visit the `Stormpath Admin Console`_ and create a new +directory. When you click the "Create Directory" button you will choose +"Github" as the provider, and enter the following information about your +Github application: + +- For the "Name" field, you can insert whatever name you want. +- For the "Github Client ID" field, insert your Github App ID which you got + in the previous steps. +- For the "Github Client Secret" field, insert your Github Client Secret + which you got in the previous steps. + +Make sure to click "Create" to finish creating your directory. + +Next, you need to hook your new Github Directory up to your Stormpath +Application. To do this, visit the `Stormpath Admin Console`_, navigate to +Applications, and select your application from the list. + +On your application page, click the "Account Stores" tab, then click the "Add +Account Store" button. From the drop down list, select your newly created +Github Directory, then save your changes. + + +Test it Out +........... + +Now that you've plugged your Github credentials into rails-stormpath, social +login should already be working! + +Open your Rails app in a browser, and try logging in by visiting the login page +(``/login``). If you're using the default login page included with this +gem and if all social login providers are set, your login page should look like the following: + +.. image:: /_static/login_page_with_all_providers.png + + +.. _Stormpath Admin Console: https://api.stormpath.com +.. _Facebook Developer Site: https://developers.facebook.com/ +.. _Google Developer Console: https://console.developers.google.com/project +.. _LinkedIn Developer Console: https://www.linkedin.com/developer/apps +.. _Github Developer Site: https://github.com/settings/developers diff --git a/docs/templates.rst b/docs/templates.rst new file mode 100644 index 0000000..ce3ac35 --- /dev/null +++ b/docs/templates.rst @@ -0,0 +1,100 @@ +.. _templates: + + +Templates +========= + + +Default Views +------------- + +By default this gem will use it's own templates for rendering its views. +The views that this gem serves by default (if the features are enabled) are: + +* Login Page +* Registration Page +* Forgot Password Page +* Change Password Page +* Email Verification Page + +If you want to customize these pages, there are two strategies. You can install +our default templates and modify them + +.. code-block:: ruby + + rails generate stormpath:views + +or you can supply your own. + + +Custom Views +------------ + +If you want to supply your own view for a given feature, you need to let us +know where it is. You do this by telling us the specific path to the file. +For example, if you had a folder named ``views`` in the root of your project, +you would declare it like this: + +.. code-block:: yaml + + web: + register: + view: 'sessions/new.html.erb' // My custom login view + + +View Variables +-------------- + +Our gem will provide these view variables to all templates that are +rendered: + ++-----------------+-------------------------------------------------------------------+ +| **Variable** | **Description** | ++-----------------+-------------------------------------------------------------------+ +| current_account | The account object of the logged in user (undefined otherwise) | ++-----------------+-------------------------------------------------------------------+ +| signed_in? | Boolean value which determines whether the user is signed in | +| | or not | ++-----------------+-------------------------------------------------------------------+ + +You can also use the values from the ``stormpath.yml`` configuration file generated by this gem. +For example, if you want to iterate over all the fields that the register form contains you would do this by accessing: + +.. code-block:: ruby + + Stormpath::Rails.config.web.register.form.fields + +or if you just need to use a conditional statement: + +.. code-block:: ruby + + Stormpath::Rails.config.web.change_password.enabled + + +Response Variables +------------------ + +Our gem will provide these objects on the response object for all JSON requests. + +========== ========== +Variable Description +========== ========== +account The account object of the logged in user (undefined otherwise) +========== ========== + +.. code-block:: ruby + + { + account: { + href: account.href, + username: account.username, + modifiedAt: account.modified_at, + status: account.status, + createdAt: account.created_at, + email: account.email, + middleName: account.middle_name, + surname: account.surname, + givenName: account.given_name, + fullName: account.full_name + } + } diff --git a/docs/user_data.rst b/docs/user_data.rst new file mode 100644 index 0000000..7195825 --- /dev/null +++ b/docs/user_data.rst @@ -0,0 +1,216 @@ +.. _user_data: + +User Data +========= + + +current_account +--------------- + +When writing your own controller methods, you will likely want to use +the account object. There are two primary ways to do this: with the `current_account` +helper method, and with our other authentication helper method. + +Resolving The Current User(Account) +.................................... + +In this situation, we have a home page which needs to render itself differently +if the user is logged in. In this scenario, we don't *require* authentication, +but we need to know if the user is logged in. In this case we use the +``current_account`` method: + + .. code-block:: ruby + + // Basic controller method example + + if current_account do + render text: "Hello #{current_account.email}" + else + render text: 'Not logged in' + end + + +Forcing Authentication +...................... + +If you require authentication for a route, you should use one of the +authentication helper methods that are documented in the +:ref:`authentication` section. + +When you use these middlewares, we won't call your controller method unless the +user is logged in. If the user is not logged in, we bypass your middleware and +redirect the user to the login page for HTML requests, or send a 401 error for +JSON requests. + +For example, if you've defined a simple view that should simply display a user's +email address, we can use the ``require_authentication!`` method to require them to be +logged in in order to have access to the show view: + + .. code-block:: ruby + + class ProfilesController < ApplicationController + before_action :require_authentication! + + def show + end + end + + +Modifying The Account +...................... + +The ``current_account`` context allows you to directly interact with the current +``account`` object. This means you can perform *any* action on the ``account`` object +directly. + +Perhaps you want to change a accounts's ``given_name`` (*first name*). You could +easily accomplish this with the following code: + +.. code-block:: ruby + + current_account.given_name = 'Clark'; + if current_account.save + puts('Successfully updated account!') + else + puts('There was an error processing your request') + end + +As you can see above, you can directly modify ``account`` attributes, then +save any changes by running ``current_account.save``. + + +Custom Data +----------- + +In addition to managing basic user fields, Stormpath also allows you to store +up to 10MB of JSON information with each user account! + +Instead of defining a database table for users, and another database table for +user profile information -- with Stormpath, you don't need either! + +Let's take a look at how easy it is to store custom data on a ``user`` +model: + +.. code-block:: ruby + + // You can add fields + current_account.custom_data[:rank] = 'General' + current_account.custom_data[:experience] = {'speed': 100, 'precision': 68}; + current_account.custom_data.save + + // And delete fields + + current_account.custom_data[:rank].delete + + // And then save it all at once + + if current_account.custom_data.save + puts('Successfully updated custom data account!') + else + puts('There was an error processing your request') + end + +As you can see above -- storing custom information on a ``user`` account is +extremely simple! + +For more information about the ``account`` object, please visit the `Ruby SDK Account Management`_ chapter. + + +Automatic Expansion +------------------- + +In Stormpath, all objects are connected in a graph. You +have to expand a resource to get its child resources, and this +is an asynchronous operation. We can pre-fetch the expanded +user data for you. Simply pass the `Expansion` resource while fetching the account: + +.. code-block:: ruby + + client.accounts.get(current_account.href, Stormpath::Resource::Expansion.new('directory')) + + +Our gem will pre-expand those resources for you, so that +they are statically available inside your methods. + +Without enabling this expansion, the response would only contain +an object which has an href to the resource, that would look +like this: + +.. code-block:: javascript + + { + href: 'http://api.stormpath.com/v1/accounts/avIu4NrfCk49uzhfCk/customData' + } + +.. note:: + + Custom data is expanded automatically, but you can disable this + +You can expand any of these *"linked resources"*: + +- ``apiKeys`` - A user's API keys. +- ``customData`` - A user's custom data. +- ``directory`` - A user's directory data. +- ``groups`` - A user's group data. +- ``groupMemberships`` - A user's group membership data. +- ``providerData`` - A user's provider data (*for social login providers*). +- ``tenant`` - A user's tenant data. + +.. _me_api: + +Current User JSON API +--------------------- + +If you are working with a front-end application, you can make a request to the +``/me`` URL to get a JSON representation of the account that is currently +logged in. If the user is not logged in, this endpoint will return a 401 +response. + +The response from the endpoint looks like this: + +.. code-block:: javascript + + { + "account": { + "href": "https://api.stormpath.com/v1/accounts/4WvCtY0oCRDzQdYH3Q0qjz", + "username": "foobar", + "email": "foo@example.com", + "givenName": "Foo", + "middleName": null, + "surname": "Bar", + "fullName": "Foo Bar", + "status": "ENABLED", + "createdAt": "2015-10-13T20:54:22.215Z", + "modifiedAt": "2016-03-17T16:40:17.631Z" + } + } + +By default we don't expand any data on the account, for security purposes. But +you can opt-in to account expansions with the following configuration in the *stormpath.yml*: + +.. code-block:: ruby + + me: + enabled: true + uri: "/me" + expand: + apiKeys: true + applications: true + customData: true + directory: true + groupMemberships: true + groups: true + providerData: true + tenant: true + +If you wish to disable the ``/me`` route entirely, you can do that as well: + +.. code-block:: ruby + + me: + enabled: false + + +.. _Account Object: https://docs.stormpath.com/ruby/quickstart/ +.. _Stormpath Ruby SDK: https://github.com/stormpath/stormpath-sdk-ruby +.. _Ruby SDK Account Management: https://docs.stormpath.com/ruby/product-guide/latest/accnt_mgmt.html