Du nutzt Microsoft Teams für die interne Kommunikation und betreibst gleichzeitig externe Services wie beispielsweise AWS-Services? Dann interessiert dich vielleicht, wie du diese beiden Tools effektiv miteinander verbinden kannst. In diesem Blogartikel erkunden wir nicht nur die Vorteile dieser Verbindung, sondern bieten dir auch eine schrittweise Anleitung zur Integration von Microsoft Teams und externen Diensten.

‍

Vorteile der Integration

Die Verknüpfung von IT-Services mit Microsoft Teams bietet zahlreiche Vorteile für eine effiziente Zusammenarbeit in technischen Umgebungen. Eine Möglichkeit ist zum Beispiel der Versand von Alarm-Nachrichten aus einem IT-Service heraus direkt an einen MS Teams-Kanal, was eine schnelle Reaktion des Dev-Teams ermöglicht und die Anzahl der erforderlichen Tools reduziert.

Auch der umgekehrte Weg, eine Nachrichtenübermittlung aus Microsoft Teams heraus an externe IT-Systeme, ist möglich. Damit wird die Steuerung von Services oder die (einfache) Übermittlung von Daten ohne Toolwechsel ermöglicht.

‍

Schritte zur Integration

MS Teams kann über Webhooks mit anderen Services verbunden werden. Dabei spielt es keine Rolle, ob es sich um Cloud Services oder lokal gehostete Server handelt, solange HTTP POST-Requests verarbeitet werden können. Mit ausgehenden Webhooks können Befehle an Dienste gesendet werden, die wiederum mit Nachrichten und Multimedia-Karten antworten, sodass reaktives Messaging ermöglicht wird. Eingehende Webhooks hingegen erlauben Benutzern, Nachrichten von externen Webdiensten zu empfangen.

‍

Erstellung ausgehender Webhooks

Die Konfiguration von Webhooks erfolgt in MS Teams auf Ebene eines Teams. Jedes Setup fügt einen neuen ausgehenden Webhook hinzu. Für reaktives Messaging benötigst du die Verwendung von “@Erwähnung”, was derzeit nur in öffentlichen Kanälen funktioniert. Bei Standard-HTTP-Nachrichtenaustausch werden Antworten direkt bei der ursprünglichen Nachricht angezeigt und können verschiedene Inhalte des Bot-Frameworks enthalten, wie z.B. Rich-Text, Bilder, Karten und Emojis. Beachte, dass ausgehende Webhooks eine HTTP POST-Anfrage an einen Webdienst senden und eine Antwort erhalten. Der Zugriff auf andere APIs ist jedoch eingeschränkt.
Um einen ausgehenden Webhook einzurichten, befolge in MS Teams folgende Schritte:

‍

1. Wähle “Teams” im linken Bereich.
2. Navigiere zum gewünschten Team und klicke auf “•••”.
3. Im Dropdown-Menü wähle “Team verwalten” aus.
4. Gehe zur Kanalseite und navigiere zu “Apps”.
5. Unter “App hochladen” findest du die Option für die Erstellung eines ausgehenden Webhooks.
6. Gib alle erforderlichen Details ein (Name, Rückruf-URL und Beschreibung) und bestätige den Dialog.
7. Du erhältst dann einen Sicherheitstoken zur Authentifizierung beim externen Service.
8. ‍

Um sicherzustellen, dass dein Dienst nur Anrufe von autorisierten MS Teams-Clients empfängt, wird ein HMAC-Code im HTTP-HMAC-Autorisierungsheader bereitgestellt. Dein Service sollte dieses Sicherheitstoken überprüfen, um die Zulässigkeit der Anfrage sicherzustellen.

‍

Erstellung eingehender Webhooks

Im Gegensatz zu ausgehenden Webhooks, bei denen der Anwender die Kommunikation initiiert, ermöglichen eingehende Webhooks externen Diensten, proaktiv in Nachrichten an MS Teams zu senden. Diese Nachrichten werden ebenfalls über HTTP POST versandt und können verschiedene Formate wie Texte, Bilder und Karten annehmen. Du kannst dabei Design-Tools wie den Adaptive Cards Designer und das Teams Developer Portal verwenden.

