nginx: serving private files with X-Accel-Redirect
Tags: nginx, php
Published: 2024-05-14 17:10:55

the problem is this: we have a bunch of files, pdfs say, on our webserver that we want people to download, but only if they’re registered users. everyone else gets `404`s.

there’s no shortage of ways to homeroll a solution to this issue (i often use private s3 buckets), but perhaps the most elegant way is to configure `nginx` to do it for us. no vendor lock in with aws, no controller methods struggling under the weight of 50mb pdfs; just `nginx` serving files.

in this post, we’re going to go over how to use the `nginx`‘s `X-Accel-Redirect` header with a light sprinking of `php` to serve files from a restricted directory.

##the high-level overview

the `X-Accel-Redirect` is a response header. this means that our backed will be returning it. this is not a header that the frontend or our users send.

when `nginx` sees this header in the response, it will look at the uri attached to it and match it to a directory we define in our `nginx` virtual hosts configuration file. it will then serve the file our backend specified from that directory.

if our frontend tries to access that uri directly, however, `nginx` will return a `404`. put that all together, and we have a way to restrict what files we’re serving to whom.

###building our file access endpoint

the first step is to build our web-hittable script that serves our restricted files. the job of this script is to take the name of the file the user wants to download and their authentication credentials. if the credentials are good, we return the `X-Accel-Redirect` header with the file name and the user gets their file. if the credentials are invalid, we return http `403`: forbidden.

lets’ write this in vanilla `php`.

```php
<?php
// get the name of the requested file
$file = $_GET['file'];
// get the access credentials
$access = $_GET['access'];
// if user has access, respond with X-Accel-Redirect for the file. otherwise, 403
if($access == 'true') { 
    header("X-Accel-Redirect: /privatefiles/$file"); // this is the uri, not the directory path
}
else {
    http_response_code(403);
}
```

this script is very basic and dramatically insecure. it accepts two parameters on the query string:

* **`file`**: the name of the file the user wants to download, ie. ‘mordor.pdf’
* **`access`**: whether the user has access to the restricted files. if this value is set to `true`, they’re in. anything else, they’re denied. in real life, we would probably use something more… secure

the heart of the functionality here is the line:

```php
header("X-Accel-Redirect: /privatefiles/$file");
```

this returns our `X-Accel-Redirect` header with a uri that comprises a path to the request file. in this case, the uris for our files with be prepended with `/privatefiles/`. if the user passed `file=mordor.pdf`, we would respond with the uri `/privatefiles/mordor.pdf`.

###configuring nginx

now the interesting part: configuring `nginx`. first, let’s take a look at the full server configuration for our virtual host:

```conf
server {
    server_name xaccel.example.ca;
    root "/var/www/html/xaccel";
    index index.html index.htm index.php;
    charset utf-8;
    ###
    # The X-Accel-Redirect uri
    #
    location /privatefiles {
        internal;
        alias /var/www/html/xaccel/restrictedfiles;
    }   
    location ~ \.php$ {
        #fastcgi_param MOD_X_ACCEL_REDIRECT_ENABLED on;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_intercept_errors off;
        fastcgi_buffer_size 16k;
        fastcgi_buffers 4 16k;
        fastcgi_connect_timeout 300;
        fastcgi_send_timeout 300;
        fastcgi_read_timeout 300;
    }   
    access_log  /var/log/nginx/xaccel.example.ca-access.log combined;
    error_log  /var/log/nginx/xaccel.example.ca-error.log error;
    sendfile off;
    client_max_body_size 100m;
    listen 80; 
}
```
if you have any experience with `nginx` a lot of this should look pretty standard. the notable part is this:

```conf
location /privatefiles {
    internal;
    alias /var/www/html/xaccel/restrictedfiles;
} 
```

this `location` block defines the uri of our files and the directory where they are stored.

when our `php` script returns the header:

```php
header("X-Accel-Redirect: /privatefiles/$file");
```

nginx will match that `/privatefiles/` uri, and look in the directory set by `alias`, in this case `/var/www/html/xaccel/restrictedfiles`. if the file exists, it gets returned.

the last thing to note here is the `internal` directive. as the name implies, this means that external users can’t access any uri starting with `/privatefiles/` directly. if we try to browse to `http://xaccel.example.ca/privatefiles/mordor.pdf`, we will get a `404`.

the result is that, users with the proper authentication can access files through our `file.php` script, but no one can browse or download them directly.

###serving from a different root directory

in the above example, the directory where we served our private files was a subdirectory of our web root.

if we want, instead, to store our private files in a totally different directory, all we have to do is update the `alias` in our `nginx` configuration, ie.

```conf
location /privatefiles {
    internal;
    alias /home/ghorwood/lotrpdfs;
}   
```

doing this has the advantage of keeping our user files out of our main repository so we don’t find ourselves in the position of overwriting them when we deploy a new version of our project.

> 🔎  this post was originally written in the [grant horwood technical blog](https://gbh.fruitbat.io/2024/05/12/nginx-serving-private-files-with-x-accel/)