Skip to content

Set up basic authentication

Want to protect a virtual host — or part of one — with a username and password prompt?

This article walks through setting it up. For the concepts (the three pieces, the same-UNIX-user rule, the Apache-vs-nginx scoping difference), see All about basic authentication.

You'll create three things, in this order:

  1. An htpasswd file on the UNIX user.
  2. One or more htpasswd users inside that file.
  3. A basic authentication realm that attaches the file to the virtual host.

The htpasswd file and the virtual host must belong to the same UNIX user.

1. Create the htpasswd file

The htpasswd file belongs to a UNIX user. Open the UNIX user that owns the virtual host you'll protect — either directly from 'UNIX Users', or via 'Projects' > the project > 'Advanced' > the 'UNIX User' tile's 'Manage' button.

Then:

  1. Under 'Htpasswd Files', click '+'.
  2. Enter a 'Name'. Lowercase letters, digits, dash, underscore.
  3. Click 'Create'.

2. Add htpasswd users

Open the htpasswd file you just created.

  1. Under 'Htpasswd Users', click '+'.
  2. Enter a 'Username' and 'Password'.
  3. Click 'Create'.
  4. Repeat for each person who should have access.

3. Attach a basic authentication realm

The realm wires the htpasswd file to a virtual host. Open the virtual host you want to protect — either directly from 'Virtual Hosts', or via 'Projects' > the project > 'Advanced' > the 'Virtual Host' tile's 'Manage' button.

Then:

  1. Under 'Basic Authentication Realms', click '+'.
  2. Enter a 'Name'. This is what the browser shows in its login prompt — pick something the visitor will recognise (e.g. Staging — client name).
  3. Pick the 'Htpasswd File' you created in step 1. Only files belonging to the same UNIX user as the virtual host appear.

  4. Scope which part of the virtual host the realm protects:

    • For Apache virtual hosts: 'Directory Path' — set to e.g. /admin to protect that subdirectory, or leave blank to protect the whole document root.
    • For nginx virtual hosts: 'URI Path' — set to e.g. /admin to protect any URI starting with that, or leave blank to protect the whole virtual host.

    Set whichever applies to the virtual host's server software; leave the other blank. 5. Click 'Create'.

The next request to the protected part of the virtual host now prompts for credentials.

Multiple realms

A virtual host can have multiple realms — useful when different paths need different credentials, or when one area should be open and another locked. Repeat step 3 with a different htpasswd file (or the same file with a different scope and name).

Restricting by IP instead

If you want IP-based access control (e.g. "only the office can reach this") rather than a credentials prompt, use firewall groups on the domain router instead. The two can be combined — basic auth and a firewall group on the same domain — so that even if one is misconfigured or bypassed, the other still blocks access.