Configurar autenticação OAuth 2.0

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. Se, em vez disso, registrar seu servidor MCP como um conector de agente no agentConnectors nó do manifesto do aplicativo Microsoft 365, use OAuthPluginVault ou DynamicClientRegistration lá também. Não use AzureKeyVault: ele existe apenas no esquema, portanto, um pacote direcionado a uma versão de esquema numerada falha na devPreview validação. Para obter mais informações, consulte Registrar servidores MCP como conectores de agente.

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. Você pode criar a configuração de autenticação de três maneiras. As abordagens recomendadas - Microsoft 365 Agents Toolkit e a habilidade de desenvolvedor de agente declarativo - criam a configuração de autenticação e atualizam o manifesto do plug-in automaticamente. Em seguida, você pode usar o portal do desenvolvedor do Teams para gerenciar e refinar a configuração de autenticação.

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 o Microsoft 365 Agents Toolkit (recomendado)

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.

1. Abra o portal do desenvolvedor do Teams. Selecione Ferramentas ->Registro de cliente OAuth.

2. Se você não tiver registros existentes, selecione Registrar cliente. Se você tiver registros existentes, selecione Novo registro de cliente OAuth.

3. 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 url propriedade do objeto de especificação do servidor MCP no manifesto do plug-in para plug-ins baseados em MCP ou a uma entrada na servers matriz 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/register Microsoft 365 Agents Toolkit, a configuração equivalente na ação no m365agents.yml será applicableToApps: AnyApp. Mantenha o appId campo nessa ação, mesmo que AnyApp o torne inerte, porque o driver de provisionamento valida appId incondicionalmente 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_access em 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.

4. Selecione Salvar.

5. 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).

Adicionar a ID de configuração de autenticação ao manifesto do plug-in

Ao criar a configuração de autenticação manualmente no portal do desenvolvedor do Teams, defina a type propriedade do objeto de autenticação de tempo de execução como OAuthPluginVaulte defina a reference_id ID de configuração de autenticação. O Agents Toolkit e a habilidade de desenvolvedor de agente declarativo fazem isso por você.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "auth config ID"
},

Considerações sobre o Microsoft Entra ID

Quando você protege seu servidor MCP usando o Microsoft Entra ID, três restrições se aplicam que você não pode contornar em ferramentas.

• O registro de cliente dinâmico não está disponível. O Microsoft Entra ID não publica um ponto de extremidade de registro RFC 7591, portanto, o registro de cliente dinâmico não tem nada para se registrar. Registre o cliente OAuth estaticamente seguindo as etapas neste artigo.
• O agentConnectors nó não tem nenhum tipo de autorização do Microsoft Entra. Ao contrário composeExtensionsde , o agentConnectors nó no manifesto do aplicativo Microsoft 365 não tem nenhum microsoftEntra tipo de autorização. Um servidor MCP protegido pelo Microsoft Entra ID sempre precisa de um aplicativo que você mesmo registra no Microsoft Entra ID, além de uma configuração de autenticação OAuth, mesmo quando o servidor tem uma API da Microsoft própria.
• O consentimento do escopo não é verificado quando você provisiona. O provisionamento não marca se o escopo solicitado pode ser consentido. Um escopo que não pode ser consentido é provisionado com êxito e, em seguida, falha mais tarde com a aprovação do administrador necessário, e o aplicativo de recursos pode ficar invisível para você e para o administrador do locatário. Confirme se um administrador consentiu com o escopo antes de provisionar.

Gerenciar 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, ela nunca reescreve um registro existente.

• Se configurationId já tiver um valor, a ação não fará nada.
• Se configurationId apontar para um registro excluído, a ação avisará e não fará nada.
• Para alterar os valores em um registro existente, use a oauth/update ação.
• Para excluir um registro, use o portal do desenvolvedor do Teams. É o único lugar onde você pode excluir uma.

Sair

Observação

Os usuários podem sair de um agente nas configurações> de ChatAgentes no Microsoft 365 Copilot. Essa ação limpa o token OAuth armazenado.

Conteúdo relacionado

• Configurar a autenticação para plug-ins de MCP e API nos agentes
• Configurar a autenticação SSO do Microsoft Entra
• Solucionar problemas de autenticação de plug-in de API e MCP