Zum Inhalt springen

OBS/CloudConnect/OAuth2: Unterschied zwischen den Versionen

Aus OBS Wiki
← Zum vorherigen Versionsunterschied
VisuellWikitext
Thiel (Diskussion | Beiträge)
Programmierer, Administratoren
2.549 Bearbeitungen
MINERVA-Thiel (Diskussion | Beiträge)
minerva
1.966 Bearbeitungen
Feldnamen des OAuth2-Eintrags korrigiert: App ID und App Secret ID statt Login und Passwort [Volltext ersetzt]
 
(6 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Vorlage:CloudConnect}}
{{Vorlage:CloudConnect}}
{{Seitentyp|Anleitung}}
= OAuth2 =


=Allgemein=
Mit OAuth2 melden sich E-Mail-Konten und Kalender in OBS bei Microsoft oder Google an, ohne dass OBS das Passwort des Benutzers kennt. Der Benutzer meldet sich einmal im Browser an und erlaubt OBS den Zugriff. Diese Seite beschreibt die Einrichtung für Microsoft. Für Google lesen Sie [[OBS/CloudConnect/Google API|Google API]].
[https://de.wikipedia.org/wiki/OAuth#OAuth_2.0_und_OpenID_Connect OAuth 2.0] (Open Authorization) ist der Name eines offenen Protokolls, das eine standardisierte, sichere API-Autorisierung für Desktop-, Web- und Mobile-Anwendungen erlaubt.
Ein Endbenutzer kann mit Hilfe dieses Protokolls einer Anwendung den Zugriff auf seine Daten erlauben (z.B.: E-Mails), die von einem anderen Dienst (z.B.: Office365) bereitgestellt werden, ohne geheime Details seiner Zugangsberechtigung (Authentifizierung) der Anwendung preiszugeben.


{{Achtung|POP3 wird erst mit der Version vom 02.11.2022 unterstützt}}
== Voraussetzungen ==
* Zugriff auf das Microsoft-Entra-Portal Ihres Microsoft-365-Mandanten mit der Rolle Anwendungsadministrator oder Cloudanwendungsadministrator, oder Sie sind Besitzer der App.


=Voraussetzungen=
{{Hinweis|POP3 mit OAuth2 unterstützt OBS ab der Version vom 02.11.2022.}}
Für das aktivieren der Authentifizierung muss die jeweilige API des Providers (z.B.: Microsoft oder Google) aktiviert werden. Zusätzlich muss für OBS eine Anwendungs-ID und eine Geheime-ID generiert werden.  
Auch kann es nötig sein weitere Einstellungen für die API zu aktivieren (z.B.: [[OBS/Stammdaten/Weitere_Stammdaten/E-Mail_Konten_erstellen/bearbeiten#Authentifiziertes_SMTP|Authentifiziertes SMTP]] bei Exchange)


Im Folgenden ist dies für Google und Microsoft beschrieben.
== Vorgehen ==
*[[OBS/CloudConnect/GoogleAPI|Google-API]]
=== App bei Microsoft registrieren ===
*[https://docs.snowflake.com/de/user-guide/oauth-azure.html Microsoft-API]
{{Schritte|1=
# Öffnen Sie [https://entra.microsoft.com entra.microsoft.com] und wählen Sie '''Anwendungen → App-Registrierungen''' und dann '''+ Neue Registrierung'''.
# Vergeben Sie einen Namen, z.B. ''OBS'', und wählen Sie bei den unterstützten Kontotypen die mehrinstanzenfähige Variante.
# Wählen Sie bei der Umleitungs-URI die Plattform ''Mobilgerät- und Desktopanwendungen'' und tragen Sie <code><nowiki>http://localhost:2132/</nowiki></code> ein.
# Registrieren Sie die App. In der Übersicht der App finden Sie die '''Anwendungs-ID (Client)'''. Notieren Sie sie.
# Legen Sie den '''Anwendungs-ID-URI''' fest. Der vorgeschlagene Wert kann bleiben.
}}


==Microsoft konfigurieren==
{{Achtung|Der Plattformtyp der Umleitungs-URI muss ''Mobilgerät- und Desktopanwendungen'' sein.}}
[[Datei:OAuth_AppID.png|border]]
===App-Registrierungen===
* unter https://aad.portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview klicken Sie im Menu auf "App-Registrierung"
* "+ Neue Registrierung"
** [[Datei:Microsoft_AppPlus.png|400px|border]]
*Es ist wichtig, die Anwendung als "mehrinstanzenfähig" (Multi-Tanend) zu erzeugen, da die Standard Endpunkte von OSB auf https://login.microsoftonline.com/'''common/''' laufen.
**Wollen Sie statt "common" Ihre eigene Domaine nutzen ("einzelner Mandant"), müssen Sie die Endpunkte in OBS entsprechend anpassen ([[OBS/CloudConnect/oAuth2#Definitionen|Definitionen]]).
**Die passenden Endpunkte können dann wie folgt aussehen: https://login.microsoftonline.com/'''BERGAU.de/'''
* in der Übersicht der neuen Registrierung finden Sie nun die Anwendungs-ID(Client)
**[[Datei:Microsoft_AppOverview.png|400px|border]]
* Unter Umleitungs-URIs (Antwort-URL) müssen Sie eine Umleitung auf http://localhost:2132/ einrichten. Dies ist wichtig für die Kommunikation mit OBS während des Authentifizierungsprozesses.
**Klicken Sie dazu auf die Umleitungs-URI und dann auf +Neue Plattform{{Achtung|Der Typ muss '''Mobilgerät- und Desktopanwendungen''' sein!}}
**[[Datei:Microsoft_AppUri.png|400px|border]]
* Die Anwendungs-ID-URI muss festgelegt werden. Standard Wert kann beibehalten werden.
**[[Datei:Microsoft_IDURI.png|400px|border]]


===API-Berechtigungen===
Mehrinstanzenfähig muss die App sein, weil die Definitionen von OBS den allgemeinen Anmeldeendpunkt <code>/common/</code> verwenden. Soll die App nur für Ihre eigene Domäne gelten, kopieren Sie die Definition mit {{F6}} und ersetzen Sie darin <code>/common/</code> durch Ihre Domäne, z.B. <code>/firma.de/</code>.
es sind keine speziellen Berechtigungen nötig.
Folgende Berechtigung sollte automatisch angelegt werden
* Microsoft Graph (1)
** User.Read


===Zertifikate & Geheimnisse===
Besondere API-Berechtigungen brauchen Sie in der App nicht einzurichten. OBS fragt die nötigen Berechtigungen bei der Anmeldung ab, der Benutzer bestätigt sie. Braucht OBS später weitere Berechtigungen, melden Sie bestehende Konten neu an.
[[Datei:OAuth_AppID_geheim.png|border]]


Über einen Klick auf "+ Neuen geheimen Clientschlüssel" erhalten Sie ein können Sie einen neuen Schlüssel mit Namen und Gültigkeit definieren.
=== Geheimen Clientschlüssel anlegen ===
{{Schritte|1=
# Wählen Sie in der App '''Verwalten → Zertifikate & Geheimnisse''', Registerkarte '''Geheime Clientschlüssel'''.
# Klicken Sie auf '''+ Neuer geheimer Clientschlüssel''', vergeben Sie eine Beschreibung und die Gültigkeit (höchstens 24 Monate) und klicken Sie auf '''Hinzufügen'''.
# Kopieren Sie sofort die Spalte '''Wert'''.
}}


'''Mit der daraus erhaltenen "Geheimen ID" (App Secret ID) und der Anwendungs-ID (App ID) können Sie die Einrichtung in OBS vornehmen.'''
{{Achtung|Kopieren Sie den '''Wert''', nicht die '''Geheimnis-ID'''. Der Wert ist nur direkt nach dem Anlegen sichtbar. Notieren Sie das Ablaufdatum: Ist der Schlüssel abgelaufen, schlägt die Anmeldung fehl, und Sie müssen einen neuen Schlüssel anlegen und in OBS eintragen.}}


=Einrichtung Email-Konto OBS=
=== OAuth2-Eintrag in OBS anlegen ===
{{Achtung|Für jeden Zugang (z.B.: E-Mail-Konto) muss eine eigene oAuth2 Authentifizierung freigeschaltet werden (Cloud-Connect). Dabei kann der API-Key aber mehrfach verwendet werden, wenn die Zugänge über ein Hauptkonto verwaltet werden (Bei Microsoft ist dies über ein Organisationskonto geregelt)}}
Den OAuth2-Eintrag legen Sie einmal an und verwenden ihn für alle E-Mail-Konten und Kalender-Konten, die dieselbe App nutzen.
{{Achtung|Ein Cloud-Connect bei dem Sie sich mit Info@test.de angemeldet haben, können Sie '''nicht''' für das E-Mail-Konto für obs@test.de nutzen, da für jeden Benutzer ein Benutzerdefinierter Schlüssel (Token) generiert wird, der für die Anmeldung genutzt wird!}}
{{Schritte|1=
# Öffnen Sie '''Stammdaten → Z Weitere Stammdaten → Cloud Connect''' und legen Sie mit {{Einfg}} einen neuen Eintrag an.
# Wählen Sie bei '''Cloud Typ''' die passende Definition (siehe Tabelle) und vergeben Sie einen '''Titel'''.
# Tragen Sie bei '''App ID''' die Anwendungs-ID und bei '''App Secret ID''' den Wert des geheimen Clientschlüssels ein.
# Sichern Sie mit {{F2}}.
}}


'''Beispiel zur Einrichtung eines Microsoft E-Mail-Kontos'''
[[Datei:OAuth2_Cloud_Edit.png|alt=Cloud-Connect-Eintrag mit OAuth2-Definition]]


#API-Key aktivieren und ID bekommen
Für Microsoft gibt es zwei Definitionen. Sie sind nicht austauschbar:
#Eintrag hinzufügen
{| class="wikitable"
##Dabei wählen Sie bei Cloud Typ den entsprechenden oAuth2 Typen aus. Weitere Infos im Abschnitt [[OBS/CloudConnect/oAuth2#Definitionen|Definitionen]]
! Definition !! Wofür
##[[Datei:OAuth2_Cloud_Edit.png|300px]]
|-
#Authentifizieren und Zugangstoken erhalten
| ''OAUTH2 Microsoft (IMAP/POP/SMTP/EWS)'' || E-Mail-Konten (IMAP, POP, SMTP) sowie Exchange-Termin- und Personensynchronisation über EWS
##Beim speichern der Daten werden die Daten geprüft und Ihr Standard Browser öffnet sich. Hier werden Sie aufgefordert sich anzumelden und den oAuth2-Zugang zu genehmigen.
|-
##Nachträglich kann dies in der Eingabemaske mit {{F10}} gemacht werden.
| ''OAUTH2 Microsoft Graph(Outlook/Exchange)'' || [[OBS/CloudConnect/Microsoft 365 Kalender|Microsoft 365-Terminsynchronisation]]
##[[Datei:OAuth_Idle.png|300px]]
|}
##[[Datei:OAuth_AppLogin.png|300px]]
#Nun können Sie den Zugang in [[OBS/Stammdaten/Weitere_Stammdaten/E-Mail_Konten_erstellen/bearbeiten#Registerkarte:_POP3_.2F_IMAP|E-Mail-Konto]] hinterlegen
##[[Datei:OAuth mail.png|300px]]


=Definitionen=
Alle Definitionen sehen Sie mit {{F10}} in der Liste '''Cloud Connect'''. Fehlt ein Anbieter, erfassen Sie seine Daten dort selbst: Autorisierungs-Endpunkt, Token-Endpunkt und Scopes.
Bei der Einrichtung von oAuth2 sind bestimmte Daten notwendig, damit der korrekte Authentifikations-Dienst der jeweiligen Organisation (Google, Microsoft) angesprochen werden kann.  


Diese sind über {{F10}} erreichbar.
[[Datei:OAuth_Def.png|rahmenlos|720px|alt=Liste der OAuth2-Definitionen]]
{{Hinweis|Hier sind auch andere Cloud-Typen zu finden. Die oAuth2 Typen sind vom Typ ctOAuth2}}


Dazu zählen folgende Daten, welche im Netz zu finden sind:
{{Achtung|Die Definitionen von OBS werden bei jedem Update mit den Standardwerten überschrieben. Wollen Sie etwas ändern, kopieren Sie die Definition mit {{F6}} und ändern Sie die Kopie.}}
*Authorisations Endpunkt
*Token Endpoint
*Scope und weitere Daten


[[Datei:OAuth_Def.png|600px]]
=== OAuth2-Eintrag verwenden ===
* '''E-Mail-Konto:''' Wählen Sie im E-Mail-Konto als Authentifizierung ''oAuth2'' und den OAuth2-Eintrag. Beim Speichern öffnet sich Ihr Browser. Melden Sie sich mit dem Konto des Postfachs an und erlauben Sie den Zugriff. Mit '''Anmelden''' erzwingen Sie eine neue Anmeldung, mit '''Testen''' prüfen Sie die hinterlegten Daten.
* '''Kalender-Konto:''' Wählen Sie bei '''oAuth2 Connect''' den OAuth2-Eintrag und melden Sie sich mit {{F10}} an, siehe [[OBS/CloudConnect/Microsoft 365 Kalender|Microsoft 365-Terminsynchronisation]] und [[OBS/CloudConnect/Exchange Kalender|Exchange-Terminsynchronisation]].


Diese werden von seitens OBS bereit gestellt. Sollte mal ein Anbieter nicht verfügbar sein, können Sie diese Daten manuell nach erfassen und nutzen.
[[Datei:OAuth mail.png|alt=E-Mail-Konto mit OAuth2-Authentifizierung]]
{{Achtung|die von OBS erstellten Einträge werden beim Update mit unseren Standard Werten überschrieben. Bitte bei Änderungen neue Einträge erstellen oder vorhandene mit {{F6}} kopieren.}}


==mehrinstanzenfähig (Multi-tannend)==
{{Achtung|Jede Anmeldung gilt nur für das Konto, mit dem Sie sich angemeldet haben. Haben Sie sich mit ''info@firma.de'' angemeldet, können Sie diese Anmeldung nicht für das Postfach ''obs@firma.de'' verwenden.}}
Da wir im Standard die Endpunkte '''/common/''' nutzen, müssen die erstelten Anwendungen in der API mehrinstanzenfähig sein. Wenn Sie eine Anwendung nur für Ihre Domäne erstellen wollen (einzelner Mandant), dann müssen Sie eine entsprechend neue Definition erstellen (oder mit {{F6}} die vorhandene Definition kopieren) und den Part /common/ durch Ihre Domäne ersetzen (Beispiel: '''/bergau.de/''')


=Bekannte Probleme=
== Ergebnis ==
==Imap Ordner können nicht eingelesen werden==
'''Testen''' zeigt die Daten des Kontos, mit dem die Anmeldung erfolgt ist. Bei Kalender-Konten zeigt '''Verbindungstest (F10)''' ''oAuth2 Token vorhanden''.
==Falsches Konto==
Wenn Sie diese Meldung beim Testen eines E-Mail-Kontos bekommen, haben Sie mit dem Cloud-Connect keine berechtigungen die Ordner Struktur des Kontos zu lesen.


Dies kann passieren, wenn der Cloud-Connect nicht zum E-Mail Konto passt.
== Wenn es nicht klappt ==
{| class="wikitable"
! Meldung !! Ursache
|-
| Ordner des E-Mail-Kontos lassen sich nicht einlesen || Die Anmeldung passt nicht zum E-Mail-Konto. Prüfen Sie mit '''Testen''', mit welchem Konto angemeldet wurde, und melden Sie sich mit '''Anmelden''' neu an. Oder IMAP ist für das Postfach abgeschaltet. Das kann nur der Administrator Ihres Microsoft-365-Mandanten ändern.
|-
| Anmeldung schlägt fehl, obwohl sie bisher funktioniert hat || Der geheime Clientschlüssel ist abgelaufen. Legen Sie einen neuen an und tragen Sie ihn im OAuth2-Eintrag bei '''App Secret ID''' ein.
|-
| <code>HTTP 401</code> im Microsoft-365-Kalender || Der OAuth2-Eintrag hat die Definition ''OAUTH2 Microsoft (IMAP/POP/SMTP/EWS)''. Für die Microsoft 365-Terminsynchronisation brauchen Sie ''OAUTH2 Microsoft Graph(Outlook/Exchange)''.
|}


Cloud-Connect für admin@test.de
== Siehe auch ==
 
* [[OBS/Stammdaten/Weitere_Stammdaten/E-Mail_Konten_erstellen/bearbeiten#Authentifiziertes_SMTP|Authentifiziertes SMTP]]
E-Mail Konto für abrechnung@test.de
* [[OBS/CloudConnect/Google API|Google API]]
 
* [[OBS/CloudConnect/Übersicht|Cloud-Schnittstellen]]
==Fehlende Berechtigungen==
Es kann auch sein, dass IMAP für das entsprechende Konto deaktiviert ist.
Dieses muss über den Domänen-Administrator aktiviert werden.

Aktuelle Version vom 2. Oktober 2026, 10:12 Uhr

OAuth2

Mit OAuth2 melden sich E-Mail-Konten und Kalender in OBS bei Microsoft oder Google an, ohne dass OBS das Passwort des Benutzers kennt. Der Benutzer meldet sich einmal im Browser an und erlaubt OBS den Zugriff. Diese Seite beschreibt die Einrichtung für Microsoft. Für Google lesen Sie Google API.

Voraussetzungen

  • Zugriff auf das Microsoft-Entra-Portal Ihres Microsoft-365-Mandanten mit der Rolle Anwendungsadministrator oder Cloudanwendungsadministrator, oder Sie sind Besitzer der App.
HINWEIS: POP3 mit OAuth2 unterstützt OBS ab der Version vom 02.11.2022.

Vorgehen

App bei Microsoft registrieren

  1. Öffnen Sie entra.microsoft.com und wählen Sie Anwendungen → App-Registrierungen und dann + Neue Registrierung.
  2. Vergeben Sie einen Namen, z.B. OBS, und wählen Sie bei den unterstützten Kontotypen die mehrinstanzenfähige Variante.
  3. Wählen Sie bei der Umleitungs-URI die Plattform Mobilgerät- und Desktopanwendungen und tragen Sie http://localhost:2132/ ein.
  4. Registrieren Sie die App. In der Übersicht der App finden Sie die Anwendungs-ID (Client). Notieren Sie sie.
  5. Legen Sie den Anwendungs-ID-URI fest. Der vorgeschlagene Wert kann bleiben.
ACHTUNG: Der Plattformtyp der Umleitungs-URI muss Mobilgerät- und Desktopanwendungen sein.

Mehrinstanzenfähig muss die App sein, weil die Definitionen von OBS den allgemeinen Anmeldeendpunkt /common/ verwenden. Soll die App nur für Ihre eigene Domäne gelten, kopieren Sie die Definition mit F6 und ersetzen Sie darin /common/ durch Ihre Domäne, z.B. /firma.de/.

Besondere API-Berechtigungen brauchen Sie in der App nicht einzurichten. OBS fragt die nötigen Berechtigungen bei der Anmeldung ab, der Benutzer bestätigt sie. Braucht OBS später weitere Berechtigungen, melden Sie bestehende Konten neu an.

Geheimen Clientschlüssel anlegen

  1. Wählen Sie in der App Verwalten → Zertifikate & Geheimnisse, Registerkarte Geheime Clientschlüssel.
  2. Klicken Sie auf + Neuer geheimer Clientschlüssel, vergeben Sie eine Beschreibung und die Gültigkeit (höchstens 24 Monate) und klicken Sie auf Hinzufügen.
  3. Kopieren Sie sofort die Spalte Wert.
ACHTUNG: Kopieren Sie den Wert, nicht die Geheimnis-ID. Der Wert ist nur direkt nach dem Anlegen sichtbar. Notieren Sie das Ablaufdatum: Ist der Schlüssel abgelaufen, schlägt die Anmeldung fehl, und Sie müssen einen neuen Schlüssel anlegen und in OBS eintragen.

OAuth2-Eintrag in OBS anlegen

Den OAuth2-Eintrag legen Sie einmal an und verwenden ihn für alle E-Mail-Konten und Kalender-Konten, die dieselbe App nutzen.

  1. Öffnen Sie Stammdaten → Z Weitere Stammdaten → Cloud Connect und legen Sie mit Einfg einen neuen Eintrag an.
  2. Wählen Sie bei Cloud Typ die passende Definition (siehe Tabelle) und vergeben Sie einen Titel.
  3. Tragen Sie bei App ID die Anwendungs-ID und bei App Secret ID den Wert des geheimen Clientschlüssels ein.
  4. Sichern Sie mit F2.

Cloud-Connect-Eintrag mit OAuth2-Definition

Für Microsoft gibt es zwei Definitionen. Sie sind nicht austauschbar:

Definition Wofür
OAUTH2 Microsoft (IMAP/POP/SMTP/EWS) E-Mail-Konten (IMAP, POP, SMTP) sowie Exchange-Termin- und Personensynchronisation über EWS
OAUTH2 Microsoft Graph(Outlook/Exchange) Microsoft 365-Terminsynchronisation

Alle Definitionen sehen Sie mit F10 in der Liste Cloud Connect. Fehlt ein Anbieter, erfassen Sie seine Daten dort selbst: Autorisierungs-Endpunkt, Token-Endpunkt und Scopes.

Liste der OAuth2-Definitionen

ACHTUNG: Die Definitionen von OBS werden bei jedem Update mit den Standardwerten überschrieben. Wollen Sie etwas ändern, kopieren Sie die Definition mit F6 und ändern Sie die Kopie.

OAuth2-Eintrag verwenden

  • E-Mail-Konto: Wählen Sie im E-Mail-Konto als Authentifizierung oAuth2 und den OAuth2-Eintrag. Beim Speichern öffnet sich Ihr Browser. Melden Sie sich mit dem Konto des Postfachs an und erlauben Sie den Zugriff. Mit Anmelden erzwingen Sie eine neue Anmeldung, mit Testen prüfen Sie die hinterlegten Daten.
  • Kalender-Konto: Wählen Sie bei oAuth2 Connect den OAuth2-Eintrag und melden Sie sich mit F10 an, siehe Microsoft 365-Terminsynchronisation und Exchange-Terminsynchronisation.

E-Mail-Konto mit OAuth2-Authentifizierung

ACHTUNG: Jede Anmeldung gilt nur für das Konto, mit dem Sie sich angemeldet haben. Haben Sie sich mit info@firma.de angemeldet, können Sie diese Anmeldung nicht für das Postfach obs@firma.de verwenden.

Ergebnis

Testen zeigt die Daten des Kontos, mit dem die Anmeldung erfolgt ist. Bei Kalender-Konten zeigt Verbindungstest (F10) oAuth2 Token vorhanden.

Wenn es nicht klappt

Meldung Ursache
Ordner des E-Mail-Kontos lassen sich nicht einlesen Die Anmeldung passt nicht zum E-Mail-Konto. Prüfen Sie mit Testen, mit welchem Konto angemeldet wurde, und melden Sie sich mit Anmelden neu an. Oder IMAP ist für das Postfach abgeschaltet. Das kann nur der Administrator Ihres Microsoft-365-Mandanten ändern.
Anmeldung schlägt fehl, obwohl sie bisher funktioniert hat Der geheime Clientschlüssel ist abgelaufen. Legen Sie einen neuen an und tragen Sie ihn im OAuth2-Eintrag bei App Secret ID ein.
HTTP 401 im Microsoft-365-Kalender Der OAuth2-Eintrag hat die Definition OAUTH2 Microsoft (IMAP/POP/SMTP/EWS). Für die Microsoft 365-Terminsynchronisation brauchen Sie OAUTH2 Microsoft Graph(Outlook/Exchange).

Siehe auch

Abgerufen von „https://wiki.bergau.de/index.php?title=OBS/CloudConnect/OAuth2&oldid=66989“