Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Pode melhorar as respostas do Cartão Adaptável em agentes declarativos para Microsoft 365 Copilot adicionando caixas de diálogo modais. Essas caixas de diálogo pop-up podem hospedar HTML/JavaScript personalizado ou exibir widgets baseados em iframe - como páginas da Web, vídeos do YouTube ou conteúdo Microsoft Stream - em uma experiência focada e interativa.
Este artigo descreve como utilizar Action.OpenUrlDialog (disponível no esquema de Cartão Adaptável versão 1.5) para iniciar caixas de diálogo modais a partir de modelos de Cartão Adaptável e como configurar a autenticação de utilizador.
Observação
A OpenUrlDialog ação encontra-se atualmente em pré-visualização.
Pré-requisitos
Para utilizar Action.OpenUrlDialogo , precisa dos seguintes pré-requisitos:
- Esquema de cartão adaptável versão 1.5
- Manifesto de plug-in API versão 2.3
- Biblioteca JS do Microsoft Teams(para cenários de autenticação)
Definir o modelo de Cartão Adaptável
Para utilizar a ação da caixa de diálogo modal:
- Adicione o modelo de Cartão Adaptável ao manifesto do Plug-in.
- Inclua o
Action.OpenUrlDialogesquema na definição do Cartão Adaptável.
O exemplo a seguir mostra o esquema para Action.OpenUrlDialog.
"actions": [
{
"type": "Action.OpenUrlDialog",
"title": "OpenDialogWithDimension",
"url": "${url}",
"dialogHeight": "large",
"dialogWidth": "600px",
"dialogTitle": "task module"
}
]
Para obter informações de referência de esquema, consulte Action.OpenUrlDialog.
Configurar o tamanho da caixa de diálogo
Use as propriedades dialogHeight e dialogWidth para definir a altura e a largura da caixa de diálogo. Estes valores ajustam-se dinamicamente com base na resolução do ecrã do utilizador e no tamanho da janela.
Pode especificar:
- Tamanhos predefinidos -
small,medium, oularge. - Valores de pixel personalizados - por exemplo,
400px,600px.
Dica
Utilize valores de píxeis para um controlo preciso. Os tamanhos predefinidos são relativos ao espaço disponível no ecrã.
A imagem seguinte mostra um exemplo de uma caixa de diálogo invocada a partir de um botão Cartão Adaptável devolvido por um agente.
Configurar autenticação
Para permitir o acesso seguro às APIs a partir da caixa de diálogo, configure a autenticação usando um dos seguintes métodos:
- Microsoft Entra ID
- OAuth 2.0 (pré-visualização)
Microsoft Entra ID configuração
Para usar a autenticação de ID de Entra para autenticação de API, use uma das seguintes abordagens:
- Configure Entra ID, OAuth 2.0 ou autenticação baseada em chave de API usando a Microsoft como o provedor de identidade.
- Use outro provedor de identidade e registre seu aplicativo em Entra ID.
Configurar a autenticação baseada em SSO
Configure o logon único (SSO) para permitir que os usuários acessem APIs sem precisar entrar várias vezes.
Para ativar o SSO:
- Atualize a aplicação Microsoft Entra ID.
- Configure o URI do ID do aplicativo.
- Configurar âmbitos e definições de consentimento.
- Pré-autorize aplicações cliente fidedignas para evitar pedidos de consentimento repetidos.
- Implemente a lógica de recuperação e validação do token.
- Use o
getAuthToken()método da biblioteca TeamsJS para recuperar um token de acesso. - Envie o token para o servidor no cabeçalho Autorização.
- Valide o lado do servidor do token.
- Use o
- Atualize o manifesto da aplicação.
- Adicione a propriedade webApplicationInfo ao manifesto do aplicativo para habilitar o SSO.
- Adicione o domínio do conteúdo da caixa de diálogo à propriedade "validDomains" do manifesto do aplicativo.
Atualizar a aplicação Microsoft Entra ID
Para configurar âmbitos e autorizar aplicações cliente fidedignas, atualize a sua aplicação Microsoft Entra ID da seguinte forma:
Adicione um URI da API à propriedade identifierUris do manifesto do aplicativo. Utilize o seguinte formato para o URI: 'api://fully-qualified-domain-name.com/{AppID}, conforme mostrado no exemplo seguinte.
"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" ],Defina o escopo da API e quem pode consentir o escopo. Na seçãoEscopos definidos por esta API do centro de administração do Microsoft Entra, selecione + Adicionar um escopo.
- Introduza o nome do âmbito. Este campo é obrigatório.
- Selecione o utilizador que pode dar consentimento para este âmbito. A opção predefinida é apenas Administradores.
- Introduza o nome a apresentar do consentimento Administração. Este campo é obrigatório.
- Introduza a descrição do consentimento de administrador. Este campo é obrigatório.
- Introduza o nome a apresentar do Consentimento do utilizador.
- Introduza a descrição para a descrição de consentimento do utilizador.
- No campo Estado , selecione a opção Habilitado para estado.
- Selecione Adicionar âmbito.
Crie IDs de cliente autorizados para aplicativos que você deseja pré-autorizar. Isto permite que o utilizador da aplicação aceda aos âmbitos (permissões) da aplicação que configurou sem necessitar de consentimento adicional. Uma vez que os utilizadores da aplicação não terão a oportunidade de recusar o consentimento, efetue uma pré-autorização apenas a aplicações cliente fidedignas.
Na seção Aplicativo cliente autorizado do centro de administração do Microsoft Entra, selecione + Adicionar um aplicativo cliente.
Introduza o ID de cliente do Microsoft 365 para as aplicações que pretende autorizar.
Implementar lógica de recuperação e validação de tokens
Adicione código para manipular o token de acesso, envie o token para o código do servidor do seu aplicativo no cabeçalho Autorização e valide o token de acesso quando ele for recebido.
Para obter acesso à aplicação para o utilizador atual da aplicação, o seu código do lado do cliente tem de efetuar uma chamada para o Teams para obter um token de acesso. Atualize o código do lado do cliente para iniciar getAuthToken() o processo de validação, conforme mostrado no exemplo a seguir.
// 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 o Teams recebe o token de acesso, armazena-o em cache para ser reutilizado conforme necessário. O token é utilizado quando getAuthToken() é chamado sem necessidade de efetuar outra chamada ao Microsoft Entra ID, até o token expirar.
Consentimento do utilizador para a caixa de diálogo
Quando telefona getAuthToken() e é necessário o consentimento do utilizador para as permissões ao nível do utilizador, o utilizador com sessão iniciada vê uma caixa de diálogo Microsoft Entra e tem de dar consentimento inicial uma vez.
Após o consentimento do utilizador, pode aceder à página Web da caixa de diálogo. Os seguintes pontos aplicam-se ao consentimento do utilizador:
- Se o administrador tiver concedido consentimento em nome do inquilino, não é necessário pedir consentimento aos utilizadores da aplicação. Isto significa que os utilizadores da aplicação não veem a caixa de diálogo de consentimento e podem aceder à aplicação sem problemas.
- Se a sua aplicação Microsoft Entra estiver registada no mesmo inquilino ao qual está a pedir uma autenticação no Teams, não será pedido ao utilizador da aplicação que dê consentimento e ser-lhe-á concedido um token de acesso de imediato. Os utilizadores da aplicação só consentem estas permissões se a aplicação Microsoft Entra estiver registada num inquilino diferente.
- Uma vez que os utilizadores têm de fornecer consentimento para o acesso à API e que o consentimento é necessário apenas uma vez por utilizador, não é necessário consentimento adicional para as caixas de diálogo.
Atualizar o manifesto da aplicação
Configure a propriedade webApplicationInfo no arquivo de manifesto do aplicativo para habilitar o SSO. Isso ajuda os usuários do agente a acessar seu agente perfeitamente. A tabela a seguir lista as propriedades da propriedade webApplicationInfo .
| Propriedade | Descrição |
|---|---|
| id | Introduza o ID da aplicação (GUID) que criou no Microsoft Entra ID. |
| recurso | Insira o URI do subdomínio do seu aplicativo e o URI da ID do aplicativo que você criou no Microsoft Entra ID quando criou o escopo. |
"webApplicationInfo": {
"id": "7c7c79df-bf9d-43b7-a464-1cb9995eb3b2",
"resource": "api://67ec-4-213-76-42.ngrok-free.app/7c7c79df-bf9d-43b7-a464-1cb9995eb3b2"
}
Especifique o domínio da URL que você deseja renderizar na caixa de diálogo na propriedade validDomains do manifesto do aplicativo, conforme mostrado no exemplo a seguir.
"validDomains": [
"contoso.com",
"mysite.someplace.com",
"othersite.someplace.com"
]
Configuração do OAuth 2.0 (versão prévia)
Para agentes que usam o OAuth 2.0 com o Microsoft Entra ID ou outros provedores de identidade, use a authentication.authenticate() função na biblioteca do TeamsJS para iniciar o fluxo de autenticação.
Para habilitar a autorização do OAuth 2.0 para caixas de diálogo de plug-in de API:
- Configure seu aplicativo para usar o Microsoft Entra ID como um provedor de identidade.
- Faça alterações no código para iniciar o fluxo de autenticação e manipular o token.
Configurar seu aplicativo para usar o Microsoft Entra ID como um provedor de identidade
Para configurar seu aplicativo para usar o Microsoft Entra ID:
- No portal do Azure, vá para o registro do aplicativo.
- Em Autenticação, na seção URI de redirecionamento , adicione a URL de redirecionamento ao ponto de extremidade de autenticação. Use o seguinte formato para a URL de redirecionamento:
https://<hostname>/auth/simple-start.
Iniciar o fluxo de autenticação e manipular o token
A maioria dos provedores de identidade não permite que o conteúdo seja colocado em um iframe. Isso significa que você precisa de uma página para hospedar o provedor de identidade que o Copilot exibe em uma janela pop-up. Use a authentication.authenticate() função da biblioteca TeamsJS para iniciar esta página quando o botão Cartão Adaptável for selecionado.
Observação
A URL para authenticate() a qual você passa é a página inicial do fluxo de autenticação. Ele deve corresponder ao que você registrou no portal do Azure.
O fluxo de autenticação deve começar em uma página do seu domínio. Certifique-se de listar esse domínio na propriedade validDomains no 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);
});
A página pop-up redireciona para o provedor de identidade para que o usuário possa entrar. O agente chama o serviço de autorização do Microsoft Entra e passa informações do usuário e do aplicativo para que o usuário possa se autenticar no Entra ID. Em seguida, o ID do Entra chama a página de retorno de chamada fornecida.
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);
});
Determine o sucesso ou a falha da solicitação de autenticação com base nas informações retornadas pelo Entra ID e chame ou authentication.notifySuccess()authentication.notifyFailure(). Se a entrada foi bem-sucedida, o usuário tem acesso aos recursos de serviço.