Compartir a través de

Habilitación del inicio de sesión único para extensiones de mensajes basadas en API

  • Artículo

El método de autenticación de inicio de sesión único (SSO) para la extensión de mensajes basada en API usa la identidad de Teams de un usuario de la aplicación para proporcionarle acceso a la aplicación. Un usuario que haya iniciado sesión en Teams no tiene que volver a iniciar sesión en la aplicación en el entorno de Teams. Microsoft Entra SSO permite que la aplicación obtenga de forma silenciosa un token de usuario emitido para su recurso por Microsoft Entra. A continuación, la aplicación puede autenticar este token y recuperar la información del perfil de usuario sin el consentimiento del usuario.

Requisitos previos

Antes de empezar, asegúrese de que tiene lo siguiente:

  • Una cuenta de Azure con una suscripción activa.
  • Conocimientos básicos sobre Microsoft Entra ID y el desarrollo de aplicaciones de Teams.

En la imagen siguiente se muestra cómo funciona el inicio de sesión único cuando un usuario de la aplicación de Teams intenta acceder a la aplicación de extensión de mensajes basada en API:

Captura de pantalla que muestra cómo funciona Microsoft Entra autorización de SSO para autenticar la extensión de mensajes basada en API.

  • El usuario invoca la aplicación de extensión de mensajes basada en API en Teams e invoca un comando que requiere autenticación.
  • La aplicación envía una solicitud al servicio back-end de Teams con el identificador de aplicación y el ámbito necesario (access_as_user).
  • El servicio back-end de Teams comprueba si el usuario ha aceptado la aplicación y el ámbito. Si no es así, muestra una pantalla de consentimiento al usuario.
  • Si el usuario da su consentimiento, Microsoft Entra genera un token de acceso para el usuario y la aplicación, y lo envía a la aplicación en el encabezado de autorización de la solicitud.
  • La aplicación valida el token y extrae la información del usuario del token, como el nombre, el correo electrónico y el identificador de objeto.
  • Después de la autenticación correcta, se concede al usuario acceso a la extensión de mensaje basada en API.

Para habilitar la autenticación sso para la extensión de mensajes basada en API, siga estos pasos:

Registro de una nueva aplicación en Microsoft Entra ID

  1. Abra el Azure Portal en el explorador web.

  2. Seleccione el icono Registros de aplicaciones.

    Captura de pantalla que muestra la página Centro de administración Microsoft Entra.

    Aparece la página Registros de aplicaciones.

  3. Seleccione + Nuevo icono de registro..

    Captura de pantalla que muestra la nueva página de registro en Centro de administración Microsoft Entra.

    Aparece la página Registrar una aplicación.

  4. Escriba el nombre de la aplicación que desea que se muestre al usuario de la aplicación. Si lo desea, puede cambiar el nombre en una fase posterior.

    Captura de pantalla que muestra la página de registro de la aplicación en Centro de administración Microsoft Entra.

  5. Seleccione el tipo de cuenta de usuario que puede acceder a su aplicación. Puede seleccionar entre opciones únicas o multiinquilino en directorios organizativos o restringir el acceso solo a cuentas personales de Microsoft.

    Opciones para tipos de cuenta admitidos
    Opción Seleccione esta opción para...
    Solo cuentas en este directorio organizativo (solo Microsoft: inquilino único) Compile una aplicación para que solo la usen los usuarios (o invitados) de su inquilino.
    A menudo denominada aplicación personalizada creada para su organización (aplicación LOB), esta aplicación es una aplicación de inquilino único en el Plataforma de identidad de Microsoft.
    Cuentas en cualquier directorio organizativo (cualquier inquilino Microsoft Entra ID multiinquilino) Permitir que los usuarios de cualquier Microsoft Entra inquilino usen la aplicación. Esta opción es adecuada si, por ejemplo, está creando una aplicación SaaS y tiene previsto que esté disponible para varias organizaciones.
    Este tipo de aplicación se conoce como una aplicación multiinquilino en el Plataforma de identidad de Microsoft.
    Cuentas en cualquier directorio organizativo (cualquier inquilino Microsoft Entra ID multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox) Dirigirse al conjunto más amplio de clientes.
    Al seleccionar esta opción, va a registrar una aplicación multiinquilino que puede admitir a los usuarios de la aplicación que también tienen cuentas personales de Microsoft.
    Solo cuentas personales de Microsoft Cree una aplicación solo para los usuarios que tengan cuentas personales de Microsoft.

    Nota:

    No es necesario escribir el URI de redirección para habilitar el inicio de sesión único para una aplicación de extensión de mensajes basada en API.

  6. Seleccione Registrar. Aparece un mensaje en el explorador que indica que se ha creado la aplicación.

    Captura de pantalla que muestra un ejemplo de la notificación después de que el registro de la aplicación se haya realizado correctamente en Azure Portal.

    Se muestra la página con el identificador de la aplicación y otros detalles de la aplicación.

    Captura de pantalla que muestra la página de detalles de la aplicación en Azure Portal.

  7. Tenga en cuenta y guarde el identificador de aplicación del identificador de aplicación (cliente) para actualizar el manifiesto de la aplicación más adelante.

    La aplicación está registrada en Microsoft Entra ID. Ahora tiene el identificador de aplicación para la aplicación de extensión de mensajes basada en API.

