Class: ActionDispatch::SSL
Relationships & Source Files | |
Inherits: | Object |
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:
-
**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. = { redirect: { host: "secure.widgets.com", port: 8080 }`
Or set ‘redirect: false` to disable redirection.
Requests can opt-out of redirection with
exclude
:config. = { 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
totrue
:config.assume_ssl = true
-
**Secure cookies**: Sets the
secure
flag on cookies to tell browsers they must not be sent along with http:// requests. Enabled by default. Setconfig.ssl_options
with ‘secure_cookies: false` to disable this feature. -
**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 totrue
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 totrue
. -
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 tofalse
.
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
-
HSTS_EXPIRES_IN =
# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 6863072000
-
PERMANENT_REDIRECT_REQUEST_METHODS =
# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 70%w[GET HEAD]
Class Method Summary
Instance Method Summary
- #call(env)
- #build_hsts_header(hsts) private
- #flag_cookies_as_secure!(headers) private
- #https_location_for(request) private
- #normalize_hsts_options(options) private
- #redirect_to_https(request) private
- #redirection_status(request) private
- #set_hsts_header!(headers) private
Constructor Details
.new(app, redirect: {}, hsts: {}, secure_cookies: true, ssl_default_redirect_status: nil) ⇒ SSL
# File 'actionpack/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 = @hsts_header = build_hsts_header( (hsts)) @ssl_default_redirect_status = ssl_default_redirect_status end
Class Method Details
.default_hsts_options
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 72
def self. { expires: HSTS_EXPIRES_IN, subdomains: true, preload: false } end
Instance Method Details
#build_hsts_header(hsts) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 122
def build_hsts_header(hsts) value = +"max-age=#{hsts[:expires].to_i}" value << "; includeSubDomains" if hsts[:subdomains] value << "; preload" if hsts[:preload] value end
#call(env)
[ GitHub ]# File 'actionpack/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 headers if @secure_cookies && !@exclude.call(request) end else return redirect_to_https request unless @exclude.call(request) @app.call(env) end end
#flag_cookies_as_secure!(headers) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 129
def (headers) = headers[Rack::SET_COOKIE] return unless if Gem::Version.new(Rack::RELEASE) < Gem::Version.new("3") = .split("\n") headers[Rack::SET_COOKIE] = .map { || if !/;\s*secure\s*(;|$)/i.match?( ) "#{}; secure" else end }.join("\n") else headers[Rack::SET_COOKIE] = Array( ).map do || if !/;\s*secure\s*(;|$)/i.match?( ) "#{}; secure" else end end end end
#https_location_for(request) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 170
def https_location_for(request) host = @redirect[:host] || request.host port = @redirect[:port] || request.port location = +"https://#{host}" location << ":#{port}" if port != 80 && port != 443 location << request.fullpath location end
#normalize_hsts_options(options) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 107
def ( ) case # Explicitly disabling HSTS clears the existing setting from browsers by setting # expiry to 0. when false self.class. .merge(expires: 0) # Default to enabled, with default options. when nil, true self.class. else self.class. .merge( ) end end
#redirect_to_https(request) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 153
def redirect_to_https(request) [ @redirect.fetch(:status, redirection_status(request)), { Rack::CONTENT_TYPE => "text/html; charset=utf-8", Constants::LOCATION => https_location_for(request) }, (@redirect[:body] || []) ] end
#redirection_status(request) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 160
def redirection_status(request) if PERMANENT_REDIRECT_REQUEST_METHODS.include?(request.raw_request_method) 301 # Issue a permanent redirect via a GET request. elsif @ssl_default_redirect_status @ssl_default_redirect_status else 307 # Issue a fresh request redirect to preserve the HTTP method. end end
#set_hsts_header!(headers) (private)
[ GitHub ]# File 'actionpack/lib/action_dispatch/middleware/ssl.rb', line 103
def set_hsts_header!(headers) headers[Constants::STRICT_TRANSPORT_SECURITY] ||= @hsts_header end