Skip to content

client_auth: Document GSSAPI channel binding and GSSAPI client usage #1706

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
cmouse wants to merge 1 commit into
base: main
Choose a base branch
from
Open

client_auth: Document GSSAPI channel binding and GSSAPI client usage #1706

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 3 additions & 0 deletions .github/actions/spelling/expect.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ bzlib
CACERTDIR
CANTCREAT
CApath
CCNAME
cdb
certbot
changetype
Expand Down Expand Up @@ -187,6 +188,7 @@ eddsa
editheader
edprivkey
edpubkey
edu
egid
EID
Eing
Expand Down Expand Up @@ -343,6 +345,7 @@ kludgy
kmail
krb
ktadd
KTNAME
ktpass
ktrace
KTY
Expand Down
41 changes: 39 additions & 2 deletions data/settings.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,38 @@ checked already when the client is created (e.g. when the namespace is initializ
not only when connecting.`
},

client_auth_gssapi_channel_binding: {
added: {
settings_client_auth_added: false
},
tags: [ 'client-auth' ],
seealso: [ 'client_auth', '[[link,auth_gssapi]]' ],
values: setting_types.BOOLEAN,
default: 'yes',
text: `
Whether the \`GSSAPI\` and \`GSS-SPNEGO\` client mechanisms send a TLS channel
binding. It is normally set inside the mechanism's [[setting,client_auth]]
filter, where the prefix is dropped:

\`\`\`[dovecot.conf]
imapc {
client_auth GSSAPI {
gssapi_channel_binding = no
}
}
\`\`\`

If enabled and the connection uses TLS, the [[rfc,5929]]
\`tls-server-end-point\` channel binding is passed to the Kerberos library. If
the binding can't be obtained, the authentication fails. This happens with
certificates whose signature algorithm has no single hash, such as Ed25519 and
Ed448. Active Directory with \`LdapEnforceChannelBinding=2\` requires the
binding, while servers that don't check channel bindings ignore it.

Without TLS no channel binding is sent. If disabled, no channel binding is sent
at all.`
},

client_auth_mechanism: {
added: {
settings_client_auth_added: false
Expand All @@ -210,6 +242,8 @@ Supported mechanisms are:
* CRAM-MD5
* DIGEST-MD5
* EXTERNAL
* GSS-SPNEGO
* GSSAPI
* LOGIN
* OAUTHBEARER
* PLAIN
Expand All @@ -219,8 +253,11 @@ Supported mechanisms are:
* SCRAM-SHA-256-PLUS
* XOAUTH2

Note that [[setting,client_auth_password]] is ignored for \`ANONYMOUS\` and
\`EXTERNAL\` mechanisms. For \`OAUTHBEARER\` and \`XOAUTH2\`
Note that [[setting,client_auth_password]] is ignored for \`ANONYMOUS\`,
\`EXTERNAL\`, \`GSSAPI\` and \`GSS-SPNEGO\` mechanisms. The last two use
Kerberos credentials instead, and are available only if Dovecot was built with
GSSAPI support. They are loaded from the \`libdovecot-gssapi\` module when
configured. See [[link,auth_gssapi]]. For \`OAUTHBEARER\` and \`XOAUTH2\`
[[setting,client_auth_password]] should be a bearer token.

Normally this setting is not set directly, but through the name of a
Expand Down
18 changes: 18 additions & 0 deletions docs/core/config/auth/mechanisms/gssapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,3 +107,21 @@ authentication mechanism and you should be able to log in.

If necessary, you can use [[setting,auth_username_format]] to normalize
usernames.

## Using GSSAPI as a Client

Dovecot can also authenticate as a GSSAPI or GSS-SPNEGO client, e.g. when
proxying. See [[link,client_auth]].

* The Kerberos credentials come from the process's default credential cache
(`KRB5CCNAME`) or from the client keytab (`KRB5_CLIENT_KTNAME` or
`default_client_keytab_name`, see
[MIT Kerberos](https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html)).
The environment variables must be passed to the process with
[[setting,import_environment]].
* Proxying with GSSAPI from a login process requires a non-chrooted login
service, because a chrooted process can't reach `krb5.conf`, the credential
cache or the GSSAPI module.
* As a client GSS-SPNEGO negotiates only Kerberos, never NTLM.
* Over TLS a channel binding is sent by default. See

@stephanbosch stephanbosch Oct 27, 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.

This sentence is a bit difficult to read. At least add a comma after TLS or make it a bit longer like: "When TLS is used, a channel binding is sent by default."

[[setting,client_auth_gssapi_channel_binding]].
Loading