[Support Guide] Access control options for your Netlify sites

Last reviewed by Netlify Support: September 2023

You’ve got an awesome Netlify site. Maybe you’re pre-launch, or maybe you’re working on a new beta version in a branch. Maybe it’s a site intended only for a limited audience, such as your co-workers. Regardless, you want to limit access. This article is a guide to what facilities are available and how you might use them.

Our most flexible and performant protection is our Identity service. This is very flexible, featuring:

Simpler but still somewhat flexible is configuring Basic Authentication with custom HTTP headers via our custom headers facility. This method is flexible in that you can configure multiple username/password pairs (and change some or all of them with a new deploy), and you can also scope this protection to specific paths or assets - put a password on accessing the spreadsheet but not the webpage linking to it, or serve an unauthenticated landing page on the same site where all the real content is protected. Something to keep in mind is that this method is set per deploy, and since we have atomic deploys, you cannot apply it to past deploys, or remove it from deploys that had it enabled accidentally. Assets protected in this way require authentication to be done at our CDN Origin (on the west coast US as of this writing) for each asset loaded, meaning that those assets will not perform as well as one that can be serviced directly from our CDN node cache, closer to the browser.

The simplest option Netlify offers is built-in site protection in your site and team settings. These options let you set a password to protect your entire site or just branch deploys and Deploy Previews; learn more about this in the docs. Note: You will need to find a way to share this password with your visitors, and if it leaks, you will need to change it and repeat the process. This can be turned on and off instantly through our UI or API as needed.

A related article is this guide to creating Build-context-specific settings, including HTTP Basic-Auth passwords, where we go into a lot of details about how to password protect “groups” of builds - only specific branches, only PR’s, etc.

We do know there are other types of password protection that folks want - retroactively applied to production deploys that aren’t published, for instance - and we don’t have a perfect way to handle that today. Let us know below what interesting solutions and struggles you have for protecting your content!

1 Like

This is a great explanation for site control. I have one question regrading HTTP Basic Auth. If my code is kept in a public repository, how to I keep the passwords hidden in the _headers file (or netlify_headers for branch builds). Is this only an effective method for private repos? Thank you

1 Like

Yes, since the headers file would need to exist in your repo, it’s only useful for Private repos. Could you explain why you need this for a public repo? I mean, if the repo is public, anyone can clone it and deploy it, thus defeating the purpose of authentication.

Thank you for the answer. That’s what I needed to know. This project will be open sourced so I intend on making the repo public eventually. So I will plan on implementing your identity service long term. Which I on my long term road map. Thank you

1 Like

I see Netlify’s blog post about automatically and conditionally defining non-production branch deploys with basic auth passwords, using makedir’s and/or context etc - but what’s not clear to me is how to simply add password protection to just a single chosen, non-main branch.

My assumption is that I could add a _headers or netlify.toml config file to just that branch and basic auth password protection would apply just to that branch. Is that correct?

I’ve tried that but it hasn’t worked for me. A couple issues might be:

a) Netlify doesn’t work like that.

b) Nextjs or Netlify is ignoring underscore _headers file when it builds the static site generation and therefore it never makes it to the “build” folder.

c) netlify.toml is only for the main branch and can’t be applied to other individual branches separately?

d) I’m missing something entirely.

Thoughts? Thanks.

Update: Apologies. The “netlify.toml solely in the non-prod branch” is now working to create a basic auth password protection.

I am glad it is working now! If you have additional questions, please let us know!

in my use case, I use HTTP Basic Auth just to keep things private for me whilst i work on them. I could use preview branches or other solutions, but honestly it’s nice to not have to have separate branches for everything I work on; I can go to my site as normal, and I see my work in progress, but others don’t - I use my site as a build diary for all my projects, and only publish public ally when i’m ready. With several projects on the go at one time, if i split this into branches i’d be always having to remember which branch and which URL was which project; rather with Basic Auth on the projects I don’t want available, I can just go to the page as normal.

Storing credentials in a repo is a terrible idea, whether it’s private or not! (it’s so easy for later a repo to become public, and the commit history will reveal all as one potential issue) - so using placeholders in the repo which are replaced by a build script is a better solution. However what you can do (if your site architecture allows it, and most should) is to split the site away from the content - have a single private repo for the site code itself and then have the site content as a second public repo which you can include as a git submodule. Thus you can have both public and private repos for the same project :slight_smile: