Open Authentication v2.0 Database (`oauth2`)

This database works with a OAuth2 (RFC 6749)provider.

You are recommended to use oauthbearer (preferred) or xoauth2authentication mechanisms with this database.

The responses from endpoints must be JSON objects.

Changed: 2.4.0: The OAuth2 mechanism no longer uses a passdb for token authentication. Password Grant still needs a oauth2 passdb.

Settings

Oauth2 overrides some of the default HTTP client and SSL settings. You can override these and any other HTTP client or SSL settings by placing them inside the oauth2 named filter.

`oauth2`

Default	[None]
Value	Named Filter
See Also	OAuth2 Authentication Database

Filter for oauth2 specific settings.

`oauth2_active_attribute`

Default	[None]
Value	string

Attribute name for (optional) checking whether account is disabled.

`oauth2_active_value`

Default	[None]
Value	string

Expected value in active_attribute. (empty = require present, but anything goes)

`oauth2_fields`

Default	[None]
Value	String List

Key-value fields to include in successful authentication.

`oauth2_force_introspection`

Default	`no`
Value	boolean

Force introspection even if tokeninfo contains wanted fields. Set this to yes if you are using oauth2_active_attribute.

`oauth2_introspection_mode`

Default	[None]
Value	string
Allowed Values	`<empty>authgetpostlocal`
See Also	`oauth2_introspection_url` `oauth2_tokeninfo_url` `oauth2_force_introspection`

To enable oauth2 you must choose how to do token introspection. oauth2_introspection_url is not required if oauth2_tokeninfo_url already provides all the necessary fields, or if you are using local validation.

You can force introspection with oauth2_force_introspection, if you need to it every time.

With local validation, oauth2_tokeninfo_url is also ignored.

Value	Description
`auth`	GET request with Bearer authentication.
`get`	GET request with token appended to URL.
`post`	POST request with token=bearer_token as content.
`local`	Attempt to locally validate and decode JWT token.

`oauth2_introspection_url`

Default	[None]
Value	string

URL for getting more information about token.

`oauth2_issuers`

Default	[None]
Value	Boolean List

Valid issuer(s) for the token.

`oauth2_local_validation`

Default	[None]
Value	Named Filter
See Also	`dict`

A dictionary for fetching validation keys.

Example:

local_validation {
  dict fs {
    fs posix {
      prefix = /tmp/keys/
    }
  }
}

`oauth2_openid_configuration_url`

Default	[None]
Value	string

URL to RFC 7628 OpenID Provider Configuration Information schema.

`oauth2_scope`

Default	[None]
Value	Boolean List

A list of valid scopes.

`oauth2_send_auth_headers`

Default	`no`
Value	boolean

Whether to send special headers about authentication to remote server. If you enable this, the following headers will be sent:

X-Dovecot-Auth-Protocol: Requested protocol, such as imap or pop3.
X-Dovecot-Auth-Local: Local IP address where client connected to.
X-Dovecot-Auth-Remote: Remote IP address of the client connection.

`oauth2_tokeninfo_url`

Default	[None]
Value	string

URL for verifying token validity. Token is appended to the URL.

Example:

oauth2_tokeninfo_url = http://endpoint/oauth/tokeninfo?access_token=

`oauth2_use_worker_with_mech`

Default	`no`
Value	boolean
See Also	`passdb_use_worker`

Use worker process to verify token. This setting only applies to mechanism. If you want to use worker with passdb oauth2, use passdb_use_worker instead. Worker processes are mostly useful for distributing local token validation to multiple CPUs.

`oauth2_username_attribute`

Default	`email`
Value	string

Username attribute in response.

`oauth2_username_validation_format`

Default	`%{user}`
Value	string
See Also	`oauth2_username_attribute`

Normalization for oauth2 provided username, this setting is normally not needed. You only need this if the username that comes from authentication will not otherwise match with oauth2_username_attribute value.

Configuration

Common

dovecot.conf

auth_mechanisms = {
  oauthbearer = yes
  xoauth2 = yes
}

oauth2 {
  # ...
}

Backend

Examples

Google

Configuration file example for Google:

oauth2 {
  tokeninfo_url = https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=
  introspection_url = https://www.googleapis.com/oauth2/v2/userinfo
  #force_introspection = yes
  username_attribute = email
}

WSO2 Identity Server

Configuration file example for WSO2 Identity Server:

oauth2 {
  introspection_mode = post
  introspection_url = https://client_id:client_secret@server.name:port/oauth2/introspect
  username_attribute = username
  active_attribute = active
  active_value = true
}

Microsoft Identity Platform

Configuration file example for Microsoft Identity Platform:

oauth2 {
  introspection_mode = auth
  introspection_url = https://graph.microsoft.com/v1.0/me
  # this can vary on your settings
  username_attribute = mail
  ssl_client_ca_file = /etc/ssl/certs/ca-certificates.crt
}

Proxy

If you want to forward oauth2 authentication to your backend, you can use various ways.

Without proxy authentication:

passdb static {
  fields {
    nopassword = yes
    proxy = yes
    proxy_mech = %{mechanism}
        # ...
  }
}

With proxy authentication, put into dovecot.conf:

oauth2 {
  # ...
  fields {
    proxy = y
    proxy_mech = %{mech}
  }
}

Proxy with Password Grant

If you want to configure proxy to get token and pass it to backend:

dovecot.conf

oauth2 {
  client_id = verySecretClientId
  client_secret = verySecretSecret
  tokeninfo_url = http://localhost:8000/oauth2?oauth=
  introspection_url = http://localhost:8000/introspect
  introspection_mode = post
  username_attribute = username
  fields {
    pass = %{oauth2:access_token}
  }
}

passdb oauth2 {
  mechanisms_filter = plain login
  oauth2 {
    # inherit common oauth2 settings from the global scope
    grant_url = http://localhost:8000/token
    fields {
      host = 127.0.0.1
      proxy = y
      proxy_mech = xoauth2
      pass = %{passdb:token}
    }
  }
}

Local Validation

Local validation allows validating tokens without connecting to an oauth2 server.

This requires that key issuer supports JWT tokens (RFC 7519).

You can put the validation keys into any dictionary.

The lookup key used is /shared/<azp:default>/<alg>/<keyid:default>.

If there is no azp element in token body, then default is used.

The alg field is always uppercased by Dovecot.

If there is no kid element in token header, default is used.

Keys are cached into memory when they are fetched; to evict them from cache you need to restart Dovecot.

If you want to do key rotation, it is recommended to use a new key id.

Example:

json

{
   "kid":"Zm9vb2Jhcgo",
   "alg":"ES256",
   "typ":"JWT"
}.{
    "sub":"testuser@example.org",
    "azp":"issuer.net-dovecot"
}

Would turn into: /shared/issuer.net-dovecot/ES256/Zm9vb2Jhcgo.

If using fs posix, key would be at /etc/dovecot/keys/issuer.net-dovecot/ES256/Zm9vb2Jhcgo.

In key id and AZP field, / are escaped with %2f and % are escaped with %25 with any driver. This is because / is a dict key component delimiter.

When using dict-fs driver, if the path starts with ., it will be escaped using two more dots. So any . turns into ..., and any .. turns into .....

For example:

json

{
    "kid":""./../../../../etc,
    "alg":"ES256",
    "typ":"JWT"
}.{
    "sub":"testuser@example.org",
    "azp":"attack"
}

Would turn into: /etc/dovecot/keys/attack/ES256/...%2f....%2f....%2f....%2f....%2fetc%2fpasswd.

Local validation can be enabled with other oauth2 options, so that if key validation fails for non-JWT keys, then online validation is performed.

You can use local validation with password grants too. This will save you introspection roundtrip to oauth2 server.

To use local validation, put into dovecot.conf:

oauth2 {
  introspection_mode = local
  local_validation {
    dict fs {
      fs posix {
        prefix=/etc/dovecot/keys/
      }
    }
  }
}

Currently, Dovecot oauth2 library implements the following features of JWT tokens:

IAT checking
NBF checking
EXP checking
ISS checking
ALG checking
SUB support
AUD support
AUD check checks client_id, not scope. If the token has scope field, this is checked for scope. KTY checking has been removed.
AZP support

The following algorithms are supported

HS256, HS384, HS512
RS256, RS384, RS512
PS256, PS384, PS512
ES256, ES384, ES512

There is currently no support for EdDSA algorithms.

ES supports any curve supported by OpenSSL for this purpose.

OpenID Discovery

Support for RFC 7628 OpenID Discovery (OIDC) can be achieved with openid_configuration_url. Setting this causes Dovecot to report OIDC configuration URL as openid-configuration element in error JSON.

Databases

Mechanisms

Formats

Extensions

Open Authentication v2.0 Database (oauth2) ​

Settings ​

oauth2

oauth2_active_attribute

oauth2_active_value

oauth2_fields

oauth2_force_introspection

oauth2_introspection_mode

oauth2_introspection_url

oauth2_issuers

oauth2_local_validation

oauth2_openid_configuration_url

oauth2_scope

oauth2_send_auth_headers

oauth2_tokeninfo_url

oauth2_use_worker_with_mech

oauth2_username_attribute

oauth2_username_validation_format

Configuration ​

Common ​

Backend ​

Examples ​

Google ​

WSO2 Identity Server ​

Microsoft Identity Platform ​

Proxy ​

Proxy with Password Grant ​

Local Validation ​

OpenID Discovery ​

Open Authentication v2.0 Database (`oauth2`)

Settings

`oauth2`

`oauth2_active_attribute`

`oauth2_active_value`

`oauth2_fields`

`oauth2_force_introspection`

`oauth2_introspection_mode`

`oauth2_introspection_url`

`oauth2_issuers`

`oauth2_local_validation`

`oauth2_openid_configuration_url`

`oauth2_scope`

`oauth2_send_auth_headers`

`oauth2_tokeninfo_url`

`oauth2_use_worker_with_mech`

`oauth2_username_attribute`

`oauth2_username_validation_format`

Configuration

Common

Backend

Examples

Google

WSO2 Identity Server

Microsoft Identity Platform

Proxy

Proxy with Password Grant

Local Validation

OpenID Discovery