Compartir vía

Configuración de la autenticación para complementos de API en agentes

  • Artículo

Puede configurar la autenticación para complementos de API en agentes que se ejecutan en Microsoft 365 Copilot mediante cualquiera de los cuatro esquemas de autenticación admitidos para conectarse sin problemas a sus API de back-end:

  • Flujo de código de autorización de OAuth 2.0
  • Microsoft Entra ID autenticación de inicio de sesión único (SSO)
  • Autenticación de clave de API
  • Sin autenticación (anónimo)

Flujo de código de autorización de OAuth 2.0

Un complemento puede acceder a una API mediante un token de portador obtenido mediante el flujo de código de autorización de OAuth 2.0, con compatibilidad opcional con la clave de prueba para intercambio de código (PKCE).

Antes de empezar, debe registrarse con el proveedor de OAuth 2.0 para obtener un identificador de cliente y un secreto. Si el proveedor de OAuth requiere que especifique los URI de redireccionamiento permitidos durante el registro de la aplicación, asegúrese de incluir https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect en la lista.

Importante

La compatibilidad del complemento de API con OAuth 2.0 tiene las siguientes limitaciones.

  • Los complementos de API solo admiten el flujo de código de autorización para OAuth 2.0.
  • No se admiten los servidores de OAuth 2.0 que devuelven 307 Temporary Redirect códigos de estado HTTP desde su punto de conexión de token.

Puede definir este esquema en la securitySchemes propiedad de un documento de OpenAPI. Para obtener más información, vea OAuth 2.0.

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

Para habilitar la autenticación de OAuth 2.0, debe registrar un cliente de OAuth en el portal para desarrolladores de Teams. Puede registrar un cliente de OAuth con Teams Toolkit en Visual Studio Code o registrarse manualmente en el portal para desarrolladores de Teams.

Registro de un cliente de OAuth con Teams Toolkit

Teams Toolkit registra el cliente de OAuth y actualiza el paquete de la aplicación automáticamente al crear un agente con el complemento de API a partir de un documento de OpenAPI existente. Debe tener la propiedad definida en el securitySchemes documento de OpenAPI.

Si el proveedor de OAuth admite PKCE, quite la marca de comentario de la siguiente línea de código en teamsapp.yml en el proyecto del agente antes de aprovisionar el agente.

# isPKCEEnabled: true

Registro de un cliente de OAuth en el portal para desarrolladores de Teams

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

  2. Si no tiene registros existentes, seleccione Registrar cliente. Si tiene registros existentes, seleccione Nuevo registro de cliente de OAuth.

  3. Rellene los campos siguientes.

    • Nombre de registro: un nombre descriptivo para el registro.
    • Dirección URL base: dirección URL base de la API. Este valor debe corresponder a una entrada de la matriz en el servers documento de OpenAPI.
    • Id. de cliente: identificador de cliente o de aplicación emitido por el proveedor de OAuth 2.0.
    • Secreto de cliente: secreto de cliente emitido por el proveedor de OAuth 2.0.
    • Punto de conexión de autorización: dirección URL del proveedor de OAuth 2.0 que las aplicaciones usan para solicitar un código de autorización
    • Punto de conexión de token: dirección URL del proveedor de OAuth 2.0 que las aplicaciones usan para canjear un código por un token de acceso
    • Actualizar punto de conexión: dirección URL del proveedor de OAuth 2.0 que las aplicaciones usan para actualizar el token de acceso
    • Ámbito: ámbito de permiso definido por la API que permite el acceso.
    • Habilitar clave de prueba para intercambio de código (PKCE): habilite esta configuración si el proveedor de OAuth admite PKCE.

  4. Haga clic en Guardar.

  5. Completar el registro genera un identificador de registro de cliente de OAuth.

Agregar el identificador de registro de cliente al manifiesto del complemento

Para usar la autenticación de OAuth 2.0 para el complemento de API, establezca la type propiedad del objeto OAuthPluginVaultde autenticación en tiempo de ejecución en y establezca en el reference_id identificador de registro de cliente desde el Portal para desarrolladores de Teams.

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

Microsoft Entra ID autenticación de SSO

Microsoft Entra ID autenticación de SSO permite la integración de inicio de sesión único (SSO) sin problemas, lo que 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 las API sin necesidad de credenciales adicionales. La API debe usar Microsoft Entra ID para controlar el acceso.

Registro de un cliente de SSO en el portal para desarrolladores de Teams

  1. Abra el portal para desarrolladores de Teams. Seleccione Herramientas ->Microsoft Entra registro de identificador de cliente de SSO.

  2. Si no tiene registros existentes, seleccione Registrar identificador de cliente. Si tiene registros existentes, seleccione Nuevo registro de cliente.

  3. Rellene los campos siguientes.

    • Nombre de registro: un nombre descriptivo para el registro.
    • Dirección URL base: dirección URL base de la API. Este valor debe corresponder a una entrada de la matriz en el servers documento de OpenAPI.
    • Restringir el uso por organización: seleccione qué organización de Microsoft 365 tiene acceso a la 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, enlace este registro con el identificador de aplicación publicado.
    • Id. de cliente: el identificador de cliente de la aplicación registrada en Microsoft Entra.

  4. Haga clic en Guardar.

  5. Al completar el registro, se genera un identificador de registro de sso de Microsoft Entra y un URI de identificador de aplicación.