Um einen eingehenden Webhook einzurichten, befolge in MS Teams die folgenden Schritte:

1. Wähle “Teams” im linken Bereich.
2. Navigiere zum gewünschten Team und klicke auf “•••”.
3. Im Dropdown-Menü wähle “Team verwalten” aus.
4. Gehe zur Kanalseite und navigiere zu “Apps”.
5. Auf der Seite “Apps” wählst du “Incoming Webhook” bzw. “Eingehenden Webhook erstellen” (dafür musst du Besitzer des Teams sein).
6. Gib dem Webhook einen Namen (und lade optional ein Bild hoch) und klicke auf “Erstellen”.
7. Anschließend erhältst du eine generierte URL, über die der Kanal erreichbar wird.
8. ‍

Die Authentifizierung bei eingehenden Webhooks in Microsoft Teams erfolgt durch die Verwendung eines generierten URL-Links, der vertraulich behandelt werden sollte.

‍

Anwendungsbeispiel

Um die umfassenden Anwendungsmöglichkeiten der Integration zu verdeutlichen, zeigen wir im Folgenden zwei Beispiele, die Aclue erfolgreich bei Kunden implementiert hat.

Anwendungsbeispiel für ausgehende Webhooks

Ausgangsbasis ist ein Lieferantenportal, in dem das Team, das die Verwaltung der Lieferanten-Website übernimmt, die Lieferanten über Neuigkeiten informieren möchte. Dazu nutzen sie einen von ihnen verwalteten Kanal und sprechen den Service durch Erwähnung im Teams-Chat an (“@News-Bot”). Der Bot – also der angesprochene Service – antwortet daraufhin mit einem entsprechenden Formular (“Action Card”), welches das Team direkt im Chat ausfüllen und versenden kann. Diese Antwort wird zurück an den Service geschickt, der sie auf der Website des Lieferantenportals angezeigt.

‍
Das Ergebnis sieht wie folgt aus:

‍

‍

Wenn die Lieferantenbetreuer im MS Teams-Chat “@News-Bot” erwähnen, wird der Endpunkt angesprochen, der bei der Einrichtung des ausgehenden Webhooks unter “Callback URL” angegeben wurde. Dieser führt zu Beginn der Request-Verarbeitung eine Authentifizierung durch. Hierbei wird die Echtheit der Anfrage mittels einer HMAC-Signatur im “Authorization”-Header überprüft. Diese Signatur wird durch Verwendung des gemeinsamen Sicherheitstokens erstellt. Bei einer gültigen Signatur erfolgt eine Reaktion auf die Anfrage.

‍

Der Code zur Authentifizierung kann in Java wie folgt aussehen:

				
					import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AuthProvider {
    private static final String SIGNING_KEY = "erhaltenerSicherheitstoken";

    public static AuthResponse validate
    (String providedHmacValue, String messageContent) {
        String calculatedHmacValue = computeHmac(messageContent);

        if (providedHmacValue.equals(calculatedHmacValue)) {
            return new AuthResponse(true, null);
        } else {
            throw new RuntimeException("AuthHeaderValueMismatch. Not Authorized!");
        }
    }

    private static String computeHmac(String messageContent) {
        try {
            byte[] serializedPayloadBytes = messageContent.getBytes("UTF-8");
            byte[] keyBytes = Base64.getDecoder().decode(SIGNING_KEY);
            SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, "HmacSHA256");

            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(secretKeySpec);

            byte[] hashBytes = mac.doFinal(serializedPayloadBytes);
            return Base64.getEncoder().encodeToString(hashBytes);
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            throw new RuntimeException("Error while verifying HMAC.", e);
        }
    }
}

				
			

‍

