Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Sie können die Antworten adaptiver Karten in deklarativen Agents für Microsoft 365 Copilot verbessern, indem Sie modale Dialogfelder hinzufügen. Diese Popupdialogfelder können benutzerdefiniertes HTML/JavaScript hosten oder iframebasierte Widgets – z. B. Webseiten, YouTube-Videos oder Microsoft Stream-Inhalte – in einer fokussierten, interaktiven Erfahrung anzeigen.
In diesem Artikel wird beschrieben, wie Action.OpenUrlDialog modale Dialogfelder aus adaptiven Kartenvorlagen gestartet werden (verfügbar im adaptiven Kartenschema Version 1.5) und wie die Benutzerauthentifizierung konfiguriert wird.
Hinweis
Die OpenUrlDialog Aktion befindet sich derzeit in der Vorschau.
Voraussetzungen
Für die Verwendung Action.OpenUrlDialogvon sind die folgenden Voraussetzungen erforderlich:
- Adaptive Kartenschema, Version 1.5
- API-Plug-In-Manifest Version 2.3
- Microsoft TeamsJS-Bibliothek (für Authentifizierungsszenarien)
Definieren der adaptiven Kartenvorlage
So verwenden Sie die modale Dialogfeldaktion:
- Fügen Sie die Adaptive Card-Vorlage zu Ihrem Plug-In-Manifest hinzu.
- Fügen Sie das
Action.OpenUrlDialogSchema in die Definition der adaptiven Karten ein.
Das folgende Beispiel zeigt das Schema für Action.OpenUrlDialog.
"actions": [
{
"type": "Action.OpenUrlDialog",
"title": "OpenDialogWithDimension",
"url": "${url}",
"dialogHeight": "large",
"dialogWidth": "600px",
"dialogTitle": "task module"
}
]
Informationen zur Schemareferenz finden Sie unter Action.OpenUrlDialog.
Größe des Dialogfelds konfigurieren
Verwenden Sie die Eigenschaften dialogHeight und dialogWidth , um die Höhe und Breite des Dialogfelds festzulegen. Diese Werte passen sich dynamisch an die Bildschirmauflösung des Benutzers und die Größe des Fensters an.
Sie können Folgendes angeben:
- Vordefinierte Größen -
small,medium, oderlarge. - Benutzerdefinierte Pixelwerte,
400pxz. B. .600px.
Tipp
Verwenden Sie Pixelwerte für eine präzise Steuerung. Vordefinierte Größen sind relativ zur verfügbaren Bildschirmfläche.
Die folgende Abbildung zeigt ein Beispiel für ein Dialogfeld, das von einer adaptiven Kartenschaltfläche aufgerufen wird, die von einem Agent zurückgegeben wird.
Authentifizierung konfigurieren
Um den sicheren Zugriff auf APIs aus dem Dialogfeld heraus zuzulassen, konfigurieren Sie die Authentifizierung mit einer der folgenden Methoden:
- Microsoft Entra ID
- OAuth 2.0 (Vorschau)
Setup der Microsoft Entra ID
Verwenden Sie einen der folgenden Ansätze, um die Entra-ID-Authentifizierung für die API-Authentifizierung zu verwenden:
- Konfigurieren Sie die Authentifizierung mit Entra-ID, OAuth 2.0 oder API-Schlüssel unter Verwendung von Microsoft als Identitätsanbieter.
- Verwenden Sie einen anderen Identitätsanbieter, und registrieren Sie Ihre App in Entra ID.
SSO-basierte Authentifizierung konfigurieren
Konfigurieren Sie einmaliges Anmelden (Single Sign-On, SSO), damit Benutzer auf APIs zugreifen können, ohne sich mehrmals anmelden zu müssen.
So aktivieren Sie SSO:
- Aktualisieren Sie die Anwendung "Microsoft Entra ID".
- Konfigurieren Sie den Anwendungs-ID-URI.
- Konfigurieren Sie Bereiche und Zustimmungseinstellungen.
- Führen Sie eine Vorautorisierung vertrauenswürdiger Clientanwendungen durch, um wiederholte Zustimmungsaufforderungen zu vermeiden.
- Implementieren Sie Tokenabruf- und Validierungslogik.
- Verwenden Sie die
getAuthToken()Methode aus der TeamsJS-Bibliothek, um ein Zugriffstoken abzurufen. - Senden Sie das Token im Autorisierungsheader an Ihren Server.
- Überprüfen Sie das Token serverseitig.
- Verwenden Sie die
- Aktualisieren Sie das App-Manifest.
- Fügen Sie dem App-Manifest die webApplicationInfo-Eigenschaft hinzu, um SSO zu aktivieren.
- Fügen Sie die Domäne des Dialogfeldinhalts der validDomains-Eigenschaft des App-Manifests hinzu.
Aktualisieren der Anwendung "Microsoft Entra ID"
Aktualisieren Sie Ihre Microsoft Entra ID-Anwendung wie folgt, um Bereiche zu konfigurieren und vertrauenswürdige Clientanwendungen zu autorisieren:
Fügen Sie der identifierUris-Eigenschaft des App-Manifests einen API-URI hinzu. Verwenden Sie für die URI das folgende Format: 'api://fully-qualified-domain-name.com/{AppID}, wie im folgenden Beispiel gezeigt.
"identifierUris": [ "api://b4ab3a28-16da-4a19-a07a-51ab0f3553db", "api://4-213-70-45.ngrok-free.app/b4ab3a28-16da-4a19-a07a-51ab0f3553db", "api://auth-58bfdecc-2870-4cda-99b4-1d30383b952b/b4ab3a28-16da-4a19-a07a-51ab0f3553db" ],Definieren Sie den Bereich für die API und wer dem Bereich zustimmen kann. Wählen Sie im AbschnittBereiche, die von dieser API definiert werden, des Microsoft Entra Admin Center die Option + Bereich hinzufügen aus.
- Geben Sie den Bereichsnamen ein. Dieses Feld ist erforderlich.
- Wählen Sie den Benutzer aus, der die Zustimmung für diesen Bereich erteilen kann. Die Standardoption ist "Nur Administratoren".
- Geben Sie den Anzeigenamen für die Admin-Zustimmung ein. Dieses Feld ist erforderlich.
- Geben Sie die Beschreibung für die Administratoreinwilligung ein. Dieses Feld ist erforderlich.
- Geben Sie den Anzeigenamen für die Benutzereinwilligung ein.
- Geben Sie die Beschreibung für die Beschreibung der Benutzereinwilligung ein.
- Wählen Sie im Feld "Status " die Option "Aktiviert" für "Status" aus.
- Wählen Sie Bereich hinzufügen aus.
Erstellen Sie autorisierte Client-IDs für Anwendungen, die Sie vorautorisieren möchten. Dadurch kann der App-Benutzer ohne zusätzliche Zustimmung auf die von Ihnen konfigurierten App-Bereiche (Berechtigungen) zugreifen. Da App-Benutzer nicht die Möglichkeit haben, die Zustimmung abzulehnen, sollten Sie nur Clientanwendungen vorautorisieren, denen Sie vertrauen.
Wählen Sie im Abschnitt Authorized client application des Microsoft Entra Admin Center die Option + Clientanwendung hinzufügen aus.
Geben Sie die Microsoft 365-Client-ID für die Anwendungen ein, die Sie autorisieren möchten.
Implementieren einer Logik zum Abrufen und Überprüfen von Token
Fügen Sie Code zur Verarbeitung des Zugriffstokens hinzu, senden Sie das Token im Autorisierungsheader an den Servercode Ihrer App, und überprüfen Sie das Zugriffstoken, wenn es empfangen wird.
Um App-Zugriff für den aktuellen App-Benutzer zu erhalten, muss Ihr clientseitiger Code Teams aufrufen, um ein Zugriffstoken abzurufen. Aktualisieren Sie den clientseitigen Code, um den Validierungsprozess zu initiieren getAuthToken() , wie im folgenden Beispiel gezeigt.
// Get auth token
// Ask Teams to get us a token from AAD
function getClientSideToken() {
return new Promise((resolve, reject) => {
display("1. Get auth token from Microsoft Teams");
microsoftTeams.authentication.getAuthToken().then((result) => {
display(result);
resolve(result);
}).catch((error) => {
reject("Error getting token: " + error);
});
});
}
Wenn Teams das Zugriffstoken erhält, wird das Token zwischengespeichert, um es bei Bedarf wiederzuverwenden. Das Token wird beim Aufruf verwendet, ohne getAuthToken() dass ein weiterer Aufruf an Microsoft Entra ID erfolgen muss, bis das Token abläuft.
Zustimmung des Benutzers zum Dialogfeld
Wenn Sie anrufen getAuthToken() und die Zustimmung des Benutzers für Berechtigungen auf Benutzerebene erforderlich ist, wird dem angemeldeten Benutzer ein Microsoft Entra Dialogfeld angezeigt, und der Benutzer muss einmal seine anfängliche Zustimmung erteilen.
Nachdem der Benutzer zugestimmt hat, kann er auf die Webseite des Dialogfelds zugreifen. Für die Nutzereinwilligung gelten folgende Punkte:
- Wenn der Administrator die Zustimmung im Namen des Mandanten erteilt hat, müssen App-Benutzer nicht zur Zustimmung aufgefordert werden. Dies bedeutet, dass den App-Benutzern das Zustimmungsdialogfeld nicht angezeigt wird und sie nahtlos auf die App zugreifen können.
- Wenn Ihre Microsoft Entra-App bei demselben Mandanten registriert ist, von dem Sie eine Authentifizierung in Teams anfordern, kann der App-Benutzer nicht um Zustimmung gebeten werden, und er erhält sofort ein Zugriffstoken. App-Benutzer stimmen diesen Berechtigungen nur zu, wenn die Microsoft Entra-App in einem anderen Mandanten registriert ist.
- Da Benutzer ihre Zustimmung für den API-Zugriff erteilen müssen und die Zustimmung nur einmal pro Benutzer erforderlich ist, ist keine zusätzliche Zustimmung für Dialogfelder erforderlich.
Aktualisieren des App-Manifests
Konfigurieren Sie die webApplicationInfo-Eigenschaft in der App-Manifestdatei, um SSO zu aktivieren. Auf diese Weise können Agent-Benutzer nahtlos auf Ihren Agent zugreifen. In der folgenden Tabelle sind die Eigenschaften der webApplicationInfo-Eigenschaft aufgeführt.
| Eigenschaft | Beschreibung |
|---|---|
| id | Geben Sie die App-ID (GUID) ein, die Sie in Microsoft Entra ID erstellt haben. |
| Ressource | Geben Sie den Unterdomänen-URI Ihrer App und den Anwendungs-ID-URI ein, den Sie in Microsoft Entra ID beim Erstellen des Bereichs erstellt haben. |
"webApplicationInfo": {
"id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
"resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
}
Geben Sie die Domäne der URL an, die Sie im Dialogfeld in der validDomains-Eigenschaft des App-Manifests rendern möchten, wie im folgenden Beispiel gezeigt.
"validDomains": [
"contoso.com",
"mysite.someplace.com",
"othersite.someplace.com"
]
OAuth 2.0-Setup (Vorschau)
Verwenden Sie für Agents, die OAuth 2.0 mit Microsoft Entra ID oder anderen Identitätsanbietern verwenden, die authentication.authenticate() Funktion in der TeamsJS-Bibliothek, um den Authentifizierungsablauf zu starten.
So aktivieren Sie die OAuth 2.0-Autorisierung für API-Plug-In-Dialogfelder:
- Konfigurieren Sie Ihre App für die Verwendung von Microsoft Entra ID als Identitätsanbieter.
- Nehmen Sie Codeänderungen vor, um den Authentifizierungsablauf zu starten und das Token zu verarbeiten.
Konfigurieren Ihrer App für die Verwendung von Microsoft Entra ID als Identitätsanbieter
So konfigurieren Sie Ihre App für die Verwendung von Microsoft Entra ID:
- Wechseln Sie im Azure-Portal zu Ihrer App-Registrierung.
- Fügen Sie unter Authentifizierung im Abschnitt Umleitungs-URI die Umleitungs-URL zu Ihrem Authentifizierungsendpunkt hinzu. Verwenden Sie für die Umleitungs-URL das folgende Format:
https://<hostname>/auth/simple-start.
Initiieren des Authentifizierungsflusses und Behandeln des Tokens
Die meisten Identitätsanbieter lassen nicht zu, dass Inhalte in einem iframe platziert werden. Dies bedeutet, dass Sie eine Seite zum Hosten des Identitätsanbieters benötigen, den Copilot in einem Popupfenster anzeigt. Verwenden Sie die authentication.authenticate() Funktion der TeamsJS-Bibliothek, um diese Seite zu starten, wenn die Schaltfläche "Adaptive Karte" ausgewählt ist.
Hinweis
Die URL, an authenticate() die Sie übergeben, ist die Startseite des Authentifizierungsflusses. Er sollte mit dem übereinstimmen, was Sie im Azure-Portal registriert haben.
Der Authentifizierungsfluss muss auf einer Seite in Ihrer Domäne beginnen. Stellen Sie sicher, dass diese Domäne in der validDomains-Eigenschaft des Manifests aufgeführt ist.
import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
url: window.location.origin + "/auth/simple-start",
width: 600,
height: 535
})
.then((result) => {
console.log("Login succeeded: " + result);
let data = localStorage.getItem(result);
localStorage.removeItem(result);
let tokenResult = JSON.parse(data);
showIdTokenAndClaims(tokenResult.idToken);
getUserProfile(tokenResult.accessToken);
})
.catch((reason) => {
console.log("Login failed: " + reason);
handleAuthError(reason);
});
Die Popupseite leitet zum Identitätsanbieter um, damit sich der Benutzer anmelden kann. Der Agent ruft den Microsoft Entra-Autorisierungsdienst auf und übermittelt Benutzer- und App-Informationen, damit sich der Benutzer bei Entra ID authentifizieren kann. Entra-ID ruft dann die von Ihnen bereitgestellte Rückrufseite auf.
app.getContext().then((context) => {
// Generate random state string and store it, so we can verify it in the callback
let state = _guid(); // _guid() is a helper function in the sample
localStorage.setItem("simple.state", state);
localStorage.removeItem("simple.error");
// Go to the Azure AD authorization endpoint
let queryParams = {
client_id: "{{appId}}",
response_type: "id_token token",
response_mode: "fragment",
scope: "https://graph.microsoft.com/User.Read openid",
redirect_uri: window.location.origin + "/auth/simple-end",
nonce: _guid(),
state: state,
// The context object is populated by Teams; the loginHint attribute
// is used as hinting information
login_hint: context.user.loginHint,
};
let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
window.location.assign(authorizeEndpoint);
});
Ermitteln Sie den Erfolg oder Misserfolg der Authentifizierungsanforderung basierend auf den von der Enttra-ID zurückgegebenen Informationen, und rufen Sie entweder authentication.notifySuccess() oder authentication.notifyFailure()auf. Wenn die Anmeldung erfolgreich war, hat der Benutzer Zugriff auf die Dienstressourcen.