Compartir vía

Autenticación de clave de API

  • Artículo

La autenticación de clave de API es un método que se usa para autenticar el acceso a la aplicación de extensión de mensajes mediante una API. Implica el uso de una clave de API única, que se pasa con cada solicitud de API para comprobar la identidad del usuario o la aplicación que inició la solicitud. La clave de API debe registrarse en Microsoft Teams y, cuando un usuario interactúa con la extensión de mensaje, Teams usa el secreto para autenticarse con la API.

Las siguientes propiedades de registro de claves de API le ayudan a proteger la clave y a asegurarse de que está limitada a la aplicación:

  • Dirección URL base: Teams transmite el secreto a los puntos de conexión de dirección URL que comienzan con el valor de este campo.
  • Inquilino de destino: para limitar el acceso de la API al inquilino de Microsoft 365 o a cualquier inquilino.
  • Id. de aplicación: para limitar el acceso de clave a una aplicación específica o a cualquier aplicación.
  • Clave de API: para autenticar el acceso a la aplicación.

Puede registrar una clave de API a través del Portal para desarrolladores para Teams y generar un identificador de registro de clave de API. Actualice el manifiesto de aplicación con el apiSecretServiceAuthConfiguration objeto con una apiSecretRegistrationId propiedad . Esta propiedad debe contener el identificador de registro de clave de API devuelto al enviar la clave de API a través del Portal para desarrolladores para Teams.

Nota:

Debe asegurarse de proteger el identificador de registro de clave de API, ya que se puede recuperar del manifiesto de aplicación de Teams. Para obtener más información sobre cómo proteger la clave de API, consulte procedimientos recomendados.

Cuando se inicia una solicitud de API, el sistema recupera la clave de API de una base de datos cifrada e la incluye en el encabezado de autorización, mediante el esquema de token de portador. El sistema envía el encabezado de autorización con la clave de API al punto de conexión definido en el manifiesto de la aplicación.

En el ejemplo siguiente se muestra la carga con el encabezado de autorización mediante el esquema de token de portador:

GET https://example.com/search?myQuery=test
Accept-Language: en-US
Authorization: Bearer <MY_API_KEY>

Registro de una clave de API

Para registrar una clave de API, siga estos pasos:

  1. Vaya alregistro de claves de APIde herramientas>.

    Captura de pantalla que muestra la opción de registro de claves de API en el Portal para desarrolladores para Teams.

  2. Seleccione + Nueva clave de API.

  3. En la página Registro de claves de API , seleccione + Agregar secreto. Aparece el cuadro de diálogo Agregar una clave de API .

  4. Escriba un valor para la clave y seleccione Guardar.

    Nota:

    Puede mantener hasta dos claves de API. Si necesita reemplazar uno, puede hacerlo sin interrupción del servicio, ya que Teams usa la otra clave configurada durante el proceso de actualización.

    Captura de pantalla que muestra el cuadro de diálogo Agregar una clave de API para agregar la clave de API para la aplicación.

  5. En Nombre de clave de API, agregue un nombre significativo para la clave de API. Por ejemplo, clave de API para la extensión de mensaje contoso.

  6. En Dirección URL base, especifique una dirección URL base común para todos los puntos de conexión de API a los que se debe llamar. Esta dirección URL debe empezar por https, incluir un nombre de dominio completo y, opcionalmente, una ruta de acceso. Teams transmite la clave al punto de conexión de dirección URL que comienza con el valor de este campo. Por ejemplo, https://api.yelp.com.

    La dirección URL base garantiza que la clave permanezca segura y no se filtre a puntos de conexión aleatorios, incluso si otra aplicación adquiere ilícitamente el identificador de registro de clave de API e la incorpora a su propia aplicación. Si la dirección URL registrada en la configuración de clave de API no es un prefijo para los puntos de conexión de destino definidos en la especificación de OpenAPI, se quita la llamada.

    Captura de pantalla que muestra las opciones Descripción y Agregar dominio en la página de registro de claves de API del Portal para desarrolladores para Teams.

  7. En Inquilino de destino, seleccione cualquiera de las siguientes opciones:

    • Inquilino principal: la clave de API solo es funcional dentro del inquilino donde está registrada.
    • Cualquier inquilino: la clave de API se puede usar en cualquier inquilino.

    Captura de pantalla que muestra las opciones Inquilino principal y Cualquier inquilino en Establecer un encabezado de inquilino de destino en Portal para desarrolladores para Teams.

  8. En Aplicación de Teams de destino, seleccione cualquiera de las siguientes opciones:

    • Aplicación de Teams existente: la opción Aplicación de Teams existente enlaza el identificador de registro de clave de API a la aplicación específica de Teams.
    • Cualquier aplicación de Teams: la clave de API se puede usar con cualquier aplicación de Teams.

    Captura de pantalla que muestra las opciones Cualquier aplicación de Teams y Aplicación existente de Teams en Establecer un encabezado de aplicación de Teams en Portal para desarrolladores para Teams.

    Se genera un identificador de registro de clave de API .

    Captura de pantalla que muestra el identificador de registro de clave de API generado en el Portal para desarrolladores para Teams.

  9. En portal para desarrolladores de Teams, seleccione Aplicaciones y seleccione una aplicación en la que quiera agregar la clave de API.

  10. Vaya a Características >de la aplicaciónExtensión de mensaje.

  11. En Autenticación, seleccione Clave de API y agregue el identificador de registro de clave de API.

    Captura de pantalla que muestra un ejemplo de la sección Autenticación con ninguna y las opciones de clave de API en el Portal para desarrolladores para Teams.

  12. Haga clic en Guardar.

