How to protect a Netlify branch behind a password

#netlify #authentication

Introduction

A common workflow in web development is to have a production branch and one or several development branches. The production branch host the actual state of your product, where you can make all your users happy. The development branches lets you test all the new things you are cooking.

The thing is: you might not want people to wander on those development branches. Maybe you want to keep your secrets, maybe you don't want potential users to get on those branches and think your products are not finished... Whatever the reason, you want to protect those branches and not let anybody see them.

Netlify to the rescue!

Netlify is a popular way to host static sites nowadays. Thankfully for us, Netlify offers a relatively simple way to protect specific branches. Let's see how you could achieve this.

IMPORTANT! For this feature to work, you need to be at least on a PRO plan. This feature won't work on the starter plan.

For the purpose of this article, I'll assume I am working with a React application.

What we are going to do is protect our branches behind a basic authentication system. Basically, you'll have an alert showing up prompting you to enter a username/password combination. If you can pass that test, you can access the page!

The _headers file

Netlify uses a _headers file to set up rules like Basic-Auth. The file is read from the public folder. The file would look like this:

/path-to-protect/*
    Basic-Auth: admin:password johnny:secret

You first specify the path you want to protect behind a username/password. Here it would be any path beginning with /path-to-protect/. Notice the wildcard _ to include all the paths beginning with _/path-to-protect/*.

The second line starts with the rule we want to enforce: Basic-Auth. Then, we specify a number of username:password combinations. Here I've added two: admin and johnny are the usernames, password and secret are the passwords. So, you could see my super secret project by entering admin/password or johnny/secret !

This is cool, but if I add this file, it would add a Basic-Auth rule to ALL my branches, includes the production one. Not good!

How to solve it

Here's one way you can solve this problem, step by step:

Create a file that will hold the Basic-Auth we want to implement.
In netlify.toml, modify the command when you are in the context of the branch you want to protect.
The command needs to copy the file you created into public/_headers

Creating the file

My file will be called netlify_headers. You can call it whatever you want, and place it wherever you want. One thing however: if you choose to put this file inside the public folder, do NOT call it _headers. That would trigger the rules for all the branches.

netlify_headers:

/*
    Basic-Auth: admin:supersecret

Here is my file. Notice that because I want to protect every single path on my super secret branch, I use /* as the path definition. Then, I'll be able to connect with the combination admin/supersecret.

netlify.toml

netlify.toml is a file read by Netlify that allows you to customize a lot of things, from your build commands to your environment variables or assets optimization... A lot of things are possible. If you don't have a netlify.toml file, create it in the root of your project.

In this file, you can customize depending on the branch you are. So, assuming I have two branches, one called production and the other dev. I could customize their configuration in my netlify.toml like so:

[context.production]
  command = "echo PROD && npm install && npm run build"
  REACT_APP_ENV_VAR = "supersecret"

[context.dev]
  command = "echo DEV && npm install && npm run build"
  REACT_APP_ENV_VAR = "whatever"

Depending on the branch we use to deploy, Netlify would read our file and run the appropriate command and set the right environment variable.

Copying the file for our protected branch

What we need to do now is to make sure we have a _headers file with the Basic-Auth rule for our dev branch. In order to do that, inside the context.dev command, we'll copy our netlify_headers file we created earlier into a _headers file. So, our command inside the netlify.toml file would look like that:

[context.dev]
  command = "cp netlify_headers public/_headers && npm install && npm run build"
  REACT_APP_ENV_VAR = "whatever"

We use the command cp to copy our file. This command takes two arguments, the first being the file we want to copy, the second being the file we want to copy our file into. Be careful about the path of your files. The file I want to copy is in the root of my project, so netlify_headers is the path I need to specify. The _headers file needs to be inside the public folder, hence the public/_headers path.

When you visit your protected branch, you will now be asked to enter a username and a password 😉

Congratulations! You now know how to protect specific branches behind an basic authentication process! Your rivals can't spy on your new cool features now 😄

have fun ❤️