Documentation

You are viewing the documentation for the 2.5.0 release in the 2.5.x series of releases. The latest stable release series is 3.0.x.

§Allowed hosts filter

Play provides a filter that lets you configure which hosts can access your application. This is useful to prevent cache poisoning attacks. For a detailed description of how this attack works, see this blog post. The filter introduces a whitelist of allowed hosts and sends a 400 (Bad Request) response to all requests with a host that do not match the whitelist.

§Enabling the allowed hosts filter

To enable the filter, first add the Play filters project to your libraryDependencies in build.sbt:

libraryDependencies += filters

Now add the allowed hosts filter to your filters, which is typically done by creating a Filters class in the root of your project:

Scala
import javax.inject.Inject

import play.api.http.HttpFilters
import play.filters.hosts.AllowedHostsFilter

class Filters @Inject() (allowedHostsFilter: AllowedHostsFilter) extends HttpFilters {
  def filters = Seq(allowedHostsFilter)
}
Java
import play.mvc.EssentialFilter;
import play.filters.hosts.AllowedHostsFilter;
import play.http.HttpFilters;

import javax.inject.Inject;

public class Filters implements HttpFilters {

    @Inject
    AllowedHostsFilter allowedHostsFilter;

    public EssentialFilter[] filters() {
        return new EssentialFilter[] { allowedHostsFilter.asJava() };
    }
}

§Configuring allowed hosts

You can configure which hosts the filter allows using application.conf. See the Play filters reference.conf to see the defaults.

play.filters.hosts.allowed is a list of strings of the form .example.com or example.com. With a leading dot, the pattern will match example.com and all subdomains (www.example.com, foo.example.com, foo.bar.example.com, etc.). Without the leading dot it will just match the exact domain. If your application runs on a specific port, you can also include a port number, for instance .example.com:8080.

You can use the . pattern to match all hosts (not recommended in production). Note that the filter also strips the dot character from the end of the host, so the example.com pattern will match example.com.

An example configuration follows.

play.filters.hosts {
  # Allow requests to example.com, its subdomains, and localhost:9000.
  allowed = [".example.com", "localhost:9000"]
}

Next: Extending Play with modules