418 lines
14 KiB
Markdown
418 lines
14 KiB
Markdown
# DigitalData.MessagingService
|
||
|
||
A .NET 8 messaging service for sending and receiving emails via SMTP, IMAP, POP3 and OAuth2, with RabbitMQ-based async delivery.
|
||
|
||
---
|
||
|
||
## Deployment als Windows-Dienst (empfohlen)
|
||
|
||
Der Betrieb als **Windows-Dienst** ist dem IIS-Hosting ausdrücklich vorzuziehen, da:
|
||
|
||
- Der RabbitMQ-Consumer dauerhaft läuft – unabhängig von eingehenden HTTP-Anfragen
|
||
- Kein IIS-Idle-Timeout, der den App-Pool beendet
|
||
- Automatischer Neustart bei Absturz (konfigurierbar)
|
||
- Verwaltung über die Windows-Dienstverwaltung (`services.msc`) oder PowerShell
|
||
|
||
---
|
||
|
||
### Voraussetzungen
|
||
|
||
- Windows Server (2016 oder neuer)
|
||
- .NET 8 Runtime **nicht erforderlich** – das Paket ist self-contained
|
||
- Administratorrechte auf dem Zielserver
|
||
- Port **1415** muss in der Firewall freigegeben sein
|
||
|
||
---
|
||
|
||
### Schritt 1: Publish
|
||
|
||
Auf dem Entwicklungsrechner im Repository-Verzeichnis:
|
||
|
||
```powershell
|
||
.\publish-windows-service.ps1
|
||
```
|
||
|
||
Die Ausgabe liegt anschließend unter:
|
||
```
|
||
M:\App&Service\0 DD - Funktionsmodule\MessagingService\PreRelease\WindowsService\net8\
|
||
```
|
||
|
||
---
|
||
|
||
### Schritt 2: Dateien auf den Server kopieren
|
||
|
||
Den gesamten Publish-Ordner auf den Server kopieren, z. B. nach:
|
||
```
|
||
D:\ProgramFiles\Digital Data\SERVICES\DigitalData.MessagingService\
|
||
```
|
||
|
||
> **Wichtig:** Die Datei `appsettings.Secrets.json` wird **nicht** mit dem Publish-Paket ausgeliefert (sie ist nicht im Git-Repository). Diese Datei muss separat auf den Server kopiert werden. Sie enthält RabbitMQ-Zugangsdaten, E-Mail-Konten und weitere sensible Einstellungen.
|
||
|
||
---
|
||
|
||
### Schritt 3: Dienst installieren
|
||
|
||
Die Datei `install-windows-service.bat` liegt im Publish-Verzeichnis. Als Administrator ausführen:
|
||
|
||
```
|
||
install-windows-service.bat
|
||
```
|
||
|
||
Das Skript führt folgende Schritte automatisch aus:
|
||
1. Vorhandenen Dienst stoppen und löschen (falls vorhanden)
|
||
2. Neuen Windows-Dienst erstellen
|
||
3. Automatischen Neustart bei Absturz konfigurieren
|
||
4. Firewall-Regel für Port 1415 hinzufügen
|
||
5. Dienst starten
|
||
|
||
---
|
||
|
||
### Schritt 4: Überprüfung
|
||
|
||
Nach der Installation die API im Browser aufrufen:
|
||
```
|
||
http://SERVER-IP:1415/swagger
|
||
http://SERVER-IP:1415/health
|
||
http://SERVER-IP:1415/serilog-ui
|
||
```
|
||
|
||
Dienststatus prüfen:
|
||
```powershell
|
||
sc.exe query "DD-MessagingService"
|
||
# oder
|
||
Get-Service "DD-MessagingService"
|
||
```
|
||
|
||
---
|
||
|
||
### Update (neue Version einspielen)
|
||
|
||
```powershell
|
||
# 1. Dienst stoppen
|
||
sc.exe stop "DD-MessagingService"
|
||
|
||
# 2. Neue Dateien ins Verzeichnis kopieren (appsettings.Secrets.json NICHT überschreiben)
|
||
|
||
# 3. Dienst starten
|
||
sc.exe start "DD-MessagingService"
|
||
```
|
||
|
||
---
|
||
|
||
### Dienst entfernen
|
||
|
||
```powershell
|
||
sc.exe stop "DD-MessagingService"
|
||
sc.exe delete "DD-MessagingService"
|
||
```
|
||
|
||
---
|
||
|
||
### Konfiguration
|
||
|
||
| Einstellung | Datei | Beschreibung |
|
||
|---|---|---|
|
||
| `Hosting:UseWindowsService` | `appsettings.json` | `true` = Windows-Dienst-Modus aktiv |
|
||
| `Hosting:Urls` | `appsettings.json` | Bind-Adresse und Port, z. B. `http://0.0.0.0:1415` |
|
||
| `DataProtection:PersistKeysToFileSystem` | `appsettings.json` | `true` = Schlüssel werden im Verzeichnis `dp-keys/` gespeichert, unabhängig vom Windows-Benutzer |
|
||
|
||
---
|
||
|
||
|
||
## Email Account Configuration
|
||
|
||
Each account is configured under `EmailAccounts.Accounts` in `appsettings.Secrets.json`.
|
||
|
||
> Different providers require different configuration fields. See provider-specific sections below.
|
||
|
||
### Common fields (all providers)
|
||
|
||
```json
|
||
{
|
||
"Id": 1,
|
||
"Username": "user@example.com",
|
||
"Password": "your_password",
|
||
"SmtpServer": "smtp.example.com",
|
||
"SmtpPort": 465,
|
||
"SmtpUseSsl": true,
|
||
"UseOAuth2": false,
|
||
"ImapServer": "imap.example.com",
|
||
"ImapPort": 993,
|
||
"ImapUseSsl": true,
|
||
"Pop3Server": "pop.example.com",
|
||
"Pop3Port": 995,
|
||
"Pop3UseSsl": true,
|
||
"IncomingProtocol": 1
|
||
}
|
||
```
|
||
|
||
> `Password` is always retained. When `UseOAuth2 = true`, SMTP/IMAP/POP3 connections use OAuth2 tokens
|
||
> instead of the password. When `UseOAuth2 = false`, the password is used directly.
|
||
> The `IncomingProtocol` field independently controls which protocol is used for receiving emails.
|
||
|
||
#### `IncomingProtocol` values
|
||
|
||
| Value | Meaning |
|
||
|-------|---------|
|
||
| `0` | None <20> send-only account, skipped by sync worker |
|
||
| `1` | IMAP with username/password |
|
||
| `2` | POP3 with username/password |
|
||
| `3` | IMAP with OAuth2 |
|
||
| `4` | POP3 with OAuth2 |
|
||
|
||
#### `OAuth2Provider` values
|
||
|
||
| Value | Meaning |
|
||
|-------|---------|
|
||
| `0` | None |
|
||
| `1` | Microsoft (Azure AD / Microsoft 365) |
|
||
| `2` | Google (Gmail / Google Workspace) |
|
||
|
||
---
|
||
|
||
## Provider-specific OAuth2 Configuration
|
||
|
||
### Google (Gmail / Google Workspace)
|
||
|
||
Google uses **user-delegated OAuth2** (authorization code flow). A one-time interactive authorization
|
||
is required to obtain a refresh token. The refresh token is then stored in the database and reused
|
||
automatically for all subsequent operations.
|
||
|
||
> The refresh token survives application restarts. It will not be overwritten by the seed process
|
||
> unless `OAuth2RefreshToken` is explicitly set to a non-empty value in `appsettings.Secrets.json`.
|
||
|
||
#### Required fields
|
||
|
||
```json
|
||
{
|
||
"UseOAuth2": true,
|
||
"OAuth2ClientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
|
||
"OAuth2ClientSecret": "GOCSPX-YOUR_CLIENT_SECRET",
|
||
"OAuth2RefreshToken": "",
|
||
"OAuth2TenantId": "",
|
||
"OAuth2Provider": 2
|
||
}
|
||
```
|
||
|
||
#### Google Cloud Console setup (one-time)
|
||
|
||
1. Go to [console.cloud.google.com](https://console.cloud.google.com) and create or select a project.
|
||
2. Enable the **Gmail API** under *APIs & Services ? Library*.
|
||
3. Go to *APIs & Services ? Credentials* ? **+ Create Credentials** ? **OAuth 2.0 Client ID**:
|
||
- Application type: **Web application**
|
||
- **Authorized redirect URIs**: add `https://YOUR_HOST/api/oauth2/google/callback`
|
||
(e.g. `https://localhost:7261/api/oauth2/google/callback` for local development)
|
||
4. Go to *APIs & Services ? OAuth consent screen*:
|
||
- Add the Gmail account under **Test users** (required while app is in Testing mode).
|
||
|
||
#### Obtaining the refresh token via the built-in authorization endpoint
|
||
|
||
The application provides a built-in OAuth2 flow <20> no external tools needed.
|
||
|
||
1. Open a browser and navigate to:
|
||
```
|
||
GET /api/oauth2/google/authorize/{accountId}
|
||
```
|
||
Example: `https://localhost:7261/api/oauth2/google/authorize/3`
|
||
|
||
2. You will be redirected to Google's consent screen. If you see **"Google hasn't verified this app"**,
|
||
click **Continue** <20> this is expected while the app is in Testing mode.
|
||
|
||
3. Sign in with the Gmail account and grant access.
|
||
|
||
4. Google redirects back to `/api/oauth2/google/callback` automatically.
|
||
The application exchanges the authorization code for a refresh token and saves it to the database.
|
||
|
||
5. A success response is returned:
|
||
```json
|
||
{ "success": true, "username": "user@gmail.com", "message": "..." }
|
||
```
|
||
|
||
6. The sync worker and all IMAP/SMTP operations will now work automatically.
|
||
|
||
> ?? The refresh token must be re-obtained if `invalid_grant` is returned.
|
||
> This happens if the token is unused for 6 months or if the user revokes access.
|
||
|
||
---
|
||
|
||
### Microsoft 365 / Exchange Online (Azure AD)
|
||
|
||
Microsoft uses **application-level OAuth2** (client credentials flow <20> no user interaction required).
|
||
Tokens are acquired automatically using the client ID, secret and tenant ID. No authorization endpoint
|
||
needs to be visited.
|
||
|
||
#### Required fields
|
||
|
||
```json
|
||
{
|
||
"UseOAuth2": true,
|
||
"OAuth2ClientId": "YOUR_APP_CLIENT_ID",
|
||
"OAuth2ClientSecret": "YOUR_APP_CLIENT_SECRET_VALUE",
|
||
"OAuth2TenantId": "yourorg.onmicrosoft.com",
|
||
"OAuth2Provider": 1
|
||
}
|
||
```
|
||
|
||
#### Azure Portal setup (one-time)
|
||
|
||
1. Go to [portal.azure.com](https://portal.azure.com) ? **Azure Active Directory** ? **App registrations** ? **+ New registration**.
|
||
2. Go to **Certificates & secrets** ? **+ New client secret** ? copy the **Value** (not the ID).
|
||
- Set this as `OAuth2ClientSecret`.
|
||
3. Go to **API permissions** ? **+ Add a permission** ? **APIs my organization uses** ? **Office 365 Exchange Online**:
|
||
- Add **Application permissions**: `IMAP.AccessAsApp`, `SMTP.SendAsApp`, `POP.AccessAsApp`
|
||
- Click **Grant admin consent**
|
||
4. In Exchange Online PowerShell, register the service principal for the mailbox:
|
||
```powershell
|
||
New-ServicePrincipal -AppId <ClientId> -ServiceId <ObjectId> -DisplayName "MessagingService"
|
||
Add-MailboxPermission -Identity "user@yourorg.onmicrosoft.com" -User <ObjectId> -AccessRights FullAccess
|
||
```
|
||
5. Set `OAuth2TenantId` to the full domain (e.g. `yourorg.onmicrosoft.com`) or tenant GUID.
|
||
|
||
> ?? `OAuth2ClientSecret` must be the **Value** shown at secret creation time, not the Secret ID (GUID).
|
||
> The value is only visible once <20> if lost, create a new secret.
|
||
|
||
> ?? `OAuth2TenantId` must be a full domain (`yourorg.onmicrosoft.com`), a tenant GUID,
|
||
> or `common`. Short names like `yourorg` are not valid and will cause `AADSTS900023`.
|
||
|
||
> No browser-based authorization is required for Microsoft <20> the application acquires tokens
|
||
> automatically on first use and caches them in memory until 5 minutes before expiry.
|
||
|
||
|
||
---
|
||
|
||
## Email Account Configuration
|
||
|
||
Each account is configured under `EmailAccounts.Accounts` in `appsettings.Secrets.json`.
|
||
|
||
> Different providers require different configuration fields. See provider-specific sections below.
|
||
|
||
### Common fields (all providers)
|
||
|
||
```json
|
||
{
|
||
"Id": 1,
|
||
"Username": "user@example.com",
|
||
"Password": "your_password",
|
||
"SmtpServer": "smtp.example.com",
|
||
"SmtpPort": 465,
|
||
"SmtpUseSsl": true,
|
||
"UseOAuth2": false,
|
||
"ImapServer": "imap.example.com",
|
||
"ImapPort": 993,
|
||
"ImapUseSsl": true,
|
||
"Pop3Server": "pop.example.com",
|
||
"Pop3Port": 995,
|
||
"Pop3UseSsl": true,
|
||
"IncomingProtocol": 1
|
||
}
|
||
```
|
||
|
||
> `Password` is always retained. When `UseOAuth2 = true`, SMTP/IMAP/POP3 connections use OAuth2 tokens
|
||
> instead of the password. When `UseOAuth2 = false`, the password is used directly.
|
||
> The `IncomingProtocol` field independently controls which protocol is used for receiving emails.
|
||
|
||
#### `IncomingProtocol` values
|
||
|
||
| Value | Meaning |
|
||
|-------|---------|
|
||
| `0` | None <20> send-only account, skipped by sync worker |
|
||
| `1` | IMAP with username/password |
|
||
| `2` | POP3 with username/password |
|
||
| `3` | IMAP with OAuth2 |
|
||
| `4` | POP3 with OAuth2 |
|
||
|
||
#### `OAuth2Provider` values
|
||
|
||
| Value | Meaning |
|
||
|-------|---------|
|
||
| `0` | None |
|
||
| `1` | Microsoft (Azure AD / Microsoft 365) |
|
||
| `2` | Google (Gmail / Google Workspace) |
|
||
|
||
---
|
||
|
||
## Provider-specific OAuth2 Configuration
|
||
|
||
### Google (Gmail / Google Workspace)
|
||
|
||
Google uses **user-delegated OAuth2** (not client credentials). A one-time authorization flow is required to obtain a refresh token.
|
||
|
||
#### Required fields
|
||
|
||
```json
|
||
{
|
||
"UseOAuth2": true,
|
||
"OAuth2ClientId": "YOUR_CLIENT_ID.apps.googleusercontent.com",
|
||
"OAuth2ClientSecret": "GOCSPX-YOUR_CLIENT_SECRET",
|
||
"OAuth2RefreshToken": "1//04YOUR_REFRESH_TOKEN",
|
||
"OAuth2TenantId": "",
|
||
"OAuth2Provider": 2
|
||
}
|
||
```
|
||
|
||
#### Setup <20> obtaining the refresh token (one-time)
|
||
|
||
1. Go to [console.cloud.google.com](https://console.cloud.google.com) and create or select a project.
|
||
2. Enable the **Gmail API** under *APIs & Services ? Library*.
|
||
3. Go to *APIs & Services ? Credentials* ? **+ Create Credentials** ? **OAuth 2.0 Client ID**.
|
||
- Application type: **Web application**
|
||
- Authorized redirect URIs: `https://developers.google.com/oauthplayground`
|
||
4. Go to *APIs & Services ? OAuth consent screen*:
|
||
- Add the Gmail account under **Test users** (required while app is in Testing mode).
|
||
5. Go to [developers.google.com/oauthplayground](https://developers.google.com/oauthplayground):
|
||
- Click **?? Settings** ? enable **"Use your own OAuth credentials"**
|
||
- Enter your **Client ID** and **Client Secret** (from step 3)
|
||
- Close settings
|
||
6. In the scope input (Step 1), enter `https://mail.google.com/` ? **Authorize APIs**
|
||
7. Sign in with the Gmail account ? grant access
|
||
8. Click **Exchange authorization code for tokens** (Step 2)
|
||
9. Copy the `refresh_token` value from the response
|
||
10. Set `OAuth2RefreshToken` in `appsettings.Secrets.json`
|
||
|
||
> ?? The refresh token must be obtained using **your own client credentials** in Playground settings.
|
||
> If obtained with Playground's default credentials, it will not work with your client secret.
|
||
|
||
> ?? Google refresh tokens expire if unused for 6 months, or if the user revokes access.
|
||
> The token must be re-obtained if `invalid_grant` is returned.
|
||
|
||
---
|
||
|
||
### Microsoft 365 / Exchange Online (Azure AD)
|
||
|
||
Microsoft uses **application-level OAuth2** (client credentials flow <20> no user interaction required).
|
||
|
||
#### Required fields
|
||
|
||
```json
|
||
{
|
||
"UseOAuth2": true,
|
||
"OAuth2ClientId": "YOUR_APP_CLIENT_ID",
|
||
"OAuth2ClientSecret": "YOUR_APP_CLIENT_SECRET_VALUE",
|
||
"OAuth2TenantId": "yourorg.onmicrosoft.com",
|
||
"OAuth2Provider": 1
|
||
}
|
||
```
|
||
|
||
#### Setup
|
||
|
||
1. Go to [portal.azure.com](https://portal.azure.com) ? **Azure Active Directory** ? **App registrations** ? **+ New registration**.
|
||
2. Go to **Certificates & secrets** ? **+ New client secret** ? copy the **Value** (not the ID).
|
||
- Set this as `OAuth2ClientSecret`.
|
||
3. Go to **API permissions** ? **+ Add a permission** ? **APIs my organization uses** ? **Office 365 Exchange Online**:
|
||
- Add **Application permissions**: `IMAP.AccessAsApp`, `SMTP.SendAsApp`, `POP.AccessAsApp`
|
||
- Click **Grant admin consent**
|
||
4. In Exchange Online PowerShell, register the service principal for the mailbox:
|
||
```powershell
|
||
New-ServicePrincipal -AppId <ClientId> -ServiceId <ObjectId> -DisplayName "MessagingService"
|
||
Add-MailboxPermission -Identity "user@yourorg.onmicrosoft.com" -User <ObjectId> -AccessRights FullAccess
|
||
```
|
||
5. Set `OAuth2TenantId` to the full domain (e.g. `yourorg.onmicrosoft.com`) or tenant GUID.
|
||
|
||
> ?? `OAuth2ClientSecret` must be the **Value** shown at secret creation time, not the Secret ID (GUID).
|
||
> The value is only visible once <20> if lost, create a new secret.
|
||
|
||
> ?? `OAuth2TenantId` must be a full domain (`yourorg.onmicrosoft.com`), a tenant GUID,
|
||
> or `common`. Short names like `yourorg` are not valid and will cause `AADSTS900023`.
|
||
|
||
|