Variante b: Manuelle Vergabe der API-Berechtigungen

Owned by h.elholm
Last updated: Nov. 23, 2023
8 min read

Alternativ zur Anbindung des aurenz Connectivity Services, wie in Variante a) beschrieben, können Sie auch die Berechtigungen, um über die GraphAPI auf die Teams-Daten zu kommen, selbst einrichten. Sie benötigen dazu Administrator Zugriff auf Ihr Microsoft Entra ID (früher Azure Active Directory). Gehen Sie dazu wie folgt vor:

 

Anmeldung am Microsoft Azure Portal

Rufen Sie dazu das Microsoft Azure Portal auf und melden Sie sich mit einem Administrator Account an:

App-Registrierung durchführen

Wählen Sie hier Azure Active Directory

Notieren Sie sich an dieser Stelle die Mandaten-ID. Diese wird später bei der Einrichtung in UC-Analytics/AlwinPro benötigt.

Für den Zugriff auf MS-Teams wird eine spezielle Berechtigung benötigt, die UC-Analytics/AlwinPro als Applikation ausweist und nicht als Anwender. Wählen Sie daher jetzt App-Registrierungen.

Wählen Sie jetzt Neue Registrierung um einen neuen Zugang für eine Applikation anzulegen

Geben Sie nun einen Namen für die Applikation ein. Wählen Sie als Kontotyp Nur Konten in diesem Organisationsverzeichnis. Klicken Sie anschließend auf Registrieren.

Ihnen wird jetzt eine Zusammenfassung der neuen Registrierung angezeigt. Notieren Sie sich hier schon einmal die Anwendungs-ID (Client). Diese wird später in AlwinPro benötigt.
Wählen Sie darin den Link Ein Zertifikat oder Geheimnis hinzufügen.

Als nächstes haben Sie die Auswahl, ob Sie ein Zertifikat hochladen möchten oder einen geheimen Clientschlüssel erstellen wollen. Wählen Sie hier Neuer geheimer Clientschlüssel.

Legen Sie jetzt einen Namen und eine Gültigkeitsdauer des geheimen Schlüssels fest.
Es ist nicht möglich einen Schlüssel zu erstellen, der dauerhaft gültig ist. Schlüssel müssen daher von Zeit zu Zeit neu erstellt und auch in UC-Analytics/AlwinPro aktualisiert werden.

Es werden jetzt der geheime Wert und die geheime ID des Schlüssel angezeigt. Kopieren Sie sich jetzt den geheimen Wert. Der geheime Wert kann zu einem späteren Zeitpunkt nicht mehr angezeigt werden. Sollten Sie den geheimen Wert verlieren, dann müssen Sie den geheimen Schlüssel löschen und einen neuen geheimen Schlüssel erzeugen.

Sie müssen jetzt folgende Werte notiert haben:

  • Mandanten-ID

  • Anwendungs ID (Client)

  • Geheimer Wert

Berechtigung hinzufügen

Im letzten Kapitel haben wir eine App Registrierung für den Zugang zu Microsoft Teams angelegt. Im nächsten Schritt muss dieser App jetzt das Recht für den Zugriff auf die Daten gewährt werden.

Wählen Sie jetzt API-Berechtigungen

Sie sehen jetzt die bereits bestehenden Berechtigungen. Diese reichen aber zum Abruf von Gesprächsdaten nicht aus. Wählen Sie daher Berechtigung hinzufügen.

Sie erhalten jetzt eine Auswahl aller Microsoft APIs, für die eine Berechtigung vergeben werden kann. Wählen Sie hier Microsoft Graph.

 

Da wir eine Berechtigung für eine Anwendung benötigen und nicht für einen Anwender, wählen Sie jetzt Anwendungsberechtigungen.

Sie erhalten jetzt eine Liste aller möglichen Berechtigungen. Hier müssen Sie drei Berechtigungen wählen:

  • CallRecords.Read.All

  • CallRecord-PstnCalls.Read.All

  • User.Read.All

Wenn Sie alle drei Berechtigungen markiert haben, klicken Sie bitte auf Berechtigungen hinzufügen.

 

Es wird jetzt wieder die Liste der vergebenen Berechtigungen angezeigt. Für die Berechtigungen wird angezeigt, dass die Berechtigung noch von einem Administrator bestätigt werden muss. Klicken Sie auf Administratorzustimmung erteilen um die Berechtigung wirksam werden zu lassen.

Der Status der Berechtigungen ändert sich jetzt auf gewährt.

Die Vergabe der Zugriffsrechte ist damit abgeschlossen und sie können sich vom Azure Portal abmelden.

Einrichtung von AlwinPro

Übersicht der drei MS Teams Anbindungs-Varianten