Configurar el ámbito para el token de acceso

Después de crear un nuevo registro de aplicaciones, configure las opciones de ámbito (permiso) para enviar el token de acceso al cliente de Teams y autorizar aplicaciones cliente de confianza para habilitar el inicio de sesión único.

Para configurar el ámbito y autorizar aplicaciones cliente de confianza, debe:

  • Agregar URI de id. de aplicación: configure las opciones de ámbito (permiso) para la aplicación. Exponga una API web y configure el URI del identificador de aplicación.
  • Configurar ámbito de API: defina el ámbito de la API y los usuarios que pueden dar su consentimiento para un ámbito. Solo puede permitir que los administradores den su consentimiento para permisos con privilegios superiores.
  • Configuración de la aplicación cliente autorizada: cree identificadores de cliente autorizados para las aplicaciones que desea autenticar previamente. Permite al usuario de la aplicación acceder a los ámbitos de la aplicación (permisos) que ha configurado, sin necesidad de ningún consentimiento adicional. Autorice previamente solo las aplicaciones cliente en las que confíe, ya que los usuarios de la aplicación no tienen la oportunidad de rechazar el consentimiento.

URI de id. de aplicación

  1. Seleccione Administrar>Exponer una API en el panel izquierdo.

    Aparece la página Exponer una API.

  2. Seleccione Agregar para generar el URI del identificador de aplicación en forma de api://{AppID}.

    Captura de pantalla que muestra cómo establecer el URI del identificador de aplicación.

    Aparece la sección para establecer el URI del identificador de aplicación.

  3. Escriba el URI del identificador de aplicación en el formato que se explica aquí.

    Captura de pantalla que muestra el URI del identificador de aplicación en Microsoft Entra ID.

    • El URI del identificador de aplicación se rellena previamente con el identificador de aplicación (GUID) en el formato api://{AppID}.
    • El formato uri del identificador de aplicación debe ser: api://fully-qualified-domain-name.com/{AppID}.
    • Inserte el fully-qualified-domain-name.com entre api:// y {AppID} (el cual es, GUID). Por ejemplo, api://example.com/{AppID}.

    Importante

    • Si va a compilar un bot independiente, escriba el URI del identificador de aplicación como api://botid-{YourBotId}. Aquí, {YourBotId} es el identificador de aplicación de Microsoft Entra.
    • Si va a compilar una aplicación con un bot, una extensión de mensaje y una pestaña, escriba el URI del identificador de aplicación como api://fully-qualified-domain-name.com/botid-{YourClientId}, donde {YourClientId} es el identificador de la aplicación de bot.
    • Si va a compilar una aplicación con una extensión de mensaje o funcionalidades de tabulación sin el bot, escriba el URI del identificador de aplicación como api://fully-qualified-domain-name.com/{YourClientId}, donde {YourClientId} es el identificador de aplicación Microsoft Entra.
    • URI de identificador de aplicación para la aplicación con varias funcionalidades: si va a crear una extensión de mensaje basada en API, escriba el URI del identificador de aplicación como api://fully-qualified-domain-name.com/{YourClientId}, donde {YourClientId} es el identificador de aplicación de Microsoft Entra.
    • Formato para el nombre de dominio: use solo letras minúsculas para el nombre de dominio.

  4. Haga clic en Guardar.

    Aparece un mensaje en el explorador que indica que se ha actualizado el URI del identificador de aplicación.

    Captura de pantalla que muestra el mensaje uri del identificador de aplicación.

    El URI del identificador de aplicación se muestra en la página.

    Captura de pantalla que muestra el URI del identificador de aplicación actualizado.

  5. Tenga en cuenta y guarde el URI del identificador de aplicación para actualizar el manifiesto de la aplicación más adelante.

