Module: ActionController::RequestForgeryProtection::ClassMethods

Module | ActionController::RequestForgeryProtection::ClassMethods
In: | lib/action_controller/request_forgery_protection.rb

### Methods

protect_from_forgery

### Public Instance methods

protect_from_forgery(options = {})

Protect a controller‘s actions from CSRF attacks by ensuring that all forms are coming from the current web application, not a forged link from another site. This is done by embedding a token based on the session (which an attacker wouldn‘t know) in all forms and Ajax requests generated by Rails and then verifying the authenticity of that token in the controller. Only HTML/JavaScript requests are checked, so this will not protect your XML API (presumably you‘ll have a different authentication scheme there anyway). Also, GET requests are not protected as these should be indempotent anyway.

You turn this on with the protect_from_forgery method, which will perform the check and raise an ActionController::InvalidAuthenticityToken if the token doesn‘t match what was expected. And it will add a _authenticity_token parameter to all forms that are automatically generated by Rails. You can customize the error message given through public/422.html.

Learn more about CSRF (Cross-Site Request Forgery) attacks:

- isc.sans.org/diary.html?storyid=1750
- en.wikipedia.org/wiki/Cross-site_request_forgery

Keep in mind, this is NOT a silver-bullet, plug ‘n’ play, warm security blanket for your rails application. There are a few guidelines you should follow:

- Keep your GET requests safe and idempotent. More reading material:
  - www.xml.com/pub/a/2002/04/24/deviant.html
  - www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1
- Make sure the session cookies that Rails creates are non-persistent. Check in Firefox and look for "Expires: at end of session"

If you need to construct a request yourself, but still want to take advantage of forgery protection, you can grab the authenticity_token using the form_authenticity_token helper method and make it part of the parameters yourself.

Example:

      class FooController < ApplicationController
        # uses the cookie session store (then you don't need a separate :secret)
        protect_from_forgery :except => :index

        # uses one of the other session stores that uses a session_id value.
        protect_from_forgery :secret => 'my-little-pony', :except => :index

        # you can disable csrf protection on controller-by-controller basis:
        skip_before_filter :verify_authenticity_token
      end

If you are upgrading from Rails 1.x, disable forgery protection to simplify your tests. Add this to config/environments/test.rb:

      # Disable request forgery protection in test environment
      config.action_controller.allow_forgery_protection = false

Valid Options:

- `:only/:except` - passed to the before_filter call. Set which actions are verified.
- `:secret` - Custom salt used to generate the form_authenticity_token. Leave this off if you are using the cookie session store.
- `:digest` - Message digest used for hashing. Defaults to ‘SHA1‘

[Validate]