Class: ActionDispatch::SSL

Inherits:
Object
  • Object
show all
Defined in:
lib/action_dispatch/middleware/ssl.rb

Overview

# Action Dispatch SSL

This middleware is added to the stack when ‘config.force_ssl = true`, and is passed the options set in `config.ssl_options`. It does three jobs to enforce secure HTTP requests:

  1. **TLS redirect**: Permanently redirects ‘http://` requests to `https://` with the same URL host, path, etc. Enabled by default. Set `config.ssl_options` to modify the destination URL:

    config.ssl_options = { redirect: { host: "secure.widgets.com", port: 8080 }`

    Or set ‘redirect: false` to disable redirection.

    Requests can opt-out of redirection with ‘exclude`:

    config.ssl_options = { redirect: { exclude: -> request { request.path == "/up" } } }

    Cookies will not be flagged as secure for excluded requests.

    When proxying through a load balancer that terminates SSL, the forwarded request will appear as though it’s HTTP instead of HTTPS to the application. This makes redirects and cookie security target HTTP instead of HTTPS. To make the server assume that the proxy already terminated SSL, and that the request really is HTTPS, set ‘config.assume_ssl` to `true`:

    config.assume_ssl = true

  2. **Secure cookies**: Sets the ‘secure` flag on cookies to tell browsers they must not be sent along with `http://` requests. Enabled by default. Set `config.ssl_options` with `secure_cookies: false` to disable this feature.

  3. **HTTP Strict Transport Security (HSTS)**: Tells the browser to remember this site as TLS-only and automatically redirect non-TLS requests. Enabled by default. Configure ‘config.ssl_options` with `hsts: false` to disable.

    Set ‘config.ssl_options` with `hsts: { … }` to configure HSTS:

    • ‘expires`: How long, in seconds, these settings will stick. The minimum required to qualify for browser preload lists is 1 year. Defaults to 2 years (recommended).

    • ‘subdomains`: Set to `true` to tell the browser to apply these settings to all subdomains. This protects your cookies from interception by a vulnerable site on a subdomain. Defaults to `true`.

    • ‘preload`: Advertise that this site may be included in browsers’ preloaded HSTS lists. HSTS protects your site on every visit *except the first visit* since it hasn’t seen your HSTS header yet. To close this gap, browser vendors include a baked-in list of HSTS-enabled sites. Go to hstspreload.org to submit your site for inclusion. Defaults to ‘false`.

    To turn off HSTS, omitting the header is not enough. Browsers will remember the original HSTS directive until it expires. Instead, use the header to tell browsers to expire HSTS immediately. Setting ‘hsts: false` is a shortcut for `hsts: { expires: 0 }`.

Constant Summary collapse

HSTS_EXPIRES_IN =

:stopdoc: Default to 2 years as recommended on hstspreload.org.

63072000
PERMANENT_REDIRECT_REQUEST_METHODS =

:nodoc:

%w[GET HEAD]

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(app, redirect: {}, hsts: {}, secure_cookies: true, ssl_default_redirect_status: nil) ⇒ SSL

Returns a new instance of SSL.



76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/action_dispatch/middleware/ssl.rb', line 76

def initialize(app, redirect: {}, hsts: {}, secure_cookies: true, ssl_default_redirect_status: nil)
  @app = app

  @redirect = redirect

  @exclude = @redirect && @redirect[:exclude] || proc { !@redirect }
  @secure_cookies = secure_cookies

  @hsts_header = build_hsts_header(normalize_hsts_options(hsts))
  @ssl_default_redirect_status = ssl_default_redirect_status
end

Class Method Details

.default_hsts_options ⇒ Object 



72
73
74
 
# File 'lib/action_dispatch/middleware/ssl.rb', line 72

def self.default_hsts_options
  { expires: HSTS_EXPIRES_IN, subdomains: true, preload: false }
end

Instance Method Details

#call(env) ⇒ Object 



88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/action_dispatch/middleware/ssl.rb', line 88

def call(env)
  request = Request.new env

  if request.ssl?
    @app.call(env).tap do |status, headers, body|
      set_hsts_header! headers
      flag_cookies_as_secure! headers if @secure_cookies && !@exclude.call(request)
    end
  else
    return redirect_to_https request unless @exclude.call(request)
    @app.call(env)
  end
end