Configuración de la autenticación SSO de Microsoft Entra

Recomendación

Recomendado: Comience con las herramientas de desarrollo de Work IQ para escenarios de complemento y agente declarativo de código profesional compatibles. Consulte el inicio rápido de WIQD. Las instrucciones basadas en el kit de herramientas siguen estando disponibles para los proyectos existentes y los flujos de trabajo que las requieren. Compruebe la compatibilidad con la capacidad y la experiencia de destino antes de elegir una herramienta: WIQD no se dirige a agentes de motor personalizados.

La autenticación de inicio de sesión único (SSO) de Microsoft Entra permite a los usuarios autenticarse con sus credenciales de Microsoft Entra ID existentes. Esta integración simplifica la administración del acceso y garantiza conexiones seguras a servidores o API de Model Context Protocol (MCP) sin necesidad de credenciales adicionales. Su servidor MCP o API debe utilizar el ID de Entra para controlar el acceso.

En este artículo se usan complementos de MCP como tutorial predeterminado. Los mismos pasos se aplican a los complementos de API creados a partir de un documento OpenAPI, excepto donde se indique lo contrario.

Configure la autenticación SSO de Entra en cuatro pasos: registrar una aplicación de Entra para proteger su servidor MCP, crear la configuración de autenticación, actualizar el registro de la aplicación de Entra y agregar la nueva audiencia de tokens a su API.

Paso 1: registrar una aplicación Entra para proteger su servidor MCP

Su servidor MCP o API debe estar protegido por un registro de aplicación Entra. Si aún no tiene una, registre una aplicación en el Centro de administración de Microsoft Entra. Anote el identificador de cliente de la aplicación: lo proporciona al crear la configuración de autenticación en el paso 2.

Paso 2: Crear la configuración de autenticación de Entra SSO

La autenticación entra SSO se basa en una configuración de autenticación (configuración de autenticación): un registro almacenado en el almacén de tokens de Microsoft Enterprise que Microsoft 365 Copilot usa para obtener tokens para el complemento MCP. Comience con WIQD para un proyecto pro-code compatible. Los procedimientos del kit de herramientas, las aptitudes para desarrolladores y el portal para desarrolladores de Teams siguen disponibles como alternativas.

Independientemente de cómo se cree, la configuración de autenticación tiene un identificador de configuración de autenticación y un identificador de aplicación URI. Utilice el URI de ID de aplicación en los pasos 3 y 4.

Importante

Independientemente de cómo cree la configuración de autenticación, debe completar los pasos 3 y 4.

Para una acción MCP, use wiqd agent add action con , --mcp-auth-type entra-ssoy --mcp-client-id establézcalo en --mcp-server-urlel ID de cliente de la aplicación Entra del paso 1. Para una acción de OpenAPI, use --openapi-auth-identity-provider microsoft-entra and --openapi-auth-client-id. Consulte la guía de comandos de acción de WIQD para ver las otras opciones de acción necesarias.

Para un manifiesto de complemento existente, use wiqd agent add auth con --plugin-manifest, --auth-name, y --auth-type microsoft-entra. Proporcione las opciones de proveedor de identidad documentadas para ese comando, incluidas --oauth-client-id. Complete el flujo de trabajo de aprovisionamiento del proyecto, obtenga el URI de identificador de aplicación de la configuración de autenticación y continúe con los pasos 3 y 4.

Usar Microsoft 365 Agents Toolkit

Cuando crea un agente con un complemento MCP en el Kit de herramientas de Microsoft 365 Agents, el kit de herramientas le solicita un tipo de autenticación al agregar el complemento MCP Server. Seleccione el SSO de Microsoft Entra y proporcione el identificador de cliente de la aplicación Entra en el paso 1. Agents Toolkit crea la configuración de autenticación en el almacén de tokens empresariales, genera el ID de configuración de autenticación y actualiza automáticamente el objeto de autenticación en tiempo de ejecución en el manifiesto del complemento.

Use la aptitud de desarrollador de agente declarativo

La aptitud de desarrollador de agente declarativo (declarative-agent-developer) es una aptitud de agente de Microsoft Work IQ que reúne los conocimientos necesarios para crear agentes declarativos. En lugar de ejecutar comandos o editar manifiestos usted mismo, describa lo que quiere Copilot o la CLI de GitHub en lenguaje natural. La aptitud aplica scaffolding al agente declarativo, agrega el complemento MCP y controla la configuración de autenticación por usted. La habilidad solo admite complementos MCP. Cuando se agrega un servidor MCP que utiliza el inicio de sesión único de Entra, la aptitud crea la configuración de autenticación en el almacén de tokens de empresa y actualiza el manifiesto del complemento sin pasos manuales.

