Agregar autenticación de terceros a la extensión de mensaje

  • Artículo

Importante

Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si busca documentación para versiones anteriores, consulte la sección Extensiones de mensaje - SDK v3 en la carpeta Recursos de la documentación.

Nota:

Después de agregar la autenticación a la extensión de mensaje, debe agregar "token.botframework.com" a la sección "validDomains" del manifiesto.

Identificación del usuario

Cada solicitud a los servicios incluye el identificador de usuario, el nombre para mostrar del usuario y Microsoft Entra identificador de objeto.

"from": {
  "id": "29:1C7dbRrC_5yzN1RGtZIrcWT0xz88KPGP9sxdpVpV8sODlgPHeQE9RqQ02hnpuKzy6zZ-AaZx6swUOMj_Dsdse3TQ4sIaeebbFBF-VgjJy_nY",
  "name": "Larry Jin",
  "aadObjectId": "cd723fa0-0591-416a-9290-e93ecf3a9b92"
},

Los valores id y aadObjectId están garantizados para el usuario autenticado de Teams. Se usan como claves para buscar las credenciales o cualquier estado almacenado en caché en el servicio. Además, cada solicitud contiene el identificador de inquilino de Microsoft Entra, que se usa para identificar la organización del usuario. Si procede, la solicitud también contiene el identificador del equipo y el identificador del canal desde el cual se origina la solicitud.

Autenticación

Si el servicio requiere la autenticación del usuario, los usuarios deben iniciar sesión antes de usar la extensión de mensaje. Los pasos de autenticación son similares a los de un bot o una pestaña. La secuencia es la siguiente:

  1. El usuario emite una consulta o se envía la consulta predeterminada automáticamente al servicio.
  2. El servicio comprueba si el usuario fue autenticado al inspeccionar el identificador de usuario de Teams.
  3. Si el usuario no está autenticado, envíe una respuesta auth con una acción sugerida openUrl que incluya la dirección URL de autenticación.
  4. El cliente de Microsoft Teams inicia un cuadro de diálogo que hospeda la página web mediante la dirección URL de autenticación especificada.
  5. Después de que el usuario inicie sesión, debe cerrar la ventana y enviar un código de autenticación al cliente de Teams.
  6. A continuación, el cliente de Teams vuelve a emitir la consulta al servicio, lo que incluye el código de autenticación aprobado en el paso 5.

El servicio debe comprobar que el código de autenticación recibido en el paso 6 coincide con el paso 5. Los pasos garantizan que un usuario malintencionado no intente suplantar o poner en peligro el flujo de inicio de sesión. El flujo "cierra el bucle" de forma eficaz para finalizar la secuencia de autenticación segura.

Responder con una acción de inicio de sesión

Para solicitar a un usuario no autenticado que inicie sesión, responda con una acción sugerida de tipo openUrl que incluya la dirección URL de autenticación.

Ejemplo de respuesta para una acción de inicio de sesión

{
  "composeExtension":{
    "type":"auth",
    "suggestedActions":{
      "actions":[
        {
          "type": "openUrl",
          "value": "https://example.com/auth",
          "title": "Sign in to this app"
        }
      ]
    }
  }
}

Nota:

  • Para que la experiencia de inicio de sesión se hospede en una ventana emergente de Teams, la parte del dominio de la dirección URL debe estar en la lista de dominios válidos de la aplicación. Para obtener más información, consulte validDomains en el esquema de manifiesto.
  • El tamaño del elemento emergente de autenticación se puede definir mediante la inclusión de parámetros de la cadena de consulta de ancho y alto, Value = $"{_siteUrl}/searchSettings.html?height=600&width=600".

Iniciar el flujo de inicio de sesión

La experiencia de inicio de sesión debe ser receptiva y ajustarse a una ventana emergente. Debe integrarse con la biblioteca cliente de JavaScript de Microsoft Teams, que usa el paso de mensajes.

Al igual que con otras experiencias incrustadas que se ejecutan dentro de Microsoft Teams, el código dentro de la ventana debe llamar primero a app.initialize(). Si el código realiza un flujo de OAuth, puede pasar al identificador de usuario de Teams a la ventana, que luego lo pasa a la dirección URL de inicio de sesión de OAuth.

Completar el flujo de inicio de sesión

Cuando la solicitud de inicio de sesión se complete y lo redirija de vuelta a la página, debe realizar los siguientes pasos:

  1. Genere un código de seguridad, un número aleatorio. Debe almacenar en caché este código en el servicio, con las credenciales obtenidas a través del flujo de inicio de sesión, como tokens de OAuth 2.0.
  2. Llame a authentication.notifySuccess y pase el código de seguridad.

En este momento, la ventana se cierra y el control se pasa al cliente de Teams. El cliente ahora vuelve a emitir la consulta de usuario original, junto con el código de seguridad de la propiedad state. El código puede usar un código de seguridad para buscar las credenciales almacenadas anteriormente y completar la secuencia de autenticación, y así completar la solicitud del usuario.

Ejemplo de solicitud reemitido

{
    "name": "composeExtension/query",
    "value": {
        "commandId": "insertWiki",
        "parameters": [{
            "name": "searchKeyword",
            "value": "lakers"
        }],
        "state": "12345",
        "queryOptions": {
            "skip": 0,
            "count": 25
        }
    },
    "type": "invoke",
    "timestamp": "2017-04-26T05:18:25.629Z",
    "localTimestamp": "2017-04-25T22:18:25.629-07:00",
    "entities": [{
        "locale": "en-US",
        "country": "US",
        "platform": "Web",
        "type": "clientInfo"
    }],
    "text": "",
    "attachments": [],
    "address": {
        "id": "f:7638210432489287768",
        "channelId": "msteams",
        "user": {
            "id": "29:1A5TJWHkbOwSyu_L9Ktk9QFI1d_kBOEPeNEeO1INscpKHzHTvWfiau5AX_6y3SuiOby-r73dzHJ17HipUWqGPgw",
            "aadObjectId": "fc8ca1c0-d043-4af6-b09f-141536207403"
        },
        "conversation": {
            "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
        },
        "bot": {
            "id": "28:c073afa8-7e77-4f92-b3e7-aa589e952a3e",
            "name": "maotestbot2"
        },
        "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
        "useAuth": true
    },
    "source": "msteams"
}

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js Manifiesto
Extensiones de mensaje: autenticación y configuración Extensión de mensaje que tiene una página de configuración, acepta solicitudes de búsqueda y devuelve los resultados después de que el usuario haya iniciado sesión. View View Ver

Consulte también

Habilitación del inicio de sesión único para la aplicación de extensión de bot y mensaje