Configurar la autenticación de OAuth 2.0

Un complemento puede acceder a un servidor o API de Protocolo de contexto de modelo (MCP) mediante un token de portador obtenido a través del flujo de código de autorización de OAuth 2.0, con la compatibilidad con la clave de prueba para intercambio de código (PKCE) habilitada de forma predeterminada. En este flujo, Microsoft 365 Copilot abre la experiencia de inicio de sesión, el proveedor de OAuth devuelve una respuesta de autorización a Microsoft Teams y Teams intercambia el código de autorización por tokens.

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 de OAuth 2.0 en tres pasos: registre un cliente OAuth con su proveedor de identidad, configure el URI de redireccionamiento y cree la configuración de OAuth 2.0.

Paso 1: Registro de un cliente OAuth con el proveedor de identidades

Registre una aplicación con su proveedor de OAuth 2.0 (su proveedor de identidad) para obtener un id. de cliente y, para un cliente confidencial (web), un secreto de cliente. Proporcione estos valores al crear la configuración de OAuth 2.0 en el paso 3.

Para un servidor MCP que requiera autorización, establezca la type propiedad del objeto de autenticación en tiempo de ejecución en OAuthPluginVault. None y ApiKeyPluginVault no se aplican a un servidor MCP que requiere autorización. En el manifiesto solo se almacena el id. de configuración de autenticación: no se escribe en él ningún id. de cliente, secreto de cliente o token. Para registrar el cliente dinámicamente en lugar de estáticamente, manténgalo type y OAuthPluginVault cree la configuración de autenticación a través del registro dinámico de clientes (DCR), que no está disponible para un servidor protegido por Microsoft Entra ID.

Nota:

Estos valores se aplican al manifiesto del complemento. Si en su lugar registra su servidor MCP como un conector de agente en el agentConnectors nodo del manifiesto de la aplicación Microsoft 365, use OAuthPluginVault or DynamicClientRegistration allí también. Don't use AzureKeyVault: solo existe en el esquema, por lo que un paquete destinado a una versión de esquema numerada no supera la devPreview validación. Para obtener más información, consulte Registro de servidores MCP como conectores de agente.

Paso 2: Configurar el URI de redireccionamiento

Agregue el siguiente URI de redireccionamiento (también denominado URL de devolución de llamada de autorización) al registro del proveedor de OAuth:

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect

Es la dirección URL a la que el proveedor de OAuth envía la respuesta de autorización después de que un usuario inicia sesión. Teams recibe la respuesta en esta dirección URL de devolución de llamada e intercambia el código de autorización por tokens. Si no registra este URI de redireccionamiento con su proveedor, se produce un error de inicio de sesión. El URI de redireccionamiento es el mismo para todos los complementos y proveedores; no lo personaliza por aplicación.

Paso 3: Crear la configuración de autenticación de OAuth 2.0

La autenticación OAuth 2.0 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 y actualizar tokens para el complemento MCP. Puede crear la configuración de autenticación de tres maneras. Los enfoques recomendados (Kit de herramientas de agentes de Microsoft 365 y la aptitud de desarrollador de agente declarativo) crean la configuración de autenticación y actualizan el manifiesto del complemento automáticamente. A continuación, puede usar el portal para desarrolladores de Teams para administrar y refinar la configuración de autenticación.

Independientemente de cómo lo cree, la configuración de autenticación tiene un identificador de configuración de autenticación al que hace referencia el manifiesto del complemento.

Al compilar un agente con un complemento de MCP (si el servidor requiere autenticación) o crear un complemento de API a partir de un documento OpenAPI existente en el Kit de herramientas de agentes de Microsoft 365, el kit de herramientas le solicita el identificador de cliente, el secreto de cliente y los ámbitos de OAuth. Agents Toolkit obtiene los puntos finales de autorización, token y actualización del punto final conocido de su servidor MCP (o del documento OpenAPI para complementos de API), crea la configuración de autenticación en el almacén de tokens de empresa y actualiza automáticamente el objeto de autenticación en tiempo de ejecución en el manifiesto del complemento.

Nota:

Para los complementos de API, debe definir la propiedad en su documento OpenAPI para que Agents securitySchemes Toolkit pueda leer los detalles de OAuth. Para obtener más información, consulte OAuth 2.0.

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

PKCE está habilitado de forma predeterminada porque muchas organizaciones bloquean los secretos de cliente. Establézcalo isPKCEEnabledfalse en m365agents.yml en el proyecto del agente antes de aprovisionar el agente solo cuando el proveedor de OAuth no admita PKCE.

isPKCEEnabled: false

Para evitar por completo los secretos de cliente, registre un cliente público con su proveedor (una plataforma de aplicaciones de una sola página en lugar de una plataforma web) y deje que PKCE asegure el intercambio de código.

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 recopila los conocimientos necesarios para crear agentes declarativos. En lugar de ejecutar comandos o editar manifiestos usted mismo, describe lo que quiere a Copilot o a la CLI de GitHub en lenguaje natural, y 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. Para OAuth 2.0, admite tanto el registro estático como el registro de cliente dinámico (DCR): crea la configuración de autenticación en el almacén de tokens de Enterprise y actualiza el manifiesto del complemento sin pasos manuales.

Sugerencia

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.

