Pre-authentication

Pre-authentication puts a plain sign-in page in front of one instance. Nobody reaches the instance, not even its own login page, until they have typed a user name and password you handed out. Use it for a staging copy, a demo that is not ready, or a customer's instance that should not be found by anyone who stumbles on its address.

The page names nothing: no product, no Odoo, no instance name. It is an ordinary web form, so the browser never shows its own password prompt, and a password manager can fill it.

It sits behind the instance's firewall rules. A caller the rules refuse gets the refusal and never sees the page; only a caller the rules admit is asked to sign in.

Setting it up

Everything lives on the instance's Firewall tab, under Pre-authentication, between Rules and Configuration. The Sign-in page card holds the switch and the session length, the Exempt card what is never asked, and Credentials who may sign in. The tab's Save saves it together with the firewall rules, and the change reaches the site with the apply that follows.

Switch it on, and choose how long a sign-in lasts: 12 hours by default, anything from 1 to 720.
Add a credential for everyone who should sign in. Leave the user name and the password empty and both are generated; the generated password is shown once, so copy it before you leave the page. A password you type yourself must be at least 12 characters. A user name uses letters, digits and . _ - @. Pre-authentication can be on with no credential at all: the exempt visitors below get in and nobody else, which suits an instance that only an office, a webhook and a monitor should reach. The tab says so while that is the case.
Add what must never be asked on the Exempt card (below), then Save.

Give each person or system its own credential, with a description saying who it is for and, where it should end by itself, an expiry. A credential can be switched off without deleting it.

What is never asked

Some traffic cannot sign in: a payment provider's webhook, a monitoring probe, an integration calling the instance's API, an office that should not have to. List it on the Exempt card rather than switching pre-authentication off. Any one entry is enough. The server's own uptime check of the instance is never asked and never logged; nothing needs listing for it.

Exemption	What it admits	Example
Paths	That path and everything under it, on a whole-segment boundary	`/payment/` admits `/payment` and `/payment/stripe/webhook`, never `/payments`
Addresses	Every request from that address or range	`203.0.113.10`, `198.51.100.0/24`
Host names	Every request from an address the name currently resolves to	`office.example.com`
Countries	Every request GeoIP places in that country	Belgium
Continents	Every request GeoIP places on that continent	Europe

Under the paths, one click adds the usual set: Payment webhooks, External API, Health check, Email images and PDF reports each add their paths, and All adds every one of them; each button adds only what is not listed yet and goes grey once it all is. The addresses, host names, countries and continents use the same editors as a firewall rule: one click adds your own public address, or the private ranges. A host name is re-resolved continuously, for a connection whose address moves; access then depends on DNS, which is unauthenticated, so use a name you control.

A country lets a lot of people in

Countries and continents are placed by the server's GeoLite2 database. Anyone placed there skips the sign-in, including whoever reaches the internet through a VPN or proxy that exits there. A visitor the database cannot place is never exempt, and while no database is loaded the countries and continents exempt nobody. See Location rules and GeoIP for setting up the database.

An exempt path must be written plainly: it starts with /, carries no //, . or .. segment, no query, no % escape, no wildcard. The root / cannot be exempt, since that would switch pre-authentication off, and paths under /__preauth belong to the sign-in page itself. A request whose path could be read two ways is never treated as exempt, whatever the list says.

What a visitor sees

The first request for any page of the instance answers with the sign-in page. A right user name and password set a cookie and take the visitor to the page they asked for; a wrong one shows the page again with one sentence that does not say which half was wrong.

Guessing is stopped twice over:

five failed attempts within fifteen minutes lock that address and that user name for fifteen minutes, whichever comes first;
the sign-in page itself accepts only a handful of attempts per minute from one address.

Both answer with 429, which lands in the instance's access log, where the ohm-429 jail and CrowdSec can act on it. See Intrusion prevention.

A sign-in lasts the session length you chose. There is no list of open sessions to end one by one; instead, any of these ends every session of that credential on the visitor's next request:

giving it a new password;
switching it off;
its expiry passing;
deleting it.

That is how you take access away from one person without touching anyone else's.

Each attempt, successful or not, is one row in the instance's Firewall > Log. Type pre-authentication in Reason contains to see only these: a refused visitor reads "pre-authentication: sign-in required", a failed attempt names no user, and a successful one says who signed in.

When the management API is down

Pre-authentication fails closed

The decision whether a visitor has signed in is made by the management API. While it is not running, for example during an update, an instance with pre-authentication switched on shows its maintenance page to everyone, exempt paths and addresses included. Instances without pre-authentication are not affected.

Copies and the license

Duplicating an instance, restoring a backup as a new instance, or importing one keeps the settings and the credentials, so the same people can sign in to the copy. The copy signs its own sessions, so a visitor signed in to the original signs in again on the copy.

When the server's license stops carrying pre-authentication, it is switched off on every instance that has it, and the site is applied without it. It is switched on again by itself, on the same instances, once the license carries it again; a license server that cannot be reached switches nothing off. See When the license changes. Deleting a credential and switching pre-authentication off are always available.