New Features¶ ↑

• A route_csrf plugin has been added. This plugin allows for more control over CSRF protection, since the user can choose where in the routing tree to enforce the protection. Additionally, the route_csrf plugin offers better security than the CSRF protection used by the csrf plugin (which uses the rack_csrf library).

  The route_csrf plugin defaults to allowing only CSRF tokens specific to a given request method and request path, and not allowing generic CSRF tokens (though it does offer optional support for such tokens). Both request-specific and generic CSRF tokens are designed to never leak the CSRF secret key, making it more difficult to forge valid CSRF tokens. Additionally, the plugin offers optional support for accepting rack_csrf tokens, which should only be enabled during a short transition period.

  Some differences between the route_csrf plugin and the older csrf plugin:

  • route_csrf supports and by default only allows CSRF tokens specific to request method and request path, as mentioned above. You can use the require_request_specific_tokens: false option to allow generic CSRF tokens.

  • route_csrf does not check the HTTP header by default, it only checks the header if the :check_header option is set. The :check_header option can be set to true to check both the parameter and the header, or set to :only to only check the header.

  • route_csrf raises by default for invalid CSRF tokens. rack_csrf returns an empty 403 response in that case. You can use the error_handler plugin to handle the Roda::RodaPlugins::RouteCsrf::InvalidToken exceptions, or you can use the csrf_failure: :empty_403 option if you would like the csrf plugin default behavior. The plugin also accepts a block for configurable failure behavior.

  • route_csrf does not use a middleware, as it is designed to give more control. In order to enforce the CSRF protection, you need to call check_csrf! in your routing tree at the appropriate place. If you are not sure where to add it, add it to the top of the routing tree, after the public or assets routes if you are using those plugins:

    route do
      r.public
      r.assets
      check_csrf!
    
      # ...
    end
    

    The check_csrf! method accepts an options hash, which can be used to override the plugin options on a per-call basis.

  • The csrf_token/csrf_tag methods take an optional path and method arguments. If a path is given, the method defaults to POST, and the resulting CSRF token can only be used to submit forms for the path and method. If a path is not given, the resulting CSRF token will be generic, but it will only work if the plugin has been configured to allow generic CSRF tokens.

  • A csrf_path method is available for easily taking a form action string and returning an appropriate path to pass to the csrf_token or csrf_tag methods.