IMAGO
Connecting to a protected server
Most people connect IMAGO to Immich with an address and an API key, and need nothing else. This page is for when your server sits behind something that wants more first: a Cloudflare tunnel with Access, a proxy that checks a secret header, a server that asks the phone for a certificate, or a certificate from your own authority. In IMAGO these live under Advanced, in the form that adds a server or an address.
These options are in testing. They are new, and have been tried on few setups. If something does not work with yours, tell us: it is how they get better.
Simpler ways first
Before setting any of this up, three things avoid it, and the Immich project recommends them over its own app’s network options, which it calls experimental:
- Two addresses in one library. Add the home address and the outside one with Add address; IMAGO uses whichever answers.
- A VPN, such as Tailscale or WireGuard. For IMAGO it is just another address.
- A certificate from a public authority, such as Let’s Encrypt, on your own domain.
What is kept, and where it goes
- Headers and certificates belong to one address, not to the app: your home address does not receive what the outside one needs.
- They are only sent over https://, and only to that address. If a request is redirected to another host, they do not follow.
- They are kept encrypted on the device, never sent to IMAGO’s servers, never included in the account sync, and never written to the support report. The report only says that an address has headers or a certificate, and never what they are.
Behind Cloudflare Access
IMAGO cannot show a login page, so it uses a service token, which Cloudflare designed for apps and scripts.
- In the Cloudflare dashboard, go to Zero Trust → Access controls → Service credentials → Service Tokens and select Create Service Token.
- Give it a name and a duration, then Generate token. Copy the Client Secret now: Cloudflare shows it only once.
- In the policy of your Access application, set the action to Service Auth and include that service token. With any other action, Access asks for a login that IMAGO cannot do.
- In IMAGO, open Advanced when adding the server and tap Cloudflare Access token. It adds the two headers; fill in the Client ID and the Client Secret as their values.
The two headers are CF-Access-Client-Id and CF-Access-Client-Secret. The token has an expiry date: when it ends, the server answers as if something in front of it were asking for authentication, and IMAGO says so.
A proxy that checks a header
If your proxy lets a request through only when it carries a header you chose, add that header under Advanced → Add header. The name and the value are yours. IMAGO does not accept names it manages itself, such as x-api-key, Host or Cookie.
Whatever the proxy is, Immich asks it to forward all headers, allow large uploads and support WebSockets. The Immich reverse proxy page has the details.
A server that asks for a certificate (mTLS)
With mutual TLS the proxy refuses any device that does not present a certificate it trusts. IMAGO takes the certificate as a .p12 or .pfx file, with its private key inside and a password.
- Create or obtain a client certificate signed by the authority your proxy trusts. If you manage it with OpenSSL, this packs a certificate and its key into a file IMAGO can read:
openssl pkcs12 -export -inkey client.key -in client.crt -out client.p12 - Put the file on the device, in a place the file chooser can reach.
- In IMAGO, Advanced → Import certificate (.p12), choose the file and type its password. IMAGO shows who the certificate is for, who issued it and until when.
The server’s own configuration is yours to make. In nginx, for example, it is a certificate authority file plus ssl_verify_client on. IMAGO warns 30 days before the certificate expires; after that date the server refuses the device without saying why.
A certificate from your own authority
If your server uses a certificate issued by an authority you created (a home lab, for instance), the device has to know that authority.
- Android: install the authority’s certificate in the system settings (the name of the screen changes with the phone; search the settings for “install certificate” and choose a CA certificate). IMAGO then trusts it for your Immich servers, and only for them: IMAGO’s own services keep trusting the system’s authorities alone.
- Windows: open the authority’s certificate file, choose Install Certificate and put it in Trusted Root Certification Authorities. IMAGO reads the Windows certificate stores.
IMAGO has no option to ignore certificate errors, on purpose: it would turn the protection off for anyone in between.
What the messages mean
- Something in front of the server answered before Immich did
- A proxy or access service asked for authentication: a login page, a redirect to another host, or a refusal that is not Immich’s own. Open Advanced and check the headers. Check that the token has not expired and that the policy allows it.
- The server asks for a client certificate
- Import one under Advanced, or check that the imported one is the one the proxy trusts and has not expired.
- This device doesn’t trust the server’s certificate
- The certificate is from an authority the device does not know, is for another name, or has expired. Install the authority (above) or use a public certificate.
- The server is unreachable
- Nothing answered. Check the address, the network and whether the server is running. A proxy that is up with Immich down shows this too.
If none of this explains it, contact support from Settings → Support and diagnostics. The report you review before sending says what kind of failure it was, never the address, the key or the headers.
Sources
- Cloudflare: service tokens
- Immich: reverse proxy
- Immich: FAQ, on the mobile app’s network features