====== Einrichtung von OAuth Client Anmeldung über Microsoft 365 mit eBiss ======

===== Teil 1: Einrichtung im Azure Portal =====

Diese Anleitung befindet sich auch als PDF in Ihrem eBiss Verzeichnis unter ''.\StandardTemplates\Misc\OAuth_M365_eBiss_Anleitung.pdf''

==== 1.1 App-Registrierung erstellen ====

Navigiere im Azure Portal zu **Entra ID** und wähle dann **Verwalten → App-Registrierungen → Neue Registrierung**.

Folgende Einstellungen vornehmen:

  * Einen eindeutigen Namen für die Anwendung vergeben.
  * Unterstützte Kontotypen wählen (Standard: //Nur Konten in diesem Organisationsverzeichnis, Einzelner Mandant//)
  * Auf **Registrieren** klicken.

==== 1.2 Client ID und Tenant-ID notieren ====

Nach der Registrierung werden zwei wichtige IDs angezeigt, die für alle weiteren Schritte benötigt werden:

^ Bezeichnung ^ Beschreibung ^
| **Client ID** | Auch „Anwendungs-ID" genannt. Eindeutige Kennung dieser App-Registrierung. |
| **Tenant-ID** | Auch „Verzeichnis-ID" genannt. Identifiziert den Azure AD-Mandanten (die Organisation). |

<WRAP important>
⚠ Beide IDs jetzt notieren – sie werden später in den PowerShell-Befehlen benötigt.
</WRAP>

==== 1.3 Client Secret erstellen ====

<WRAP info>
**Hinweis:** Zertifikatsgeheimnisse werden aktuell nicht unterstützt. Es muss ein Client Secret verwendet werden.
</WRAP>

Navigiere zu **Zertifikate & Geheimnisse → Clientanmeldeinformationen → Neuer geheimer Clientschlüssel**.

  * Eine Beschreibung und eine Gültigkeitsdauer wählen.
  * Auf **Hinzufügen** klicken.

<WRAP important>
⚠ Das Client Secret wird nur einmal angezeigt! Direkt nach der Erstellung kopieren und sicher speichern.
</WRAP>

==== 1.4 Unternehmens-Objekt-ID notieren ====

Wechsle in Entra ID zu **Unternehmensanwendungen**. Die neu erstellte App-Registrierung in der Liste suchen und öffnen.

^ Bezeichnung ^ Beschreibung ^
| **Objekt-ID** | Die ID des Enterprise-Anwendungsobjekts – abweichend von der Client ID der App-Registrierung. |

==== 1.5 API-Berechtigungen hinzufügen ====

Navigiere zurück zur App-Registrierung unter **API-Berechtigungen → Berechtigung hinzufügen**.

  * Reiter **„Von meiner Organisation verwendete APIs"** wählen.
  * Nach „SMTP" suchen und die Berechtigung **SMTP.SendAsApp** hinzufügen.
  * Nach „POP" suchen und die Berechtigung **POP.AccessAsApp** hinzufügen.

<WRAP important>
⚠ Diese Berechtigungen erfordern eine Admin-Einwilligung. Einen Azure-Administrator bitten, die Berechtigungen zu genehmigen („Admin-Zustimmung erteilen").
</WRAP>

===== Teil 2: Konfiguration per PowerShell =====

Die folgenden Schritte müssen von einem **Exchange-Administrator** in PowerShell ausgeführt werden.

==== 2.1 Exchange Online Modul laden und verbinden ====

<code powershell>
Import-Module ExchangeOnlineManagement

Connect-ExchangeOnline -Organization <Tenant ID>
</code>

^ Cmdlet ^ Beschreibung ^
| ''Import-Module'' | Lädt das Exchange Online PowerShell-Modul, das die spezifischen Cmdlets für Exchange-Verwaltung bereitstellt. |
| ''Connect-ExchangeOnline'' | Baut eine authentifizierte Verbindung zu Exchange Online auf. Der Parameter ''-Organization'' gibt die Tenant-ID an, um den richtigen Mandanten zu adressieren. |

==== 2.2 Service Principal registrieren ====

<code powershell>
New-ServicePrincipal -AppId <Client ID> -ObjectId <Object ID> -DisplayName <DisplayName>
</code>

^ Cmdlet ^ Beschreibung ^
| ''New-ServicePrincipal'' | Registriert die Azure AD-App-Registrierung als Service Principal in Exchange Online. Erst dadurch erkennt Exchange die App als berechtigten Akteur. AppId = Client ID, ObjectId = Unternehmens-Objekt-ID, DisplayName frei wählbar (aus Schritt 1.4). |

==== 2.3 SMTP-Authentifizierung aktivieren ====

Wähle eine der beiden Optionen:

=== Option A: Nur für ein einzelnes Postfach ===

<code powershell>
Set-CASMailbox -Identity <user@domain.com> -SmtpClientAuthenticationDisabled $false
</code>

^ Cmdlet ^ Beschreibung ^
| ''Set-CASMailbox'' | Konfiguriert die Client Access Services (CAS) für ein einzelnes Postfach. Mit ''-SmtpClientAuthenticationDisabled $false'' wird SMTP-Auth speziell für dieses Postfach aktiviert, auch wenn sie organisationsweit deaktiviert ist. |

=== Option B: Organisationsweit ===

<code powershell>
Set-TransportConfig -SmtpClientAuthenticationDisabled $false
</code>

^ Cmdlet ^ Beschreibung ^
| ''Set-TransportConfig'' | Ändert die globale Transportkonfiguration für die gesamte Organisation. Aktiviert SMTP-Client-Authentifizierung für alle Postfächer. Nur empfohlen, wenn alle Postfächer SMTP Auth benötigen. |

==== 2.4 Postfachberechtigungen vergeben ====

<code powershell>
Add-MailboxPermission -Identity <user@domain.com> -User "<DisplayName>" -AccessRights FullAccess
</code>

^ Cmdlet ^ Beschreibung ^
| ''Add-MailboxPermission'' | Gewährt dem Service Principal (referenziert über den DisplayName aus Schritt 2.2) vollständigen Zugriff (FullAccess) auf das angegebene Postfach. Nötig, damit die App E-Mails lesen und verwalten kann (z. B. per POP). |

<code powershell>
Add-RecipientPermission <user@domain.com> -Trustee "<DisplayName>" -AccessRights SendAs
</code>

^ Cmdlet ^ Beschreibung ^
| ''Add-RecipientPermission'' | Erlaubt dem Service Principal, E-Mails im Namen des angegebenen Postfachs zu versenden („Send As"). Der Trustee ist der DisplayName des Service Principals aus Schritt 2.2. |

===== Teil 3: Konfiguration in eBiss3 =====

Die Kommunikationskanäle werden in eBiss3 unter **Kommunikationskanäle einrichten** konfiguriert. Folgende Einstellungen gelten für beide Kanäle, sofern nicht abweichend angegeben.

==== 3.1 SMTP Send (ausgehende E-Mails) ====

^ Parameter ^ Wert ^
| **Host** | ''smtp.office365.com'' |
| **Port** | ''587'' |
| **SSL-Verhalten** | Explicit (STARTTLS – Verbindung startet unverschlüsselt, wird dann auf TLS hochgestuft) |
| **Authentifizierung** | OAuth 2.0 |
| **Benutzername** | Vollständige E-Mail-Adresse des Absenders (z. B. ''sender@domain.com'') |
| **Client ID** | Client-ID aus Schritt 1.2 |
| **Client Secret** | Client Secret aus Schritt 1.3 |
| **Server URL** | ''<nowiki>https://login.microsoftonline.com/<Tenant-ID>/oauth2/v2.0/token</nowiki>'' |
| **Auth URL / Scope** | ''<nowiki>https://outlook.office365.com/.default</nowiki>'' |

==== 3.2 POP3 Receive (eingehende E-Mails) ====

Die Konfiguration entspricht weitgehend dem SMTP-Send-Kanal. Folgende Parameter weichen ab:

^ Parameter ^ SMTP Send ^ POP3 Receive ^
| **Host** | ''smtp.office365.com'' | ''outlook.office365.com'' |
| **Port** | ''587'' | ''995'' |
| **SSL-Verhalten** | Explicit | Implicit (direkte TLS-Verbindung ohne vorherigen Klartext-Handshake) |

Alle übrigen Parameter (Authentifizierung, Benutzername, Client ID, Client Secret, Server URL, Auth URL) bleiben identisch zu SMTP Send.

----

Nach Abschluss aller drei Teile ist die OAuth 2.0-Verbindung zwischen eBiss3 und Microsoft 365 vollständig eingerichtet.