silverstripe-framework/docs/en/02_Developer_Guides/14_Files/03_File_Security.md

summary: Manage access permission to assets

File Security

Security overview

File security is an important concept, and is as essential as managing any other piece of data that exists in your system. As pages and dataobjects can be either versioned, or restricted to view by authenticated members, it is necessary at times to apply similar logic to any files which are attached to these objects in the same way.

Out of the box SilverStripe Framework comes with an asset storage mechanism with two stores, a public store and a protected one. Most operations which act on assets work independently of this mechanism, without having to consider whether any specific file is protected or public, but can normally be instructed to favour private or protected stores in some cases.

For instance, in order to write an asset to a protected location you can use the following additional config option:

:::php
$store = singleton(AssetStore::class);
$store->setFromString('My protected content', 'Documents/Mydocument.txt', null, null, array(
    'visibility' => AssetStore::VISIBILITY_PROTECTED
));

User access control

Access for files is granted on a per-session basis, rather than on a per-member basis, via whitelisting accessed assets. This means that access to any protected asset must be made prior to the user actually attempting to download that asset. This is normally done in the PHP request that generated the response containing the link to that file.

An automated system will, in most cases, handle this whitelisting for you. Calls to getURL() will automatically whitelist access to that file for the current user. Using this as a guide, you can easily control access to embedded assets at a template level.

:::ss
<ul class="files">
    <% loop $File %>
        <% if $canView %>
            <li><a href="$URL">Download $Title</a></li>
        <% else %>
            <li>Permission denied for $Title</li>
        <% end_if %>
    <% end_loop >
</ul>

Users who are able to guess the value of $URL will not be able to access those urls without being authorised by this code.

In order to ensure protected assets are not leaked publicly, but are properly whitelisted for authorised users, the following should be considered:

• Caching mechanisms which prevent $URL being invoked for the user's request (such as $URL within a partial cache block) will not whitelist those files automatically. You can manually whitelist a file via PHP for the current user instead, by using the following code to grant access.

  :::php class PageController extends ContentController { public function init() { parent::init(); // Whitelist any protected files on this page for the current user foreach($this->Files() as $file) { if($file->canView()) { $file->grantFile(); } } } }

• If a user does not have access to a file, you can still generate the URL but suppress the default permission whitelist by invoking the getter as a method, but pass in a falsey value as a parameter. (or '0' in template as a workaround for all parameters being cast as string)

  ::php <% if not $canView %>

• Access to $Title is denied
<% else %>

• Alternatively, if a user has already been granted access, you can explicitly revoke their access using the revokeFile method.

  :::php class PageController extends ContentController { public function init() { parent::init(); // Whitelist any protected files on this page for the current user foreach($this->Files() as $file) { if($file->canView()) { $file->grantFile(); } else { // Will revoke any historical grants $file->revokeFile(); } } } }

Controlling asset visibility

The asset API provides three main mechanisms for setting the visibility of an asset. Note that these operations are applied on a per file basis, and unlike revoke or grant methods these do not affect visibility for specific users.

Visibility can be specified when files are created via one of the AssetStore::VISIBILITY_PROTECTED or AssetStore::VISIBILITY_PUBLIC constants. It's advisable to ensure the visibility of any file is declared as early as possible, so that potentially sensitive content never touches any public facing area.

E.g.

:::php
$object->MyFile->setFromLocalFile($tmpFile['Path'], $filename, null, null, array(
    'visibility' => AssetStore::VISIBILITY_PROTECTED
));

You can also adjust the visibility of any existing file to either public or protected.

:::
// This will make the file available only when a user calls `->grant()`
$object->SecretFile->protectFile();

// This file will be available to everyone with the URL
$object->PublicFile->publishFile();

One thing to note is that all variants of a single file will be treated as a single entity for access control, so specific variants cannot be individually controlled.

How file access is protected

Public urls to files do not change, regardless of whether the file is protected or public. Similarly, operations which modify files do not normally need to be told whether the file is protected or public either. This provides a consistent method for interacting with files.

In day to day operation, moving assets to or between either of these stores does not normally alter these asset urls, as the routing mechanism will infer file access requirements dynamically. This allows you to prepare predictable file urls on a draft site, which will not change once the page is published, but will be protected in the mean time.

For instance, consider two files OldCompanyLogo.gif in the public store, and NewCompanyLogo.gif in the protected store, awaiting publishing.

Internally your folder structure would look something like:

:::
assets/
    .htaccess
    .protected/
        .htaccess
        a870de278b/
            NewCompanyLogo.gif
    33be1b95cb/
        OldCompanyLogo.gif

The urls for these two files, however, do not reflect the physical structure directly.

• http://www.mysite.com/assets/33be1b95cb/OldCompanyLogo.gif will be served directly from the web server, and will not invoke a php request.
• http://www.mysite.com/assets/a870de278b/NewCompanyLogo.gif will be routed via a 404 handler to PHP, which will be passed to the [api:ProtectedFileController] controller, which will serve up the content of the hidden file, conditional on a permission check.

When the file NewCompanyLogo.gif is made public, the url will not change, but the file location will be moved to assets/a870de278b/NewCompanyLogo.gif, and will be served directly via the web server, bypassing the need for additional PHP requests.

:::php
$store = singleton(AssetStore::class);
$store->publish('NewCompanyLogo.gif', 'a870de278b475cb75f5d9f451439b2d378e13af1');

After this the filesystem will now look like below:

:::
assets/
    .htaccess
    .protected/
        .htaccess
    33be1b95cb/
        OldCompanyLogo.gif
    a870de278b/
        NewCompanyLogo.gif

Performance considerations

In order to ensure that a site does not invoke any unnecessary PHP processes when serving up files, it's important to ensure that your server is configured correctly. Serving public files via PHP will add unnecessary load to your server, but conversely, attempting to serve protected files directly may lead to necessary security checks being omitted.

See the web server setting section below for more information on configuring your server properly

Performance: Static caching

If you are deploying your site to a server configuration that makes use of static caching, it's essential that you ensure any page or dataobject cached adequately publishes any linked assets. This is due to the fact that static caching will bypass any PHP request, which would otherwise be necessary to whitelist protected files for these users.

This is especially important when dealing with draft content, as frontend caches should not attempt to cache protected content being served to authenticated users. This can be achieved by configuring your cache correctly to skip Pragma: no-cache headers and the bypassStaticCache cookie.

Configuring protected assets

Configuring: Protected folder location

In the default SilverStripe configuration, protected assets are placed within the web root into the assets/.protected folder, into which is also generated a .htaccess or web.config configured to deny any and all direct web requests.

In order to better ensure these files are protected, it's recommended to move this outside of the web root altogether.

For instance, given your web root is in the folder /sites/mysite/www, you can tell the asset store to put protected files into /sites/mysite/protected with the below .env setting:

SS_PROTECTED_ASSETS_PATH="/sites/mysite/protected"

Configuring: File types

In addition to configuring file locations, it's also important to ensure that you have allowed the appropriate file extensions for your instance. This can be done by setting the File.allowed_extensions config.

:::yaml
File: 
  allowed_extensions: 
    - 7zip 
    - xzip

Any file not included in this config, or in the default list of extensions, will be blocked from any requests to the assets directory. Invalid files will be blocked regardless of whether they exist or not, and will not invoke any PHP processes.

Configuring: Protected file headers

In certain situations, it's necessary to customise HTTP headers required either by intermediary caching services, or by the client, or upstream caches.

When a protected file is served it will also be transmitted with all headers defined by the SilverStripe\Filesystem\Flysystem\FlysystemAssetStore.file_response_headers config. You can customise this with the below config:

:::yaml
SilverStripe\Filesystem\Flysystem\FlysystemAssetStore:
  file_response_headers:
    Pragma: 'no-cache'

Configuring: Archive behaviour

By default, the default extension AssetControlExtension will control the disposal of assets attached to objects when those objects are archived. For example, unpublished versioned objects will automatically have their attached assets moved to the protected store. The archive of draft or (or deletion of unversioned objects) will have those assets permanantly deleted (along with all variants).

Note that regardless of this setting, the database record will still be archived in the version history for all Versioned DataObjects.

In some cases, it may be preferable to have any assets retained for archived versioned dataobjects, instead of deleting them. This uses more disk storage, but will allow the full recovery of archived records and files.

This can be applied to DataObjects on a case by case basis by setting the keep_archived_assets config to true on that class. Note that this feature only works with dataobjects with the Versioned extension.

:::php
class MyVersiondObject extends DataObject {
    /** Ensure assets are archived along with the DataObject */
    private static $keep_archived_assets = true;
    /** Versioned */
    private static $extensions = array('Versioned');
}

The extension can also be globally disabled by removing it at the root level:

:::yaml
DataObject:
  AssetControl: null

Configuring: Web server settings

If the default server configuration is not appropriate for your specific environment, then you can further customise the .htaccess or web.config by editing one or more of the below:

• Assets_HTAccess.ss: Template for public permissions on the Apache server.
• Assets_WebConfig.ss: Template for public permissions on the IIS server.
• Protected_HTAccess.ss: Template for the protected store on the Apache server (should deny all requests).
• Protected_WebConfig.ss: Template for the protected store on the IIS server (should deny all requests).

Each of these files will be regenerated on ?flush, so it is important to ensure that these files are overridden at the template level, not via manually generated configuration files.

Configuring Web Server: Apache server

In order to ensure that public files are served correctly, you should check that your ./assets .htaccess bypasses PHP requests for files that do exist. The default template (declared by Assets_HTAccess.ss) has the following section, which may be customised in your project:

# Non existant files passed to requesthandler
RewriteCond %{REQUEST_URI} ^(.*)$
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule .* ../framework/main.php?url=%1 [QSA]

You will need to ensure that your core apache configuration has the necessary AllowOverride settings to support the local .htaccess file.

Configuring Web Server: Windows IIS 7.5+

Configuring via IIS requires the Rewrite extension to be installed and configured properly. Any rules declared for the assets folder should be able to dynamically serve up existing files, while ensuring non-existent files are processed via the Framework.

The default rule for IIS is as below (only partial configuration displayed):

<rule name="Protected and 404 File rewrite" stopProcessing="true">
    <match url="^(.*)$" />
    <conditions>
        <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
    </conditions>
    <action type="Rewrite" url="../framework/main.php?url={R:1}" appendQueryString="true" />
</rule>

You will need to make sure that the allowOverride property of your root web.config is not set to false, to allow these to take effect.

Configuring Web Server: Other server types

If using a server configuration which must be configured outside of the web or asset root, you will need to make sure you manually configure these rules.

For instance, this will allow your nginx site to serve files directly, while ensuring dynamic requests are processed via the Framework:

:::
location ^~ /assets/ {
    sendfile on;
    try_files $uri /framework/main.php?url=$uri&$query_string;
}