README.md

dropwizard-web-security

A bundle for applying default web security functionality to a dropwizard application. It covers the following areas:

• Cross-Origin Resource Sharing (CORS) [2] [3]
• Web Application Security Headers (Content Security Policy, etc.)

Usage

1. Add the dependency to your project.

   repository {
       jcenter()
   }
   
   dependencies {
       compile 'com.palantir.websecurity:dropwizard-web-security:<latest-version>'
   }

2. Ensure your configuration implements WebSecurityConfigurable.

   public static final class ExampleConfiguration extends Configuration implements WebSecurityConfigurable {
   
       @JsonProperty("webSecurity")
       @NotNull
       @Valid
       private final WebSecurityConfiguration webSecurity = WebSecurityConfiguration.DEFAULT;
   
       public WebSecurityConfiguration getWebSecurityConfiguration() {
           return this.webSecurity;
       }
   }

3. Add the bundle to your application.

   public class ExampleApplication extends Application<ExampleConfiguration> {
   
       @Override
       public void initialize(Bootstrap<ExampleConfiguration> bootstrap) {
           bootstrap.addBundle(new WebSecurityBundle());
       }
   }

Configuration

App Security headers are added by default. The following are the default values, only specify values in your configuration if they differ from the default values shown below.

webSecurity:
  contentSecurityPolicy: "default-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'self';"     # CSP
  contentTypeOptions: "nosniff"                                                     # X-Content-Type-Options
  frameOptions: "sameorigin"                                                        # X-Frame-Options
  xssProtection: "1; mode=block"                                                    # X-XSS-Protection

NOTE: To disable a specific header, set the value to "".

CORS Configuration

CORS is disabled by default. To enable CORS, set the allowedOrigins method to a non-empty string.

The following are the default values, only specify values if they differ from the default values shown below.

webSecurity:
  cors:
    allowCredentials: false
    allowedHeaders: "Accept,Authorization,Content-Type,Origin,X-Requested-With"
    allowedMethods: "DELETE,GET,HEAD,POST,PUT"
    allowedOrigins: ""
    chainPreflight: true
    exposedHeaders: ""
    preflightMaxAge: 1800

NOTE: The values shown are from CrossOriginFilter, except the following:

• allowedOrigins - set to blank instead of "*" to require the user to enter the allowed origins
• allowCredentials - set to false by default since credentials should be passed via the Authorization header
• allowedHeaders - set to include the default set of headers and the Authorization header
• allowedMethods - set to include a default set of commonly used methods

Advanced Usage

App-Specific Settings

You can customize your application's defaults by defining it inside of your Dropwizard application. Any value not set will be set to the default values.

Note: the application default values will be overridden by the YAML defined values.

public static final class ExampleApplication extends Application<ExampleConfiguration> {

    private final WebSecurityConfiguration webSecurityDefaults = WebSecurityConfiguration.builder()

            // set app defaults for different header values
            .contentSecurityPolicy(CSP_FROM_APP)
            .contentTypeOptions(CTO_FROM_APP)

            // CORS is still DISABLED, since the allowedOrigins is not set, but the default value will be
            // respected if it's ever turned on
            .cors(CorsConfiguration.builder()
                    .preflightMaxAge(60 * 10)
                    .build())

            .build();

    private final WebSecurityBundle webSecurityBundle = new WebSecurityBundle(this.webSecurityDefaults);

    @Override
    public void initialize(Bootstrap<ExampleConfiguration> bootstrap) {
        bootstrap.addBundle(this.webSecurityBundle);
    }
}

Using the Derived Configuration

You can also get the derived configuration to create a matching WebSecurityHeaderInjector:

WebSecurityHeaderInjector injector = new WebSecurityHeaderInjector(webSecurityBundle.getDerivedConfiguration());

Contributing

Before working on the code, if you plan to contribute changes, please read the CONTRIBUTING document.

License

This project is made available under the Apache 2.0 License.