From 600e1dd6f7c132242832292187d4089d699c6b3e Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 30 Aug 2026 10:26:14 -0400 Subject: [PATCH 1/2] docs(auth): clarify recoverable password storage Explain when recoverable login passwords are stored in authentication-token records and the consequences. Document the actual RSA key-size performance threshold (214 and neither "300" nor 250) and clarify that the 469-byte account-password limit applies regardless of this option. Signed-off-by: Josh --- config/config.sample.php | 47 ++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/config/config.sample.php b/config/config.sample.php index 6a2ab485c2269..4abda71cf94ca 100644 --- a/config/config.sample.php +++ b/config/config.sample.php @@ -575,21 +575,40 @@ 'auth.webauthn.enabled' => true, /** - * Whether encrypted passwords should be stored in the database + * Whether recoverable login passwords should be stored in authentication-token + * records. + * + * When enabled and the login password is available to Nextcloud, a separate, + * reversibly encrypted copy of the password is stored in the server-side records + * associated with the user's authentication tokens. This is separate from the + * one-way password hash used for account authentication. + * + * The recoverable password copy is used for features that require the original + * login credentials, such as connecting to external storage, autoconfiguring + * accounts in the Mail app, and periodically checking whether a password remains + * valid. + * + * A recoverable password is encrypted using an RSA key pair associated with its + * authentication-token record. Passwords longer than 214 bytes require a larger + * RSA key, which increases token-generation overhead. + * + * Administrators may wish to disable this option when users routinely use very + * long passwords (215 to 469 bytes), when one-time login credentials should not + * be stored, or when deployed authentication flows do not require password + * recovery. Disabling it prevents the recoverable password copy from being stored + * and avoids password-length-related RSA key-size increases. However, operations + * that require Nextcloud to have access to the original login password will no + * longer work. + * + * NOTE: Nextcloud enforces a maximum account password length of 469 bytes whether + * this option is enabled or disabled. + * + * WARNING: If disabled, password changes made directly in an external user + * backend, such as LDAP, no longer automatically invalidate connected clients. + * Users can still disconnect clients by deleting their app tokens from the + * security settings. * - * The passwords are only decrypted using the login token stored uniquely in the - * clients and allow connecting to external storages, autoconfiguring mail accounts in - * the mail app, and periodically checking if the password is still valid. - * - * This might be desirable to disable this functionality when using one-time - * passwords or when having a password policy enforcing long passwords (> 300 - * characters). - * - * By default, the passwords are stored encrypted in the database. - * - * WARNING: If disabled, password changes on the user backend (e.g., on LDAP) no - * longer log connected clients out automatically. Users can still disconnect - * the clients by deleting the app token from the security settings. + * Defaults to ``true``. */ 'auth.storeCryptedPassword' => true, From 470527ef462d63f2452d630fd4899e99222dd4f2 Mon Sep 17 00:00:00 2001 From: Josh Date: Sun, 30 Aug 2026 10:49:56 -0400 Subject: [PATCH 2/2] chore(config.sample.php): fixup spacing Signed-off-by: Josh --- config/config.sample.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/config.sample.php b/config/config.sample.php index 4abda71cf94ca..8915171e45a4d 100644 --- a/config/config.sample.php +++ b/config/config.sample.php @@ -582,7 +582,7 @@ * reversibly encrypted copy of the password is stored in the server-side records * associated with the user's authentication tokens. This is separate from the * one-way password hash used for account authentication. - * + * * The recoverable password copy is used for features that require the original * login credentials, such as connecting to external storage, autoconfiguring * accounts in the Mail app, and periodically checking whether a password remains