Recomendación

Para ver un vídeo tutorial sobre el uso de la aptitud de desarrollador de agente declarativo, consulte Creación de agentes declarativos con la aptitud de desarrollador de agente declarativo.

Usar el portal para desarrolladores de Teams

El registro en el portal para desarrolladores de Teams es opcional si usa el kit de herramientas de agentes o la aptitud de desarrollador de agente declarativo. Úselo cuando desee crear la configuración de autenticación manualmente o, más comúnmente, para administrar una configuración de autenticación que Agents Toolkit o la habilidad ya crearon. En el portal, puede restringir la configuración de autenticación a una aplicación específica de Teams o de Microsoft 365 a la organización y modificar otras propiedades.

  1. Abra el portal para desarrolladores de Teams. Seleccione Herramientas -Registro del id. de cliente de SSO de> Microsoft Entra.

  2. Si no tiene ningún registro existente, seleccione Registrar id. de cliente. Si tiene registros existentes, seleccione Registro de nuevo cliente.

  3. Rellene los campos siguientes.

    • Nombre de registro: un nombre descriptivo para el registro.
    • Dirección URL base: la dirección URL base de la API. Este valor debe corresponder a la URL de la url propiedad del objeto MCP Server Spec en el manifiesto de complementos para complementos basados en MCP o a una entrada de la matriz en el servers documento OpenAPI para complementos de API.
    • Restringir el uso por organización: seleccione qué organización de Microsoft 365 tiene acceso a su aplicación para acceder a los puntos de conexión de API.
    • Restringir el uso por aplicación: seleccione cualquier aplicación de Teams si no conoce el identificador final de la aplicación. Después de publicar la aplicación, vincule este registro con el identificador de la aplicación publicada.
    • Client ID: El ID de cliente de la aplicación registrada en Entra.
    • Alcance: Los permisos que su complemento solicita a Entra. Al igual que con OAuth 2.0, use los valores de ámbito requeridos por la aplicación y la API de Entra.
  4. Selecciona Guardar.

  5. Al completar el registro, se crea la configuración de autenticación y se genera un identificador de configuración de autenticación (actualmente etiquetado como identificador de registro de SSO de Microsoft Entra en el portal para desarrolladores de Teams) y un identificador de aplicación URI.

Agregar el identificador de configuración de autenticación al manifiesto del complemento

Al crear la configuración de autenticación manualmente en el portal para desarrolladores de Teams, establezca la type propiedad del objeto de autenticación en tiempo de ejecución en OAuthPluginVaulty establézcala reference_id en el identificador de configuración de autenticación. Agents Toolkit y la habilidad de desarrollador de agente declarativo hacen esto por usted.

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

Paso 3: Actualizar el registro de la aplicación Entra

Independientemente de cómo haya creado la configuración de autenticación en el paso 2, complete los pasos siguientes.

  1. Abra el Centro de administración de Microsoft Entra. Actualice el registro de la aplicación Entra que protege el servidor MCP o la API con el URI de id. de aplicación del registro de SSO. Si tiene un URI de identificador de aplicación existente asignado al registro de la aplicación, use el editor de manifiestos para agregar otro URI en la sección identifierUris .

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

    Nota

    No se pueden agregar varios URI a través de la interfaz de usuario del Centro de administración de Entra. La interfaz de usuario solo muestra el primer URI de la lista. Agregar varios URI no afecta a los URI y ámbitos existentes, incluso si se muestran de forma diferente en la interfaz de usuario.

  2. Seleccione Autenticación en Administrar. Agregue https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect a los URI de redireccionamiento en la plataforma web .

  3. Seleccione Exponer una API en Administrar. Seleccione Agregar una aplicación cliente y agregue el identificador de cliente del almacén de tokens de Microsoft Enterprise. ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b

Paso 4: Agregar la nueva audiencia de tokens a la API

Actualice el servidor MCP o la API para permitir el nuevo identificador URI como audiencia de token. Si el servidor MCP o la API validan el identificador de aplicación cliente, asegúrese de que el identificador de cliente (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) del almacén de tokens empresariales de Microsoft se agregue como aplicación cliente permitida.

Recomendación

Si el servidor MCP o la API usa el flujo en nombre de para obtener acceso a otra API web que requiere que el usuario otorgue consentimiento, devuelva un 401 Unauthorized error para que el agente solicite al usuario que inicie sesión para otorgar consentimiento.