El identificador de registro de clave de API se actualiza como el valor de la propiedad en el apiSecretRegistrationId manifiesto de la aplicación. Puede comprobar el identificador de registro de clave de API en el manifiesto de la aplicación en el Portal para desarrolladores de Teams.

Actualizar el manifiesto de la aplicación

Agregue un apiSecretServiceAuthConfiguration objeto con una apiSecretRegistrationId propiedad, que contiene el identificador de referencia al enviar la clave de API a través del Portal para desarrolladores para Teams. Para obtener más información, vea composeExtensions.commands.

"composeExtensions": [
    {
      "composeExtensionType": "apiBased",
      "authorization": {
        "authType": "apiSecretServiceAuth",
        "apiSecretServiceAuthConfiguration": {
            "apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
        }
      },

Procedimientos recomendados

  • Clave de API:

    • La clave de API debe tener al menos 10 caracteres y como máximo 2048 caracteres.
    • Después de actualizar la clave de API, la clave tarda hasta una hora en reflejarse en todo el sistema.

  • Dirección URL base:

    • La dirección URL base debe comenzar por https para garantizar una comunicación segura.
    • Debe incluir el nombre de host completo para especificar el dominio exacto.
    • Puede agregar una ruta de acceso opcional para definir un punto de entrada específico para la API.

    Esta estructura es fundamental para la seguridad de las claves de API, ya que Teams envía la clave de API a los puntos de conexión que comienzan con la dirección URL base especificada.

  • Inquilino de destino: a medida que desarrolle la aplicación dentro del inquilino de Microsoft 365, inicialmente la probará como una aplicación personalizada creada para su organización (aplicación LOB) o aplicación personalizada. Durante esta fase, debe registrar la clave de API en el inquilino de inicio como inquilino de destino para asegurarse de que la clave permanece exclusiva para el inquilino.

    Una vez que haya completado las pruebas y esté listo para enviar el manifiesto de la aplicación al Centro de partners de la Tienda Teams, deberá cambiar la configuración del inquilino de destino a Cualquier inquilino. Este cambio permite que el identificador de registro de clave de API se use en varios inquilinos una vez que la aplicación esté disponible en la Tienda Teams.

  • Identificador de aplicación de Teams: a medida que desarrolla la aplicación en el inquilino de Microsoft 365 y comienza a probarla como una aplicación personalizada creada para su organización (LOB) o aplicación personalizada, debe establecer el identificador de registro de clave de API con el identificador de aplicación de Teams como Cualquier aplicación de Teams. Esta configuración permite usar la clave con cualquier aplicación de Teams cargada como una aplicación personalizada y aplicaciones personalizadas creadas para su organización (aplicaciones LOB) para generar identificadores después de cargarlos. No tendrá el identificador de la aplicación en esta fase.

    La seguridad de la clave se mantiene a través del inquilino principal y la dirección URL base. Cuando esté listo para publicar la aplicación en el mundo, debe cambiar la configuración de Id. de aplicación de Teams a Aplicación de Teams existente e introducir el identificador de la aplicación de Teams. Por último, envía el manifiesto de la aplicación al Centro de partners para su inclusión en la Tienda Teams. El registro de clave de API ahora está asociado a la aplicación específica de Teams y no se puede usar con otros usuarios.

    Para una aplicación personalizada creada para su organización (LOB) o aplicación personalizada, hay un identificador de aplicación interno que es difícil de acceder. En este escenario, limite la configuración al inquilino donde se usa la aplicación. Para otras aplicaciones, vincule el registro de clave de API con el identificador de aplicación publicado después de publicarlo en la Tienda Teams.

Recursos adicionales