From 6889dbac3d743d246c41d4001c6ec442f6d403c1 Mon Sep 17 00:00:00 2001 From: Stephan Bosch Date: Wed, 19 Aug 2026 14:59:40 +0200 Subject: [PATCH 1/2] settings.js: Document the new client_auth* settings --- data/settings.js | 120 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/data/settings.js b/data/settings.js index ecc402e63..b0a581c88 100644 --- a/data/settings.js +++ b/data/settings.js @@ -62,6 +62,126 @@ destination IP address belongs to, for instance, a load-balancer rather than the server itself.` }, + client_auth: { + tags: [ 'client-auth' ], + values: setting_types.NAMED_LIST_FILTER, + seealso: [ 'client_auth_mechanism', 'client_auth_authzid', + 'client_auth_authid', 'client_auth_password' ], + text: ` +This settings filter provides a scope for client authentication settings for +a particular authentication mechanism and declares the availability of that +mechanism for client authentication. The mechanism will be used if support is +also indicated by the server. This way, several different mechanisms can be +configured, each with specific settings. + +The filter name refers to the [[setting,client_auth_mechanism]] setting. + +Mechanisms are attempted in the order of configuration, so preferred mechanisms +should be configured first. If [[setting,client_auth_mechanism]] is set +outside the scope of this filter, the indicated mechanism is used with settings +in that context (a client_auth filter block for that mechanism is not used). +Also, in that case, server support is not checked and the mechanism is attempted +blindly. + +Client authentication settings are expected to be scoped further by settings +filters for the various protocol clients that need authentication, such as +[[setting,imapc]], [[setting,pop3c]], [[setting,submission_relay]], and +[[setting,mail_submit]]. + +Example: +\`\`\`[dovecot.conf] +mail_driver = imapc +mail_path = +mailbox_list_index = no +imapc { + host = 127.0.0.1 + port = 993 + ssl = imaps + + client_auth PLAIN { + authid = master-user + authzid = owner-user + password = frop + } + client_auth OAUTHBEARER { + authzid = owner-user + password = vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg== + } +} + +submission_relay { + smtp_client_host = submission.example.com + smtp_client_port = 587 + smtp_client_ssl = no + + client_auth_authzid = user + client_auth_password = frop + + client_auth SCRAM-SHA-256 { } + client_auth SCRAM-SHA-1 { } + client_auth CRAM-MD5 { } + client_auth PLAIN { } +} + +mail_submit { + smtp_client_host = localhost + smtp_client_port = 25 + + client_auth_mechanism = PLAIN + client_auth_authzid = mail-out + client_auth_password = frop +} +\`\`\`` + }, + + client_auth_authid: { + tags: [ 'client-auth' ], + seealso: [ 'client_auth_authzid', 'client_auth_password', + 'client_auth_mechanism' ], + values: setting_types.STRING, + text: ` +The authentication identity to be used for authenticating as a client to a +remote service.` + }, + + client_auth_authzid: { + tags: [ 'client-auth' ], + seealso: [ 'client_auth_authid', 'client_auth_password', + 'client_auth_mechanism' ], + values: setting_types.STRING, + text: ` +The authorization identity to be used after authenticating as a client to a +remote service.` + }, + + client_auth_password: { + tags: [ 'client-auth' ], + seealso: [ 'client_auth_authzid', 'client_auth_authid', + 'client_auth_mechanism' ], + values: setting_types.STRING, + text: ` +The password to be used for authenticating as a client to a remote service. This +is the password belonging to the authentication identity \`client_auth_authid\`.` + }, + + client_auth_mechanism: { + tags: [ 'client-auth' ], + seealso: [ 'client_auth_authzid', 'client_auth_authid', + 'client_auth_password' ], + values: setting_types.STRING, + text: ` +The authentication mechanism (sometimes called scheme) to be used for +authenticating as a client to a remote service. Currently, this is always a SASL +mechanism. If left unconfigured, SASL authentication will use the PLAIN +mechanism by default. For IMAP and POP3 clients, it will use the basic login +commands in that case if possible (LOGIN for IMAP and USER + PASS for POP3, so +SASL support is not required). However, if the authentication +\`client_auth_authid\` and authorization \`client_auth_authzid\` identities are +both also unconfigured, no authentication is configured at all. In that case, +authentication will be skipped if it is optional or this will be reported as an +error otherwise.` + }, + fs: { tags: [ 'fs' ], values: setting_types.NAMED_LIST_FILTER, From e790876420d694aaf854897b97b40981a3f8f484 Mon Sep 17 00:00:00 2001 From: Stephan Bosch Date: Wed, 19 Aug 2026 20:01:17 +0200 Subject: [PATCH 2/2] data/settings - Document the new client_auth* settings and their use for imapc and pop3c --- data/settings.js | 101 ++++++++++++++++++++++++++++++++++++++++++++--- data/updates.js | 3 +- 2 files changed, 97 insertions(+), 7 deletions(-) diff --git a/data/settings.js b/data/settings.js index b0a581c88..60b5947d8 100644 --- a/data/settings.js +++ b/data/settings.js @@ -66,7 +66,7 @@ than the server itself.` tags: [ 'client-auth' ], values: setting_types.NAMED_LIST_FILTER, seealso: [ 'client_auth_mechanism', 'client_auth_authzid', - 'client_auth_authid', 'client_auth_password' ], + 'client_auth_authid', 'client_auth_password'], text: ` This settings filter provides a scope for client authentication settings for a particular authentication mechanism and declares the availability of that @@ -85,8 +85,7 @@ blindly. Client authentication settings are expected to be scoped further by settings filters for the various protocol clients that need authentication, such as -[[setting,imapc]], [[setting,pop3c]], [[setting,submission_relay]], and -[[setting,mail_submit]]. +[[setting,imapc]] and [[setting,pop3c]]. Example: \`\`\`[dovecot.conf] @@ -141,7 +140,21 @@ mail_submit { values: setting_types.STRING, text: ` The authentication identity to be used for authenticating as a client to a -remote service.` +remote service. + +To authenticate as a master user to e.g. an IMAP server but use a separate login +user, the following configuration should be employed, where the credentials are +represented by masteruser and masteruser-secret: + +\`\`\` +imapc { + client_auth_authid = masteruser + client_auth_authzid = %{user} + client_auth_password = masteruser-secret +} +\`\`\` + +[[variable,mail-user]] can be used.` }, client_auth_authzid: { @@ -151,7 +164,9 @@ remote service.` values: setting_types.STRING, text: ` The authorization identity to be used after authenticating as a client to a -remote service.` +remote service. + +[[variable,mail-user]] can be used.` }, client_auth_password: { @@ -179,7 +194,25 @@ SASL support is not required). However, if the authentication \`client_auth_authid\` and authorization \`client_auth_authzid\` identities are both also unconfigured, no authentication is configured at all. In that case, authentication will be skipped if it is optional or this will be reported as an -error otherwise.` +error otherwise. + +Supported mechanisms are: + + * ANONYMOUS + * CRAM-MD5 + * DIGEST-MD5 + * EXTERNAL + * LOGIN + * OAUTHBEARER + * PLAIN + * SCRAM-SHA-1 + * SCRAM-SHA-1-PLUS + * SCRAM-SHA-256 + * SCRAM-SHA-256-PLUS + * XOAUTH2 + +Note that [[setting,client_auth_password]] is ignored for \`ANONYMOUS\` and \`EXTERNAL\` mechanisms. +For \`OAUTHBEARER\` and \`XOAUTH2\` [[setting,client_auth_password]] should be a bearer token.` }, fs: { @@ -6729,6 +6762,16 @@ Variables allowed: The port is used with the URLAUTH extension in IMAP operation.` }, + imapc: { + tags: [ 'imapc', 'client-auth' ], + values: setting_types.NAMED_LIST_FILTER, + seealso: [ 'client_auth_mechanism', 'client_auth_authzid', + 'client_auth_authid', 'client_auth_password' ], + text: ` +This settings filter provides a scope for settings for imapc. This is for example +used to configure [[setting,client_auth] for imapc specifically.` + }, + imapc_cmd_timeout: { default: '5 mins', tags: [ 'imapc' ], @@ -6946,6 +6989,11 @@ imapc_list_prefix = INBOX }, imapc_master_user: { + removed: { + settings_imapc_credentials_removed: ` +Dropped in favor of using the global +[[setting,client_auth_authid]].` + }, tags: [ 'imapc' ], seealso: [ 'imapc_password', 'imapc_user' ], values: setting_types.STRING, @@ -6987,6 +7035,11 @@ This setting is used to limit maximum memory usage.` }, imapc_password: { + removed: { + settings_imapc_credentials_removed: ` +Dropped in favor of using the global +[[setting,client_auth_password]].` + }, tags: [ 'imapc' ], seealso: [ 'imapc_master_user', 'imapc_user', 'imapc_sasl_mechanisms' ], values: setting_types.STRING, @@ -7011,6 +7064,12 @@ If using master users, this setting will be the password of the master user.` }, imapc_sasl_mechanisms: { + deprecated: { + settings_auth_debug_deprecated: ` +The setting is obsolete, and kept only for backwards compatibility. + +Use [[setting,client_auth]] instead.` + }, default: 'plain', tags: [ 'imapc' ], values: setting_types.BOOLLIST, @@ -7080,6 +7139,11 @@ Only used if [[setting,imapc_ssl]] is enabled.` }, imapc_user: { + removed: { + settings_imapc_credentials_removed: ` +Dropped in favor of using the global +[[setting,client_auth_authzid]].` + }, tags: [ 'imapc', 'imapc-auth' ], seealso: [ 'imapc_master_user', 'imapc_password', 'imapc_sasl_mechanisms' ], values: setting_types.STRING, @@ -10263,6 +10327,16 @@ in uppercase) and with [[variable,global]]: | \`%{guid}\` | Dovecot GUID for the message |` }, + pop3c: { + tags: [ 'pop3c', 'client-auth' ], + values: setting_types.NAMED_LIST_FILTER, + seealso: [ 'client_auth_mechanism', 'client_auth_authzid', + 'client_auth_authid', 'client_auth_password' ], + text: ` +This settings filter provides a scope for settings for pop3c. This is for example +used to configure [[setting,client_auth] for pop3c specifically.` + }, + pop3c_features: { tags: [ 'pop3c' ], values: setting_types.BOOLLIST, @@ -10282,6 +10356,11 @@ Workarounds: }, pop3c_master_user: { + removed: { + settings_pop3c_credentials_removed: ` +Dropped in favor of using the global +[[setting,client_auth_authid]].` + }, tags: [ 'pop3c' ], seealso: [ 'pop3c_password', 'pop3c_user' ], values: setting_types.STRING, @@ -10302,6 +10381,11 @@ pop3c_password = masteruser-secret }, pop3c_password: { + removed: { + settings_pop3c_credentials_removed: ` +Dropped in favor of using the global +[[setting,client_auth_password]].` + }, tags: [ 'pop3c' ], seealso: [ 'pop3c_master_user', 'pop3c_user' ], values: setting_types.STRING, @@ -10364,6 +10448,11 @@ Only used if [[setting,pop3c_ssl]] is enabled.` }, pop3c_user: { + removed: { + settings_pop3c_credentials_removed: ` +Dropped in favor of using the global +[[setting,client_auth_authzid]].` + }, default: '%{user}', tags: [ 'pop3c' ], seealso: [ 'pop3c_master_user', 'pop3c_password' ], diff --git a/data/updates.js b/data/updates.js index f0419c20f..e6a23e3e5 100644 --- a/data/updates.js +++ b/data/updates.js @@ -164,6 +164,7 @@ export const updates = { settings_http_server_settings_added: '2.4.0', settings_imap_compress_on_proxy_added: '2.4.2', settings_imap_compress_on_proxy_changed: '2.4.5', + settings_imapc_credentials_removed: '2.4.5', settings_imapc_features_changed: '2.4.0', settings_imapc_ssl_verify_removed: '2.4.0', settings_inet_listener_type_added: '2.4.0', @@ -185,6 +186,7 @@ export const updates = { settings_passdb_mechanisms_filter_added: '2.4.0', settings_passdb_sql_update_query_removed: '2.4.5', settings_passdb_static_password_added: '2.4.0', + settings_pop3c_credentials_removed: '2.4.5', settings_service_reuse_port_added: '2.4.4', settings_sieve_max_cpu_time_changed: '2.4.5', settings_sieve_notify_mailto_max_headers_added: '2.4.5', @@ -202,5 +204,4 @@ export const updates = { settings_quota_mailbox_message_count_added: '2.4.0', settings_submission_add_received_header_added: '2.4.0', settings_verbose_ssl_removed: '2.4.0', - }