Rendering User Content

Multiple features of Jenkins, and many more in plugins, serve files that can be viewed or downloaded from Jenkins. Some built-in examples of that are the workspace browser, archived artifacts, file parameters to builds, or the /userContent/ directory. Plugins like plugin:javadoc[Javadoc], plugin:htmlpublisher[HTML Publisher], or plugin:maven-plugin[Maven Integration] (when publishing the Maven site) prominently feature functionality that serves HTML controlled by users from Jenkins.

This can be a risk, as Cross-Site Scripting attacks could be put into those HTML files by people with influence over builds who may not be fully trusted.

Content-Security-Policy

By default, Jenkins serves files that could come from less trusted sources with a strict Content-Security-Policy HTTP response header. This default prevents all JavaScript and other active elements, and only allows CSS and images served from other files in Jenkins.

While this is safe, it also prevents a lot of useful functionality from working, such as rich, dynamic HTML reports created during builds. It is possible to configure Content-Security-Policy. This is often a difficult tradeoff between functionality and security, so should only be done with great care.

Resource Root URL

As an alternative to relaxing Content-Security-Policy, administrators can configure Jenkins to serve files from potentially less trusted sources from a different domain. This option can be configured in Manage Jenkins » Configure System in the section Serve resource files from another domain.

If the resource root URL is defined, Jenkins will instead redirect requests for user-created resource files to URLs starting with the URL configured here. These URLs will not set the CSP header, allowing JavaScript and similar features to work. For this option to work as expected, the following constraints and considerations apply:

  • The resource root URL must be a valid alternative choice for the Jenkins URL for requests to be processed correctly.

  • The Jenkins URL must be set and it must be different from this resource root URL (in fact, a different host name is required).

  • Once set, Jenkins will only serve resource URL requests via the resource root URL. All other requests will get HTTP 404 Not Found responses.

Once this URL has been set up correctly, Jenkins will redirect requests to workspaces, archived artifacts, and similar collections of usually user-generated content to URLs starting with the resource root URL. Instead of a path like job/name_here/ws, resource URLs will contain a token encoding that path, the user for which the URL was created, and when it was created. These resource URLs access static files as if the user for which they were created would access them: If the user’s permission to access these files is removed, the corresponding resource URLs will not work anymore either. These URLs are accessible to anyone without authentication until they expire, so sharing these URLs is akin to sharing the files directly.

Security considerations

Authentication

Resource URLs do not require authentication (users will not have a valid session for the resource root URL). Sharing a resource URL with another user, even one lacking Overall/Read permission for Jenkins, will grant that user access to these files until the URLs expire.

Expiration

Resource URLs expire after 30 minutes by default. Expired resource URLs will redirect users to their equivalent Jenkins URLs, so that the user can reauthenticate, if necessary, and then be redirected back to a new resource URL that will be valid for another 30 minutes. This will generally be transparent to the user if they have a valid Jenkins session. Otherwise, they will need to authenticate with Jenkins again. However, when browsing pages with HTML frames, like Javadoc sites, the login form cannot appear in a frame. In these cases, users will need to reload the top-level frame to make the login form appear.

To change how quickly resource URLs expire, set the system property jenkins.security.ResourceDomainRootAction.validForMinutes to the desired value in minutes. Earlier expiration might make it harder to use these URLs, while later expiration increases the likelihood of unauthorized users gaining access through URLs shared with them by authorized users.

Authenticity

Resource URLs encode the URL, the user for which they were created, and their creation timestamp. Additionally, this string contains an HMAC to ensure the authenticity of the URL. This prevents attackers from forging URLs that would grant them access to resource files as if they were another user.