HTTP Auth and IP Whitelisting

EasyEngine can put a site behind HTTP basic authentication, allow listed IP addresses through without a password, or both. You manage this with ee auth. Rules apply to one site or, with global, to every site on the server.

From v4.13.0, a site’s rules cover every domain the site serves:

the site’s own domain
every subsite of a subdomain multisite (*.example.com)
every alias domain, including wildcard aliases such as *.example.net

Add HTTP auth to a site

Create a user with a password you choose:


			ee auth create example.com --user=editor --pass='a-strong-password'

Leave out --user to use the default username easyengine, and leave out --pass to get a random password. EasyEngine prints the credentials when it creates them.

			ee auth create example.com

Passwords can contain spaces and special characters. Quote them so your shell passes them through unchanged.

Add HTTP auth to every site

Use global in place of a site name. Sites that have no rules of their own use the global rules.

			ee auth create global --user=team --pass='a-strong-password'

Allow IP addresses without a password

Add a comma-separated list of IPv4 or IPv6 addresses, with an optional CIDR prefix:

			ee auth create example.com --ip=203.0.113.10,198.51.100.0/24,2001:db8::/32

EasyEngine checks each entry before it saves anything:

An IPv4 prefix must be between 0 and 32, and an IPv6 prefix between 0 and 128.
An entry that isn’t a valid address or prefix is refused, and the error names it.
A repeated address in the same list is saved once.

To allow addresses on every site, use global:

			ee auth create global --ip=203.0.113.10

Multisite subsites and alias domains

You don’t need extra commands for subsites or aliases. When you add auth or IP rules to a site, EasyEngine applies them to all of its domains.

For a subdomain multisite:

			ee site create example.com --type=wp --mu=subdom
ee auth create example.com --user=editor --pass='a-strong-password'

blog.example.com, shop.example.com and every other subsite now ask for the same credentials.

For alias domains, the rules follow the aliases as you change them:

			ee site update example.com --add-alias-domains='example.net,*.example.net'

When you add an alias, EasyEngine writes its auth and whitelist rules before the proxy starts serving it.
When you remove an alias, its rules are removed too.
If an alias update fails, EasyEngine removes the rules it wrote for that update.

Rules stay per site. A site’s credentials never apply to another site on the server, even when the two share a parent domain. For example, shop.example.com as its own site doesn’t use the rules of the multisite example.com.

Alias domain names

ee site create --alias-domains and ee site update --add-alias-domains accept a hostname (example.net) or a wildcard hostname (*.example.net). EasyEngine refuses a name when:

a label starts with - or _, or ends with -
it is one of the reserved names default or default_admin_tools
it isn’t a valid hostname (for example a..b or ../site)

Invalid names are listed in the error before anything changes. Blank entries such as a.com,,b.com are ignored.

Update or remove rules

Change a user’s password:


			ee auth update example.com --user=editor --pass='a-new-password'

Replace the allowed IP addresses:


			ee auth update example.com --ip=203.0.113.20

Remove a user, or remove an IP address:

			ee auth delete example.com --user=editor
ee auth delete example.com --ip=203.0.113.10

List a site’s rules:


			ee auth list example.com

When you delete a site with ee site delete, EasyEngine removes all of its auth and whitelist rules.

Upgrading from an earlier version

When you upgrade to v4.13.0 or later with ee cli update, EasyEngine regenerates every site’s auth and whitelist rules. Subsites and alias domains pick up each site’s existing credentials. You don’t need to run any command.

From v4.13.1, the upgrade also checks stored IP whitelist entries. It removes entries that the proxy can’t load, and rewrites valid entries in their standard form (for example 10.0.0.0/08 becomes 10.0.0.0/8). If a stored entry is skipped, EasyEngine warns you and shows the command that removes it.

Hand-made wildcard auth files

This applies only if you created files in the nginx-proxy htpasswd or vhost.d directories by hand. If you manage auth only with ee auth, skip this section.

From v4.13.0, nginx-proxy picks the auth file for a host in this order:

htpasswd/<host> (and vhost.d/<host>_acl), if it exists.
For a host that is literally *.X: htpasswd/_wildcard.X (and vhost.d/_wildcard.X_acl).
Otherwise, the global htpasswd/default (and vhost.d/default_acl).

A hand-made _wildcard.X file no longer applies to X itself or to hosts that are not *.X. Give X its own htpasswd/X file if you relied on that.