Apache Sling Security

This module is part of the Apache Sling project.

The Apache Sling Security module provides:

• CSRF protection through the Referrer Filter
• download hardening through the Content Disposition Filter

This OSGi bundle can be used as a standalone bundle outside of Apache Sling. In that case, only the Referrer Filter functionality is available, as the Content Disposition Filter depends on the Apache Sling API.

Requirements

• Java 11+
• Maven

The project inherits build plugins and checks from Sling parent POM 66.

Build and test

• Build: mvn clean install
• Build without tests: mvn clean install -DskipTests
• Run tests: mvn test
• Run ReferrerFilter tests: mvn test -Dtest=ReferrerFilterTest
• Run ContentDispositionFilter tests: mvn test -Dtest=ContentDispositionFilterTest
• Run a single test method: mvn test -Dtest=ReferrerFilterTest#testMethodName
• Run Spotless check: mvn spotless:check
• Apply Spotless formatting: mvn spotless:apply
• Run RAT license checks: mvn rat:check
• Run OSGi baseline checks: mvn baseline:check

Referrer Filter (CSRF protection)

The Referrer Filter is registered as an OSGi HTTP Whiteboard Preprocessor and checks browser-originated modification requests. It validates the referer header and falls back to origin when referer is not present. The filter is applied to configured modification methods and supports path and user-agent based exclusions.

Configuration PID: org.apache.sling.security.impl.ReferrerFilter

Main configuration options:

• Allow Empty (allow.empty)
• Allow Hosts (allow.hosts)
• Allow Regexp Host (allow.hosts.regexp)
• Filter Methods (filter.methods)
• Exclude Regexp User Agent (exclude.agents.regexp)
• Exclude Paths (exclude.paths)

Sample configuration

{
  "allow.empty": false,
  "allow.hosts": ["mysite.com", "localhost"],
  "allow.hosts.regexp": [],
  "filter.methods": ["POST", "PUT", "DELETE", "COPY", "MOVE"],
  "exclude.agents.regexp": [],
  "exclude.paths": []
}

It is also possible to amend this configuration with factory configurations for:

• Factory PID: org.apache.sling.security.impl.ReferrerFilterAmendmentImpl

Sample amendment configuration

{
  "allow.hosts": ["mysite.com", "localhost"],
  "allow.hosts.regexp": [],
  "exclude.agents.regexp": [],
  "exclude.paths": []
}

Content Disposition Filter

The Content Disposition Filter is a Sling request/forward filter that adds Content-Disposition: attachment for configured resource paths on GET and HEAD requests. It supports exact path includes, prefix includes (* suffix), exclusions, and optional all-path mode.

The header is only added for resources that contain jcr:data directly or below jcr:content/jcr:data. Per-path content type lists are interpreted as excluded content types for that path.

Configuration PID: org.apache.sling.security.impl.ContentDispositionFilter

Main configuration options:

• Included Resource Paths & Content Types (sling.content.disposition.paths)
• Excluded Resource Paths (sling.content.disposition.excluded.paths)
• Enable For All Resource Paths (sling.content.disposition.all.paths)

Sample configuration

{
  "sling.content.disposition.paths": [
    "/content/secure/*",
    "/content/files/report.pdf:text/html,text/plain"
  ],
  "sling.content.disposition.excluded.paths": [
    "/content/secure/preview"
  ],
  "sling.content.disposition.all.paths": false
}