[schmitch]

Fixes #551

docs/deployment.md (Service accounts) said a service account's name is never forwarded to a credential-forwarding upstream. That holds only while the local realm is enabled and comes before every credential-forwarding realm:

• the realms are asked in priority order (crates/server/src/auth/realms.rs);
• local ends a password attempt as a service account itself: LocalPasswordProvider rejects it after a dummy verification, a terminal answer;
• the forwarding provider asks its upstream before it looks up any account (crates/core/src/auth/upstream_basic.rs).

So with a forwarding realm moved ahead of local, or local disabled, a login or Basic attempt as ci@example.com sends ci and the typed password upstream. The attempt is still refused, because map_identity_to_principal maps an upstream verdict only onto an upstream-basic account of that realm.

Changes

I took the issue's first option and qualified the docs. The other option, having the forwarding provider look up the name before forwarding, adds an account lookup to every forwarded attempt, and the issue is filed as documentation.

• Service accounts: the "never forwarded upstream" parenthesis becomes a bullet of its own. It says the realms are asked in the order Admin → Authentication lists them, that a new realm is added after local, and what happens with a forwarding realm ahead of it or local disabled: the name goes upstream and the attempt is still refused. Local and invited accounts behave the same.
• Inviting users: "nothing is forwarded to a credential-forwarding realm" made the same claim for invited users, so it gets the same qualification with a link.
• Changelog: docs/changes/2.2.0/551.docs.md.

Checks run

cargo xtask changelog --check, cargo xtask docs --check (the new anchor link resolves).

---

Generated by Claude Code