Plug v1.5.0-rc.0 Plug.SSL View Source

A plug to force SSL connections.

If the scheme of a request is https, it’ll add a strict-transport-security header to enable HTTP Strict Transport Security.

Otherwise, the request will be redirected to a corresponding location with the https scheme by setting the location header of the response. The status code will be 301 if the method of conn is GET or HEAD, or 307 in other situations.

x-forwarded-proto

If your Plug application is behind a proxy that handles HTTPS, you will need to tell Plug to parse the proper protocol from the x-forwarded-proto header. This can be done using the :rewrite_on option:

plug Plug.SSL, rewrite_on: [:x_forwarded_proto]

The command above will effectively change the value of conn.scheme by the one sent in x-forwarded-proto.

Since rewriting the scheme based on x-forwarded-proto can open up security vulnerabilities, only provide the option above if:

  • your app is behind a proxy
  • your proxy strips x-forwarded-proto headers from all incoming requests
  • your proxy sets the x-forwarded-proto and sends it to Plug

Options

  • :rewrite_on - rewrites the scheme to https based on the given headers
  • :hsts - a boolean on enabling HSTS or not, defaults to true
  • :expires - seconds to expires for HSTS, defaults to 31_536_000 (a year).
  • :preload - a boolean to request inclusion on the HSTS preload list (for full set of required flags, see: Chromium HSTS submission site), defaults to false
  • :subdomains - a boolean on including subdomains or not in HSTS, defaults to false
  • :host - a new host to redirect to if the request’s scheme is http, defaults to conn.host. It may be set to a binary or a tuple {module, function, args} that will be invoked on demand

Port

It is not possible to directly configure the port in Plug.SSL because HSTS expects the port to be 443 for SSL. If you are not using HSTS and wants to redirect to HTTPS on another port, you can sneak it alongside the host, for example: host: "example.com:443".

Link to this section Summary

Functions

Callback implementation for Plug.call/2

Callback implementation for Plug.init/1

Link to this section Functions

Callback implementation for Plug.call/2.

Callback implementation for Plug.init/1.