nginx: serving private files with X-Accel-Redirect

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 404s.

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
// 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:

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:

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:

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:

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.

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