Configurar a autenticação SSO do Microsoft Entra

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.

A autenticação de logon único (SSO) do Microsoft Entra permite que os usuários se autentiquem com suas credenciais existentes do Microsoft Entra ID. Essa integração simplifica o gerenciamento de acesso e garante conexões seguras com servidores ou APIs MCP (Model Context Protocol) sem a necessidade de credenciais extras. Seu servidor MCP ou API deve usar o Entra ID para controlar o acesso.

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 SSO do Entra em quatro etapas: registre um aplicativo Entra para proteger seu servidor MCP, crie a configuração de autenticação, atualize o registro do aplicativo Entra e adicione o novo público de token à sua API.

Etapa 1: registrar um aplicativo Entra para proteger seu servidor MCP

Seu servidor MCP ou API deve ser protegido por um registro do aplicativo Entra. Se você ainda não tiver um, registre um aplicativo no centro de administração do Microsoft Entra. Observe a ID do cliente do aplicativo - você a fornece ao criar a configuração de autenticação na Etapa 2.

Etapa 2: Criar a configuração de autenticação SSO do Entra

Entra A autenticação SSO depende de uma configuração de autenticação (configuração de autenticação) - um registro armazenado no armazenamento de tokens do Microsoft Enterprise que o Microsoft 365 Copilot usa para obter 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 e um URI de ID do aplicativo. Você usa o URI da ID do aplicativo nas etapas 3 e 4.

Importante

Independentemente de como você cria a configuração de autenticação, você ainda deve concluir as Etapas 3 e 4.

Para uma ação MCP, use wiqd agent add action com , --mcp-auth-type entra-ssoe --mcp-client-id defina como --mcp-server-urlo ID do cliente do aplicativo Entra da Etapa 1. Para uma ação OpenAPI, use --openapi-auth-identity-provider microsoft-entra e --openapi-auth-client-id. Consulte a orientação do comando de ação WIQD para obter as outras opções de ação necessárias.

Para um manifesto de plug-in existente, use wiqd agent add auth com --plugin-manifest, --auth-namee --auth-type microsoft-entra. Forneça as opções do provedor de identidade documentadas para esse comando, incluindo --oauth-client-id. Conclua o fluxo de trabalho de provisionamento do projeto, obtenha o URI da ID do aplicativo da configuração de autenticação e continue com a Etapa 3 e a Etapa 4.

Usar o Kit de Ferramentas de Agentes do Microsoft 365

Quando você cria um agente com um plug-in MCP no Microsoft 365 Agents Toolkit, o kit de ferramentas solicita um tipo de autenticação à medida que você adiciona o plug-in do servidor MCP. Selecione SSO do Microsoft Entra e forneça a ID do cliente do aplicativo Entra da Etapa 1. O Agents Toolkit cria a configuração de autenticação no armazenamento de tokens da empresa, gera a ID de configuração de autenticação e atualiza o objeto de autenticação de tempo de execução no manifesto do plug-in automaticamente.

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, descreva o que deseja para o Copilot ou a GitHub CLI em linguagem natural. A habilidade cria o scaffolds 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. Quando você adiciona um servidor MCP que usa o SSO do Entra, a habilidade cria a configuração de autenticação no armazenamento de tokens 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.

  1. Abra o portal do desenvolvedor do Teams. Selecione Ferramentas - Registro de ID de cliente SSO do> Microsoft Entra.

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

  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 qual organização do Microsoft 365 tem acesso ao seu aplicativo para acessar os pontos de extremidade da API.
    • Restringir o uso por aplicativo: Selecione Qualquer aplicativo do Teams se você não souber a ID final do aplicativo. Depois de publicar seu aplicativo, vincule esse registro à ID do aplicativo publicado.
    • ID do cliente: O ID do cliente do aplicativo registrado no Entra.
    • Escopo: as permissões que seu plug-in solicita da Entra. Assim como no OAuth 2.0, use os valores de escopo exigidos pelo aplicativo Entra e pela API.
  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 SSO do Microsoft Entra no portal do desenvolvedor do Teams) e um URI da ID do aplicativo.

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"
},

Etapa 3: atualizar o registro do aplicativo Entra

Independentemente de como você criou a configuração de autenticação na Etapa 2, conclua as etapas a seguir.

  1. Abra o centro de administração do Microsoft Entra. Atualize o registro do aplicativo Entra que protege seu servidor MCP ou API com o URI da ID do aplicativo do registro SSO. Se você tiver um URI de ID de aplicativo existente mapeado para o registro do aplicativo, use o editor de manifesto para adicionar outro URI na seção identifierUris .

    "identifierUris": [
      "<<URI1>>",
      "<<URI2>>"
    ]
    

    Observação

    Não é possível adicionar vários URIs por meio da interface do usuário do centro de administração do Entra. A interface do usuário exibe apenas o primeiro URI na lista. A adição de vários URIs não afeta os URIs e escopos existentes, mesmo que eles sejam exibidos de forma diferente na interface do usuário.

  2. Selecione Autenticação em Gerenciar. Adicione https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect aos URIs de redirecionamento na plataforma Web .

  3. Selecione Expor uma API em Gerenciar. Selecione Adicionar um aplicativo cliente e adicione a ID do cliente do armazenamento de token do Microsoft Enterprise, ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b.

Etapa 4: adicionar o novo público-alvo do token à sua API

Atualize seu servidor MCP ou API para permitir o novo URI do identificador como o público-alvo do token. Se o servidor MCP ou a API validarem a ID do aplicativo cliente, certifique-se de que a ID do cliente do armazenamento de tokens do Microsoft Enterprise (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) seja adicionada como um aplicativo cliente permitido.

Dica

Se o servidor MCP ou a API usar o fluxo em nome de para obter acesso a outra API da Web que exija que o usuário conceda consentimento, retorne um 401 Unauthorized erro para fazer com que o agente solicite que o usuário entre para conceder consentimento.