Class: ActionDispatch::SSL

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

Overview

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
 (e.g. `redirect: { host: "secure.widgets.com", port: 8080 }`), or set
 `redirect: false` to disable this feature.

2. Secure cookies: Sets the `secure` flag on cookies to tell browsers they
 mustn't 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 `18.weeks`. Defaults to
`180.days` (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 https://hstspreload.appspot.com 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 }.

Requests can opt-out of redirection with exclude:

config.ssl_options = { redirect: { exclude: -> request { request.path =~ /healthcheck/ } } }

Constant Summary collapse

HSTS_EXPIRES_IN =

Default to 180 days, the low end for https://www.ssllabs.com/ssltest/ and greater than the 18-week requirement for browser preload lists.

15552000

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Returns a new instance of SSL.



53
54
55
56
57
58
59
60
61
62
 
# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 53

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

  @redirect = redirect

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

  @hsts_header = build_hsts_header(normalize_hsts_options(hsts))
end

Class Method Details

.default_hsts_options ⇒ Object 



49
50
51
 
# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 49

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

Instance Method Details

#call(env) ⇒ Object 



64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 64

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
    end
  else
    return redirect_to_https request unless @exclude.call(request)
    @app.call(env)
  end
end