A Dropwizard bundle for applying default web security functionality
Java Other
Latest commit 2c45f72 Jan 27, 2017 @jmcampanini jmcampanini committed with qinfchen silence javadoc linting warnings (#74)

README.md

dropwizard-web-security

Circle CI Download

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

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: ""
    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.