Skip to content

Backgrounds

How-to Guides

Technical References

Restricting Site Access /

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

Prerequisites

The instructions below require the Access-controlled files feature to be activated on an environment. Create a request with VIP Support and indicate in the request which environment(s) should have the Access-controlled files feature activated.

VIP-CLI commands require VIP-CLI to already be installed on your local machine.

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-plugins, 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.

Last updated: September 07, 2021