Microsoft Teams bietet drei Schnittstellen, über die man Gesprächsdaten abrufen kann:

  • Call Records Schnittstelle:
    Diese Schnittstelle liefert Teams-interne Kommunikationsdaten unabhängig des Anschlusses an das PSTN/ den ITSP. 

  • Direct Routing Calls Schnittstelle:
    Dies ist die korrekte Schnittstelle, wenn MS Teams Telefonie über einen Session Border Controller erfolgt (Direct Routing) 

  • PSTN Calls Schnittstelle:
    Dies ist die korrekte Schnittstelle, wenn MS Teams Telefonie über einen ITSP Anschluss bei Microsoft erfolgt (Operator Connect oder Dialplan) 

 

Einrichtung der Call Records Schnittstelle

Einrichtung des AlwinPro Teams Connectivity Server im lokalen Kundennetz

Die Einrichtung der AlwinPro Teams Connectivity Server ist nur dann notwendig, wenn Sie die Call Records Schnittstelle nutzen wollen. Bei Verwendung der Direct Routing Calls oder PSTN Calls Schnittstelle entfällt dieser Punkt.

Für den Betrieb von AlwinPro mit der Call Records Schnittstelle ist der AlwinPro Teams Connectivity Server notwendig. Dieser Server wird von Microsoft Teams über die IDs neuer Gesprächsdaten informiert. Dieser Server muss vom öffentlichen Internet und von der AlwinPro Installation aus erreichbar sein. Die Installation erfolgt daher in der Regel auf einem Server in der DMZ des Unternehmens und nicht auf dem AlwinPro Server.

  1. Erzeugen Sie auf dem DMZ-Server ein neues Verzeichnis und kopieren Sie dort den Inhalt des Verzeichnisses AlwinProTeamsServer von der AlwinPro Installations-CD hinein.

  2. Starten Sie AlwinProTeamsServer.exe als Administrator.

  3. Sie sehen jetzt die Einstellmöglichkeiten des Programms:

     

    Legen Sie hier als erstes den Port fest, über den der AlwinPro Teams Connectivity Server erreichbar ist. Ein HTTPS Port muss hier vergeben werden, da Microsoft zurzeit Gesprächsinformationen nur über HTTPS überträgt. Einen HTTP Port können Sie optional zusätzlich festlegen. Klicken Sie anschließend auf Einstellungen speichern.

  4. Für einen HTTPS Zugang ist ein SSL-Zertifikat notwendig. Klicken Sie daher auf SSL-Zertifikat

  5. Für ein SSL-Zertifikat wird ein privater Schlüssel benötigt. Im Auslieferungszustand ist zwar bereits ein privater Schlüssel mit einer Länge von 1024 Bit enthalten, sie sollten aber aus Sicherheitsgründen immer einen eigenen, privaten Schlüssel erzeugen. Wenn Sie eine höhere Sicherheit wünschen, so können Sie hier eine andere Länge des Schlüssels festlegen. Klicken Sie anschließend auf Erzeugen um den privaten Schlüssel zu erzeugen.

  6. Legen Sie im Feld Common Name den Namen fest, unter dem der AlwinPro Teams Connectivity Server vom Internet aus erreichbar ist. Achten Sie darauf, dass der Name wirklich exakt stimmt, sonst ist das Zertifikat später ungültig. Klicken Sie anschließend auf das darunter liegende Erzeugen. Es öffnet sich jetzt ein Fenster, in dem Sie Name und Ort für den erzeugten Zertifikatsrequest angeben können. Lassen Sie diesen Zertifikatsrequest von einer vertrauenswürdigen Zertifizierungsstelle signieren. Sie erhalten damit ein Zertifikat. Achten Sie darauf, dass das Zertifikat im PEM Format erstellt wird (Manchmal auch als Apache-Format bezeichnet). Andere Formate können vom AlwinPro Teams Connectivity Server nicht gelesen werden.

  7. (Optional) Es kann sein, dass die Zertifizierungsstelle von Ihnen verlangt, eine Datei zur Verifikation ihres Servers zur Verfügung zu stellen. Geben Sie dazu bei Web-Pfad den Pfad (ohne Server Namen) an, unter dem die Zertifizierungsstelle die Datei erwartet und laden Sie die Datei mit Hilfe der Upload Schaltfläche hoch. Schließen Sie jetzt die Zertifikatsverwaltung, speichern Sie die Einstellungen und starten Sie den Server, jedoch ohne HTTPS, da zurzeit noch kein gültiges Zertifikat vorhanden ist. Nach Abschluss der Verifikation durch die Zertifizierungsstelle, beenden Sie den Server, aktivieren Sie wieder HTTPS und kehren Sie zur Zertifikatsverwaltung zurück.

  8. Sobald Ihnen ein Zertifikat im PEM-Format vorliegt, Wählen Sie Laden und geben den Dateinamen des Zertifikats an. Das Zertifikat wird jetzt geprüft und im AlwinPro Teams Connectivity Server installiert. Schließen Sie anschließend das Fenster

  9. Sichern Sie jetzt die Dateien alwin.key und alwin.cert aus dem Installationsverzeichnis des AlwinPro Teams Connectivity Servers. Diese Dateien enthalten ihren privaten Schlüssel und ihr Zertifikat. Sollten Sie den AlwinPro Teams Connectivity Server aus irgendeinem Grund neu installieren müssen, müssen Sie auch diese beiden Dateien wieder herstellen, sonst ist ihr Zertifikat verloren und sie müssen ein neues beantragen.

  10. Nachdem Sie wieder ins Hauptfenster zurückgekehrt sind, wählen Sie Einstellungen testen. Sollte dieser Test erfolgreich sein, so können Sie fortfahren, ansonsten müssen Sie den gemeldeten Fehler erst beheben.

  11. Wählen Sie jetzt im Bereich Dienst die Auswahl Installieren.

  12. und im nächsten Schritt dann Starten.

  13. Überprüfen Sie jetzt, ob der Server auch wirklich aus dem Internet und von der AlwinPro Installation aus erreichbar ist. Geben Sie dazu die vergebene URL in einen Web Browser ein. Führen diesen Test unbedingt vom öffentlichen Internet und vom AlwinPro Server aus durch.
    Im Erfolgsfall erhalten Sie diese Anzeige:

  14. Der AlwinPro Teams Connectivity Server ist jetzt vollständig installiert. Fahren Sie nun mit der Einrichtung von AlwinPro fort.