Configuración del ámbito de API

Nota:

  • La extensión de mensaje basada en API solo admite el ámbito de access_as_user .
  • La API recibe un token de acceso Microsoft Entra con el ámbito establecido access_as_user en como registrado en el Azure Portal. Sin embargo, el token no está autorizado para llamar a ninguna otra API de bajada, como Microsoft Graph.

  1. Seleccione + Agregar un ámbito en la sección Ámbitos definidos por esta API.

    Captura de pantalla que muestra la opción seleccionar ámbito.

    Aparece la página Agregar un ámbito.

  2. Introduzca los detalles para configurar el ámbito.

    En la captura de pantalla se muestra cómo agregar detalles de ámbito en Azure.

    1. Introduzca el nombre del ámbito. Este campo es obligatorio.
    2. Seleccione el usuario que puede dar su consentimiento para este ámbito. La opción predeterminada es Solo administradores.
    3. Introduzca el nombre para mostrar del consentimiento del administrador. Este campo es obligatorio.
    4. Introduzca la descripción para el consentimiento del administrador. Este campo es obligatorio.
    5. Introduzca el nombre para mostrar del consentimiento del usuario.
    6. Introduzca la descripción del consentimiento del usuario.
    7. Seleccione la opción Habilitado para el estado.
    8. Seleccione Agregar ámbito.

    Aparece un mensaje en el explorador que indica que se ha agregado el ámbito.

    Captura de pantalla que muestra el mensaje agregado de ámbito.

    El nuevo ámbito definido se muestra en la página.

    Captura de pantalla que muestra un ejemplo del ámbito agregado a la aplicación en Azure Portal.

Configuración de la aplicación cliente autorizada

  1. Vaya a la página Exponer una API a la sección Aplicación cliente autorizada y seleccione + Agregar una aplicación cliente.

    Captura de pantalla que muestra la aplicación cliente autorizada.

    Aparece la página Agregar una aplicación cliente.

  2. Escriba el identificador de cliente de Microsoft 365 adecuado para las aplicaciones que desea autorizar para la aplicación web de la aplicación.

    Captura de pantalla que muestra la opción Id. de cliente y Ámbitos autorizados para agregar una aplicación cliente a la aplicación en Azure Portal. Adición de una aplicación cliente

    Nota:

    Los identificadores de cliente de Microsoft 365 para aplicaciones móviles, de escritorio y web para Teams son los identificadores reales que debe agregar.

    1. Seleccione uno de los siguientes identificadores de cliente:

      Usar Id. de cliente Para autorizar...
      1fec8e78-bli4-4aaf-ab1b-5451cc387264 Aplicación móvil o de escritorio de Teams
      5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Aplicación web de Teams

    2. Seleccione el URI de identificador de aplicación que creó para la aplicación en Ámbitos autorizados para agregar el ámbito a la API web que ha expuesto.

    3. Seleccione Agregar aplicación.

      Aparece un mensaje en el explorador que indica que se ha agregado la aplicación cliente autorizada.

      Captura de pantalla que muestra el mensaje agregado de la aplicación cliente.

      El identificador de cliente de la aplicación autorizada se muestra en la página.

      Captura de pantalla que muestra la aplicación cliente agregada.

Nota:

Puede autorizar más de una aplicación cliente. Repita los pasos de este procedimiento para configurar otra aplicación cliente autorizada.

Ha configurado correctamente el ámbito de la aplicación, los permisos y las aplicaciones cliente. Asegúrese de anotar y guardar el URI del identificador de aplicación. A continuación, configure la versión del token de acceso.

