HSTS

Http4s provides a Middleware giving support for HTTP Strict Transport Security (HSTS). The middleware is called HSTS and simply adds a header to enable a HSTS security policy. Though it is not enforced, HSTS only makes sense for an https service.

Examples in this document have the following dependencies.

libraryDependencies ++= Seq(
  "org.http4s" %% "http4s-dsl" % http4sVersion,
  "org.http4s" %% "http4s-server" % http4sVersion
)

And we need some imports.

import org.http4s._
import org.http4s.dsl.io._
import cats.effect.IO

Let’s make a simple service that will be exposed and wrapped with HSTS.

val service = HttpService[IO] {
  case _ =>
    Ok("ok")
}
// service: HttpService[IO] = Kleisli(
//   org.http4s.HttpService$$$Lambda$12903/708292025@2ac4f0a1
// )

val request = Request[IO](Method.GET, uri("/"))
// request: Request[IO] = Request(
//   Method("GET"),
//   Uri(None, None, "/", Query(), None),
//   HttpVersion(1, 1),
//   Headers(),
//   Stream(..),
//   org.http4s.AttributeMap@8cf85da
// )

// Do not call 'unsafeRunSync' in your code
val response1 = service.orNotFound(request).unsafeRunSync
// response1: Response[IO] = Response(
//   Status(200),
//   HttpVersion(1, 1),
//   Headers(
//     Content-Type(MediaType(text/plain), Some(Charset(UTF-8))),
//     Content-Length(2L)
//   ),
//   Stream(..),
//   org.http4s.AttributeMap@8cf85da
// )
response1.headers
// res0: Headers = Headers(
//   Content-Type(MediaType(text/plain), Some(Charset(UTF-8))),
//   Content-Length(2L)
// )

If we were to wrap this on the HSTS middleware.

import org.http4s.server.middleware._
val hstsService2 = HSTS(service)
// hstsService2: HttpService[IO] = Kleisli(
//   org.http4s.server.middleware.HSTS$$$Lambda$13524/963615858@10deb3e6
// )

// Do not call 'unsafeRunSync' in your code
val response2 = hstsService2.orNotFound(request).unsafeRunSync
// response2: Response[IO] = Response(
//   Status(200),
//   HttpVersion(1, 1),
//   Headers(
//     Content-Type(MediaType(text/plain), Some(Charset(UTF-8))),
//     Content-Length(2L),
//     Strict-Transport-Security(31536000L, true, false)
//   ),
//   Stream(..),
//   org.http4s.AttributeMap@8cf85da
// )
response2.headers
// res1: Headers = Headers(
//   Content-Type(MediaType(text/plain), Some(Charset(UTF-8))),
//   Content-Length(2L),
//   Strict-Transport-Security(31536000L, true, false)
// )

Now the response has the Strict-Transport-Security header which will mandate browsers supporting HSTS to always connect using https.

As described in Middleware, services and middleware can be composed though HSTS is something you may want enabled across all your routes.

Configuration

By default HSTS is configured to indicate that all requests during 1 year should be done over https and it will contain the includeSubDomains directive by default.

If you want to preload or change other default values you can pass a custom header, e.g.

import org.http4s.headers._
import scala.concurrent.duration._

val hstsHeader = `Strict-Transport-Security`.unsafeFromDuration(30.days, includeSubDomains = true, preload = true)
// hstsHeader: Strict-Transport-Security = Strict-Transport-Security(
//   2592000L,
//   true,
//   true
// )
val hstsService3 = HSTS(service, hstsHeader)
// hstsService3: HttpService[IO] = Kleisli(
//   org.http4s.server.middleware.HSTS$$$Lambda$13524/963615858@23008a56
// )

// Do not call 'unsafeRunSync' in your code
val response3 = hstsService3.orNotFound(request).unsafeRunSync
// response3: Response[IO] = Response(
//   Status(200),
//   HttpVersion(1, 1),
//   Headers(
//     Content-Type(MediaType(text/plain), Some(Charset(UTF-8))),
//     Content-Length(2L),
//     Strict-Transport-Security(2592000L, true, true)
//   ),
//   Stream(..),
//   org.http4s.AttributeMap@8cf85da
// )
response3.headers
// res2: Headers = Headers(
//   Content-Type(MediaType(text/plain), Some(Charset(UTF-8))),
//   Content-Length(2L),
//   Strict-Transport-Security(2592000L, true, true)
// )

HSTS

Configuration

References