This FAQ is about trying to connect your UpdraftCentral remote control dashboard to a site which has additional access restrictions beyond WordPress’s ordinary login mechanism. For example, perhaps it requires a browser password to be entered, or is restricted to specific IP addresses.
Example of being asked for a browser password
There is no “one-size fits all” answer to this question. This is mainly because:
- there are many different possible access restrictions
- different webservers are configured in different ways
- different web browsers also behave differently and
- the CORS protocol which handles direct authentication (UpdraftCentral, by default, connects directly from the browser to your managed site) interacts with HTTP authentication in complex ways. We have collected together relevant information below, based on all our testing and experience.
- web browsers also have security restrictions on processing of non-https content on https dashboards
Some of the information below is quite technical. Not all of it is relevant to every situation. You ca solve most problems just by tweaking the available options in the UpdraftCentral site configuration, and, as a last resort, trying the “via mothership” connection mode (see the relevant section below).
The most common case: Apache with password-protection
Here’s the short summary of what to do in the most common case: that your webserver is Apache, and protected by a password that’s configured in your .htaccess file. In that case, just complete all of these steps…
- Stick a <LimitExcept> container around your “Require” statement in .htaccess, so that it does not apply to OPTIONS commands.
- Add some extra lines to your .htaccess, so that Apache will send some extra headers that are needed
- Turn off the “Send CORS headers” option in the site configuration for the site in your UpdraftCentral dashboard.
Here’s how the .htaccess file then looks, with Apache 2.4; if copying this, then remember to change the lines indicated to fit with your setup:
# Added a rewrite to respond with a 200 SUCCESS on every OPTIONS request.
RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=200,L,E=HTTP_ORIGIN:%{HTTP:ORIGIN}]]
# Add the necessary headers. Remember to tweak your site configuration in UpdraftCentral so that UpdraftCentral does not send CORS headers - otherwise, there will be two sets, and it will break.
# Adjust the next line so that it has the address of the server that your UpdraftCentral site is on, including either https:// or https:// as relevant (but not the full path)
Header always set Access-Control-Allow-Origin "https://localhost"
Header always set Access-Control-Allow-Methods "POST, GET, OPTIONS"
Header always set Access-Control-Max-Age "1000"
Header always set Access-Control-Allow-Headers "authorization,x-secondary-user-agent"
Header always set Access-Control-Allow-Credentials "true"
AuthType Basic
AuthName "Authentication Required"
# Adjust the next line so that it points to your .htpasswd file
AuthUserFile "/home/mysite/public_html/.htpasswd"
<LimitExcept OPTIONS>
Require valid-user
</LimitExcept>
If this isn’t your setup, then read on for the more detailed discussion…
SSL dashboard (mothership) controlling non-SSL websites
If the site that your UpdraftCentral dashboard is on (which we call the “mothership”) is using SSL (which is the case for updraftplus.com), then all communications to the controlled site go via the mothership. They cannot be sent direct to the site, because web browsers’ “mixed content” security policies forbid SSL sites from contacting non-SSL sites. As such, regardless of what connection mode you set in the UpdraftCentral settings, if you access your dashboard via SSL, then UpdraftCentral will handle the connection in “via mothership” mode. Please bear that in mind when reading the below! This being so, in this case, none of the material about CORS below will apply (as explained further down).
IP address restrictions
If your webserver restricts access based upon IP addresses, then you will need to add the IP address that you are browsing from to the list of allowed IP addresses. (Connections in UpdraftCentral come directly from the browser, not from the server that the UpdraftCentral dashboard is installed on (a.k.a. the “mothership”) if these are different). If that is not possible (e.g. you are on the move, with limited access to configure your webserver), then you may wish to switch UpdraftCentral’s mode to route all connections via the mothership and allow the IP address of the mothership – see the section on doing so further down.
In Apache 2.4, this is done with statements like the below:
<RequireAll>
Require all granted
# Change the IP address on the next line to yours
Require ip 1.2.3.4
</RequireAll>
Older Apache versions have a different syntax.
Browser passwords (i.e. HTTP authentication)
If access to your website is protected by a password (i.e. not just the ordinary WordPress login password – but a pop-up in your browser that is before you see anything from WordPress), then UpdraftCentral will need this in order to be able to connect.
Settings for configuring a browser password are in the expert section of the “Add Site” window. They can also be edited later by editing the site configuration. Note that it is normal for your browser to also ask you to type in the username and password as well. Whether UpdraftCentral’s configured password, or the one you enter in your browser directly, gets used, can depend upon some complicated (under the hood) interactions.
You will also see the option “Send CORS headers” in this section. Normally, this option should be on. It tells UpdraftCentral on the controlled site to set the headers that are required by the CORS protocol (the protocol which controls what resources a web browser is allowed to fetch from a controlled site). However, CORS and HTTP authentication have some difficult interactions. If you are sure that you are entering the correct username and password, then you should open your web browser’s developer console. If you see errors there about CORS, then try turning off this option. Note, though, that it may also be necessary to add new configuration directly to your webserver. More information on this is below. Also, you can try the “Via mothership” connection mode, also described below. That connection mode eliminates the complexities of the CORS protocol entirely.
Setting CORS headers on password-protected sites
CORS is a protocol for making sure that a web browser can only run code from authorised sites. UpdraftCentral is normally able to handle all of this automatically. However, on password-protected sites, there can be a chicken-and-egg situation:
- UpdraftCentral on the remote site can’t be contacted without the password, and thus it can’t set the needed authentication headers
- But, without the needed authentication headers, the browser won’t allow the resource to be accessed at all, and so won’t even ask for the password
In many cases, UpdraftCentral can detect this issue and work around it, or provide appropriate advice. This cannot be done, however, in 100% of cases. In such cases, you may need to tweak your webserver’s configuration to help.
If you have this problem, then your web brower’s JavaScript console will be mentioning problems to do with CORS and/or access controls.
There are two important things: 1) That your webserver sends CORS headers 2) That your webserver only sends one lot of CORS headers. Please read on for advice. If all else fails, then you can switch UpdraftCentral’s connection mode to route all traffic via the webserver that you have UpdraftCentral installed on (i.e. the “Mothership”) – see the section below on “UpdraftCentral connection mode”.
It’s best to configure your webserver to not require password authentication for an HTTP OPTIONS request. These requests are used by browsers to work out whether the request is allowed. By turning off authentication for OPTIONS requests, this allows UpdraftCentral on the remote site to be reached and to respond that the further requests (which will be password-protected) should be allowed through. This is generally safe to do. OPTIONS requests do not send commands or pass information.
To do this in Apache, edit the Apache configuration where the password is being required, and add a <LimitExcept> statement to cause it to not be required for an OPTIONS request, plus smoe further lines to make Apache return a 200 status code instead of a 401 (unauthorised) code on these requests. Here is an example below of a normal Apache password configuration in an .htaccess file:
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/home/mysite/public_html/.htpasswd"
Require valid-user
And here is the same configuration, but now with the <LimitExcept> command added so that it will not require a password with an OPTIONS request, and the other extra lines:
# Added a rewrite to respond with a 200 SUCCESS on every OPTIONS request.
RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=200,L,E=HTTP_ORIGIN:%{HTTP:ORIGIN}]]
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/home/mysite/public_html/.htpasswd"
<LimitExcept OPTIONS>
Require valid-user
</LimitExcept>
In the lighttpd webserver, you can do similiar things like so:
$HTTP["request-method"] != "OPTIONS" {
auth.backend = "htdigest"
# (etc. - the rest of your authentication configuration)
}
If you need to get your webserver to send the CORS headers, then go to the UpdraftCentral site configuration, and turn off the option for UpdraftCentral on the remote site to send them (otherwise, you will have two sets – which breaks the CORS protocol). Then, add webserver configuration to send these directly. Here is an example for Apache – you will need to change the origin header to specify the server (but not the full path) for the site that has the UpdraftCentral dashboard on it; in the example below, the dashboard is on https://localhost
# Change the next line to match where your UpdraftCentral dashboard is hosted
Header always set Access-Control-Allow-Origin "https://localhost"
Header always set Access-Control-Allow-Methods "POST, GET, OPTIONS"
Header always set Access-Control-Max-Age "1000"
Header always set Access-Control-Allow-Headers "authorization,x-secondary-user-agent"
Header always set Access-Control-Allow-Credentials "true"
With the lighttpd server, it is easiest to leave the option for UpdraftCentral to send CORS headers (in the site configuration on), and only configure lighttpd to send those headers with OPTIONS requests, with a fragment like the below (again, remember to edit the origin header):
$HTTP["request-method"] == "OPTIONS" {
# Edit the origin header to indicate the address of the site with your UpdraftCentral dashboard
setenv.add-response-header = (
"Access-Control-Allow-Origin" => "https://localhost",
"Access-Control-Allow-Methods" => "POST, GET, OPTIONS",
"Access-Control-Max-Age" => "1000",
"Access-Control-Allow-Headers" => "authorization,x-secondary-user-agent",
"Access-Control-Allow-Credentials" => "true" )
}
Remember that, if this all gets too complex, you can change UpdraftCentral’s connection mode (see below), to avoid issues with CORS completely.
UpdraftCentral connection mode
In the vast majority of cases, UpdraftCentral will “just work”. However, sometimes, it may be necessary to go into the advanced settings, and change the “connection mode” for a particular site, in order to be able to control it.
Normally, UpdraftCentral will connect to the site directly from the browser, for the fastest possible results. However, on some setups, this may be problematic – e.g. if your site only allows access to specific IP addresses and your browser is on a floating IP, or if you use HTTP authentication and are unable to configure your server to send the necessary CORS headers to get this to work (see the relevant sections above for information on what this means). In this case, changing your connection mode may help. A description of the available modes is below.
The available connection modes are:
- “Direct (authentication method chosen automatically)” – this is the default. It contacts the remote site directly via AJAX (cross-site request). In the event of an HTTP username/password being entered in the configuration, it will decide itself on the best way to try this. This decision is based on your web browser, because different web browsers behave differently in this case.
- “Direct (authentication via jQuery)” – this also contacts the remote site directly. It’s identical, unless there’s an HTTP password. If there is, it’ll use the method of sending HTTP authentication that works in most web browsers. This can support any method of HTTP authentication (e.g. basic, digest, NTLM) that your web browser supports.
- “Direct (manually constructed authentication)” – also direct, and uses (if necessary) the HTTP authentication method that works in Firefox, and possibly other browsers too. If the site does have HTTP authentication, then only HTTP “basic” authentication can work; digest (or other) forms of authentication are not supported.
- “Via mothership (slower, but better compatibility with some awkward setups)” – this works like traditional remote control plugins do. It sends the request via AJAX to the mothership (i.e. the UpdraftCentral plugin on the mothership), which then sends it on to the remote site. If HTTP authentication is needed, it can support HTTP “basic” authentication and “digest”, as long as your mothership is running PHP 5.4+; if running an earlier version, then digest (or other) forms of authentication are not supported. It is slower, because of the relaying of the request and reply (instead of direct browser-to-site communications).
Posted in: UpdraftCentral
