Vermittlungsplatz als Teams-App bereitstellen

Wozu dient das

Vermittlungskräfte, die den ganzen Tag in Microsoft Teams arbeiten, können den EasyUC-Vermittlungsplatz direkt dort öffnen. Dazu wird der Vermittlungsplatz als persönliche, tenant-interne Teams-App bereitgestellt. Teams lädt die Seite des Vermittlungsplatzes als Tab in der App-Leiste.

Die Anmeldung läuft über das aktive Teams-Konto: Der Benutzer klickt Mit Teams anmelden, Teams stellt ein Zugriffstoken für den bereits angemeldeten Benutzer aus, EasyUC prüft es und öffnet die Sitzung des Vermittlungsplatzes. Das Kennwort des Benutzers wird nicht an EasyUC übertragen.

Das App-Paket ist eine ZIP-Datei mit einem Manifest und zwei Symbolen. Es enthält keine Kennwörter, Clientschlüssel oder Token. EasyUC-Hostname, Client-ID und die Adressen von Datenschutzerklärung und Nutzungsbedingungen sind öffentliche Angaben.

Voraussetzungen

• Lizenzmodule acd (Vermittlungsplatz) und teams.
• Ein vollständiger DNS-Name für EasyUC, zum Beispiel easyuc.kunde.de, mit HTTPS auf Port 443 und einer öffentlich vertrauenswürdigen Zertifikatskette. Reine IP-Adressen und selbstsignierte Zertifikate eignen sich nicht für einen Teams-Tab.
• Erreichbare Seiten für Datenschutz und Nutzungsbedingungen über HTTPS.
• Im Microsoft-Tenant des Kunden das Recht, eine App-Registrierung anzulegen und eine benutzerdefinierte Teams-App hochzuladen und freizugeben.
• In EasyUC ist der Teams-Tenant des Kunden angelegt und aktiv, mit Verzeichnis-ID (Tenant-ID) und Anwendungs-ID (Client-ID). EasyUC prüft das Teams-Token gegen diese beiden Werte.
• Die Vermittlungskräfte sind als aktivierte Attendants eingetragen und ihrem Microsoft-Konto zugeordnet (Kapitel „Attendants und Geräte zuordnen“).
• Der Paket-Generator aus dem EasyUC-Lieferumfang (tools/teams-attendant-app) und Python 3 auf einem Arbeitsrechner.

Schritt für Schritt: App-Registrierung für die Teams-Anmeldung vorbereiten

1. Öffnen Sie im Microsoft Entra Admin Center Identity → Applications → App registrations und die App-Registrierung, deren Anwendungs-ID in EasyUC am Tenant hinterlegt ist. Legen Sie andernfalls mit New registration eine an und tragen Sie ihre ID am Tenant ein.
2. Setzen Sie im Manifest der Entra-App unter api den Wert requestedAccessTokenVersion auf 2.
3. Legen Sie unter Expose an API die Application ID URI in der Form api://EASYUC-HOSTNAME/CLIENT-ID an, zum Beispiel api://easyuc.kunde.de/00000000-0000-0000-0000-000000000000.
4. Erstellen Sie dort einen delegierten Scope mit dem Namen access_as_user, Zustimmung durch Administratoren und Benutzer, Zustand aktiviert.
5. Tragen Sie unter Authorized client applications die beiden Teams-Clients von Microsoft ein: 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams Desktop und Mobile) und 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams Web). Autorisieren Sie für beide den Scope.
6. Für diese Anmeldung sind keine Microsoft-Graph-Berechtigung und kein Clientschlüssel nötig.

Schritt für Schritt: App-Paket erzeugen und prüfen

1. Wechseln Sie auf dem Arbeitsrechner in das Verzeichnis des EasyUC-Lieferumfangs.
2. Erzeugen Sie das Paket: python3 tools/teams-attendant-app/generate-package.py --fqdn easyuc.kunde.de --client-id CLIENT-ID --privacy-url https://www.kunde.de/datenschutz --terms-url https://www.kunde.de/nutzungsbedingungen.
3. Die ZIP-Datei liegt danach unter tools/teams-attendant-app/dist/. Sie enthält genau manifest.json, color.png und outline.png.
4. Prüfen Sie das Paket: python3 tools/teams-attendant-app/validate-package.py gefolgt vom Pfad der ZIP-Datei.

Schritt für Schritt: App in Teams hochladen und freigeben

1. Öffnen Sie das Teams Admin Center des Kunden.
2. Wählen Sie Teams apps → Manage apps.
3. Öffnen Sie Actions → Upload new app und laden Sie die ZIP-Datei hoch.
4. Geben Sie die App für die Gruppe der Vermittlungskräfte frei.
5. Optional heften Sie die App über eine Setup Policy in der App-Leiste an.
6. Der Benutzer öffnet in Teams die App EasyUC Attendant. Sie erscheint unter den Apps der eigenen Organisation.
7. Der Benutzer klickt auf der Seite Vermittlungsplatz in Microsoft Teams auf Mit Teams anmelden. Der Vermittlungsplatz öffnet sich.

Schritt für Schritt: Paket aktualisieren

1. Erzeugen Sie das Paket mit derselben Client-ID und einer höheren Version, zum Beispiel --version 4.5.1. So behält die App ihre Identität.
2. Prüfen Sie die neue ZIP-Datei mit validate-package.py.
3. Laden Sie sie im Teams Admin Center als Update der bestehenden App hoch.

Felder und Optionen

Ergebnis prüfen und Fehler eingrenzen

• Erfolg: Die App erscheint in Teams, der Tab lädt die Anmeldeseite, und nach Mit Teams anmelden öffnet sich der Vermittlungsplatz ohne Kennworteingabe.
• Tab wird nicht geladen: Prüfen Sie HTTPS-Zertifikat und DNS des EasyUC-Hostnamens und ob der Hostname im Paket exakt stimmt.
• Teams meldet eine falsche Ressource: Vergleichen Sie die Application ID URI in Microsoft Entra Zeichen für Zeichen mit api://EASYUC-HOSTNAME/CLIENT-ID.
• „Die Anmeldung mit Ihrem Microsoft-Teams-Konto ist fehlgeschlagen. Bitte versuchen Sie es erneut.“ Prüfen Sie den Scope access_as_user, die beiden vorautorisierten Teams-Clients und ob Verzeichnis-ID und Anwendungs-ID am EasyUC-Tenant zu dieser Entra-App gehören.
• „Dieses Microsoft-Konto ist nicht für den Vermittlungsplatz freigeschaltet.“ Der Benutzer ist kein aktivierter Attendant oder seinem Microsoft-Konto nicht zugeordnet.
• „Die Microsoft-Anmeldung ist noch nicht vollständig eingerichtet. Bitte wenden Sie sich an die Verwaltung.“ Für die Verzeichnis-ID gibt es in EasyUC keinen eindeutigen aktiven Tenant.
• „Die Microsoft-Anmeldung ist in dieser Installation nicht verfügbar.“ Das Teams-Modul ist nicht aktiv.
• „Der Vermittlungsplatz konnte in Microsoft Teams nicht initialisiert werden. Bitte öffnen Sie ihn erneut in Teams.“ Schließen Sie den Tab und öffnen Sie die App neu.
• Hochladen wird abgelehnt: Prüfen Sie mit validate-package.py und kontrollieren Sie die App-Verwaltungsrichtlinie des Tenants für benutzerdefinierte Apps.