Skip to main content

OAuth2 Profiles

OAuth (Open Authorization) 2.0 ist ein offenes Protokoll für eine standardisierte, sichere API-Autorisierung von Desktop-, Mobile- und Web-Anwendungen.

Damit KIX E-Mails bspw. von einem Office365 Mailkonto abrufen oder darüber versenden kann, muss eine OAuth2-Authentifizierung angewendet werden. Für den Versand muss möglicherweise SMTP mit Authentifizierung auf dem Konto bei Microsoft Office365 zuvor aktiviert werden.

Um die Authentifizierung in KIX bereit zu stellen, gehen Sie schrittweise wie nachfolgend beschrieben vor.

Für die Einrichtung zentralisierter Anmeldungen mittels OpenID Connect (OIDC) (z. B. via KeyCloak, Azure, GitLab o. ä.) können hier ebenfalls die Profile angelegt werden. Für diese ist keine Autorisierung notwendig.

Die Beispiel-Konfiguration für die Authentifizierung befindet sich im SysConfig-Schlüssel Authentication###000-OIDC.

Offizielle Hilfeseiten von Microsoft:

Schritt 1 - Microsoft Azure Portal

  1. Melden Sie sich auf dem Azure-Portal an.

  2. Rufen Sie Azure Active Directory auf.

  3. Wählen Sie in der Leiste Azure-Dienste die Option App-Registrierungen aus.

    Optional: Sie können die Suchfunktion im Seitenheader nutzen, um die App-Registrierungen zu suchen.

    OAuth2_AppRegistrierungen.png

    1. Wählen Sie den Punkt Neue Registrierung in der Menüleiste aus.

    2. Vergeben Sie einen beliebigen Anzeigenamen für die Registrierung. Dieser ist später für KIX nicht relevant.

    3. Geben Sie im Punkt Unterstützte Kontotypen an, wer die Anwendung verwenden kann.

      Setzen Sie die Auswahl auf Nur Konten in diesem Organisationsverzeichnis (nur <Firma> – einzelner Mandant).

      Hinweis: Anstelle von <Firma> sollte Ihr eigener Firmenname stehen.

    4. Für Umleitungs-URI ist im Auswahlfeld Web zu wählen und als URI <HttpType>://<FQDN>/ oauth2redirect einzutragen.

      Dies kann auch zu einem späteren Zeitpunkt eingetragen bzw. geändert werden.

      Die Umleitungs-URI entspricht dem Frontent-FQDN in KIX, z. B. https://myKIXFrontendHost.example.com/oauth2redirect.

      Hinweis

      Microsoft verlangt, dass die Redirect-URI auf HTTPS verweist

  4. Öffnen Sie in der linken Aktionsleiste den Menüeintrag Verwalten.

    OAuth2-Zertifikate-Geheimnisse.png

  5. Klicken Sie auf Zertifikate & Geheimnisse.

    Wählen Sie den Punkt Neuer geheimer Clientschlüssel aus und lassen Sie sich den Schlüssel in der rechten Sidebar erstellen.

    Merken bzw. notieren Sie sich den Schlüssel (Wert), denn er wird bei erneutem Aufruf nur teilweise angezeigt und muss sonst neu hinterlegt werden.

    Wichtig

    Es ist die Aufgabe des Administrators, dass für das Postfach ein gültiger Clientschlüssel (Gültigkeitsdauer max. 2 Jahre) im KIX hinterlegt ist.

  6. Für den Posteingang:

    1. Rufen Sie in der linken Aktionsleiste API-Berechtigungen auf.

    2. Klicken Sie dann auf Berechtigungen hinzufügen.

    3. Wählen Sie anschließend Microsoft Graph aus.

    4. Wählen Sie den Punkt Delegierte Berechtigungen aus.

    5. Wählen Sie an dieser Stelle IMAP.AccessAsUser.All sowie offline_access aus und bestätigen Sie die Auswahl.

      Diese wird nun in einer Tabelle angezeigt, wobei die Spalte Status leer bleibt (Standardwert).

    6. Erteilen Sie die Zustimmung des Administrators für den Vorgang

      (Feld Administratorzustimmung für <Ihre Firma> rechts neben Feld Berechtigung hinzufügen).

      Die Spalte Status in der Tabelle mit den ausgewählten Berechtigungen zeigt nun einen grünen Haken und den Zusatz gewährt für <Ihre Firma> .

    7. Führen Sie optional diese Schritte erneut durch, wenn Sie Berechtigungen hinzufügen möchten, z. B. für den Postausgang.

  7. Für den Postausgang:

    1. Rufen Sie in der linken Aktionsleiste API-Berechtigungen auf.

    2. Klicken Sie dann auf Berechtigungen hinzufügen.

    3. Wählen Sie anschließend Microsoft Graph aus.

    4. Wählen Sie den Punkt Delegierte Berechtigungen aus.

    5. Wählen Sie an dieser Stelle SMTP.Send sowie offline_access aus und bestätigen Sie die Auswahl.

      Diese wird nun in einer Tabelle angezeigt, wobei die Spalte Status leer bleibt (Standardwert).

    6. Erteilen Sie die Zustimmung des Administrators für den Vorgang

      (Feld Administratorzustimmung für <Ihre Firma> rechts neben Feld Berechtigung hinzufügen).

      Die Spalte Status in der Tabelle mit den ausgewählten Berechtigungen zeigt nun einen grünen Haken und den Zusatz gewährt für <Ihre Firma> .

    7. Führen Sie optional diese Schritte erneut durch, wenn Sie Berechtigungen hinzufügen möchten, z. B. für den Posteingang.

  8. Wählen Sie in der linken Aktionsleiste Übersicht aus.

    Merken bzw. notieren Sie sich die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant). Die Daten sehen Sie in der Zusammenfassung.

    Sie müssen diese ID im Feld Client ID angeben, wenn Sie in KIX ein OAuht2 Profil anlegen.

