A plug to force SSL connections and enable HSTS.

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

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.

Besides being a Plug, this module also provides conveniences for configuring SSL. See configure/1.

x-forwarded-*

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

plug Plug.SSL, rewrite_on: [:x_forwarded_host, :x_forwarded_port, :x_forwarded_proto]

Rewriting happens on all requests, before the SSL options are processed. For further details, refer to Plug.RewriteOn.

Plug Options

• :rewrite_on - rewrites the given connection information 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 (1 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
• :exclude - exclude certain request from redirecting to the https scheme. It defaults to [hosts: ["localhost", "127.0.0.1"]]. See the "Exclude option" section below
• :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
• :log - The log level at which this plug should log its request info. Default is :info. Can be false to disable logging

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 want to redirect to HTTPS on another port, you can sneak it alongside the host, for example: host: "example.com:443".

Exclude option

There are many situations where one may want to avoid Plug.SSL from redirecting, such as requests coming from localhost or 127.0.0.1, or from health check endpoints.

This can be done via the :exclude option, which allows you to specify conditions to skip the redirect. As long as any of the conditions match, the route will be excluded, it must be one of:

• [hosts: list_of_hosts, ...] - skips redirection if the request matches any of the given hosts

• [paths: list_of_paths, ...] - skips redirection if the request matches any of the given paths

• [conn: {mod, fun, args}, ...] - calls the given mod, fun, and args with Plug.Conn prepended to the list of arguments. The plug will be excluded if the call returns true

The default value is [hosts: ["localhost", "127.0.0.1"]]. If you pass any additional value, you must explicitly preserve the above if you want the hosts to remain excluded.

For example, you may define it as:

plug Plug.SSL,
  exclude: [
    hosts: ["localhost", "127.0.0.1"],
    paths: ["/health"]
  ]