El registro del cliente OAuth en el portal para desarrolladores de Teams conecta la configuración del complemento del agente con el registro del proveedor de OAuth que emite tokens para el servidor MCP o la API. Los valores de este registro deben coincidir con el proveedor de OAuth, el manifiesto del complemento y el punto de conexión de API protegido. Las direcciones URL base no coincidentes, las restricciones de aplicación o los identificadores de configuración de autenticación pueden impedir que los usuarios inicien sesión o pueden bloquear el intercambio de tokens.

Advertencia

Restrinja el registro a cualquier aplicación de Teams. Un registro que está restringido a una aplicación específica de Teams se enlaza a ese identificador de aplicación de Teams. Microsoft 365 Copilot no resuelve ese identificador cuando llama a un servidor MCP, por lo que el aprovisionamiento finaliza correctamente y, a continuación, cada llamada a la herramienta devuelve un 404 error.

  1. Abra el portal para desarrolladores de Teams. Seleccione Herramientas -registro de> cliente OAuth.

  2. Si no tiene ningún registro existente, seleccione Registrar cliente. Si tiene registros existentes, seleccione Nuevo registro de cliente OAuth.

  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é organizaciones de Microsoft 365 pueden usar este registro de OAuth para acceder a los puntos de conexión de API. Use Mi organización solo para desarrollo o pruebas en un espacio empresarial. Use cualquier organización de Microsoft 365 cuando el complemento deba funcionar en todos los inquilinos.
    • Restringir el uso por aplicación: seleccione cualquier aplicación de Teams. No enlace el registro a la id. de aplicación de Teams existente para un servidor MCP. Si aprovisiona la configuración de autenticación con Microsoft 365 Agents Toolkit en su lugar, la configuración equivalente en la oauth/register acción en m365agents.yml es applicableToApps: AnyApp. Mantenga el campo en esa acción aunque AnyApp lo haga inerte, ya que el controlador de aprovisionamiento valida appId incondicionalmente y al quitarlo se interrumpe el appId aprovisionamiento.
    • Id. de cliente: el id. de cliente o de aplicación emitido por el proveedor de OAuth 2.0.
    • Secreto de cliente: el secreto de cliente emitido por el proveedor de OAuth 2.0.
    • Punto de conexión de autorización: la dirección URL de su proveedor de OAuth 2.0 que las aplicaciones usan para solicitar un código de autorización.
    • Punto de conexión de token: la dirección URL de su proveedor de OAuth 2.0 que las aplicaciones usan para canjear un código por un token de acceso.
    • Actualizar punto de conexión: la dirección URL de su proveedor de OAuth 2.0 que las aplicaciones usan para actualizar el token de acceso.
    • Ámbito: los permisos que el complemento solicita al proveedor de OAuth. Use los valores de ámbito requeridos por el proveedor y la API. Si su proveedor usa la Plataforma de identidad de Microsoft y el complemento necesita tokens de actualización, inclúyalo offline_access con los ámbitos delegados específicos de la API.
    • Habilitar clave de prueba para intercambio de código (PKCE): deje esta configuración habilitada. Está activado de forma predeterminada; deshabilítelo solo si su proveedor de OAuth no admite PKCE.

  4. Haga clic en 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 cliente OAuth en el portal para desarrolladores de Teams).

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

Consideraciones sobre Microsoft Entra ID

Al proteger el servidor MCP mediante Microsoft Entra ID, se aplican tres restricciones que no se pueden evitar en las herramientas.

  • El registro de cliente dinámico no está disponible. Microsoft Entra ID no publica un punto de conexión de registro RFC 7591, por lo que el registro dinámico de clientes no tiene nada con qué registrarse. Registre el cliente OAuth de forma estática siguiendo los pasos descritos en este artículo.
  • Este agentConnectors nodo no tiene ningún tipo de autorización de Microsoft Entra. A diferencia composeExtensionsde , el agentConnectors nodo del manifiesto de la aplicación Microsoft 365 no tiene ningún microsoftEntra tipo de autorización. Un servidor MCP protegido por Microsoft Entra ID siempre necesita una aplicación en la que te registres con Microsoft Entra ID, además de una configuración de autenticación OAuth, incluso cuando el servidor esté frente a una API de Microsoft propia.
  • El consentimiento del ámbito no se comprueba cuando se aprovisiona. El aprovisionamiento no comprueba si se puede dar el consentimiento al ámbito que solicita. Un ámbito que no se puede consentir se aprovisiona correctamente y luego falla con la aprobación del administrador, y la aplicación de recursos puede ser invisible tanto para usted como para el administrador de inquilinos. Confirme que un administrador ha dado su consentimiento al ámbito antes de aprovisionar.

Administrar la configuración de autenticación

La oauth/register acción en m365agents.yml solo crea una configuración de autenticación u omite la creación de una, nunca vuelve a escribir un registro existente.

  • Si configurationId ya tiene un valor, la acción no hace nada.
  • Si configurationId apunta a un registro que eliminó, la acción le advierte y no hace nada.
  • Para cambiar los valores de un registro existente, use la oauth/update acción.
  • Para eliminar un registro, use el portal para desarrolladores de Teams. Es el único lugar donde puede eliminar uno.

Cerrar sesión

Nota:

Los usuarios pueden cerrar la sesión de un agente desdeAgentes de configuración> de chat en Microsoft 365 Copilot. Esta acción borra el token de OAuth almacenado.

Contenido relacionado

  • Last updated on