docs: enhance documentation with mailserver-admin configuration details

Author: jeboehm

.mkdocs.yaml

@@ -20,6 +20,7 @@ nav:
       - upgrade.md
   - Configuration:
       - configuration/environment-variables.md
+      - configuration/mailserver-admin.md
       - configuration/dns-configuration.md
       - configuration/external-mysql.md
       - configuration/relayhost.md
@@ -29,13 +30,15 @@ nav:
       - configuration/roundcube.md
       - configuration/tls.md
   - Administration:
+      - administration/login.md
       - administration/dashboard.md
       - administration/manage-domains.md
       - administration/manage-users.md
       - administration/manage-aliases.md
       - administration/manage-fetchmail.md
       - administration/dkim-signing.md
       - administration/dns-validation-wizard.md
+      - administration/user-roles.md
   - Recipes:
       - Docker:
           - Traefik Reverse Proxy: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/compose/traefik-reverse-proxy
@@ -44,4 +47,5 @@ nav:
   - Development:
       - development/architecture.md
       - development/development.md
+      - development/mailserver-admin.md
   - Issues: https://github.com/jeboehm/docker-mailserver/issues

README.md

@@ -1,13 +1,16 @@
 # docker-mailserver
 
-![Logo](/docs/logo/logo.png?raw=true)
+![Logo](/docs/logo/logo.png)
 