Einrichtung der AlwinPro Datenquelle für die Call Record Schnittstelle

  1. Wählen Sie in der Datenaufnahme den Menüpunkt Telefonanlagen > Einstellen und anschließend den Punkt Neu. Wählen Sie nun die Microsoft Teams Datenquelle mit Graph-API

  2. Folgen Sie dem Assistenten und geben Sie die entsprechenden Daten ein

  3. Die Einstellungen der Datenquelle enthält eine Reihe von Registerkarten, wovon nur zwei spezifisch für Microsoft Teams sind:
    Verzeichnis Scannen: Hier wird das Verzeichnis angegeben, in dem die von Microsoft heruntergeladenen Gespräche zwischengespeichert werden, bevor sie verarbeitet werden. In der Regel können die Werte so belassen werden, wie sie sind.
    Microsoft Teams: Hier sind die Teams-Daten einzutragen

  4. Wählen Sie die Registerkarte Microsoft Teams. Wählen Sie dort als API Call Record.

     

    Die Werte für Mandanten ID, Anwendungs ID und Geheimer Wert entnehmen Sie aus den Einstellungen im Microsoft Azure-Portal, wie oben beschrieben. Für den Zugang zum AlwinPro Teams Connectivity Server geben Sie die jeweilige URL ein, die sie beim Test aus dem letzten Kapitel verwendet haben.

  5. Wählen Sie anschließend Test um die Einstellungen zu überprüfen.

  6. Nach erfolgreichem Test kann die Datenquelle für den Abruf von Daten verwendet werden.

Hinweis: Nach dem Führen eines Gesprächs werden die Daten von Microsoft an den AlwinPro Teams Connectivity Server übertragen. Das Übertragen der Daten erfolgt aber nicht sofort. In unseren Tests haben wir eine Verzögerung von bis zu 20 Minuten festgestellt, wobei die Verzögerung allerdings von Gespräch zu Gespräch stark unterschiedlich war.

Einrichtung der AlwinPro Datenquelle für die Direct Routing Call Schnittstelle oder PSTN Call Schnittstelle

  1. Wählen Sie in der Datenaufnahme den Menüpunkt Telefonanlagen > Einstellen und anschließend den Punkt Neu. Wählen Sie nun die Microsoft Teams Datenquelle mit Graph-API

  2. Folgen Sie dem Assistenten und geben Sie die entsprechenden Daten ein

  3. Die Einstellungen der Datenquelle enthält eine Reihe von Registerkarten, wovon nur zwei spezifisch für Microsoft Teams sind:
    Verzeichnis Scannen: Hier wird das Verzeichnis angegeben, in dem die von Microsoft heruntergeladenen Gespräche zwischengespeichert werden, bevor sie verarbeitet werden. In der Regel können die Werte so belassen werden, wie sie sind.
    Microsoft Teams: Hier sind die Teams-Daten einzutragen

  4. Wählen Sie die Registerkarte Microsoft Teams. Wählen Sie dort als API Direct routing calls bzw. PSTN Calls

     

    Die Werte für Mandanten ID, Anwendungs ID und Geheimer Wert entnehmen Sie aus den Einstellungen im Microsoft Azure-Portal, wie oben beschrieben.

  5. Wählen Sie anschließend Test um die Einstellungen zu überprüfen.

  6. Nach erfolgreichem Test kann die Datenquelle für den Abruf von Daten verwendet werden.

Hinweis; Microsoft bietet über diese Schnittstelle nicht die Möglichkeit "neue" Gespräche abzurufen. Deshalb werden bei jedem Abwurf alle Gespräche abgerufen, die in den letzten 24 Stunden begonnen haben. Gespräche, die bereits abgerufen wurden, werden anschließend verworfen. Dies bedeutet aber auch, dass Gespräche mit einer Dauer von mehr als 24 Stunden nicht erfasst werden können.

 

© aurenz GmbH 2022