Repository navigation
Adding Cloudflare Access (optional)
This page is an optional add-on to Remote Access with Cloudflare Tunnel. Cloudflare Access only works in Cloudflare Tunnel mode.
With just a tunnel, anyone who finds your hostname can load the RWSOLS login page and guess at your passphrase. Cloudflare Access puts a login of its own in front of it, at Cloudflare's edge: visitors have to prove who they are (an emailed one-time code, Google, GitHub, whatever you've configured) before their request is passed on to your Pi at all. Strangers never reach the Pi.
RWSOLS doesn't just trust that this happened. When Access is configured, RWSOLS checks the signed token that Access attaches to every request (the Cf-Access-Jwt-Assertion header), and refuses requests for the tunnel hostname that don't carry a valid one. So even if someone found a way around Cloudflare, they would still be turned away. Your RWSOLS passphrase is still required on top of all that. Access is an extra layer, not a replacement.
Use it if your RWSOLS is on the open internet through a tunnel. It's free for small teams (see Cloudflare's pricing for the current limits). Skip it if you only use the tunnel from places where you can't complete a login, or you'd rather rely on the passphrase alone.
Things to know:
- It only applies to requests for the tunnel hostname (or arriving on the tunnel's loopback listener). Browsing to RWSOLS on your LAN by its
.localname or IP is unaffected. - Scripts and apps that can't do a browser login need a service token. See below.
- A working Cloudflare Tunnel setup.
- Cloudflare Zero Trust (Cloudflare One) enabled on your Cloudflare account. The free plan is fine, but you do have to complete the one-time onboarding, which gives you a team name and a team domain such as
example.cloudflareaccess.com. - The Pi must be able to make outbound HTTPS requests to your team domain, to download Cloudflare's signing keys.
Use this if you chose the automatic tunnel path. The API token needs the tunnel permissions from the tunnel page, plus:
- Account > Access: Apps and Policies > Edit
- Account > Access: Organizations, Identity Providers, and Groups > Read
- Account > Access: Service Tokens > Edit (only if you want a service token)
Run python3 setup.py --remote-access (or the full setup) and choose Cloudflare Tunnel. After the tunnel questions you'll be asked:
- "Enable Cloudflare Access for wol.example.com?" Answer
y. - "Emails allowed to log in (comma separated, may be blank)". A short box explains what you are being asked: individual addresses that may log in with a one-time code emailed to them.
- "Allow everyone with an email at this domain (e.g. example.com, may be blank)". This lets everyone with an address at that domain in (handy for family or a team). You need to give at least one email address or one domain between these two questions.
- "How long should a login last?" Choose 1 day, 1 week or 1 month (the default). After a visitor logs in with the emailed code, that browser stays logged in for this long before Cloudflare asks for a new code. Longer means fewer codes to type; shorter means a browser someone else gets hold of stops working sooner. The RWSOLS passphrase is asked for either way. Run the wizard again to change it.
- "Also create a service token for non-browser clients (scripts, apps)?" (default No, and most people should answer No). Cloudflare Access asks a person to log in through a web page, which a program cannot do. A service token is a pair of secret values that a program sends instead, so it gets through without the login page. Example: a phone shortcut, a home automation system or a script that wakes your computer by calling RWSOLS directly, with nobody opening the page in a browser. If you only use RWSOLS in a browser you do not need one, and you can add one later by running the wizard again. Answering Yes needs one more permission on the API token (Access: Service Tokens > Edit), which the token link cannot pre-select; the wizard only lists that permission when you answer Yes.
The remaining questions (allowlist, API token) are as described on the tunnel page. The allowlist question is a multi-select with a reason next to each name; the tunnel hostname is always included. Then, along with the tunnel, the wizard:
- reads your team domain from your account,
- creates an Allow policy named
RWSOLS wol.example.com allowfrom the emails and domain you entered, - if you asked for one: creates a service token named
RWSOLS wol.example.com(valid for one year) and a Service Auth policy namedRWSOLS wol.example.com service auth, - creates a self-hosted Access application named
RWSOLS (wol.example.com)for your hostname, with the login length you chose, and attaches the policies (an existing application for that hostname is reused; its login length is only changed if the wizard created it), - writes
$ACCESS_TEAM_DOMAINand$ACCESS_AUDinto config.php, and switches on the Access checks in Apache and PHP.
If you created a service token, the wizard prints its Client ID and Client Secret once at the end. Copy them somewhere safe (a password manager) straight away. They are not stored anywhere, and Cloudflare can't show the secret again; if you lose it, create a new token in the dashboard.
To turn Access off later, re-run the wizard and answer No to the Access question. If the wizard created the Access application, it offers to delete it.
Use this if you chose the manual tunnel path, or you want to set up Access yourself. The dashboard menu names change from time to time; these are the current ones at the time of writing.
- In the Cloudflare dashboard, open Zero Trust (Cloudflare One) and go to Access controls > Applications. Select "Create new application" and choose Self-hosted.
- Add a public hostname for the application: your subdomain and domain, for example
wol.example.com, with no path. - Add an Access policy with the action Allow, and an Include rule such as "Emails" (your own address) or "Emails ending in" (
@example.com). Select the identity providers you want to offer. The one-time PIN works with no setup. Access applications deny everyone by default, so without an Allow policy nobody can log in. - Save the application. Then open it again for editing (Access controls > Applications > Edit) and look in "Additional settings" for the Application Audience (AUD) Tag. It's a 64-character hexadecimal string. Copy it.
- Find your team domain, which is
<your-team-name>.cloudflareaccess.com. The team name is shown in the Zero Trust settings (the wizard points you at Settings, under General or Custom Pages). Enter it withouthttps://. - Run
python3 setup.py --remote-access, pick Cloudflare Tunnel, and answeryto "Enable Cloudflare Access". Enter the "Team domain" and the "Application AUD tag" when asked. The wizard checks the format of both.
Or, if you prefer to edit config.php by hand, set these two lines and then run python3 setup.py --remote-access so the webroot copy and the Apache configuration are regenerated:
$ACCESS_TEAM_DOMAIN = "example.cloudflareaccess.com";
$ACCESS_AUD = "0000000000000000000000000000000000000000000000000000000000000000";
Access is active only when both $ACCESS_TEAM_DOMAIN and $ACCESS_AUD are set. Then, for requests for the tunnel hostname (or arriving on the tunnel listener):
- Apache refuses requests that have no
Cf-Access-Jwt-Assertionheader at all (HTTP 403). - PHP verifies the token: it must be signed (RS256) with one of the keys published at
https://<team domain>/cdn-cgi/access/certs, be issued byhttps://<team domain>, have the right audience (your AUD tag), and not be expired (and not be used before its start time). A 60 second allowance is made for clock differences. Otherwise: HTTP 403 with an empty body. - The signing keys are cached for about an hour. It never re-fetches more than about once a minute.
- It fails closed. If the keys can't be fetched and the cached copy has expired, everything for the tunnel hostname is denied until they can be.
- If only one of the two settings is set, all tunnel requests are denied.
For POST actions (wake, sleep, status), the email address of the person who logged in is written to syslog. See below.
RWSOLS itself ships no API, scripts, or shortcuts. But a lot of people drive it from their own: an iOS Shortcut, Home Assistant, a cron job, curl. These work by sending the same form the web page does: a POST with the fields password and submitbutton (with the value Wake Up!, Sleep! or Check Status), to the page with ?computer=N (the number of the computer in your $COMPUTER_NAME list, starting at 0).
With Access in front, those callers can't do an interactive login, so they need a service token. A service token is a Client ID and Client Secret pair that they send as two request headers, CF-Access-Client-Id and CF-Access-Client-Secret. Access checks them and, if the application has a Service Auth policy for that token, passes the request through with a signed token attached, which RWSOLS then verifies like any other.
- The wizard can do all of this: answer
yto "Also create a service token for non-browser clients". It creates the token and the Service Auth policy, and prints the Client ID and Client Secret once. - By hand: in the dashboard, go to Access controls > Service credentials > Service Tokens, select "Create Service Token", and copy the secret when it is shown (once). Then, in your Access application, add a policy with the action Service Auth and an Include rule that matches that token. A Service Auth policy is required: an Allow policy never lets a service token through.
A request looks like this:
curl -X POST "https://wol.example.com/?computer=0" \
-H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
-H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET" \
--data-urlencode "password=$RWSOLS_PASSPHRASE" \
--data-urlencode "submitbutton=Wake Up!"
Use Sleep! or Check Status as the submitbutton value for the other actions. Keep the values in environment variables (or your app's secret storage) rather than typing them into the command, so they don't land in your shell history. In an iOS Shortcut or a Home Assistant rest_command, use the same two headers and the same two form fields.
Be aware that the service token only gets the request past Access. Your RWSOLS passphrase is still required, and a service token that leaks can wake your computers (when combined with the passphrase). The tokens the wizard creates expire after one year. Rotate or delete them from the dashboard.
I get a blank 403 page from my hostname. The 403 can come from three places:
- Cloudflare itself (a Cloudflare-branded page or login): your login isn't allowed by the Allow policy. Check the email address and domain in the policy.
- Apache, because the request had no
Cf-Access-Jwt-Assertionheader: the request didn't go through Access. Check that your Access application is for exactly the same hostname as the tunnel hostname, and that you're visitinghttps://wol.example.comrather than the Pi directly. These refusals aren't logged by RWSOLS; look in/var/log/apache2/tunnel_access.log. - RWSOLS (PHP), which rejected the token. These are logged to syslog; see below.
Only one key set. If just one of $ACCESS_TEAM_DOMAIN and $ACCESS_AUD is set, every tunnel request gets a 403, and the log says "access misconfigured: set both ACCESS_TEAM_DOMAIN and ACCESS_AUD". Set both, or set both back to NULL, and re-run python3 setup.py --remote-access.
Wrong audience or issuer. The log says "wrong aud" or "wrong iss". The AUD tag is per application; make sure you copied it from the application that protects this hostname, and that the team domain is the one for your account (no https://, no trailing slash).
Clock skew ("expired" or "not yet valid"). Tokens are checked against the Pi's clock, with 60 seconds of leeway. A Pi that has been offline or has a dead clock battery can be off by more. Check with timedatectl and make sure NTP sync is active (sudo timedatectl set-ntp true).
"signing key unavailable". The Pi couldn't fetch the keys from https://<team domain>/cdn-cgi/access/certs, or what came back had no usable key. Try it from the Pi: curl -s https://example.cloudflareaccess.com/cdn-cgi/access/certs | head -c 300. A typo in the team domain, no outbound internet, DNS problems or a missing PHP curl extension (php-curl; RWSOLS needs it for the sleep command anyway) are the usual causes. Because RWSOLS fails closed, the site stays locked until the keys can be fetched.
Reading the log. RWSOLS writes to syslog with the tag rwsols:
sudo journalctl -t rwsols -n 50
You'll see two kinds of Access lines:
-
denied tunnel request from <ip>: <reason>, where the reason is one of the above (for examplemissing access token,access token rejected: expired). These are rate limited to 10 per minute, followed by a one line summary of how many were suppressed. -
access identity "<identity>" from <ip> POST action "<action>" computer "<n>", logged for each wake, sleep or status request made through Access. The identity is the email address of the person who logged in. For a service token it is the token'scommon_namevalue, which Cloudflare sets to the token's Client ID.
(C) 2021 Jeremy Blum, Blum Idea Labs, LLC. This software is licensed under GPL v3