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.
Dica
Recomendado: Comece com o Work IQ Dev Tools para cenários de plug-in e de agente declarativo de código profissional com suporte. Consulte o início rápido do WIQD. As instruções baseadas em kit de ferramentas permanecem disponíveis para projetos e fluxos de trabalho existentes que as exigem. Verifique a capacidade e o suporte à experiência de destino antes de escolher uma ferramenta: O WIQD não tem como alvo agentes de mecanismo personalizados.
Um plug-in pode acessar um servidor MCP (Protocolo de Contexto de Modelo) ou API usando um token de portador obtido por meio do fluxo de código de autorização OAuth 2.0, com suporte a Chave de Prova para Troca de Código (PKCE) habilitado por padrão. Nesse fluxo, o Microsoft 365 Copilot abre a experiência de entrada, o provedor OAuth retorna uma resposta de autorização ao Microsoft Teams e o Teams troca o código de autorização por tokens.
Este artigo usa plug-ins MCP como o passo a passo padrão. As mesmas etapas se aplicam a plug-ins de API criados a partir de um documento OpenAPI, exceto quando indicado.
Configure a autenticação do OAuth 2.0 em três etapas: registre um cliente OAuth com seu provedor de identidade, configure o URI de redirecionamento e crie a configuração do OAuth 2.0.
Etapa 1: registrar um cliente OAuth com seu provedor de identidade
Registre um aplicativo com seu provedor OAuth 2.0 (seu provedor de identidade) para obter uma ID do cliente e, para um cliente confidencial (Web), um segredo do cliente. Forneça esses valores ao criar a configuração do OAuth 2.0 na Etapa 3.
Para um servidor MCP que requer autorização, defina a type propriedade do objeto de autenticação de tempo de execução como OAuthPluginVault.
None e ApiKeyPluginVault não se aplicam a um servidor MCP que exija autorização. Somente a ID de configuração de autenticação é armazenada no manifesto. Nenhuma ID do cliente, segredo do cliente ou token é gravado nela. Para registrar o cliente dinamicamente em vez de estaticamente, mantenha type como OAuthPluginVault e crie a configuração de autenticação por meio do DCR (registro dinâmico de cliente), que não está disponível para um servidor protegido pelo Microsoft Entra ID.
Observação
Esses valores se aplicam ao manifesto do plug-in MCP para ações de agente declarativo. Se, em vez disso, você configurar o servidor MCP remoto de um plug-in por meio agentConnectors do manifesto do aplicativo Microsoft 365, use OAuthPluginVault ou, para um servidor que dê suporte a DCR, DynamicClientRegistration. Os esquemas de manifesto do aplicativo 1.29 e 1.30 também incluem AzureKeyVault, mas a aceitação do esquema não estabelece suporte na experiência de destino. Para requisitos de configuração e host, consulte Configurar servidores MCP remotos para plug-ins do Microsoft 365 Copilot.
Etapa 2: configurar o URI de redirecionamento
Adicione o seguinte URI de redirecionamento (também chamado de URL de retorno de chamada de autorização) ao registro do provedor OAuth:
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect
Essa é a URL para a qual seu provedor OAuth envia a resposta de autorização depois que um usuário entra. O Teams recebe a resposta nessa URL de retorno de chamada e troca o código de autorização por tokens. Se você não registrar esse URI de redirecionamento com seu provedor, a entrada falhará. O URI de redirecionamento é o mesmo para todos os plug-ins e provedores. Você não pode personalizá-lo por aplicativo.
Etapa 3: criar a configuração de autenticação OAuth 2.0
A autenticação OAuth 2.0 depende de uma configuração de autenticação (configuração de autenticação): um registro armazenado no repositório de tokens do Microsoft Enterprise que o Microsoft 365 Copilot usa para obter e atualizar tokens para seu plug-in MCP. Comece com o WIQD para um projeto pró-código com suporte. Os procedimentos do Kit de ferramentas, Developer-skill e Portal do desenvolvedor do Teams permanecem disponíveis como alternativas.
Independentemente de como você a cria, a configuração de autenticação tem uma ID de configuração de autenticação que o manifesto do plug-in faz referência.
Usar Ferramentas de Desenvolvimento do Work IQ (recomendado)
Para uma ação MCP, use wiqd agent add action com --mcp-server-url e --mcp-auth-type oauth. Forneça os dados do cliente cadastrado por meio de --mcp-client-id, --mcp-client-secret quando necessário, e --mcp-scopes. Para uma ação OpenAPI, use --openapi-auth-identity-provider oauth e as opções , --openapi-auth-client-secret--openapi-auth-client-ide --openapi-auth-scopes correspondentes. Habilite o PKCE para essa rota OpenAPI com --openapi-auth-pkce quando o provedor der suporte a ela. Consulte a orientação do comando de ação WIQD.
Para um manifesto de plug-in existente, use wiqd agent add auth com --plugin-manifest, --auth-namee --auth-type oauth. Use o ponto de extremidade OAuth, o escopo e as opções de cliente desse comando; sua opção PKCE é --oauth-pkce. Conclua o fluxo de trabalho de provisionamento do projeto para seu ambiente. Para registro automático de clientes em vez de OAuth estático, siga a rota WIQD DCR.
Usar o Kit de Ferramentas de Agentes do Microsoft 365
Quando você cria um agente com um plug-in MCP (se o servidor exigir autenticação) ou cria um plug-in de API a partir de um documento OpenAPI existente no Microsoft 365 Agents Toolkit, o kit de ferramentas solicita a ID do cliente OAuth, o segredo do cliente e os escopos. O Agents Toolkit busca os pontos de extremidade de autorização, token e atualização do ponto de extremidade conhecido do seu servidor MCP (ou do documento OpenAPI para plug-ins de API), cria a configuração de autenticação no armazenamento de tokens da empresa e atualiza o objeto de autenticação de tempo de execução no manifesto do plug-in automaticamente.
Observação
Para plug-ins de API, você deve definir a securitySchemes propriedade em seu documento OpenAPI para que o Agents Toolkit possa ler os detalhes do OAuth. Para obter mais informações, consulte OAuth 2.0.
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: <authorization_url>
tokenUrl: <token_url>
refreshUrl: <refresh_url>
scopes:
scope: description
O PKCE é habilitado por padrão, porque muitas organizações bloqueiam segredos de cliente. Defina isPKCEEnabled como false no m365agents.yml em seu projeto de agente antes de provisionar o agente somente quando seu provedor OAuth não der suporte a PKCE.
isPKCEEnabled: false
Para evitar totalmente os segredos do cliente, registre um cliente público com seu provedor - uma plataforma de aplicativo de página única em vez de uma plataforma Web - e deixe o PKCE proteger a troca de código.
Usar a habilidade de desenvolvedor de agente declarativo
A habilidade de desenvolvedor de agente declarativo (declarative-agent-developer) é uma habilidade de agente no Microsoft Work IQ que empacota o conhecimento necessário para criar agentes declarativos. Em vez de executar comandos ou editar manifestos por conta própria, você descreve o que deseja para o Copilot ou a GitHub CLI em linguagem natural, e a habilidade cria o suporte do agente declarativo, adiciona o plug-in MCP e lida com a configuração de autenticação para você. A habilidade dá suporte apenas a plug-ins MCP. Para o OAuth 2.0, ele dá suporte ao registro estático e ao DCR (registro dinâmico de cliente): ele cria a configuração de autenticação no armazenamento de token da empresa e atualiza o manifesto do plug-in sem etapas manuais.
Dica
Para obter um vídeo passo a passo sobre como usar a habilidade de desenvolvedor de agente declarativo, consulte Criar agentes declarativos com a habilidade de desenvolvedor de agente declarativo.
Usar o portal do desenvolvedor do Teams
O registro no portal do desenvolvedor do Teams é opcional se você usar o Kit de Ferramentas de Agentes ou a habilidade de desenvolvedor de agente declarativo. Use-o quando quiser criar a configuração de autenticação manualmente ou, mais comumente, para gerenciar uma configuração de autenticação que o Agents Toolkit ou a habilidade já criou. No portal, você pode restringir a configuração de autenticação a um aplicativo específico do Teams ou organização do Microsoft 365 e modificar outras propriedades.
O registro do cliente OAuth no portal do desenvolvedor do Teams conecta a configuração do plug-in do agente ao registro do provedor OAuth que emite tokens para o servidor MCP ou API. Os valores nesse registro devem corresponder ao provedor OAuth, ao manifesto do plug-in e ao ponto de extremidade da API protegida. URLs base incompatíveis, restrições de aplicativo ou IDs de configuração de autenticação podem impedir que os usuários entrem ou podem bloquear a troca de tokens.
Aviso
Restrinja o registro para Qualquer aplicativo do Teams. Um registro restrito a um aplicativo específico do Teams é associado a essa ID do aplicativo do Teams. O Microsoft 365 Copilot não resolve essa ID quando chama um servidor MCP, portanto, o provisionamento é concluído com êxito e, em seguida, cada chamada de ferramenta retorna um 404 erro.
Abra o portal do desenvolvedor do Teams. Selecione Ferramentas ->Registro de cliente OAuth.
Se você não tiver registros existentes, selecione Registrar cliente. Se você tiver registros existentes, selecione Novo registro de cliente OAuth.
Preencha os seguintes campos.
- Nome do registro: um nome amigável para o seu registro.
-
URL base: a URL base da API. Esse valor deve corresponder à URL na
urlpropriedade do objeto de especificação do servidor MCP no manifesto do plug-in para plug-ins baseados em MCP ou a uma entrada naserversmatriz em seu documento OpenAPI para plug-ins de API. - Restringir o uso por organização: selecione quais organizações do Microsoft 365 podem usar esse registro OAuth para acessar seus pontos de extremidade de API. Use Minha organização somente para desenvolvimento ou teste em um locatário. Use qualquer organização do Microsoft 365 quando o plug-in precisar funcionar entre locatários.
-
Restringir o uso por aplicativo: selecione qualquer aplicativo do Teams. Não vincule o registro à ID do aplicativo Teams existente para um servidor MCP. Se você provisionar a configuração de autenticação com o
oauth/registerMicrosoft 365 Agents Toolkit, a configuração equivalente na ação no m365agents.yml seráapplicableToApps: AnyApp. Mantenha oappIdcampo nessa ação, mesmo queAnyAppo torne inerte, porque o driver de provisionamento validaappIdincondicionalmente e removê-lo interrompe o provisionamento. - ID do cliente: a ID do cliente ou a ID do aplicativo emitida pelo provedor OAuth 2.0.
- Segredo do cliente: seu segredo do cliente emitido pelo provedor OAuth 2.0.
- Ponto de extremidade de autorização: a URL do provedor OAuth 2.0 que os aplicativos usam para solicitar um código de autorização.
- Ponto de extremidade do token: a URL do provedor OAuth 2.0 que os aplicativos usam para resgatar um código para um token de acesso.
- Atualizar ponto de extremidade: a URL do provedor OAuth 2.0 que os aplicativos usam para atualizar o token de acesso.
-
Escopo: as permissões que seu plug-in solicita do provedor OAuth. Use os valores de escopo exigidos pelo seu provedor e pela API. Se o provedor usar a plataforma de identidade da Microsoft e o plug-in precisar de tokens de atualização, inclua-o
offline_accessem todos os escopos delegados específicos da API. - Habilitar Chave de Prova para Troca de Código (PKCE): deixe essa configuração habilitada. Está ativado por padrão; desabilite-o somente se o provedor OAuth não der suporte a PKCE.
Selecione Salvar.
A conclusão do registro cria a configuração de autenticação e gera uma ID de configuração de autenticação (atualmente rotulada como ID de registro do cliente OAuth no portal do desenvolvedor do Teams).
Adicione o ID de configuração de autenticação ao manifesto do plug-in
Quando cria manualmente a configuração da autenticação no portal do programador do Teams, defina a type propriedade do objeto de autenticação de tempo de execução como OAuthPluginVault, e o reference_id ID de configuração da autenticação. O Kit de Ferramentas de Agentes e a habilidade de desenvolvedor do agente declarativo fazem isso por você.
"auth": {
"type": "OAuthPluginVault",
"reference_id": "auth config ID"
},
Microsoft Entra ID considerações
Quando você protege seu servidor MCP usando Microsoft Entra ID, três restrições se aplicam que você não pode contornar em ferramentas.
- O registo dinâmico de cliente não está disponível. Microsoft Entra ID não publica um ponto de extremidade de registro RFC 7591, portanto, o registro dinâmico do cliente não tem nada contra o qual se registrar. Registre o cliente OAuth estaticamente seguindo as etapas neste artigo.
- O
agentConnectorsnó não tem nenhum tipo de autorização Microsoft Entra. Ao contráriocomposeExtensionsdo , o nó no manifestoagentConnectorsda aplicação Microsoft 365 nãomicrosoftEntratem nenhum tipo de autorização. Um servidor MCP protegido por Microsoft Entra ID precisa sempre de uma aplicação na qual se registe no Microsoft Entra ID, bem como de uma configuração de autenticação OAuth, mesmo quando o servidor está na frente de uma API original da Microsoft. - O consentimento do âmbito não é verificado quando aprovisiona. O aprovisionamento não marcar se o âmbito pedido pode ser consentido. Um âmbito que não pode ser consentido com provisões com êxito e que falha mais tarde com a aprovação necessária do administrador, e a aplicação de recursos pode ficar invisível para si e para o administrador do inquilino. Confirme que um administrador consentiu com o escopo antes de provisionar.
Gerir a configuração de autenticação
A oauth/register ação no m365agents.yml apenas cria uma configuração de autenticação ou ignora a criação de uma - nunca reescreve um registo existente.
- Se
configurationIdjá tiver um valor, a ação não fará nada. - Se
configurationIdapontar para um registo que eliminou, a ação avisa-o e não faz nada. - Para alterar os valores num registo existente, utilize a
oauth/updateação. - Para eliminar um registo, utilize o portal do programador do Teams. É o único local onde pode eliminar um.
Sair
Observação
Os utilizadores podem terminar sessão de um agente a partir das definições> de ChatAgentes no Microsoft 365 Copilot. Esta ação limpa o token OAuth armazenado.