Sobald die Authentifizierung erfolgreich ist, bereitet das System das Formular vor und gibt es als Response zurück an MS Teams. In unserem Beispiel setzen wir das Formular als Action Card um. Dadurch können alle Felder direkt im Formular ausgefüllt werden und die eingegebenen Informationen können anschließend über die “Submit”-Aktion an eine vordefinierte URL gesendet werden.Die Action Card wird in JSON definiert. Der Code für das oben dargestellte Formular sieht wie folgt aus:

				
					import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class AuthProvider {
    private static final String SIGNING_KEY = "erhaltenerSicherheitstoken";

    public static AuthResponse validate
    (String providedHmacValue, String messageContent) {
        String calculatedHmacValue = computeHmac(messageContent);

        if (providedHmacValue.equals(calculatedHmacValue)) {
            return new AuthResponse(true, null);
        } else {
            throw new RuntimeException("AuthHeaderValueMismatch. Not Authorized!");
        }
    }

    private static String computeHmac(String messageContent) {
        try {
            byte[] serializedPayloadBytes = messageContent.getBytes("UTF-8");
            byte[] keyBytes = Base64.getDecoder().decode(SIGNING_KEY);
            SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, "HmacSHA256");

            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(secretKeySpec);

            byte[] hashBytes = mac.doFinal(serializedPayloadBytes);
            return Base64.getEncoder().encodeToString(hashBytes);
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            throw new RuntimeException("Error while verifying HMAC.", e);
        }
    }
}

				
			

‍

Anwendungsbeispiel für eingehende Webhooks

Für einen Kunden im E-Commerce-Bereich wurde eine Webhook-Integration implementiert, um das Team des Online-Shops über erwartete Spitzenlasten zu informieren, die durch App-Push-Kampagnen ausgelöst werden könnten. Die Benachrichtigung an Microsoft Teams wird automatisch ausgelöst, wenn die Anzahl der Empfänger einen vordefinierten Schwellwert überschreitet. In diesem Fall wird eine JSON-Nachricht über einen POST-Request an den zuvor erstellten Webhook-Endpunkt gesendet.
Die genaue Struktur der Nachricht sowie des zugehörigen JSON-Formats sind nachfolgend dargestellt:

‍

				
					{
    "type": "message",
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "content": {
                "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
                "type": "AdaptiveCard",
                "version": "1.2",
                "body": [
                    {
                        "type": "TextBlock",
                        "id": "titel",
                        "text": "**News veröffentlichen**",
                        "size": "Large"
                    },
                    {
                        "type": "Input.Text",
                        "id": "TitelDerNews",
                        "placeholder": "Titel der News"
                    },
                    {
                        "type": "Input.Text",
                        "id": "InhaltDerNews",
                        "placeholder": "Inhalt der News"
                    },
                    {
                        "type": "ActionSet",
                        "id": "Submit",
                        "actions": [
                            {
                                "type": "Action.Submit",
                                "id": "publishNews",
                                "title": "veröffentlichen",
                                "url": "https://receivingEndpoint.de",
                                "body": "{\"TitelDerNews\": \"{{TitelDerNews.value}}\", \"InhaltDerNews\":\"{{InhaltDerNews.value}}\" }",
                                "data": {
                                    "action": "publishNews"
                                }
                            }
                        ]
                    }
                ],
                "padding": "None"
            }
        }
    ]
}
				
			

‍

Fazit und Ausblick

Zusammenfassend hat die Integration von Microsoft Teams in externe Dienste unsere Arbeit erleichtert und die Anzahl der benötigten Tools reduziert, was definitiv eine positive Entwicklung darstellt. Jedoch bringt die Implementierung von Action Cards eine spezifische Herausforderung mit sich, da die korrekte Erstellung und Formatierung des JSON-Codes komplex sein kann und ggf. bei bestimmten MS Teams-Versionen unerwartete Anzeigeprobleme verursacht. Daher ist ausführliches Testen essentiell.

‍

Für die Zukunft sehen wir weiterhin Potenzial, unsere Arbeitsproduktivität zu steigern, und neue, kreative Möglichkeiten zu erkunden. Es eröffnen sich Chancen, effizienter zu kommunizieren und Arbeitsprozesse weiter zu optimieren.