Access-controlled files

The Access-controlled files feature restricts access to files and media uploaded to the WordPress Media Library. Two modes of Access-controlled files are supported:

• Restrict access to unpublished files mode: Files attached to draft content can only be downloaded or viewed if the request comes from a logged in WordPress user who is authorized to view the content the file is attached to.
  This mode is useful if sensitive content is regularly posted and limited access to the media attached to that content is desired.
• Restrict access to all files mode: All files in the site can only be downloaded or viewed by logged in WordPress users with capability to “read” the published content on the site.
  This mode is useful for intranets and private sites.

Only one mode can be enabled on a single site at a single time.

The Access-controlled files feature has no effect on static files (CSS, JS, etc.) committed to your application’s GitHub repo.

Enabling an Access-controlled files mode

After the Access-controlled files feature has been activated on the environment, add the following code to /vip-config/vip-config.php:

define( 'VIP_FILES_ACL_ENABLED', true );

The VIP-CLI examples below include a @<app-alias>.<env> placeholder that must be updated with the relevant VIP application alias and environment values before running the commands.

Restrict access to unpublished files

• This mode will only apply to files uploaded directly via the post editor. That creates a parent-child relationship between the post and file, which is then used to determine access and permissions.
• This mode will not apply to files uploaded directly to the WordPress Media Library, even if the file is later inserted into the post from the Media Library or a link to the file is copy-pasted directly into the post.

VIP-CLI

Set the vip_files_acl_restrict_unpublished_enabled option to a value of 1 (to disable set to 0).

vip @<app-alias>.<env> -- wp option update vip_files_acl_restrict_unpublished_enabled 1

Code

// Restrict Access to Unpublished Files
add_filter( 'pre_option_vip_files_acl_restrict_unpublished_enabled', function( $value ) {
    return 1;
} );

Restrict access to all files

VIP-CLI

Set the vip_files_acl_restrict_all_enabled option to a value of 1 to enable (to disable set to 0).

vip @<app-alias>.<env> -- wp option update vip_files_acl_restrict_all_enabled 1

Code

// Restrict All Files
add_filter( 'pre_option_vip_files_acl_restrict_all_enabled', function( $value ) {
    return 1;
} );

Enabling modes for sites on a multisite

Access-controlled files modes can be applied either globally to a WordPress multisite environment or on a per-site basis.

Enabling with VIP-CLI

• Per-site: Specify a single site by running the command with the --url=<url> flag and replacing <url> with the site’s URL.

Enabling with code

• Global: Code to enable modes for Access-controlled files should be added to client-mu-plugins.
• Per-site: Also in code added to client-mu-plugin, include logic to selectively enable a mode for a specific site on a network using get_current_blog_id().
• Per-site: Code can be added to a theme’s functions.php or any other loaded path in the theme or a plugin enabled for a specific site.

Considerations

Performance Impact

Enabling this feature can increase response times for files uploaded to the WordPress Media Library. Serving a file while this feature is active may involve a request to the WordPress application to determine per-user permissions, adding to the overall response time.

• For Access-controlled files and media, all requests can be around 10-15% slower.
• For public files and media, the first (uncached) request is expected to be around 10-15% slower. All future requests are cached and should not be impacted.

Incompatible with Basic Authentication

This feature is incompatible with our Basic Authentication feature. Environments with active Basic Authentication cannot enable the Access-controlled files feature.

To restrict access to the front end of your site while the Access-controlled files feature is active, we recommend using a different access restriction method, such as the maintenance mode plugin.

Potential conflict for self-referencing files

It might be necessary to import a WordPress XML file to an environment that has the same domain as the site from which the XML file was exported. This will result in an import that is “self-referencing”, meaning that it both exports from and imports into the same domain. An import of this kind can happen when adding media library references to a site’s media library following a media import.

If Access-controlled files is enabled, the WordPress importer will be unable to access the media path for a given media asset. The WordPress importer is only able to add media references to a media library if the media path is publicly accessible.

To prevent this issue, set VIP_FILES_ACL_ENABLED to false in vip-config.php for the duration of the XML import. The constant can be set back to true after the import has been completed.