If you’re using Laravel Forge to host your sites, then you’re probably also using it to host staging sites that are being tested before they go live. It’s usually a good idea to put such sites behind a basic authentication to prevent the likes of Google prying on your pre-production work.

The good news is that password protecting a site with Laravel Forge is really simple to implement.

Create the password

We can use the server tool htpasswd to generate a password which comes pre-installed on Forge servers. So the first step is to ssh onto your Forge server.

You will then need to change directory to wherever you want to store your authentication credentials. It’s a good idea to store this one directory above the webroot of your site; for a Laravel or CakePHP application this will be the root of your project.

Now let’s create the password using htpasswd from the command line:

htpasswd -c .htpasswd dev

This will create a new file called .htpasswd (that’s what the -c flag is for) in the current directory with the username dev. You will be prompted for a password which you will be asked to enter twice to confirm.

Configure nginx

Next you need to set up the basic authentication in nginx with the file/password you’ve just created.

Login to your Forge account and go to edit the site you want to password protect. In the bottom right you’ll find a Files button, click this and select the Edit Nginx Configuration option. In the editor that pops up find the location / block. It will look something like this to start with:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Append this block with the auth_basic configuration:

location / {
    try_files $uri $uri/ /index.php?$query_string;

    auth_basic            "Restricted Area";
    auth_basic_user_file  /home/forge/staging.example.com/.htpasswd;
}

Save the changes. Forge will automatically check your configuration file’s syntax and load the changes if successful. If it all goes well, you should get a message a bit like this:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Testing your site protection

The final thing to do is to check that the site is now behind authentication.

Head over to the site you’ve just protected and make sure that you are prompted by the browser for login credentials. Check that it will only grant you access to the site if you enter valid login details as set up when you generated the password.

If it doesn’t work, double check your nginx configuration and make sure that the password file exists at the path defined by auth_basic_user_file.

Forgotten password

If you take a look at the file generated by htpasswd you will see that by default it hashes the passwords for added security. Unfortunately, this means that if you forget the password you can no longer retrieve it. If this happens then you can update the password via the command line:

htpasswd .htpasswd dev

This will prompt for a new password for the dev user in the .htpasswd file of the current directory. Enter a password and you should be good to start using the new credentials.