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 or Restrict access to all files.

Limitations

• Only one mode can be enabled on a single WordPress site at a single time.
• The Access-controlled files feature has no effect on static files (e.g., CSS, JS) committed to an application’s GitHub repository.
• The Access-controlled files feature is incompatible with Basic Authentication.
• A VIP Local Development Environment will be unable to proxy media files from a WordPress multisite environment that has the Access-controlled files feature activated.

Enable “Restrict access to unpublished files” mode

When the Restrict access to unpublished files mode is enabled, 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.

Restrict access to unpublished files mode is useful if sensitive content is regularly posted and limited access to the media attached to that content is desired.

• 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.

// Restrict access to unpublished files mode
add_filter( 'pre_option_vip_files_acl_restrict_unpublished_enabled', function( $value ) {
    return 1;
} );

vip @<app-name>.<env> -- wp option add vip_files_acl_restrict_unpublished_enabled 1

vip @<app-name>.<env> -- wp option update vip_files_acl_restrict_unpublished_enabled 0

vip @<app-name>.<env> -- wp option add vip_files_acl_restrict_unpublished_enabled 1 --url=<url>

Enable “Restrict access to all files” mode

When Restrict access to all files mode is enabled, 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.

// Restrict access to all files mode
add_filter( 'pre_option_vip_files_acl_restrict_all_enabled', function( $value ) {
    return 1;
} );

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

vip @<app-name>.<env> -- wp option update vip_files_acl_restrict_all_enabled 0

vip @<app-name>.<env> -- wp option add vip_files_acl_restrict_all_enabled 1 --url=<url>

Allow access to Access-controlled files for specific requests

The vip_files_acl_file_visibility filter is useful for mobile applications or plugins that require access to Access-controlled files.

The vip_files_acl_file_visibility filter validates if a request for an Access-controlled file is legitimate. The filter accepts the parameters $file_visibility and $file_path, and returns one of the filter value constants (i.e., Automattic\VIP\Files\Acl\FILE_IS_PUBLIC , Automattic\VIP\Files\Acl\FILE_IS_PRIVATE_AND_ALLOWED , and Automattic\VIP\Files\Acl\FILE_IS_PRIVATE_AND_DENIED) to indicate what level of access to a file can be granted for a request.

Requests for Access-controlled files can be sent with HTTP Authorization header X-Original-Authorization and User Agent X-Original-User-Agent. One or both of these headers can be included in a vip_files_acl_file_visibility filter for additional validation of a request.

The HTTP Authorization header can be sent with credentials for authenticating a request. If the token value assigned to the Authorization header in a request can be matched and validated by the environment receiving the request, the request is identified as legitimate. A matching value on the receiving environment can be stored as an environment variable.

In this code example, requests from a mobile application are granted access to Access-controlled files if the token passed by X-Original-Authorization matches the environment variable APP_FILE_ACCESS_TOKEN, and the filter value constant returned is FILE_IS_PRIVATE_AND_ALLOWED:

/**
 * Allow mobile app requests to have access to Access-controlled files
 */
function vip_check_file_visibility_for_mobile_request( $file_visibility, $file_path ) {
    /**
     * Allow mobile requests with a token
     */
    $token_header = isset( $_SERVER['HTTP_X_ORIGINAL_AUTHORIZATION'] ) ? sanitize_text_field( $_SERVER['HTTP_X_ORIGINAL_AUTHORIZATION'] ) : false;

    // Get token from environment variable.
    $token = vip_get_env_var( 'APP_FILE_ACCESS_TOKEN', '' );
    if ( $token === $token_header ) {
        return Automattic\VIP\Files\Acl\FILE_IS_PRIVATE_AND_ALLOWED;
    }

    return $file_visibility;
}
add_filter( 'vip_files_acl_file_visibility', 'vip_check_file_visibility_for_mobile_request', 11, 2 );

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 VIP’s Basic Authentication. Environments with Basic Authentication enabled cannot activate the Access-controlled files feature.

To restrict access to the front end of a site while the Access-controlled files feature is active, using a different access restriction method is recommended, 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/vip-config.php for the duration of the XML import. The constant can be set back to true after the import has been completed.