diff --git a/docs/config/authentication.md b/docs/config/authentication.md
index 05365cb3..0ff48484 100644
--- a/docs/config/authentication.md
+++ b/docs/config/authentication.md
@@ -65,7 +65,7 @@ Comma-separated allowlist of `password`, `magic_link`, and/or `oidc`. Default (w
 
 **OIDC master rule.** When OIDC is enabled, magic-link login is **hard-disabled** regardless of this list. The IdP is the identity boundary; magic-link would bypass any 2FA / step-up policy the IdP enforces. The startup gate above does **not** trigger in this case — OIDC provides the login path.
 
-Legacy alias: `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=true` still removes `password` from the effective allowlist.
+**DEPRECATED** alias: `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=true` still removes `password` from the effective allowlist. Setting it emits a boot warning; the flag will be removed in the next major release. Migrate to `OXICLOUD_AUTH_METHODS=oidc` (and add `OXICLOUD_AUTH_POLICIES=auto_redirect_if_standalone_oidc` if you want the server-side `/login` redirect too).
 
 ### `OXICLOUD_REQUIRE_VERIFIED_EMAIL`
 
diff --git a/docs/config/env.md b/docs/config/env.md
index 8fd5be1c..d4e99e51 100644
--- a/docs/config/env.md
+++ b/docs/config/env.md
@@ -46,7 +46,7 @@ Most runtime variables use the `OXICLOUD_` prefix. A few build-time or allocator
 | `OXICLOUD_HASH_PARALLELISM` | `2` | Argon2id parallelism lanes |
 | `OXICLOUD_DISABLE_REGISTRATION` | false | Disable registration of new user accounts |
 | `OXICLOUD_REGISTRATION_ALLOWED_EMAIL_DOMAINS` | — | Comma-separated allowlist of email domains accepted on `POST /api/auth/register` (case-insensitive, exact match on the post-`@` part). Empty = any domain is allowed. **Distinct from `OXICLOUD_EXTERNAL_EMAIL_DOMAINS`**: this one gates SELF-registration (public sign-up), the external list gates INVITATIONS (grants + magic-link to third parties). An operator can lock sign-up to their company domain while leaving invitations open. Subdomains must be listed explicitly. Rejected registrations return 403 `RegistrationDomainNotAllowed` and emit an `audit` line. Example: `mycompany.com,mycompany-eu.com`. |
-| `OXICLOUD_AUTH_METHODS` | `password,magic_link` | Comma-separated allowlist of auth methods (`password`, `magic_link`, `oidc`). **Fail-fast**: unknown token → boot panic; empty allowlist → boot panic; `oidc` in list without `OXICLOUD_OIDC_ENABLED=true` → boot panic. Removing `password` disables `POST /api/auth/login` (returns 403 `PasswordLoginDisabled`) and password-based `register` (returns 403 `PasswordRegistrationDisabled`). Removing `magic_link` disables `POST /api/auth/magic-link/send` (returns 403 `MagicLinkLoginDisabled`) and the redemption path for login-purpose tokens. Setting `OXICLOUD_AUTH_METHODS=oidc` is the cleanest "SSO-only" posture. **Loose semantic (deprecation warning)**: if this list is explicitly set WITHOUT `oidc` but `OXICLOUD_OIDC_ENABLED=true`, OIDC is served regardless — a boot warning is emitted and this will become a fail-fast panic in the next major release. **Startup gate**: if `magic_link` is the only working method (no `password`, no `oidc`) AND no SMTP transport is configured (`OXICLOUD_SMTP_HOST` empty), the server refuses to start. **OIDC master rule**: when OIDC is enabled, magic-link login is hard-disabled regardless of this list (would otherwise bypass IdP-enforced MFA / step-up). Legacy alias: `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=true` still removes `password` from the list. |
+| `OXICLOUD_AUTH_METHODS` | `password,magic_link` | Comma-separated allowlist of auth methods (`password`, `magic_link`, `oidc`). **Fail-fast**: unknown token → boot panic; empty allowlist → boot panic; `oidc` in list without `OXICLOUD_OIDC_ENABLED=true` → boot panic. Removing `password` disables `POST /api/auth/login` (returns 403 `PasswordLoginDisabled`) and password-based `register` (returns 403 `PasswordRegistrationDisabled`). Removing `magic_link` disables `POST /api/auth/magic-link/send` (returns 403 `MagicLinkLoginDisabled`) and the redemption path for login-purpose tokens. Setting `OXICLOUD_AUTH_METHODS=oidc` is the cleanest "SSO-only" posture. **Loose semantic (deprecation warning)**: if this list is explicitly set WITHOUT `oidc` but `OXICLOUD_OIDC_ENABLED=true`, OIDC is served regardless — a boot warning is emitted and this will become a fail-fast panic in the next major release. **Startup gate**: if `magic_link` is the only working method (no `password`, no `oidc`) AND no SMTP transport is configured (`OXICLOUD_SMTP_HOST` empty), the server refuses to start. **OIDC master rule**: when OIDC is enabled, magic-link login is hard-disabled regardless of this list (would otherwise bypass IdP-enforced MFA / step-up). Legacy alias (**DEPRECATED**): `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=true` still removes `password` from the list but emits a boot warning; removal in next major release. |
 | `OXICLOUD_AUTH_POLICIES` | — | Comma-separated additive policy switches. Each token grants an exception or restriction to the default auth behaviour; empty (unset) = pure defaults. Recognised tokens: `permit_magic_link_for_password_users` (allow magic-link login for accounts that also have a password — off by default because magic-link would weaken the password to mailbox-strength; OIDC-linked users are still refused regardless); `auto_redirect_if_standalone_oidc` (when OIDC is the only working login method, auto-redirect the login page to the IdP instead of showing a click-to-continue button — off by default to avoid redirect loops on IdP failure and preserve logout UX). |
 | `OXICLOUD_REQUIRE_VERIFIED_EMAIL` | `false` | When `true`, `POST /api/auth/login` returns 403 `EmailNotVerified` for any account whose `email_verified_at` is NULL. Users can prove control by requesting a magic-link (whose redemption stamps `email_verified_at`), so this composes with `magic_link` in `OXICLOUD_AUTH_METHODS` to give users a self-service verification path. Admin-created (`POST /api/admin/users`) and setup-admin (`POST /api/setup`) users are auto-verified. OIDC-JIT users are also stamped verified at creation. |
 
@@ -211,7 +211,7 @@ See the [OIDC configuration guide](/config/oidc) for details.
 | `OXICLOUD_OIDC_FRONTEND_URL` | `http://localhost:8086` | Frontend URL to redirect to after login |
 | `OXICLOUD_OIDC_AUTO_PROVISION` | `true` | Auto-create users on first SSO login (JIT provisioning) |
 | `OXICLOUD_OIDC_ADMIN_GROUPS` | — | Comma-separated OIDC groups that grant admin role |
-| `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | Hide password form when OIDC is active |
+| `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | **DEPRECATED** — emits boot warning; slated for removal in next major release. Use `OXICLOUD_AUTH_METHODS=oidc` (and optionally `OXICLOUD_AUTH_POLICIES=auto_redirect_if_standalone_oidc` for server-side `/login` redirect) instead. Still removes `password` from the effective allowlist when set to `true` — kept working so upgrading deployments don't break. |
 | `OXICLOUD_OIDC_PROVIDER_NAME` | `SSO` | Display name for the provider shown in UI |
 
 ## WOPI (Office Editing)
diff --git a/docs/config/oidc.md b/docs/config/oidc.md
index acf53c83..2e58fa4e 100644
--- a/docs/config/oidc.md
+++ b/docs/config/oidc.md
@@ -48,7 +48,7 @@ OXICLOUD_OIDC_PROVIDER_NAME="Authentik"
 | `OXICLOUD_OIDC_FRONTEND_URL` | `http://localhost:8086` | Where to redirect the browser after auth |
 | `OXICLOUD_OIDC_AUTO_PROVISION` | `true` | Auto-create users on first login |
 | `OXICLOUD_OIDC_ADMIN_GROUPS` | — | OIDC groups that grant admin role |
-| `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | Hide password login when OIDC is active |
+| `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN` | `false` | **DEPRECATED** — use `OXICLOUD_AUTH_METHODS=oidc` instead. Emits a boot warning; slated for removal in next major release. |
 | `OXICLOUD_OIDC_PROVIDER_NAME` | `SSO` | Label shown on the login button |
 
 ::: warning
diff --git a/example.env b/example.env
index 9577001b..9e00b084 100644
--- a/example.env
+++ b/example.env
@@ -550,7 +550,13 @@ OXICLOUD_OIDC_ENABLED=false
 # Example: admins,cloud-admins
 #OXICLOUD_OIDC_ADMIN_GROUPS=
 
-# Disable password-based login entirely when OIDC is active (default: false)
+# DEPRECATED: prefer OXICLOUD_AUTH_METHODS=oidc (with optional
+# OXICLOUD_AUTH_POLICIES=auto_redirect_if_standalone_oidc for the
+# server-side /login redirect). This flag still works but emits a
+# boot warning; removal is planned for the next major release.
+#
+# Legacy path — disables password-based login entirely when OIDC is
+# active (default: false).
 #OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=false
 
 # Display name for the OIDC provider shown in UI (default: SSO)
@@ -744,8 +750,10 @@ OXICLOUD_WOPI_ENABLED=false
 # identity provider; magic-link would sidestep any 2FA / step-up the
 # IdP enforces.
 #
-# Legacy alias: `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=true` still removes
-# `password` from this list. New deployments should prefer this env var.
+# DEPRECATED alias: `OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN=true` still
+# removes `password` from this list but emits a boot warning; it will be
+# removed in the next major release. New deployments MUST use this
+# `OXICLOUD_AUTH_METHODS` env var instead.
 #
 # Default (when unset): password + magic_link.
 #OXICLOUD_AUTH_METHODS=password,magic_link
diff --git a/src/common/config.rs b/src/common/config.rs
index dd4b2e6c..85aca2ca 100644
--- a/src/common/config.rs
+++ b/src/common/config.rs
@@ -2753,13 +2753,36 @@ impl AppConfig {
         // response; this line makes the effect apply uniformly through
         // `is_method_allowed(Password)` so services don't need to check
         // both flags.
-        if let Ok(v) = env::var("OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN")
-            && v.parse::<bool>().unwrap_or(false)
-        {
-            config
-                .auth
-                .allowed_auth_methods
-                .retain(|m| *m != AuthMethod::Password);
+        //
+        // Deprecated in favour of the composable `OXICLOUD_AUTH_METHODS=oidc`
+        // allowlist which handles the same SSO-only intent alongside the
+        // AUTH_POLICIES vector. Warn every time the env var is observed so
+        // operators migrating a config from a pre-AUTH_METHODS release see
+        // the recommendation on the first boot after upgrade. Removal is
+        // slated for the next major release; the setting continues to work
+        // until then to avoid breaking existing deployments.
+        if let Ok(v) = env::var("OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN") {
+            let parsed = v.parse::<bool>().unwrap_or(false);
+            tracing::warn!(
+                "OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN is DEPRECATED and will \
+                 be removed in a future major release. Use \
+                 `OXICLOUD_AUTH_METHODS=oidc` instead (add \
+                 `OXICLOUD_AUTH_POLICIES=auto_redirect_if_standalone_oidc` \
+                 to also enable server-side /login redirect). \
+                 Current value: {} — {}",
+                v,
+                if parsed {
+                    "password login is disabled"
+                } else {
+                    "no effect (value must be `true` to take effect)"
+                },
+            );
+            if parsed {
+                config
+                    .auth
+                    .allowed_auth_methods
+                    .retain(|m| *m != AuthMethod::Password);
+            }
         }
 
         if let Ok(v) = env::var("OXICLOUD_REQUIRE_VERIFIED_EMAIL") {