Merge branch 'feature/doc_request_forgery_protection_for_api'

1 files changed, 17 insertions, 7 deletions

diff --git a/actionpack/lib/action_controller/metal/request_forgery_protection.rb b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
index 367b736035..663a969f72 100644
--- a/actionpack/lib/action_controller/metal/request_forgery_protection.rb
+++ b/actionpack/lib/action_controller/metal/request_forgery_protection.rb
@@ -13,9 +13,14 @@ module ActionController #:nodoc:
   # by including a token in the rendered HTML for your application. This token is
   # stored as a random string in the session, to which an attacker does not have
   # access. When a request reaches your application, \Rails verifies the received
-  # token with the token in the session. Only HTML and JavaScript requests are checked,
-  # so this will not protect your XML API (presumably you'll have a different
-  # authentication scheme there anyway).
+  # token with the token in the session. All requests are checked except GET requests
+  # as these should be idempotent. Keep in mind that all session-oriented requests
+  # should be CSRF protected, including Javascript and HTML requests.
+  #
+  # Since HTML and Javascript requests are typically made from the browser, we
+  # need to ensure to verify request authenticity for the web browser. We can
+  # use session-oriented authentication for these types requests, by using
+  # the `protect_form_forgery` method in our controllers.
   #
   # GET requests are not protected since they don't have side effects like writing
   # to the database and don't leak sensitive information. JavaScript requests are
@@ -26,15 +31,20 @@ module ActionController #:nodoc:
   # Ajax) requests are allowed to make GET requests for JavaScript responses.
   #
   # It's important to remember that XML or JSON requests are also affected and if
-  # you're building an API you'll need something like:
+  # you're building an API you should change forgery protection method in
+  # <tt>ApplicationController</tt> (by default: <tt>:exception</tt>):
   #
   #   class ApplicationController < ActionController::Base
   #     protect_from_forgery unless: -> { request.format.json? }
   #   end
   #
-  # CSRF protection is turned on with the <tt>protect_from_forgery</tt> method,
-  # which checks the token and resets the session if it doesn't match what was expected.
-  # A call to this method is generated for new \Rails applications by default.
+  # CSRF protection is turned on with the <tt>protect_from_forgery</tt> method.
+  # By default <tt>protect_from_forgery</tt> protects your session with
+  # <tt>:null_session</tt> method, which provides an empty session during request
+  #
+  # We may want to disable CSRF protection for APIs since they are typically
+  # designed to be state-less. That is, the requestion API client will handle
+  # the session for you instead of Rails.
   #
   # The token parameter is named <tt>authenticity_token</tt> by default. The name and
   # value of this token must be added to every layout that renders forms by including