OBS/CloudConnect/oAuth2

Wiki » Cloud Connect

HINWEIS: Bitte beachten sie dass für den Betrieb der Schnittstelle der Cloud-Dienst in OBS aktiviert sein muss.

CloudConnect

• Übersicht
• Einrichtung: Google API
• Einrichtung: Google Calendar
• Einrichtung: Exchange Terminsynchronisation
• Einrichtung: Exchange Personensynchronisation
• Einrichtung: oAuth2-Authentifizierung

Allgemein

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

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.: Authentifiziertes SMTP bei Exchange)

Im Folgenden ist dies für Google und Microsoft beschrieben.

• Google-API
• Microsoft-API

Microsoft konfigurieren

App-Registrierungen

• unter https://aad.portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview klicken Sie im Menu auf "App-Registrierung"
• "+ Neue Registrierung"
  • 
• 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.
  • weitere Information erhalten Sie hier
• in der Übersicht der neuen Registrierung finden Sie nun die Anwendungs-ID(Client)
  • 
• 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 "+Plattform hinzufügen"
    ACHTUNG: Der Typ muss Mobilgerät- und Desktopanwendungen sein!
  • 
  • Nach erfolgreichen speichern, kehren Sie durch einen Klick auf Übersicht zur Übersicht zurück
• Die Anwendungs-ID-URI muss festgelegt werden. Standard Wert kann beibehalten werden.
  • 
  • Nach erfolgreichen speichern, kehren Sie durch einen Klick auf Übersicht zur Übersicht zurück

API-Berechtigungen

es sind keine speziellen Berechtigungen nötig. OBS fragt die nötigen Berechtigungen bei der Authentifizierung ab. Diese werden dann vom jeweiligen Benutzer bestätigt.

Siehe auch den Abschnitt Berechtigungen.

Zertifikate & Geheimnisse

Über einen Klick auf "+ Neuen geheimen Clientschlüssel" erhalten Sie ein können Sie einen neuen Schlüssel mit Namen und Gültigkeit definieren.

Mit der daraus erhaltenen "Geheimen ID" (App Secret ID) und der Anwendungs-ID (App ID) (in der Übersicht zu finden) können Sie die Einrichtung in OBS vornehmen.

Einrichtung Email-Konto OBS

Der nun angelegte API-Zugang wird in OBS in der Liste der Cloud-Connects (Stammdaten -> Z Weitere Stammmdaten -> Cloud-Connect) einmal angelegt und kann dann für E-Mail-Konten, Kallendersynchronisation und Personensynchronisation genutzt werden.

HINWEIS: mit neueren Version ist es nicht mehr nötig mehrere Cloud_Connect Api Einträge mit den Selbern API Key anzulegen. Wenn die API gleich bleibt, kann diese wieder verwendet werden

Beispiel zur Einrichtung eines Microsoft E-Mail-Kontos

1. in der OBS Liste Cloud Connect können Sie die oAuth2 Definitionen hinzufügen
   1. Dabei wählen Sie über den Cloud Typ den entsprechenden oAuth2 Typen aus. Weitere Infos im Abschnitt Definitionen
   2. 
2. Diesen Eintrag können Sie nun im E-Mail-Konto hinterlegen, wenn Sie als Authentifizierungsmethode oAuth2 ausgewählt haben.
   1. 
3. Authentifizieren und Zugangstoken erhalten
   1. Beim speichern der Daten öffnet sich Ihr Standard Browser. Hier werden Sie aufgefordert sich anzumelden und den oAuth2-Zugang zu genehmigen.
      1. 
      2. 
         1. Alternativ können Sie über die Schaltfläche Anmelden, eine Anmeldung erzwingen (um zum Beispiel vorhandene Daten zu überschreiben)
         2. Über die Schaltfläche Testen können Sie die hinterlegten Daten prüfen

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!

Definitionen

Bei der Einrichtung von oAuth2 sind bestimmte Daten notwendig, damit der korrekte Authentifikations-Dienst der jeweiligen Organisation (Google, Microsoft) angesprochen werden kann.

OBS gibt für bekannte Dienste die entsprechenden Daten bereits vor. Diese sind über F10 in der Liste der Cloud-Connects erreichbar.

HINWEIS: Hier sind auch andere Cloud-Typen zu finden. Die oAuth2 Typen sind vom Typ ctOAuth2

zu den nötigen Daten für die oAuth2 Konfiguration zählen unter anderem folgende Daten, welche im Netz zu finden sind:

• Authorisations Endpunkt (URL zum anmelde Dienst)
• Token Endpoint (URL um AcessTokens zu erhalten oder zu aktualisieren)
• Scope und weitere Daten

Sollte mal ein Anbieter nicht verfügbar sein, können Sie diese Daten manuell nach erfassen und nutzen.

ACHTUNG: die von OBS erstellten Einträge werden bei einem Update mit unseren Standard Werten überschrieben. Bitte bei Änderungen neue Einträge erstellen oder vorhandene mit F6 kopieren.

mehrinstanzenfähig (Multi-tannend)

Da wir im Standard die Endpunkte /common/ nutzen, müssen die erstellten 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/)

Berechtigungen

Alle von OBS benötigten Berechtigungen zum zugriff auf die jeweiligen Funktionen des Dienstes werden beim Anmelden in das Konto gesetzt und müssen vom Benutzer, der sich gerade anmeldet bestätigt werden.

Darüber hinaus sollten in der API keine weiteren Einstellungen gemacht werden müssen.

Wenn von OBS neue Berechtigungen benötigt werden, werden diese von OBS entsprechend bereit gestellt.

Bereits angemeldete Konten müssen dann aber unter Umständen neu gesetzt werden.

Bekannte Probleme

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 die oAuth2-Anmeldung nicht zum E-Mail Konto passt.

Mit dem Testen-Knopf im E-Mail Konto können Sie die zu Anmeldung genutzten Daten einsehen

Fehlende Berechtigungen

Es kann auch sein, dass IMAP für das entsprechende Konto deaktiviert ist.

Dieses muss über den Domänen-Administrator aktiviert werden.