# Authentication

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/run/authentication/>.

Authentication is on by default. Anyone who reaches the app can use your Immich library through it,
so it asks for a sign-in before it shows anything. Keep one UI replica.
Everyone who can sign in can use the library and change what Settings offers, so with OIDC set an
allow-list (`allowed_emails` or `allowed_domains`). Login, server, render-worker and model-path
settings stay with `config.yaml` and the environment; see
[settings only the operator sets](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md#settings-only-the-operator-sets).

The first start with nothing configured generates a password for you. To pick your own, use Basic
auth below. Use OIDC for your existing identity provider, or trusted headers when an authenticated
proxy is the only route to the app.
[Proxy, TLS and bind-address setup](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md) is a separate operator guide.

![The sign-in page: username, password and Sign in](https://sam-dumont.github.io/immich-memories/img/screenshots/login.png)

## The generated password

With basic sign-in and no password configured, the first start generates one. The username is
`admin` unless you set `auth.username`. The app stores only a scrypt hash of the password in
`generated-login.json`, next to `config.yaml` (`~/.immich-memories/` for a pip or uv install,
`/home/immich/.immich-memories` in the Docker image, which is the config volume).

The first start prints the username and password once in the server log:
`docker compose logs immich-memories` (or `docker logs immich-memories`) in Docker, the terminal for
`immich-memories ui`. No web page shows it. The sign-in page only tells you where to look.

Later starts never print it again. Write it down, or sign in and move to a password of your own.
When several workers start at once, one of them makes the password and prints it; the others use
that one and print nothing.

If `generated-login.json` can't be read (a truncated or hand-edited file), the old password is
gone. The next start keeps the broken file as `generated-login.json.corrupt-<time>`, makes a new
password and prints it, after a warning that says so.

Lost it? Make a new one. The command writes a new hash, prints the new password once in the
terminal and signs every browser out.

```bash
docker compose exec immich-memories immich-memories auth reset-password
```

On a pip or uv install, run `immich-memories auth reset-password` directly.

## Basic auth

This is the Immich Memories app login. Choose its username and password yourself, or keep the generated one; your Immich,
NAS and operating-system accounts do not set them. It is independent of the Basic installation tier.

Set these two variables in the shipped Compose setup's `.env`:

```ini
IMMICH_MEMORIES_AUTH_USERNAME=admin
IMMICH_MEMORIES_AUTH_PASSWORD=choose-a-long-password
```

Run `docker compose up -d` to apply the change. In a stack editor with no `.env`, add both
variables to the app service's `environment:` block and redeploy the stack.

"Basic" names the provider: a username and password typed into the login page, which starts a session cookie. The app does not accept an HTTP `Authorization: Basic` header, so `curl -u` gets 401; script it with `POST /auth/login` and the cookie (a [Synology example](https://sam-dumont.github.io/immich-memories/docs/run/reference/synology-operations.md#checking-auth-with-curl) shows the calls).

Set both; one alone is ignored. Configured credentials replace the generated password. From a
shell each line needs `export` in front of it. A password under 12 characters works, but startup
and `immich-memories preflight` warn about it. The YAML form:

```yaml
advanced:
  auth:
    provider: basic
    username: admin
    password: ${MY_SECRET_PASSWORD}
```

If `MY_SECRET_PASSWORD` is not set, the server refuses to start rather than take
`${MY_SECRET_PASSWORD}` as the password. Set the variable, or drop the line to use the generated
password.

## OIDC / SSO

Any OpenID Connect provider, with PKCE, discovered from `issuer_url/.well-known/openid-configuration`.
Docker images ship `authlib`; a pip install needs `immich-memories[auth]`.

```yaml
advanced:
  auth:
    enabled: true
    provider: oidc
    issuer_url: https://your-idp.example.com
    client_id: immich-memories
    client_secret: ${OIDC_CLIENT_SECRET}  # empty for public clients
    public_url: https://memories.example.com  # the URL users reach you on
    allowed_emails: [me@example.com]
    allowed_domains: [example.com]        # exact: does not admit sub.example.com
    auto_launch: false                     # true: straight to the IdP, no login page
```

`public_url` pins the `redirect_uri` sent to the IdP, so it must match what you registered there,
and it is what makes callback-origin validation possible. Register the callback URL
`https://your-host/auth/callback`. The app does not send a `post_logout_redirect_uri`; registering
`https://your-host/logout` at the IdP does not make logout return there. Auth0: a Regular
Web Application. Keycloak: a client with client authentication enabled. Authelia: a client with
`pkce_challenge_method: S256`, scopes `openid`, `email`, `profile`, grant type
`authorization_code`. The rest of the `auth` keys are in the
[config reference](https://sam-dumont.github.io/immich-memories/docs/reference/config-reference.md).

An expired sign-in or a reused callback returns you to the sign-in page with
"Sign-in expired. Try again." Click the SSO button to start a fresh sign-in.
This page waits for your click even with `auto_launch: true`.

> **Your IdP decides who you are, not whether you may enter:** With no allow-list, anyone your IdP authenticates becomes a full admin of this app, Immich API key
> included. Fine for a personal tenant; wrong for a shared realm or an Auth0 tenant with social
> sign-ups. Set `allowed_emails` or `allowed_domains`: either list admits, matching ignores case, and
> once either is set the token must carry both `email` and the boolean `email_verified: true`.
> Configure your provider to verify addresses and include that claim: a matching address the IdP has
> not verified is refused, because on a tenant with open sign-ups anyone can type one. A refused
> account gets a "Not authorised" page, not a redirect loop.

## Trusted header (reverse proxy)

For a proxy that authenticates (Traefik + Authelia, nginx + oauth2-proxy) and forwards the user in
a header.

```yaml
advanced:
  auth:
    enabled: true
    provider: header
    user_header: Remote-User    # default
    email_header: Remote-Email  # default, optional
    trusted_proxies:
      - 172.20.0.2              # your proxy; prefer a /32 over a whole Docker network
    session_ttl_hours: 24
```

Headers are read only when the immediate peer is in `trusted_proxies`; from anyone else the request
is unauthenticated, and an empty `trusted_proxies` here fails validation at startup. The app strips
nothing, so a proxy that forwards the header from an untrusted source is your problem to fix.
Authelia forwards `Remote-User` and `Remote-Email` by default.

The header is read on every request: a different user in it switches the session to that user,
and a request without it is not signed in. Header auth uses `trusted_proxies` only. With
`FORWARDED_ALLOW_IPS` present, even if empty, the app refuses to start, since uvicorn would
replace the proxy's address with the visitor's before the check runs. Remove the variable
entirely and keep direct access restricted to the authenticating proxy.

## Turning it off on purpose

For a throwaway test on your own machine you can run with no sign-in:

```ini
IMMICH_MEMORIES_AUTH__ENABLED=false
```

(or `enabled: false` under `advanced: auth:`). Anyone who reaches the app can then use your Immich
API key. The UI binds to localhost only, and answers only local hosts and `server.allowed_hosts`,
unless you pass an explicit host. To reach it from the LAN without a login of its own, put your own
auth proxy in front and use [header sign-in](#trusted-header-reverse-proxy).

## Behind a reverse proxy with TLS

[Network and security](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md) has the complete proxy recipe and the four settings
that make HTTPS login work.

## Sessions

A session is a signed cookie and lasts `session_ttl_hours` (24 by default). The key that signs it
is `IMMICH_MEMORIES_STORAGE_SECRET`, or else `~/.immich-memories/.storage_secret`, generated on
first start, so logins survive a restart; change it and every session ends. A key you set must be
32 random characters or more, without placeholder words like `change-me`; anything shorter and
the app refuses to start. Generate one with `openssl rand -hex 32`.

**Sign out** in the top bar sends `POST /logout` and ends every session of that user, in every browser: a
copy of the cookie taken before the sign-out no longer opens the app. OIDC logout also ends the
IdP session when the IdP advertises `end_session_endpoint`; the app sends no return URL.
For header auth, app logout does not sign out of the proxy, which can authenticate the next
request again. Changing the password, the provider
or the OIDC allow-list ends every session of every user.

Auth is set in the environment or `config.yaml` only, and a change needs a restart.

Sign-in failures are counted per client address (IPv6 clients per /64), per username across all
addresses, and overall. Five failures from one address lock it out for ten minutes. After five
failures, a username waits 30 seconds, then twice as long after each further failure (up to ten
minutes), wherever the guesses come from. A hundred failures in ten minutes pause every sign-in for a minute. Scripts authenticate to
[the trigger endpoint](https://sam-dumont.github.io/immich-memories/docs/make/automate.md#trigger-it-over-http) with
`server.trigger_token` instead.

Sign-out only accepts POST. `GET /logout` returns 405 and leaves the session active.
Requests from another browser origin are refused before any session is ended.
