1 files changed, 192 insertions, 0 deletions
diff --git a/doc/wiki/PasswordDatabase.oauth2.txt b/doc/wiki/PasswordDatabase.oauth2.txt
new file mode 100644
index 0000000..5928cf5
--- /dev/null
+++ b/doc/wiki/PasswordDatabase.oauth2.txt
@@ -0,0 +1,192 @@
+Open Authentication v2.0 database
+=================================
+
+Since v2.2.28. This database works with a oauth2 provider such as google or
+facebook. You are recommended to use xoauth2 or oauthbearer <authentication
+mechanisms> [Authentication.Mechanisms.txt] with this. The responses from
+endpoints must be JSON objects.
+
+Configuration
+-------------
+
+Common
+------
+
+In dovecot.conf put
+
+---%<-------------------------------------------------------------------------
+auth_mechanisms = $auth_mechanisms oauthbearer xoauth2
+
+passdb {
+  driver = oauth2
+  mechanisms = xoauth2 oauthbearer
+  args = /etc/dovecot/dovecot-oauth2.conf.ext
+}
+---%<-------------------------------------------------------------------------
+
+Backend
+-------
+
+Configuration file example for Google
+[https://developers.google.com/identity/protocols/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
+tls_ca_cert_file = /etc/ssl/certs/ca-certificates.crt
+---%<-------------------------------------------------------------------------
+
+Configuration file example for WSO2 Identity Server
+[http://wso2.com/identity-and-access-management]
+
+---%<-------------------------------------------------------------------------
+introspection_mode = post
+introspection_url =
+https://adminuser:adminpass@server.name:port/oauth2/introspect
+username_attribute = username
+tls_ca_cert_file = /etc/ssl/certs/ca-certificates.crt
+active_attribute = active
+active_value = true
+---%<-------------------------------------------------------------------------
+
+Proxy
+-----
+
+If you want to forward oauth2 authentication to your backend, you can use
+various ways
+
+Without proxy authentication
+
+---%<-------------------------------------------------------------------------
+passdb {
+  driver = static
+  args = nopasssword=y proxy=y proxy_mech=%m ...
+}
+---%<-------------------------------------------------------------------------
+
+or with proxy authentication, put into dovecot-oauth2.conf.ext
+
+---%<-------------------------------------------------------------------------
+pass_attrs = proxy=y proxy_mech=%m
+---%<-------------------------------------------------------------------------
+
+Proxy with password grant (since v2.3.6)
+----------------------------------------
+
+If you want to configure proxy to get token and pass it to backend
+
+passdb settings
+
+---%<-------------------------------------------------------------------------
+passdb {
+  driver = oauth2
+  mechanisms = oauthbearer xoauth2
+  args = /usr/local/etc/dovecot/dovecot-oauth2.token.conf.ext
+}
+
+passdb {
+  driver = oauth2
+  mechanisms = plain login
+  args = /usr/local/etc/dovecot/dovecot-oauth2.plain.conf.ext
+}
+---%<-------------------------------------------------------------------------
+
+put into dovecot-oauth2.token.conf.ext
+
+---%<-------------------------------------------------------------------------
+grant_url = http://localhost:8000/token
+client_id = verySecretClientId
+client_secret = verySecretSecret
+tokeninfo_url = http://localhost:8000/oauth2?oauth=
+introspection_url = http://localhost:8000/introspect
+introspection_mode = post
+use_grant_password = no
+debug = yes
+username_attribute = username
+pass_attrs = pass=%{oauth2:access_token}
+---%<-------------------------------------------------------------------------
+
+put into dovecot-oauth2.plain.conf.ext
+
+---%<-------------------------------------------------------------------------
+grant_url = http://localhost:8000/token
+client_id = verySecretClientId
+client_secret = verySecretSecret
+introspection_url = http://localhost:8000/introspect
+introspection_mode = post
+use_grant_password = yes
+debug = yes
+username_attribute = username
+pass_attrs = host=127.0.0.1 proxy=y proxy_mech=xoauth2
+pass=%{oauth2:access_token}
+---%<-------------------------------------------------------------------------
+
+Full config file
+----------------
+
+---%<-------------------------------------------------------------------------
+### OAuth2 password database configuration
+
+## url for verifying token validity. Token is appended to the URL
+# tokeninfo_url = http://endpoint/oauth/tokeninfo?access_token=
+
+## introspection endpoint, used to gather extra fields and other information.
+# introspection_url = http://endpoint/oauth/me
+
+## How introspection is made, valid values are
+##   auth = GET request with Bearer authentication
+##   get  = GET request with token appended to URL
+##   post = POST request with token=bearer_token as content
+# introspection_mode = auth
+
+## Force introspection even if tokeninfo contains wanted fields
+## Set this to yes if you are using active_attribute
+# force_introspection = no
+
+## wanted scope of validity (optional)
+# scope = something
+
+## username attribute in response (default: email)
+# username_attribute = email
+
+## username normalization format (default: %Lu)
+# username_format = %Lu
+
+## Attribute name for checking whether account is disabled (optional)
+# active_attribute =
+
+## Expected value in active_attribute (empty = require present, but anything
+goes)
+# active_value =
+
+## Extra fields to set in passdb response (in passdb static style)
+# pass_attrs =
+
+## Timeout in milliseconds
+# timeout_msecs = 0
+
+## Enable debug logging
+# debug = no
+
+## Max parallel connections (how many simultaneous connections to open)
+# max_parallel_connections = 1
+
+## Max pipelined requests (how many requests to send per connection, requires
+server-side support)
+# max_pipelined_requests = 1
+
+## HTTP request raw log directory
+# rawlog_dir = /tmp/oauth2
+
+## TLS settings
+# tls_ca_cert_file = /path/to/ca-certificates.txt
+# tls_ca_cert_dir = /path/to/certs/
+# tls_cert_file = /path/to/client/cert
+# tls_key_file = /path/to/client/key
+# tls_cipher_suite = HIGH:!SSLv2
+# tls_allow_invalid_cert = FALSE
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)