Skip to content

Latest commit

 

History

History
215 lines (180 loc) · 7.17 KB

README.md

File metadata and controls

215 lines (180 loc) · 7.17 KB
Raw

dropwizard-web

Build Status Coverage Status Maven Central

Provides support for configuring various http headers that are important for web services.

Supports

  • HTTP Strict Transport Security (HSTS)
  • X-Frame-Options
  • X-Content-Type-Options
  • X-XSS-Protection (XSS)
  • Content Security Policy (CSP)
  • Cross-Origin Resource Sharing (CORS)
  • other custom headers

Usage

In your application's Configuration class, add a WebConfiguration object:

public class ExampleConfiguration extends Configuration {
    ...

    @Valid
    @NotNull
    @JsonProperty("web")
    private WebConfiguration webConfiguration = new WebConfiguration();

    public WebConfiguration getWebConfiguration() {
        return webConfiguration;
    }

    public void setWebConfiguration(final WebConfiguration webConfiguration) {
        this.webConfiguration = webConfiguration;
    }
}

Add a WebBundle to the Boostrap object in your initialize method:

bootstrap.addBundle(new WebBundle<ExampleConfiguration>() {
    @Override
    public WebConfiguration getWebConfiguration(final ExampleConfiguration configuration) {
        return configuration.getWebConfiguration();
    }
});

Basic Configuration

Define the following configuration in your config.yml file:

web:
  uriPath: /api
  hsts:
    enabled: true
  frame-options:
    enabled: true
  content-type-options:
    enabled: true
  xss-protection:
    enabled: true

uriPath should indicate the path where APIs are served from.

This minimal config results in the following:

  • HSTS configured for 1 year, including sub domains
  • Frames disabled
  • Content-Type sniffing disabled
  • XSS filtering on in block mode

Support for CORS or CSP require additional configuration.

Maven Artifacts

This project is available on Maven Central. To add it to your project simply add the following dependencies to your pom.xml:

<dependency>
  <groupId>io.dropwizard.modules</groupId>
  <artifactId>dropwizard-web</artifactId>
  <version>${dropwizard-web.version}</version>
</dependency>

Configuration Reference

Web Configuration

Name Default Description
hsts (1 year, including sub domains) Configure Strict-Transport-Security.
frame-options (disable frames) Configure X-Frame-Options.
content-type-options (disable content-type sniffing) Configure X-Content-Type-Options.
xss-protection (on in block mode) Configure X-XSS-Protection.
csp (none) Configure Content Security Policy.
cors (none) Configure Cross-Origin Resource Sharing.
headers (none) Configure custom headers.

HTTP Strict Transport Security (HSTS)

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security

web:
  hsts:
    enabled: true
    maxAge: 365 days
    includeSubDomains: true
Name Default Description
maxAge 365 days The time that the browser should remember that a site is only to be accessed using HTTPS.
includeSubDomains true If true, this rule applies to all of the site's subdomains as well.
preload false See Preloading Strict Transport Security for details.
enabled false If false, does not apply header(s).

X-Frame-Options

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options

web:
  frame-options:
    enabled: true
    option: SAMEORIGIN
Name Default Description
option DENY Must be one of: DENY, SAMEORIGIN, ALLOW-FROM
origin (none) If option is ALLOW-FROM, identifies the origin that will be allowed to display this page in a frame.
enabled false If false, does not apply header(s).

X-Content-Type-Options

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options

web:
  content-type-options:
    enabled: true
Name Default Description
enabled false If false, does not apply header(s).

X-XSS-Protection (XSS)

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection

web:
  xss-protection:
    enabled: true
    on: true
    block: true
Name Default Description
on true If true, enables XSS filtering.
block true If true, when browser detects an attack, the page will not be rendered. If false, the browser will sanitize the page to remove the unsafe parts.
enabled false If false, does not apply header(s).

Content Security Policy (CSP)

web:
  csp:
    enabled: true
    policy: "default-src 'self'"
Name Default Description
policy (none) Policy directives that control resources the browser is allowed to load for a page.
reportOnlyPolicy (none) Same as 'policy' but only reports violations instead of preventing them.
enabled false If false, does not apply header(s).

Cross-Origin Resource Sharing (CORS)

web:
  cors:
    allowedOrigins: ["example.com"]
    allowedMethods: ["DELETE","GET","HEAD","POST","PUT"]
    allowedHeaders: ["Accept","Authorization","Content-Type","Origin","X-Requested-With"]
    preflightMaxAge: 30 minutes
Name Default Description
allowedOrigins (all origins) A list of origins that are allowed to access the resources.
allowedTimingOrigins (no origins) A list of origins that are allowed to time the resources.
allowedMethods ["GET","POST","HEAD"] A list of HTTP methods that are allowed to be used when accessing the resources.
preflightMaxAge 30 minutes The duration that preflight requests can be cached by the client.
allowCredentials true A boolean indicating if the resource allows requests with credentials.
exposedHeaders (empty list) A list of HTTP headers that are allowed to be exposed on the client.
chainPreflight true If true, preflight requests are chained to their target resource for normal handling (as an OPTION request). Else, the filter will respond to the preflight.

Other Headers

web:
  headers:
    X-Custom-Header-1: custom value 1
    X-Custom-Header-2: custom value 2
Name Default Description
headers (none) Map of headers (name and value) to include in the response.

Support

Please file bug reports and feature requests in GitHub issues.