Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
È possibile migliorare le risposte della scheda adattiva negli agenti dichiarativi per Microsoft 365 Copilot aggiungendo finestre di dialogo modali. Queste finestre popup possono ospitare HTML/JavaScript personalizzato o visualizzare widget basati su iframe, ad esempio pagine Web, video di YouTube o contenuto di Microsoft Stream, all'interno di un'esperienza interattiva mirata.
Questo articolo descrive come utilizzare Action.OpenUrlDialog (disponibile nello schema Adaptive Card versione 1.5) per avviare finestre di dialogo modali dai modelli Adaptive Card e come configurare l'autenticazione utente.
Nota
L'azione OpenUrlDialog è attualmente in anteprima.
Prerequisiti
Per utilizzare Action.OpenUrlDialog, sono necessari i prerequisiti seguenti:
- Schema della scheda adattiva versione 1.5
- Manifesto del plug-in API versione 2.3
- Libreria JS di Microsoft Teams (per scenari di autenticazione)
Definire il modello di scheda adattiva
Per utilizzare l'azione della finestra di dialogo modale:
- Aggiungi il modello di scheda adattiva al manifesto del plug-in.
- Includi lo
Action.OpenUrlDialogschema nella definizione della scheda adattiva.
L'esempio seguente mostra lo schema per Action.OpenUrlDialog.
"actions": [
{
"type": "Action.OpenUrlDialog",
"title": "OpenDialogWithDimension",
"url": "${url}",
"dialogHeight": "large",
"dialogWidth": "600px",
"dialogTitle": "task module"
}
]
Per informazioni di riferimento allo schema, vedere Action.OpenUrlDialog.
Configura le dimensioni della finestra di dialogo
Usare le proprietà dialogHeight e dialogWidth per impostare l'altezza e la larghezza della finestra di dialogo. Questi valori si adattano dinamicamente in base alla risoluzione dello schermo dell'utente e alle dimensioni della finestra.
È possibile specificare:
- Dimensioni predefinite -
small, ,mediumolarge. - Valori di pixel personalizzati,
400pxad esempio , .600px
Suggerimento
Usa i valori dei pixel per un controllo preciso. Le dimensioni predefinite sono relative allo spazio disponibile sullo schermo.
L'immagine seguente mostra un esempio di finestra di dialogo richiamata da un pulsante Scheda adattiva restituito da un agente.
Configurare l'autenticazione
Per consentire l'accesso sicuro alle API dalla finestra di dialogo, configurare l'autenticazione utilizzando uno dei metodi seguenti:
- Microsoft Entra ID
- OAuth 2.0 (anteprima)
Configurazione di Microsoft Entra ID
Per utilizzare l'autenticazione Entra ID per l'autenticazione API, utilizza uno dei seguenti approcci:
- Configurare l'ID Entra, OAuth 2.0 o l'autenticazione basata su chiave API usando Microsoft come provider di identità.
- Utilizzare un altro provider di identità e registrare l'app in Entra ID.
Configurare l'autenticazione basata su SSO
Configurare Single Sign-On (SSO) per consentire agli utenti di accedere alle API senza dover accedere più volte.
Per abilitare SSO:
- Aggiornare l'applicazione Microsoft Entra ID.
- Configurare l'URI dell'ID applicazione.
- Configurare gli ambiti e le impostazioni di consenso.
- Preautorizzare le applicazioni client attendibili per evitare richieste di consenso ripetute.
- Implementare la logica di recupero e convalida dei token.
- Usare il
getAuthToken()metodo della libreria TeamsJS per recuperare un token di accesso. - Inviare il token al server nell'intestazione Authorization.
- Convalidare il token lato server.
- Usare il
- Aggiornare il manifesto dell'app.
- Aggiungi la proprietà webApplicationInfo al manifesto dell'app per abilitare SSO.
- Aggiungere il dominio del contenuto della finestra di dialogo alla proprietà 'validDomains del manifesto dell'app.
Aggiornare l'applicazione Microsoft Entra ID
Per configurare gli ambiti e autorizzare le applicazioni client attendibili, aggiornare l'applicazione Microsoft Entra ID come segue:
Aggiungere un URI API alla proprietà identifierUris del manifesto dell'app. Usare il formato seguente per l'URI: 'api://fully-qualified-domain-name.com/{AppID}, come illustrato nell'esempio seguente.
"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" ],Definisci l'ambito dell'API e chi può fornire il consenso all'ambito. Negliambiti definiti da questa sezione API dell'Interfaccia di amministrazione di Microsoft Entra, selezionare + Aggiungi un ambito.
- Immettere il nome dell'ambito. Questo campo è obbligatorio.
- Selezionare l'utente che può fornire il consenso per questo ambito. L'opzione predefinita è Solo amministratori.
- Immettere il nome visualizzato del consenso dell'Amministratore. Questo campo è obbligatorio.
- Immettere la descrizione per il consenso dell'amministratore. Questo campo è obbligatorio.
- Immettere il nome visualizzato del consenso dell'utente.
- Immettere la descrizione per la descrizione del consenso dell'utente.
- Nel campo Stato selezionare l'opzione Abilitato per lo stato.
- Selezionare Aggiungi ambito.
Creare ID client autorizzati per le applicazioni a cui si desidera preautorizzare. In questo modo l'utente dell'app può accedere agli ambiti dell'app (autorizzazioni) configurati senza richiedere ulteriori consensi. Poiché gli utenti delle app non avranno la possibilità di rifiutare il consenso, pre-autorizzare solo le applicazioni client attendibili.
Nella sezione Applicazione client autorizzata dell'Interfaccia di amministrazione di Microsoft Entra, selezionare + Aggiungi un'applicazione client.
Immettere l'ID client di Microsoft 365 per le applicazioni da autorizzare.
Implementare la logica di recupero e convalida dei token
Aggiungere il codice per gestire il token di accesso, inviarlo al codice del server dell'app nell'intestazione Authorization e convalidare il token di accesso quando viene ricevuto.
Per ottenere l'accesso all'app per l'utente corrente dell'app, il codice lato client deve effettuare una chiamata a Teams per ottenere un token di accesso. Aggiornare il codice sul lato client da usare getAuthToken() per avviare il processo di convalida, come illustrato nell'esempio seguente.
// 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);
});
});
}
Quando Teams riceve il token di accesso, memorizza il token nella cache per poterlo riutilizzare in base alle esigenze. Il token viene usato quando getAuthToken() viene chiamato senza la necessità di effettuare un'altra chiamata a Microsoft Entra ID, fino alla scadenza del token.
Consenso dell'utente alla finestra di dialogo
Quando si effettua una chiamata getAuthToken() ed è necessario il consenso dell'utente per le autorizzazioni a livello di utente, l'utente connesso vede una finestra di dialogo Microsoft Entra e l'utente deve fornire il consenso iniziale una sola volta.
Dopo il consenso, l'utente può accedere alla pagina Web della finestra di dialogo. I punti seguenti si applicano al consenso dell'utente:
- Se l'amministratore ha concesso il consenso per conto del tenant, non è necessario che agli utenti dell'app venga richiesto il consenso. Ciò significa che gli utenti dell'app non vedono la finestra di dialogo di consenso e possono accedere all'app senza problemi.
- Se l'app Microsoft Entra è registrata nello stesso tenant da cui si richiede l'autenticazione in Teams, all'utente dell'app non può essere chiesto di fornire il consenso e viene immediatamente concesso un token di accesso. Gli utenti dell'app accettano queste autorizzazioni solo se l'app Microsoft Entra è registrata in un tenant diverso.
- Poiché gli utenti devono fornire il consenso per l'accesso all'API e il consenso è richiesto una sola volta per utente, non è necessario alcun consenso aggiuntivo per le finestre di dialogo.
Aggiornare il manifesto dell'app
Configurare la proprietà webApplicationInfo nel file manifesto dell'app per abilitare SSO. In questo modo gli utenti dell'agente possono accedere facilmente all'agente. Nella tabella seguente sono elencate le proprietà della proprietà webApplicationInfo .
| Proprietà | Descrizione |
|---|---|
| id | Immettere l'ID app (GUID) creato in Microsoft Entra ID. |
| risorsa | Immettere l'URI del sottodominio dell'app e l'URI dell'ID applicazione creato in Microsoft Entra ID al momento della creazione dell'ambito. |
"webApplicationInfo": {
"id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
"resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
}
Specificare il dominio dell'URL di cui si vuole eseguire il rendering nella finestra di dialogo nella proprietà validDomains del manifesto dell'app, come illustrato nell'esempio seguente.
"validDomains": [
"contoso.com",
"mysite.someplace.com",
"othersite.someplace.com"
]
Configurazione di OAuth 2.0 (anteprima)
Per gli agenti che usano OAuth 2.0 con Microsoft Entra ID o altri provider di identità, usare la authentication.authenticate() funzione nella libreria TeamsJS per avviare il flusso di autenticazione.
Per abilitare l'autorizzazione OAuth 2.0 per le finestre di dialogo del plug-in API:
- Configurare l'app per l'uso di Microsoft Entra ID come provider di identità.
- Apportare modifiche al codice per avviare il flusso di autenticazione e gestire il token.
Configurare l'app per l'uso di Microsoft Entra ID come provider di identità
Per configurare l'app per l'utilizzo di Microsoft Entra ID:
- Nel portale di Azure, passare alla registrazione dell'app.
- In Autenticazione, nella sezione URI di reindirizzamento , aggiungere l'URL di reindirizzamento all'endpoint di autenticazione. Utilizzare il formato seguente per l'URL di reindirizzamento:
https://<hostname>/auth/simple-start.
Avviare il flusso di autenticazione e gestire il token
La maggior parte dei provider di identità non consente l'inserimento di contenuti in un iframe. Ciò significa che è necessaria una pagina per ospitare il provider di identità che Copilot mostra all'interno di una finestra popup. Usa la authentication.authenticate() funzione della libreria TeamsJS per avviare questa pagina quando viene selezionato il pulsante Scheda adattiva.
Nota
L'URL a authenticate() cui si passa è la pagina iniziale del flusso di autenticazione. Deve corrispondere a quello registrato nel portale di Azure.
Il flusso di autenticazione deve iniziare in una pagina del dominio. Assicurarsi di elencare questo dominio nella proprietà validDomains del manifesto.
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);
});
La pagina popup reindirizza al provider di identità in modo che l'utente possa accedere. L'agente chiama il servizio di autorizzazione di Microsoft Entra e passa le informazioni sull'utente e sull'app in modo che l'utente possa eseguire l'autenticazione in Entra ID. Entra ID chiama quindi la pagina di callback specificata.
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);
});
Determinare l'esito positivo o negativo della richiesta di autenticazione in base alle informazioni restituite dall'ID Entra e chiamare o authentication.notifySuccess() .authentication.notifyFailure() Se l'accesso è stato completato, l'utente ha accesso alle risorse del servizio.