From 4a6cfca180e67194b8cd6e9b8e33535d997d63e8 Mon Sep 17 00:00:00 2001
From: Keval Kapdee <keval@kapdee.uk>
Date: Sat, 4 Nov 2023 12:37:09 +0000
Subject: [PATCH] Initial documentation

---
 README.md                                   |  1 +
 docs/content/config/advanced/auth-oauth2.md | 60 +++++++++++++++++++++
 docs/mkdocs.yml                             |  1 +
 3 files changed, 62 insertions(+)
 create mode 100644 docs/content/config/advanced/auth-oauth2.md

diff --git a/README.md b/README.md
index b3072cd9..ab83964d 100644
--- a/README.md
+++ b/README.md
@@ -48,3 +48,4 @@ If you have issues, please search through [the documentation][documentation::web
 - Support for [LetsEncrypt](https://letsencrypt.org/), manual and self-signed certificates
 - A [setup script](https://docker-mailserver.github.io/docker-mailserver/latest/config/setup.sh) for easy configuration and maintenance
 - SASLauthd with LDAP authentication
+- Basic OAuth2 authentication
diff --git a/docs/content/config/advanced/auth-oauth2.md b/docs/content/config/advanced/auth-oauth2.md
new file mode 100644
index 00000000..8123d307
--- /dev/null
+++ b/docs/content/config/advanced/auth-oauth2.md
@@ -0,0 +1,60 @@
+---
+title: 'Advanced | Basic OAuth2 Authentication'
+---
+
+## Introduction
+
+**Warning** - This is only a supplement to the existing account provisioners; FILE and LDAP. Accounts must still be created using the `setup` command or added to the LDAP directory respectively. Reasoning for this can be found in #3579. Future iterations on this feature may allow it to be a full account provisioner.
+
+For now, this adds the ability for a 3rd party application such as Roundcube to authenticate with DMS (dovecot) using a token obtained from an OAuth2 provider instead of passing passwords around.
+
+## Example (Authentik & Roundcube)
+
+???+ example "Authentik"
+    1. Create a new OAuth2 provider
+    2. Note the client id and client secret
+    3. Set the allowed redirect url to `https://roundcube.domain.com/index.php/login/oauth` (obviously changing your domain as needed)
+
+???+ example "Docker Mailserver `mailserver.env`"
+    ```env
+    # -----------------------------------------------
+    # --- OAUTH2 Section ----------------------------
+    # -----------------------------------------------
+
+    # empty => OAUTH2 authentication is disabled
+    # 1 => OAUTH2 authentication is enabled
+    ENABLE_OAUTH2=1
+
+    # empty => verySecretId
+    # Specify the OAuth2 client ID
+    OAUTH2_CLIENT_ID=<insert client id here>
+
+    # empty => verySecretSecret
+    # Specify the OAuth2 client secret
+    OAUTH2_CLIENT_SECRET=<insert client secret here>
+
+    # empty => https://oauth2.domain.com/userinfo/
+    # Specify the user info endpoint URL of the oauth2 provider
+    OAUTH2_INTROSPECTION_URL=https://authentik.domain.com/application/o/userinfo/
+    ```
+
+???+ example "Roundcube `oauth2.inc.php` ([documentation](https://github.com/roundcube/roundcubemail/wiki/Configuration))"
+    ```php
+    $config['oauth_provider'] = 'generic';
+    $config['oauth_provider_name'] = 'Authentik';
+    $config['oauth_client_id'] = '<insert client id here>';
+    $config['oauth_client_secret'] = '<insert client secret here>';
+    $config['oauth_auth_uri'] = 'https://authentik.domain.com/application/o/authorize/';
+    $config['oauth_token_uri'] = 'https://authentik.domain.com/application/o/token/';
+    $config['oauth_identity_uri'] = 'https://authentik.domain.com/application/o/userinfo/';
+
+    // Optional: disable SSL certificate check on HTTP requests to OAuth server
+    // See http://docs.guzzlephp.org/en/stable/request-options.html#verify for possible values
+    $config['oauth_verify_peer'] = false;
+
+    $config['oauth_scope'] = 'email openid profile';
+    $config['oauth_identity_fields'] = ['email'];
+
+    // Boolean: automatically redirect to OAuth login when opening Roundcube without a valid session
+    $config['oauth_login_redirect'] = false;
+    ```
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index bd41a798..0855dd08 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -142,6 +142,7 @@ nav:
           - 'Postfix': config/advanced/override-defaults/postfix.md
           - 'Modifications via Script': config/advanced/override-defaults/user-patches.md
         - 'LDAP Authentication': config/advanced/auth-ldap.md
+        - 'OAuth2 Authentication': config/advanced/auth-oauth2.md
         - 'Email Filtering with Sieve': config/advanced/mail-sieve.md
         - 'Email Gathering with Fetchmail': config/advanced/mail-fetchmail.md
         - 'Email Gathering with Getmail': config/advanced/mail-getmail.md