Skip to content

wip: Sasl client settings auto #1609

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stephanbosch wants to merge 2 commits into
base: main
Choose a base branch
from
Open

wip: Sasl client settings auto #1609

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6889dba
settings.js: Document the new client_auth* settings
stephanbosch Aug 19, 2026
e790876
data/settings - Document the new client_auth* settings and their use …
stephanbosch Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
209 changes: 209 additions & 0 deletions data/settings.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,159 @@
than the server itself.`
},

client_auth: {
tags: [ 'client-auth' ],
values: setting_types.NAMED_LIST_FILTER,
seealso: [ 'client_auth_mechanism', 'client_auth_authzid',

Check failure on line 68 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`authzid` is not a recognized word (unrecognized-spelling)
'client_auth_authid', 'client_auth_password'],

Check failure on line 69 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`authid` is not a recognized word (unrecognized-spelling)
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).

@sirainen sirainen Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

`client_auth`. But .. I don't understand what this sentence is trying to say. I suppose it should be its own paragraph with an example. If that is even something that should be done at all? Maybe this text belongs to client_auth_mechanism setting anyway?

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]] and [[setting,pop3c]].

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

Check failure on line 101 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`authid` is not a recognized word (unrecognized-spelling)
authzid = owner-user

Check failure on line 102 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`authzid` is not a recognized word (unrecognized-spelling)
password = frop

Check failure on line 103 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`frop` is not a recognized word (unrecognized-spelling)
}
client_auth OAUTHBEARER {
authzid = owner-user
password = vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==

Check failure on line 107 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`GEu` is not a recognized word (unrecognized-spelling)

Check failure on line 107 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`HRhdmlzd` is not a recognized word (unrecognized-spelling)

Check failure on line 107 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`Bhb` is not a recognized word (unrecognized-spelling)

Check failure on line 107 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`Rlck` is not a recognized word (unrecognized-spelling)

Check failure on line 107 in data/settings.js

View workflow job for this annotation

GitHub Actions / Spell checking 

`Nvb` is not a recognized word (unrecognized-spelling)
}
}

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 { }

@sirainen sirainen Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

{ } will give error

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

@sirainen sirainen Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess this shows the configuration works like this, but is it something we actually want to encourage? I'm guessing not -> remove it.

}
\`\`\``
},

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.

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: {
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.

@sirainen sirainen Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this default to %{user}?


[[variable,mail-user]] can be used.`
},

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\`.`

@sirainen sirainen Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we now reusing this client_auth_password for too many things? Should we for example have instead client_auth_oauth2_token setting?

},

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.

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: {
tags: [ 'fs' ],
values: setting_types.NAMED_LIST_FILTER,
Expand Down Expand Up @@ -6609,6 +6762,16 @@
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' ],
Expand Down Expand Up @@ -6826,6 +6989,11 @@
},

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,
Expand Down Expand Up @@ -6867,6 +7035,11 @@
},

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,
Expand All @@ -6891,6 +7064,12 @@
},

imapc_sasl_mechanisms: {
deprecated: {
settings_auth_debug_deprecated: `

@sirainen sirainen Sep 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

definitely not 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,
Expand Down Expand Up @@ -6960,6 +7139,11 @@
},

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,
Expand Down Expand Up @@ -10143,6 +10327,16 @@
| \`%{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,
Expand All @@ -10162,6 +10356,11 @@
},

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,
Expand All @@ -10182,6 +10381,11 @@
},

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,
Expand Down Expand Up @@ -10244,6 +10448,11 @@
},

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' ],
Expand Down
3 changes: 2 additions & 1 deletion data/updates.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand All @@ -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',
Expand All @@ -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',

}