Autenticación del token

Cuando la extensión de mensaje llama a la API durante la autenticación, recibe una solicitud con el token de acceso del usuario. A continuación, la extensión de mensaje agrega el token en el encabezado de autorización de la solicitud HTTP saliente. El formato de encabezado es Authorization: Bearer <token_value>. Por ejemplo, cuando una extensión de mensaje realiza una llamada API a un servicio que requiere autenticación. La extensión crea una solicitud HTTP de la siguiente manera:

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Una vez que la extensión de mensaje basada en API obtiene un encabezado de solicitud con token, realice los pasos siguientes:

  • Autenticar: compruebe el token de las notificaciones de audiencia, ámbito, emisor y firma para comprobar si el token es para la aplicación. Para obtener más notificaciones, consulte Notificaciones de token de identificador.

    En el ejemplo siguiente se muestra el token web JSON (JWT) con un encabezado y una respuesta:

    {
"typ": "JWT",
"rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.",
"alg": "RS256",
"kid": "q-23falevZhhD3hm9CQbkP5MQyU"
}.{
  "aud": "00000002-0000-0000-c000-000000000000",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1712509315,
  "nbf": 1712509315,
  "exp": 1712513961,
  "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=",
  "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
  "azpacr": "0",
  "name": "John Doe",
  "oid": "00000000-0000-0000-0000-000000000000",
  "preferred_username": "john.doe@contoso.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8",
  "tid": "12345678-aaaa-bbbb-cccc-9876543210ab",
  "uti": "h7DMQwSPAEeiEe62JJUGAA",
  "ver": "2.0"
  }

  • Usar el token: extraiga la información de usuario del token, como el nombre, el correo electrónico y el identificador de objeto, y use el token para llamar a la propia API de la aplicación de extensión de mensaje. Para obtener más información sobre la referencia de notificaciones con detalles sobre las notificaciones incluidas en los tokens de acceso, consulte Notificaciones de token de acceso.

Actualizar el manifiesto de la aplicación

Actualice las siguientes propiedades en el archivo de manifiesto de la aplicación:

  • webApplicationInfo: la webApplicationInfo propiedad se usa para habilitar el inicio de sesión único para la aplicación con el fin de ayudar a los usuarios de la aplicación a acceder a la aplicación de extensión de mensajes basada en API sin problemas. El URI del identificador de aplicación que registró en Microsoft Entra ID se configura con el ámbito de la API que ha expuesto. Para obtener más información, consulte webApplicationInfo.

       Captura de pantalla que muestra la configuración del manifiesto de la aplicación.

  • microsoftEntraConfiguration: habilita la autenticación de SSO para la aplicación. Configure la supportsSingleSignOn propiedad para true admitir el inicio de sesión único y reducir la necesidad de varias autenticaciones. Si la propiedad se establece en false o se deja vacía, el usuario no puede cargar la aplicación en Teams y se produce un error en la validación de la aplicación.

Para configurar el manifiesto de aplicación:

  1. Abra la aplicación de extensión de mensajes basada en API.

  2. Abra la carpeta del manifiesto de la aplicación.

    Nota:

  3. Abra el archivo manifest.json.

  4. Agregue el siguiente fragmento de código a la webApplicationInfo sección del archivo de manifiesto de la aplicación:

    "webApplicationInfo":
{
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}

    donde,

    • {Microsoft Entra AppId}es el identificador de aplicación que creó al registrar la aplicación en Microsoft Entra ID. Es el GUID.
    • api://subdomain.example.com/{Microsoft Entra AppId}es el URI de identificador de aplicación que registró al crear el ámbito en Microsoft Entra ID.

  5. Agregue el siguiente fragmento de código a la composeExtensions sección del archivo de manifiesto de la aplicación:

    "authorization": {
  "authType": "microsoftEntra",
  “microsoftEntraConfiguration”: {
    “supportsSingleSignOn”: true
  }
},

  6. Guarde el archivo de manifiesto de la aplicación.

Enhorabuena. Ha habilitado el inicio de sesión único para las extensiones de mensaje basadas en API.

Recursos adicionales