Client Authentication

Added: 2.4.6

Dovecot doesn't only authenticate its own users. In several places it is itself a client that logs into another server:

Client	Settings filter	Notes
imapc mailbox format	imapc	Also used for migrations and shared mailboxes between backends.
pop3c mailbox format	pop3c
passdb imap	imapc inside the passdb	The password given by the user is used as client_auth_password automatically.

All of them use the same client_auth_* settings and the same SASL client implementation, which this page describes. The settings are placed inside the client's filter, because the same setting names are shared by all the clients:

imapc {
  host = imap.example.com
  ssl = imaps
  client_auth_authzid = %{user}
  client_auth_password = secret
}

This is not to be confused with the Authentication of Dovecot's own users, nor with proxy passdb, where the passdb lookup tells the login process where and how to log in.

Identities and Password

SASL authentication has two identities:

• client_auth_authid is the authentication identity: the user whose client_auth_password is used to prove who the client is.
• client_auth_authzid is the authorization identity: the user whose mails are accessed after the authentication.

For a regular login they are the same, so only client_auth_authzid needs to be set. An empty client_auth_authid means that the authorization identity is used for authenticating as well. The two differ when logging in as a master user: the master user and its password are the authentication identity and the actual user is the authorization identity.

imapc {
  client_auth_authid = masteruser
  client_auth_password = masteruser-secret
  client_auth_authzid = %{user}
}

Inside the imapc and pop3c filters client_auth_authzid defaults to %{owner_user}: the logged in user, or the owner of a shared namespace.

The existence of the password is checked already when the client is created, so a missing client_auth_password for a mechanism that needs one fails e.g. the namespace initialization for imapc, not only the first connection. The ANONYMOUS and EXTERNAL mechanisms don't use a password. For OAUTHBEARER and XOAUTH2 the password is the bearer token.

Mechanism Selection

The mechanism is chosen in one of three ways:

Configured Mechanism List

Each client_auth filter block declares a mechanism that the client is allowed to use. The first configured mechanism that the server also advertises is used, so the preferred mechanisms should be listed first. Settings inside a block apply to that mechanism only, which allows e.g. a different token for OAUTHBEARER than the password for PLAIN:

imapc {
  host = imap.example.com
  ssl = imaps
  client_auth_authzid = %{user}

  client_auth SCRAM-SHA-256 {
    password = secret
  }
  client_auth OAUTHBEARER {
    password = vF9dft4qmTc2Nvb3RlckBhbHRhdmlzdGEuY29tCg==
  }
  client_auth PLAIN {
    password = secret
  }
}

If the server advertises none of the configured mechanisms, the login fails with an error listing both the configured and the advertised mechanisms. There is no fallback to the next mechanism if the authentication itself fails, e.g. because of a wrong password.

Explicit Mechanism

If client_auth_mechanism is set directly inside the client's filter, without any client_auth blocks, that mechanism is used without checking whether the server advertises it. This is mainly useful when the server doesn't advertise its mechanisms correctly.

pop3c {
  host = pop3.example.com
  client_auth_mechanism = PLAIN
  client_auth_authzid = %{user}
  client_auth_password = secret
}

No Configured Mechanism

If neither is configured, the PLAIN mechanism is used if the server advertises it, or if the server's mechanisms aren't known. For IMAP and POP3 the basic LOGIN command and USER + PASS commands are used instead whenever the server allows them, so SASL support isn't required from the server at all. If the server doesn't advertise PLAIN, the first advertised mechanism that Dovecot supports and that works with a password is used.

If no mechanism and no identities are configured, there is nothing to authenticate with. The connection fails with an "Authentication not configured" error.

Supported Mechanisms

See client_auth_mechanism for the list. GSSAPI and GSS-SPNEGO are currently available only for doveadm auth test and doveadm auth login, not for the clients listed above.

Channel Binding

The SCRAM-SHA-1-PLUS and SCRAM-SHA-256-PLUS mechanisms bind the authentication to the TLS connection, so that the credentials can't be relayed through a man-in-the-middle. They require a TLS connection: tls-unique channel binding is used with TLS 1.2 and tls-exporter with TLS 1.3.

When the non-PLUS SCRAM-SHA-1 or SCRAM-SHA-256 mechanism is used over a TLS connection, channel binding is used anyway if the server also advertises the corresponding -PLUS mechanism, as required by RFC 5802.

If the server doesn't advertise the -PLUS mechanism, the authentication is done without channel binding, but Dovecot tells the server that it would have supported channel binding. If the server actually does support it, the -PLUS mechanism must have been removed from the advertised list by an attacker, and the server fails the authentication.

The client_auth filter names are matched against the server's advertised mechanisms as-is. For example a server advertising only SCRAM-SHA-256-PLUS doesn't match a client_auth SCRAM-SHA-256 { } filter, so client_auth SCRAM-SHA-256-PLUS { } must be configured instead.

Overrides

The filter-scoped settings are written with a / in overrides:

doveadm -o imapc_host=imap.example.com \
  -o imapc/client_auth_authzid=user@example.com \
  -o imapc/client_auth_password=secret \
  -o mail_driver=imapc -o mail_path= mailbox list -u user@example.com

passdb static {
  fields {
    userdb_imapc/client_auth_authzid = %{user}
    userdb_imapc/client_auth_password = %{password}
  }
}

Debugging

The client logs the mechanism selection and the identities it uses as debug messages under the sasl-client event category, which is a child of the client's own category:

log_debug = category=sasl-client

For imapc, doveadm mailbox list with the imapc settings given as -o overrides (see Overrides) is a quick way to test the login without changing the running configuration.

Settings

client_auth

Default	[None]
Value	Named List Filter
See Also	client authentication client_auth_mechanism client_auth_authzid client_auth_authid client_auth_password
Changes	Added: 2.4.6

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 client_auth_mechanism setting. The first configured mechanism that the server also advertises is used, so the preferred mechanisms should be configured first. There is no fallback to the next mechanism if the authentication itself fails.

Client authentication settings are expected to be scoped further by settings filters for the various protocol clients that need authentication, such as imapc and pop3c. See client authentication for an overview.

Example:

mail_driver = imapc
mail_path =
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==
  }
}

client_auth_authid

Default	[None]
Value	string
See Also	client_auth_authzid client_auth_password client_auth_mechanism client authentication
Changes	Added: 2.4.6

The authentication identity to be used for authenticating as a client to a remote service. This is the identity whose client_auth_password is used. If it is empty, client_auth_authzid is used as the authentication identity as well.

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
}

Mail user variables can be used.

client_auth_authzid

Default	Inside the imapc and pop3c filters the default is %{owner_user}: the logged in user, or the owner of a shared namespace.
Value	string
See Also	client_auth_authid client_auth_password client_auth_mechanism client authentication
Changes	Added: 2.4.6 Changed: 2.4.6 For pop3c the default used to be %{user} (the old pop3c_user default). It is now %{owner_user}, the same as for imapc. This makes a difference only for shared namespaces.

The authorization identity to be used after authenticating as a client to a remote service, i.e. the user whose mails are accessed. If client_auth_authid is empty, this identity is also used for authenticating.

Mail user variables can be used.

client_auth_mechanism

Default	[None]
Value	string
See Also	client_auth client_auth_authzid client_auth_authid client_auth_password client authentication
Changes	Added: 2.4.6

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.

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 client_auth_password is ignored for ANONYMOUS and EXTERNAL mechanisms. For OAUTHBEARER and XOAUTH2 client_auth_password should be a bearer token.

Normally this setting is not set directly, but through the name of a client_auth filter. The mechanism is then used only if the server also advertises it:

imapc {
  host = 127.0.0.1
  port = 993
  ssl = imaps

  # Authentication fails if the server doesn't announce SCRAM-SHA-256 support
  client_auth SCRAM-SHA-256 {
    authzid = owner-user
    password = frop
  }
}

When a non-PLUS SCRAM mechanism is configured and the server advertises the corresponding -PLUS variant, the client automatically uses channel binding if the connection is TLS encrypted and channel binding is available. See client authentication: channel binding.

If no mechanism is configured, the PLAIN mechanism is used by default. For IMAP and POP3 the basic login commands are used instead in that case, if possible (LOGIN for IMAP and USER + PASS for POP3), so SASL support is not required from the server. If the server doesn't advertise PLAIN, the first mechanism advertised by the server that Dovecot supports and that uses a password is used. However, if the authentication client_auth_authid and authorization client_auth_authzid identities are both also unconfigured, no authentication is configured at all and the connection fails with an "Authentication not configured" error.

Example:

imapc {
  host = 127.0.0.1
  port = 993
  ssl = imaps

  # Will authenticate using IMAP LOGIN command, or use PLAIN mechanism if LOGIN
  # command is disabled.
  client_auth_authzid = owner-user
  client_auth_password = frop
}

If client_auth_mechanism is set directly, without any client_auth filter block in that context (e.g. inside a surrounding imapc or pop3c filter block), the indicated mechanism is used blindly; server support is not checked.

Example:

imapc {
  host = 127.0.0.1
  port = 993
  ssl = imaps

  # PLAIN mechanism will be used without consulting server capabilities
  client_auth_mechanism = PLAIN
  client_auth_authid = master-user
  client_auth_authzid = owner-user
  client_auth_password = frop
}

client_auth_password

Default	[None]
Value	string
See Also	client_auth_authzid client_auth_authid client_auth_mechanism client authentication
Changes	Added: 2.4.6

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. For the OAUTHBEARER and XOAUTH2 mechanisms this is the bearer token. The ANONYMOUS and EXTERNAL mechanisms don't use it.

The password is required for all the other mechanisms. Its existence is checked already when the client is created (e.g. when the namespace is initialized for imapc), not only when connecting.

imapc

Value	Named Filter
See Also	imapc client_auth client_auth_authzid client_auth_authid client_auth_password client_auth_mechanism client authentication

This settings filter provides a scope for settings for imapc.

The filter is needed for configuring the generic client_auth and ssl_client_* settings for imapc specifically, since the same settings are used also by other clients.

Example:

imapc {
  host = imap.example.com
  ssl = imaps
  client_auth_authzid = %{user}
  client_auth_password = secret
}

pop3c

Value	Named Filter
See Also	pop3c client_auth client_auth_authzid client_auth_authid client_auth_password client_auth_mechanism client authentication

This settings filter provides a scope for settings for pop3c.

The filter is needed for configuring the generic client_auth and ssl_client_* settings for pop3c specifically, since the same settings are used also by other clients.

Example:

pop3c {
  host = pop3.example.com
  ssl = pop3s
  port = 995
  client_auth_authzid = %{user}
  client_auth_password = secret
}