Schritt 2 - OAuth2-Profil anlegen

OAuth2-Profil_bearbeiten.png

Abb.: Beispielkonfiguration eines OAuth2 Profils in KIX

Wichtig

Bei der Erstellung und später der Authentifizierung des Profils, muss der Benutzer angelegt werden, der für das Postfach bzw. Mailversand verwendet werden soll.

Möchte man beispielsweise über 'mail@test.onmicrosoft.com' ein Postfach nutzen, so muss die Authentifizierung über diesen Benutzer erfolgen.

Ein abweichender Admin-User (bspw. 'admin@test.onmicrosoft.com') hat keine Berechtigung darauf.

Anmerkung

Das System (Backend) muss auf Authorisierungs-URL und Token URL zugreifen können (im Beispiel den Host https://login.microsoftonline.com/) .

Es ist bei Bedarf ein entsprechender Systemproxy zu konfigurieren. (SysConfig-Schlüssel WebUserAgent::Proxy)

  1. Navigieren Sie in KIX zu System > OAuth2 Profile.

    In der sich öffnenden Übersicht können Sie Profile anlegen, löschen oder einen Tabellen-CSV-Export ausführen. Die Tabelle enthält alle bisher angelegten Profile.

  2. Klicken Sie auf Neues Profil, um ein neues Profil anzulegen.

    Es öffnet sich ein Formular-Dialog, in dem Sie die Parameter des Profils angeben können.

  3. Füllen Sie alle Formularfelder aus:

    • Name: Geben Sie einen Namen für das Profil ein.

    • Authorisierungs-URL: Tragen Sie die URL für die OAuth2-Authorisierung ein. Sie wird zum Starten der Anfrage verwendet.

      Beispiel für den Aufbau bei Office365:

      https://login.microsoftonline.com/<Tenant-ID/Verzeichnis-ID>/oauth2/v2.0/authorize 

    • Token-URL: Tragen Sie die URL für die OAuth2-Token ein.

      Sie wird zum Einholen des Zugriffstoken bzw. Refresh-Token verwendet.

      Beispiel für den Aufbau bei Office365:

      https://login.microsoftonline.com/<Tenant-ID/Verzeichnis-ID>/oauth2/v2.0/token 

    • Weiterleitungs-URL: Dieses Feld wird vom System vor ausgefüllt.

      Sollte die Adresse nicht deckungsgleich mit der im Azure-Portal angegebenen sein (Schritt 1 - Punkt 3 - Unterpunkt 5) muss sie entsprechend geändert werden.

    • Client ID: Tragen Sie hier die Client ID ein.

      Für Office365 ist das die "Anwendungs-ID (Client)" aus der Übersicht im Azure ein.

    • Client Secret: Tragen Sie hier das Client-Secret ein.

      Für Office365 ist das der Clientschlüssel aus Zertifikate & Geheimnisse im Azure ein.

    • Scope: Hinterlegen Sie hier die anzufordernden Berechtigungen (durch Leerzeichen getrennt)

      Beispiele für Office365:

      • offline_access https://outlook.office.com/SMTP.Send

      • offline_access https://outlook.office.com/ IMAP.AccessAsUser.All

    • Gültigkeit: Setzen Sie das Formular auf gültig, um es verwenden zu können.

  4. Klicken Sie abschließend auf Speichern, um das Formular zu speichern.

  5. Klicken Sie in der Übersicht der Profile in der Spalte Autorisierung erneuern auf .

    Nach der Übermittlung erfolgt eine automatische Weiterleitung zu Microsoft, um die benötigten Berechtigungen freizugeben und einen Code zur Authentifizierung des Systems anzufordern.

    Dazu ist eine https-Verbindung zwingend erforderlich! 

    Bei der Authentifizierung des Profils muss der oben angelegte Nutzer, für den der Token erstellt wurde, verwendet werden.

    OAuth_Berechtigungen.jpeg

  6. Wenn die Berechtigungen akzeptiert wurden, erhalten Sie eine positive Bestätigung.

War die Token-Anfrage erfolgreich, dann befindet sich in der Übersicht der Profile ein Haken in der vorletzten Spalte. Der Haken kennzeichnet dabei nur, dass ein Token (Access- und/oder Refresh-Token) vorhanden ist, jedoch nicht, ob diese (auf Seiten von Microsoft) noch gültig sind. Ändert Sie zum Beispiel die Berechtigungen in Azure, muss die Token-Anfrage erneut durchgeführt werden.

Schritt 3 - E-Mail-Konto anlegen

  1. Navigieren Sie in KIX zu Kommunikation > E-Mail > Posteingang.

  2. Klicken Sie in der Tabelle auf Neues Konto.

    Es wird ein Formular-Dialog geöffnet, in dem Sie das E-Mail- Konto anlegen können.

  3. Wählen Sie unter Typ eine Option, welche auf _OAuth2 endet.

    Hinweis: IMAPTLS_OAuth2 wird von Office365 nicht mehr unterstützt.

    Nach dieser Auswahl wird das Profilfeld angezeigt. Das Passwortfeld wird ausgeblendet, da es nicht benötigt wird.

  4. Wählen Sie unter OAuth2 Profil das im KIX angelegte Profil aus (s. Schritt 2 - OAuth2-Profil anlegen)

  5. Füllen Sie die restlichen Formularfelder aus und speichern Sie das Mailkonto.

    Lesen Sie hierzu ggf. unter Posteingang nach.

Schritt 4 - Mailversand konfigurieren

  1. Navigieren Sie zu Kommunikation > E-Mail > Postausgang.

    Es wird ein Formular-Dialog geöffnet, in dem Sie den Postausgang konfigurieren können.

  2. Das Formular besitzt im Feld Typ die Eigenschaften SMTP OAuth2, SMTPS OAuth2 sowie SMTPTLS OAuth2.

    Hinweis: In Verbindung mit Microsoft muss SMTPTLS OAuth2 verwendet werden. Andere Typen werden nicht akzeptiert.

  3. Wie beim Posteingang wird je nach gewähltem Typ entweder das OAuth2 Profile-Feld oder das Passwort-Feld angezeigt. Wählen Sie das in KIX angelegte Profil aus (s. Schritt 2 - OAuth2-Profil anlegen)

  4. Füllen Sie die restlichen Formularfelder aus und klicken Sie anschließend auf Speichern.

    Lesen Sie hierzu ggf. unter Postausgang nach.

Wichtig

Das Profil wird im SysConfig-Schlüssel SendmailModule::OAuth2_Profile gespeichert.

Wird das Profil umbenannt, muss das Profil in der Konfiguration des Postausgangs oder direkt in der SysConfig erneut gesetzt werden!

In diesem Abschnitt: