Esquemas de autenticación para complementos de API para Microsoft 365 Copilot

Artículo
12/18/2024

Importante

Los complementos de API solo se admiten como acciones dentro de agentes declarativos. No se habilitan en Microsoft 365 Copilot.

Los complementos de API para Microsoft 365 Copilot admiten tres esquemas de autenticación para conectarse a sus API de back-end.

Flujo de código de autorización de OAuth 2.0
Clave de API a través de la autenticación del portador
Sin autenticación (anónimo)

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

Este esquema de autenticación permite a un complemento acceder a una API mediante un token de portador adquirido por un flujo de código de autorización de OAuth 2.0. Este esquema se puede representar en un documento OpenAPI de la securitySchemes propiedad . Consulte OAuth 2.0 para obtener más información.

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.

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

Para usar este esquema de autenticación en un complemento, debe registrar un cliente de OAuth en el portal para desarrolladores de Teams.

Sugerencia

Si el documento de OpenAPI incluye la securitySchemes propiedad , Teams Toolkit puede registrar el cliente de OAuth y actualizar el manifiesto automáticamente al generar un complemento a partir de una API existente.

Si el proveedor de OAuth admite proof key for Code Exchange (PKCE), quite la marca de comentario de la siguiente línea en teamsapp.yml en el proyecto del complemento de API.

# isPKCEEnabled: true

Registro de un cliente de OAuth

Nota:

Si el proveedor de OAuth requiere especificar uri de redireccionamiento permitidos al registrar la aplicación, incluya https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect en los URI de redireccionamiento permitidos.

Abra el explorador y vaya al portal para desarrolladores de aplicaciones de Teams. Seleccione Herramientas en el panel de navegación izquierdo.
Seleccione Registro de cliente de OAuth. Si no tiene registros existentes, seleccione Registrar cliente; Si tiene registros existentes, seleccione Nuevo registro de cliente de OAuth.
Rellene los campos siguientes.
- Nombre de registro: un nombre descriptivo para el registro
- Dirección URL base: dirección URL base de la API
- Id. de cliente: identificador de cliente o de aplicación emitido por el servidor de OAuth 2.0
- Secreto de cliente: el secreto de cliente emitido por el servidor de OAuth 2.0
- Punto de conexión de autorización: dirección URL del servidor 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 servidor de OAuth 2.0 que las aplicaciones usan para canjear un código por un token de acceso
- Punto de conexión de actualización: dirección URL del servidor de OAuth 2.0 que las aplicaciones usan para actualizar el token de acceso
- Ámbito: ámbito de permiso definido por la API que concede acceso.
- Habilitar clave de prueba para intercambio de código (PKCE): habilite esta configuración si el proveedor de OAuth admite PKCE.
Haga clic en Guardar.

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

Adición de la autenticación de OAuth 2.0 al manifiesto del complemento

Para usar la autenticación de OAuth 2.0 en el complemento, 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": "client registration ID"
},

Clave de API a través de la autenticación del portador

Este esquema de autenticación permite a un complemento acceder a una API mediante una clave o token de API de larga duración. Este token se envía en solicitudes de API en el Authorization encabezado como un token de portador. Este esquema se puede representar en un documento OpenAPI de la securitySchemes propiedad . Consulte Autenticación del portador para obtener más información.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Nota:

Los complementos de API no admiten el esquema de seguridad de clave de API de OpenAPI. Las API que usan claves de API para la autenticación deben usar el esquema de seguridad de autenticación de portador y aceptar la clave de API en el Authorization encabezado. No se puede definir un encabezado personalizado ni enviar la clave como un parámetro de consulta o una cookie.

Para usar este esquema de autenticación en un complemento, debe registrar una clave de API en el portal para desarrolladores de Teams.

Sugerencia

Si el documento de OpenAPI incluye la securitySchemes propiedad , Teams Toolkit puede registrar la clave de API y actualizar el manifiesto automáticamente al generar un complemento a partir de una API existente.

Registro de una clave de API

Abra el explorador y vaya al portal para desarrolladores de aplicaciones de Teams. Seleccione Herramientas en el panel de navegación izquierdo.
Seleccione Registro de claves de API. Si no tiene registros existentes, seleccione Registrar cliente; Si tiene registros existentes, seleccione Nueva clave de API.
Seleccione Agregar secreto y escriba la clave de API.
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
Haga clic en Guardar.

Completar el registro genera un identificador de registro de clave de aplicación.

Adición de la autenticación de clave de API al manifiesto del complemento

Para usar la autenticación de clave de API en el 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 aplicación 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"
},

Compartir a través de