Single sign-on and client certificates¶
Can you put the servers behind a sign-in proxy (single sign-on, such as Authelia) or ask for client certificates (mTLS)? Partly. Firefox calls most of the servers in the background, where it sends neither cookies nor a client certificate. So those hosts must stay open. What you can put behind either one is the accounts' web pages, where people sign up and sign in, and the admin UI.
This page says what works and why, then how to set it up. It applies to the self-hosted accounts; with Mozilla's accounts, only the admin UI and the Sync server are yours, and the Sync server must stay open.
What works¶
Tested with Firefox 158 on Linux, against the stack of tests/e2e-fxa.sh (CLIENT_CERT=1 and SSO=authelia, see Testing):
| Host | Client certificate | Sign-in proxy (forward auth) |
|---|---|---|
Accounts pages, FXA_CONTENT_URL |
yes, but on the open paths | yes, but on the open paths |
| Admin UI | yes, the whole host | yes, with its trusted header, or OpenID Connect |
Accounts API, FXA_AUTH_URL |
no | no |
Profile server, FXA_PROFILE_URL |
no | no |
Sync server, SYNC_PUBLIC_URL |
no | no |
Pairing server, FXA_PAIRING_URL |
not with phones, see Mobile | no |
With either one in front of the accounts pages, a new Firefox shows your sign-in page or uses its certificate when it opens the accounts pages, then signs up or signs in, gets its keys and syncs as usual. A second device gets the data, and the admin UI sees both devices. Sync does not depend on the proxy's session afterwards: none of its requests carries the cookie (below).
What the pages' gate protects¶
It keeps strangers away from the sign-up and sign-in pages. It does not decide who has an account: the accounts API stays open, and a program can sign up or sign in through it without the pages, as Firefox's own code does. Who can sign up is the sign-up policy's job, which the API applies whatever the pages. Keep it on, with an allowlist, and use the gate on the pages as one more layer.
To keep the whole server off the internet, put it behind a VPN or a firewall instead: those apply to every connection, Firefox's background requests too.
Why not the other hosts¶
What Firefox sends¶
Firefox makes its accounts and Sync requests as anonymous requests: no cookies, no HTTP authentication and no client certificate.
- The accounts API, the profile, the tokenserver and the configuration of the accounts go through RESTRequest, which sets
LOAD_ANONYMOUS("Don't send user cookies and such over the wire"). - Firefox's TLS layer gives no client certificate to an anonymous connection (nsNSSIOLayer.cpp,
ANONYMOUS_CONNECT). - The Sync server's requests are a
fetch()of Firefox's own code (resource.sys.mjs), which sends none either. - The accounts pages call the API with cross-origin requests without credentials: no cookie, and no client certificate unless you set
network.cors_preflight.allow_client_certtotrueinabout:config.
The tests show it. A Firefox with a client certificate, and with Authelia's session cookie for the parent domain:
| Request | Client certificate sent | Cookie sent |
|---|---|---|
| a page in a tab, the accounts pages' own requests to their host | yes | yes |
| the pairing websocket of the computer | yes | not checked |
the accounts' configuration, /.well-known/fxa-client-configuration |
no | no |
| the accounts API, the profile, the OAuth tokens, the devices | no | no |
| the tokenserver and the Sync server | no | no |
What breaks, host by host
- Client certificates required on all the accounts hosts and the Sync server: Firefox cannot even read the configuration. The Browser Console says
Failed to get configuration object from "https://accounts.example.com/.well-known/fxa-client-configuration"with0x804b0065(NS_ERROR_NET_UNCLEAN_SHUTDOWN: the server closed the connection that came without a certificate), and the Sync preferences never get to the sign-in page. Every other request type of the table above fails the same way,NetworkError when attempting to fetch resource. - The accounts API behind the sign-in proxy: the first page, with the email field, shows "Bad Request: System unavailable, try again soon". Its requests to the API start with CORS preflights, which never carry cookies, and get the proxy's redirect to its sign-in page.
- The Sync server behind the sign-in proxy: the sign-in finishes ("Sync is turned on"), then Sync fails with
error.sync.reason.no_node_found: the tokenserver'sGET /1.0/sync/1.5gets the proxy's401, though Firefox has the proxy's cookie for the parent domain.
The open paths¶
Of the accounts pages' host, a few paths are fetched without a browser tab, and must stay open:
| Path | Fetched by |
|---|---|
/.well-known/fxa-client-configuration |
Firefox, for identity.fxaccounts.autoconfig.uri (anonymous) |
/.well-known/openid-configuration |
the admin UI's server, to sign in with these accounts |
/__heartbeat__, /__lbheartbeat__ |
the admin UI's public checks, and your monitoring |
They hold no personal data. Everything else of that host is pages, their scripts and styles, and their own requests, which the browser sends with the certificate or the cookie.
The servers among themselves¶
The servers call each other at their internal addresses, never through your reverse proxy: the Sync server checks Firefox's tokens at FXA_OAUTH_SERVER_URL (http://fxa-auth:9000/v1), the auth and profile servers call each other directly. The proxy's log of a whole test run shows no request from them.
The admin UI is the exception: it uses the public URLs, as Firefox would.
- To sign in with the accounts: the discovery on the pages' host (an open path), then the tokens and keys on the API host and the email on the profile host.
- Its public checks:
/__heartbeat__of each host, and the sign-up gate through the API host.
None of them is behind the gate when you follow this page. The backups connect to the databases only.
Client certificates¶
-
Make a CA for your devices, and a client certificate for each person, signed by it. With OpenSSL, for example:
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -days 3650 \ -subj "/CN=Firefox Sync devices" -keyout client-ca.key -out client-ca.crt openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -subj "/CN=alice@example.com" \ -keyout alice.key -out alice.csr printf 'extendedKeyUsage=clientAuth\n' > client.ext openssl x509 -req -in alice.csr -CA client-ca.crt -CAkey client-ca.key -CAcreateserial -days 825 \ -extfile client.ext -out alice.crt openssl pkcs12 -export -in alice.crt -inkey alice.key -name "Firefox Sync" -out alice.p12Keep
client-ca.keyoffline. The proxy needsclient-ca.crtonly. -
Ask for them on the accounts pages, in your proxy (below), and on the admin UI's host if you publish it.
- In Firefox, see Firefox.
nginx¶
The first server of access-control-example.conf replaces the accounts pages' server of proxy/nginx.conf (Reverse proxy). It asks for the certificate at the handshake (ssl_verify_client optional), lets the open paths through, and answers 403 to the rest without one. A certificate of another CA gets 400.
For the admin UI's host, the whole host, in its server of proxy/nginx.conf:
ssl_client_certificate /etc/nginx/client-ca.crt;
ssl_verify_client on;
Caddy¶
As the test's, in the accounts pages' site. With proxy/Caddyfile (or the bundled Caddy's), put the lines inside the site, without it, into proxy/caddy.d/content.caddy, which it imports there and which stays when it is written again (Caddy):
accounts.example.com {
tls {
client_auth {
mode verify_if_given
trust_pool file /etc/caddy/client-ca.crt
}
}
@no_certificate {
not path /.well-known/fxa-client-configuration /.well-known/openid-configuration /__heartbeat__ /__lbheartbeat__
vars {http.request.tls.client.subject} ""
}
respond @no_certificate "a client certificate is required" 403
reverse_proxy 127.0.0.1:3030
}
Match on the subject, not the fingerprint: without a certificate, Caddy's {http.request.tls.client.fingerprint} is the hash of nothing, not empty. For the admin UI's host, the whole host: mode require_and_verify.
Firefox¶
On each computer, once per Firefox profile:
- Settings, Privacy & Security, Certificates, View Certificates, tab Your Certificates, Import: the
.p12file and its password. - Firefox asks which certificate to send each time a site wants one. To send it without asking, set
security.default_personal_certtoSelect Automaticallyinabout:config, as the tests do. It then sends the first certificate that fits to any site that asks for one.
No enterprise policy imports a client certificate: Certificates.Install installs CAs only (policy templates). SecurityDevices loads a PKCS #11 module, such as a smart card's.
Sign-in proxy¶
With Authelia, as the test runs it (tests/caddy/authelia): its session cookie on the parent domain (example.com), its pages on a host of their own (auth.example.com), a file of users. Other forward-auth proxies work the same way: what matters is to leave the other hosts and the open paths out.
In Authelia's configuration, a rule for the hosts it guards:
access_control:
default_policy: deny
rules:
- domain: [accounts.example.com, admin.example.com]
policy: two_factor
session:
cookies:
- domain: example.com
authelia_url: https://auth.example.com
nginx¶
The second server of access-control-example.conf, commented out, follows Authelia's nginx integration: auth_request on every path but the open ones, which go straight to the accounts pages.
Caddy¶
As for the client certificates, with proxy/Caddyfile the lines of the site go into proxy/caddy.d/content.caddy, and Authelia's own site (auth.example.com) into proxy/caddy.d/sites.caddy:
accounts.example.com {
@sso not path /.well-known/fxa-client-configuration /.well-known/openid-configuration /__heartbeat__ /__lbheartbeat__
forward_auth @sso 127.0.0.1:9091 {
uri /api/authz/forward-auth
}
reverse_proxy 127.0.0.1:3030
}
The admin UI¶
Behind the sign-in proxy, the admin UI can take the user from the proxy's header, or sign in with OpenID Connect: Signing in. Its Authelia examples are there.
Mobile¶
Not tested here: only desktop Firefox is.
- The phones sync the same way, through the same open hosts, so this page's limits apply to them too.
- Android: Firefox for Android 138 and later can use client certificates installed in Android (bug 1813930), but does not remember the choice across restarts (bug 2025124, open). Whether the sign-in pages work with one, or with a sign-in proxy, when you set a custom accounts server: untested.
- iOS: Firefox for iOS has no client certificates (firefox-ios#25313, open). With client certificates on the accounts pages, an iPhone cannot sign in. A sign-in proxy's pages may work there: untested.
- Pairing: with a phone, the computer shows a QR code and both connect to the pairing server. The computer's websocket sends the certificate, the phone's is untested: leave the pairing host open.
On Kubernetes¶
Notes for the chart's Ingresses: Access control.