-`docker-mailserver` is inspired by the renowned [ISPMail guide](https://workaround.org/ispmail/).
+`docker-mailserver` is inspired by the renowned [ISPMail guide](https://workaround.org/).
 This project lets you run your own email services, giving you independence from large providers. It is a secure, customizable, and feature-rich solution for managing your email infrastructure.
 
 Container images are built on [Alpine Linux](https://alpinelinux.org) or vendor base images and are kept lightweight.
 
-[![Build & Tests](https://github.com/jeboehm/docker-mailserver/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/jeboehm/docker-mailserver/actions/workflows/build.yml)
+[![Build & Tests](https://github.com/jeboehm/docker-mailserver/actions/workflows/build.yml/badge.svg)](https://github.com/jeboehm/docker-mailserver/actions/workflows/build.yml)
+[![Validate Manifests](https://github.com/jeboehm/docker-mailserver/actions/workflows/test-yaml-schema.yml/badge.svg)](https://github.com/jeboehm/docker-mailserver/actions/workflows/test-yaml-schema.yml)
+[![Release](https://github.com/jeboehm/docker-mailserver/actions/workflows/release.yml/badge.svg)](https://github.com/jeboehm/docker-mailserver/actions/workflows/release.yml)
+[![Documentation](https://github.com/jeboehm/docker-mailserver/actions/workflows/docs.yml/badge.svg)](https://github.com/jeboehm/docker-mailserver/actions/workflows/docs.yml)
 
 ## 📚 Documentation
 
@@ -57,6 +60,10 @@ For detailed installation instructions, see the [Installation Guide](https://jeb
 
 ![DKIM setup](docs/images/admin/dkim_edit.png)
 
+### DNS Validation Wizard
+
+![DNS Validation Wizard](docs/images/admin/dns_validation_wizard.png)
+
 ## Links
 
 - [Documentation](https://jeboehm.github.io/docker-mailserver/) - Complete documentation and guides

docs/administration/login.md

@@ -0,0 +1,17 @@
+# Login
+
+The login page provides authentication to access the `mailserver-admin` interface. Users can authenticate using either regular email address and password credentials and OAuth2, depending on the configuration.
+
+![Login](../images/admin/login.png)
+
+## Authentication Methods
+
+### Local Authentication
+
+By default, users authenticate using their email address and password configured in the mailserver.
+
+### OAuth2 Authentication
+
+OAuth2 authentication can be enabled to allow users to log in using an external identity provider. When OAuth2 is enabled, a login button appears on the login page. Currently, this is only useful for granting admin rights to users.
+
+For OAuth2 configuration options, see [mailserver-admin configuration](../configuration/mailserver-admin.md#oauth2).

docs/administration/manage-users.md

@@ -11,6 +11,7 @@ Users are email accounts associated with a specific domain. Each user has a uniq
 - **Admin**: Can manage users across all domains
 - **Domain Admin**: Can manage users within their assigned domain only
 - **User**: Cannot manage other users, only their own account settings
+  See [User Roles](user-roles.md) for more information.
 
 ## User Operations
 
@@ -87,10 +88,12 @@ When a user is set to send only, they can only send emails. They cannot receive
 ### Admin
 
 When a user is set to admin, they can manage other users and domains.
+See [User Roles](user-roles.md) for more information.
 
 ### Domain Admin
 
 When a user is set to domain admin, they can manage users and aliases within their assigned domain.
+See [User Roles](user-roles.md) for more information.
 
 ## User Access
 

docs/administration/user-roles.md

@@ -0,0 +1,28 @@
+# User Roles
+
+In `mailserver-admin`, there are three distinct user roles, each with different levels of access and permissions:
+
+1. **Admin**
+    - **Permissions**: Can perform all actions within the application.
+    - **Capabilities**:
+        - Manage all mail domains, users, aliases, and DKIM settings.
+        - Full access to all features and configurations.
+
+2. **Domain Admin**
+    - **Permissions**: Limited to managing users, aliases, and fetchmail accounts within their own domain.
+    - **Capabilities**:
+        - Create, update, and remove users within their domain.
+        - Define and manage mail aliases within their domain.
+        - Configure and manage fetchmail accounts within their domain.
+    - **Restrictions**:
+        - Cannot add or edit new domains.
+        - Cannot manage DKIM settings for any domain.
+
+3. **User**
+    - **Permissions**: Limited to managing their own fetchmail accounts.
+    - **Capabilities**:
+        - Login to the application.
+        - Configure and manage their personal fetchmail accounts.
+    - **Restrictions**:
+        - Cannot manage users, aliases, or domains.
+        - No access to DKIM settings or domain configurations.

docs/configuration/environment-variables.md

@@ -85,7 +85,7 @@ when you use Kubernetes or decide to rename services somehow.
 
 ### mailserver-admin Configuration
 
-See [mailserver-admin](https://github.com/jeboehm/mailserver-admin?tab=readme-ov-file#environment-variables) for more information.
+See [mailserver-admin](mailserver-admin.md) for more information.
 
 ### PHP Configuration
 

docs/configuration/mailserver-admin.md

@@ -0,0 +1,59 @@
+# mailserver-admin configuration
+
+## OAuth2
+
+To use OAuth2, you need to create a new OAuth2 client in your OAuth2 provider. The redirect URI should be
+`https://example.com/login/check-oauth`. The client ID and client secret should be added to the `.env` file.
+
+Depending on your needs, you can configure `mailserver-admin` to give admin rights to a user by testing for a specific group in the groups
+field of the OAuth user information. Set the name of your administrator group to the `OAUTH_ADMIN_GROUP` variable in the `.env` file. If you
+leave `OAUTH_ADMIN_GROUP` empty, all authenticated users will have admin rights. You must make sure to handle the login permissions in your
+OAuth2 provider.
+
+### OAuth2 configuration example
+
+```bash
+OAUTH_ENABLED=true
+OAUTH_CLIENT_ID=xxxxx-xxxx-xxxx-xxxx-xxxxxxx
+OAUTH_CLIENT_SECRET=xxxxxxxxxxxxx
+OAUTH_CLIENT_SCOPES="email profile groups"
+OAUTH_AUTHORIZATION_URL=https://id.example.com/authorize
+OAUTH_ACCESS_TOKEN_URL=https://id.example.com/api/oidc/token
+OAUTH_INFOS_URL=https://id.example.com/api/oidc/userinfo
+OAUTH_BUTTON_TEXT="Login with OIDC"
+OAUTH_ADMIN_GROUP=admin
+OAUTH_PATHS_IDENTIFIER=sub
+```
+
+## Environment variables
+
+The following environment variables can be set in the `.env` file or in the environment:
+
+### General
+
+- `APP_ENV`: The environment the application is running in. Default: `prod`
+- `APP_SECRET`: A secret key used by Symfony for various purposes (e.g., CSRF tokens). Default: `randomly generated`.
+- `CSRF_ENABLED`: Whether CSRF protection is enabled. Default: `true`.
+- `TRUSTED_PROXIES`: A list of trusted proxy IP addresses.
+
+### Database
+
+- `MYSQL_USER`: The MySQL database user.
+- `MYSQL_PASSWORD`: The MySQL database password.
+- `MYSQL_HOST`: The MySQL database host.
+- `MYSQL_DATABASE`: The MySQL database name.
+- `REDIS_HOST`: The Redis server host.
+- `REDIS_PORT`: The Redis server port.
+- `REDIS_PASSWORD`: The Redis server password.
+
+### OAuth2
+
+- `OAUTH_ENABLED`: Whether OAuth2 is enabled. Default: `false`.
+- `OAUTH_CLIENT_ID`: The client ID for the OAuth2 provider.
+- `OAUTH_CLIENT_SECRET`: The client secret for the OAuth2 provider.
+- `OAUTH_CLIENT_SCOPES`: The scopes requested from the OAuth2 provider. Default: `"email profile groups"`.
+- `OAUTH_AUTHORIZATION_URL`: The authorization URL for the OAuth2 provider.
+- `OAUTH_ACCESS_TOKEN_URL`: The access token URL for the OAuth2 provider.
+- `OAUTH_INFOS_URL`: The user information URL for the OAuth2 provider.
+- `OAUTH_ADMIN_GROUP`: The name of the administrator group in the OAuth2 provider.
+- `OAUTH_BUTTON_TEXT`: The text displayed on the OAuth2 login button. Default: `"Login with OIDC"`.