Actualización del registro de la aplicación Microsoft Entra

  1. Abra Centro de administración Microsoft Entra. Actualice el registro de Microsoft Entra aplicación que protege la API con el URI del identificador de aplicación generado por el portal para desarrolladores de Teams. Si tiene un URI de identificador de aplicación existente asignado al registro de la aplicación, puede usar el editor de manifiestos para agregar otro URI en la sección identifierUris .

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

    Nota:

    No se admite la adición de varios URI a través de la interfaz de usuario del Centro de administración Microsoft Entra. La interfaz de usuario solo muestra el primer URI de la lista. Agregar varios URI no afecta a los URI y ámbitos existentes aunque se muestren 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 empresariales de Microsoft, ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b.

Adición del identificador de registro de SSO al manifiesto del complemento

Establezca la type propiedad del objeto OAuthPluginVaultde autenticación en tiempo de ejecución en y establezca en reference_id el Microsoft Entra identificador de registro de SSO desde el portal para desarrolladores de Teams.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "SSO registration ID"
},

Adición de la nueva audiencia de token a la API

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

Sugerencia

Si la API usa el flujo en nombre de para obtener acceso a otra API web que requiere que el usuario conceda consentimiento, devuelva un 401 Unauthorized error para que el agente pida al usuario que inicie sesión para conceder el consentimiento.

Autenticación de clave de API

Algunas API usan claves de API para la autorización. Una clave de API es un secreto compartido que el cliente incluye en las solicitudes de API para autenticarse y obtener acceso. Los complementos de API admiten el envío de la clave de API de tres maneras:

  • Como token de portador en el Authorization encabezado
  • Como valor en un encabezado personalizado
  • Como parámetro de consulta

Adición de una clave de API al documento de OpenAPI

Microsoft 365 Copilot determina cómo enviar la clave de API en función de la securitySchemes entrada del documento de OpenAPI.

Token de portador

Si la API acepta la clave de API como token de portador, habilite la autenticación de portador en el documento de OpenAPI. Para obtener más información, consulte Autenticación del portador.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Encabezado personalizado

Si la API acepta la clave de API en un encabezado personalizado, habilite la autenticación de clave de API en el documento de OpenAPI con la in propiedad establecida header en y la name propiedad establecida en el nombre del encabezado. Para obtener más información, consulte Claves de API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

Parámetro de consulta

Si la API acepta la clave de API en un parámetro de consulta, habilite la autenticación de clave de API en el documento de OpenAPI con la in propiedad establecida query en y la name propiedad establecida en el nombre del parámetro de consulta. Para obtener más información, consulte Claves de API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

Registro de una clave de API

Para habilitar la autenticación de clave de API, debe registrar la clave de API en el portal para desarrolladores de Teams. Puede registrar la clave de API con el kit de herramientas de Teams en Visual Studio Code o mediante el registro manual en el portal para desarrolladores de Teams.

Registro de una clave de API con el kit de herramientas de Teams

Teams Toolkit registra la clave de API y actualiza el paquete de la aplicación automáticamente al crear un agente con el complemento de API a partir de un documento de OpenAPI existente. Debe tener la propiedad definida en el securitySchemes documento de OpenAPI.

Nota:

Teams Toolkit solo admite claves de API como tokens de portador y no puede crear complementos de API basados en documentos de OpenAPI que usen un encabezado personalizado o un parámetro de consulta. Como solución alternativa, puede quitar temporalmente las securitySchemes propiedades y security de OpenAPI para generar el paquete del complemento y, a continuación, volver a agregarlas al documento de OpenAPI en el proyecto del complemento antes del aprovisionamiento. Debe registrar manualmente la clave de API.

Registro de una clave de API en el portal para desarrolladores de Teams

  1. Abra el portal para desarrolladores de Teams. Selección de Herramientas:>registro de claves de API

  2. Si no tiene registros existentes, seleccione Crear una clave de API. Si tiene registros existentes, seleccione Nueva clave de API.

  3. Seleccione Agregar secreto y escriba la clave de API.

  4. Rellene los campos siguientes.

    • Nombre de clave de API: un nombre descriptivo para el registro.
    • Dirección URL base: dirección URL base de la API. Este valor debe corresponder a una entrada de la matriz en el servers documento de OpenAPI.
    • Inquilino de destino: limite el acceso de la API al inquilino principal o no.
    • Aplicación de Teams de destino: seleccione Cualquier aplicación de Teams si no conoce el identificador final de la aplicación. Después de publicar la aplicación, enlace este registro con el identificador de aplicación publicado.

  5. Haga clic en Guardar.

  6. Completar el registro genera un identificador de registro de clave de API.

Adición del identificador de registro de clave de API al manifiesto del complemento
  1. En el archivo de manifiesto del complemento, establezca la type propiedad del objeto ApiKeyPluginVaultde autenticación en tiempo de ejecución en y establezca en el reference_id identificador de registro de clave de API desde el portal para desarrolladores de Teams.
"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "app key registration ID"
},

Sin autenticación (anónimo)

En el caso de las API que no requieren ninguna autenticación o para entornos de desarrollador en los que aún no se ha implementado la autenticación, los complementos pueden acceder a las API de forma anónima. En este caso, establezca la type propiedad del objeto Nonede autenticación en tiempo de ejecución en .

"auth": {
  "type": "None"
},