Publicando una aplicación en Microsoft Teams y usando su API de SSO

Con el confinamiento debido al covid-19, las plataformas empresariales de comunicación y colaboración se han vuelto una necesidad, como es el caso de Microsoft Teams.

Microsoft Teams es una plataforma muy completa, ofrece toda la suite de aplicaciones de Microsoft 365, video conferencias, chat, almacenamiento…y además, si tenemos los permisos suficientes, podemos subir aplicaciones propias al marketplace de nuestro dominio/tenant de Microsoft.

En este post vamos a ver cómo crear una aplicación para Teams basada en React JS. Esta App estará securizada, lo que significa que deberemos estar logados para poder utilizarla, pero para evitar al usuario final de Teams hacer log in múltiples veces, le logaremos automáticamente utilizando el SSO que ofrece a través de una API JavaScript.

Requisitos previos

Lo primero que necesitaremos para poder crear aplicaciones y subirlas al marketplace de Teams, es tener suficientes permisos dentro del dominio de Microsoft. Si no los tenemos, podemos crearnos una cuenta de desarrollador @onmicrosoft siguiendo estas guías.

Lo siguiente será tener nuestra aplicación en React JS accesible desde internet, en nuestro caso estará alojada en https://lab.onesaitplatform.com/web/teams-example/

Creación de la aplicación en Azure AD

En este paso vamos a dar de alta la aplicación en Azure AD, para poder utilizar la funcionalidad de SSO dentro de Microsoft Teams.

Con nuestra cuenta de microsoft, desde el portal de azure, crearemos una aplicación nueva en Azure AD. Seleccionamos un nombre y habilitamos que cualquier cuenta de Microsoft pueda usarla.

Nueva aplicación de Azure AD

Cuando acabe el proceso de registro, nos llevará a una pantalla con el detalle de la aplicación, seleccionaremos exponer una API.

Exponer una API

Seleccionamos agregar un ámbito, se abrirá un pop up y pondremos como nombre del ámbito access_as_user, permitiremos el consentimiento a usuarios y administradores, y por último nos aseguraremos de que queda habilitado:

Agregar ámbito a la aplicación

Una vez agregado el ámbito, editaremos la URI de id. de aplicación (botón del lápiz), añadiendo a la URI la URL del dominio donde se encuentra nuestra aplicación React, por lo que quedaría así:

api://lab.onesaitplatform.com/fc8e45f6-6487-4d25-9e88-26ed262e06ab

URI de id de aplicación

Lo siguiente será añadir las aplicaciones cliente de Teams necesarias que van a conectarse a esta App:

  • 1fec8e78-bce4-4aaf-ab1b-5451cc387264: Aplicación para equipos móviles o de escritorio
  • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346: Aplicación Web de Teams

Para ello, le damos a agregar una aplicación cliente e introducimos ambos identificadores.

Añadir aplicaciones cliente de Teams

Como último paso, iremos a la sección de Permisos de API y editaremos los permisos, haciendo click en “Microsoft Graph“. Además del que viene por defecto User.Read dentro de Microsoft Graph añadiremos: email, offline_access, openid, profile.

Habilitar permisos de la API
Permisos de la API de autenticación de Azure AD

Modificación de la aplicación React JS

Tendremos que adaptar el código de la aplicación React para que utilice la librería JS de SSO de Microsoft.

Haremos uso de la dependencia https://www.npmjs.com/package/@microsoft/teams-js

npm i @microsoft/teams-js

En la página de Login la importaremos para usarla:

import * as microsoftTeams from "@microsoft/teams-js";

Y en el método del ciclo de vida del componente componentDidMount() añadiremos las siguientes líneas:

componentDidMount(){
      microsoftTeams.initialize();
      microsoftTeams.authentication.getAuthToken({
         successCallback: result => {
            this._exchangeToken(result);
         },
         failureCallback: reason => {
            alert(reason)
         }
       });
    }

En la función de success simplemente llamaremos a nuestro Identity Manager para intercambiar el token JWT de Microsoft por un JWT propio. El Identity Manager se encargará de descodificar el JWT de Microsoft (en base 64) , y extraer el usuario (preferred_username) para logarlo automáticamente. Esta lógica se puede hacer en JavaScript puro, pero en nuestro caso, la aplicación utiliza un Identity Manager, por lo que es necesario tener un token expedido por dicho componente.

El token JWT de Microsoft descodificado tiene la siguiente información:

{
  "aud": "6e74172b-be56-4843-9ff4-e66a39bb12e3",
  "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0",
  "iat": 1537231048,
  "nbf": 1537231048,
  "exp": 1537234948,
  "aio": "AXQAi/8IAAAAtAaZLo3ChMif6KOnttRB7eBq4/DccQzjcJGxPYy/C3jDaNGxXd6wNIIVGRghNRnwJ1lOcAnNZcjvkoyrFxCttv33140RioOFJ4bCCGVuoCag1uOTT22222gHwLPYQ/uf79QX+0KIijdrmp69RctzmQ==",
  "azp": "6e74172b-be56-4843-9ff4-e66a39bb12e3",
  "azpacr": "0",
  "name": "Abe Lincoln",
  "oid": "690222be-ff1a-4d56-abd1-7e4f7d38e474",
  "preferred_username": "abeli@microsoft.com",
  "rh": "I",
  "scp": "access_as_user",
  "sub": "HKZpfaHyWadeOouYlitjrI-KffTm222X5rrV3xDqfKQ",
  "tid": "72f988bf-86f1-41af-91ab-2d7cd011db47",
  "uti": "fqiBqXLPj0eQa82S-IYFAA",
  "ver": "2.0"
}

Con esta modificación, si accedemos a la aplicación desplegada, veremos que no hace nada, y sigue apareciendo el login, esto es porque si la librería de Microsoft Teams se ejecuta fuera de Teams, no hará nada.

Empaquetado de la aplicación para Teams

El último paso es empaquetar la aplicación en un zip para poder subirla al marketplace de Teams. En dicho zip necesitaremos los siguientes archivos:

  • manifest.json Archivo JSON que contiene la información necesaria para que la aplicación de Teams pueda integrar nuestra aplicación
  • icon.png Icono para mostrar de nuestra aplicación en teams, este irá referenciado en el manifest anterior.

Para crear el manifest.json podéis partir de esta plantilla:

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.5/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0",
  "id": "fc8e45f6-6487-4d25-9e88-26ed262e06ab",
  "packageName": "com.onesaitplatform.lab",
  "developer": {
    "name": "Javier Gomez Cornejo ",
    "websiteUrl": "https://onesaitplatform.atlassian.net/wiki",
    "privacyUrl": "https://onesaitplatform.atlassian.net/wiki",
    "termsOfUseUrl": "https://onesaitplatform.atlassian.net/wiki"
  },
  "name": {
    "short": "React JS (SSO)",
    "full": "React JS SSO"
  },
  "description": {
    "short": "React JS App",
    "full": "React JS App SSO "
  },
  "icons": {
    "outline": "platform_logo.png",
    "color": "platform_logo.png"
  },
  "accentColor": "#ffffff",
  "staticTabs": [
    {
      "contentUrl": "https://lab.onesaitplatform.com/web/teams-example/",
      "entityId": "reactclient",
      "name": "React API Client",
      "scopes": [
        "personal"
      ]
    }
  ],
  "webApplicationInfo":
  {
    "id": "fc8e45f6-6487-4d25-9e88-26ed262e06ab",
    "resource": "api://lab.onesaitplatform.com/fc8e45f6-6487-4d25-9e88-26ed262e06ab"
  }
}

Tendréis que cambiar los siguientes atributos:

  • id: este es el id de la aplicación de Azure AD que creamos antes:
ID de aplicación Azure AD
  • packageName: es el dominio donde está nuestra aplicación React desplegada, pero en orden inverso: com.onesaitplatform.lab
  • staticTabs.contentUrl: aquí pondremos la URL de nuestra aplicación React. Será lo que muestre la pestaña del teams
  • icons: pondremos el nombre de nuestro icon.png elegido
  • webApplicationInfo: aquí deberemos poner el ID de aplicación de Azure AD, y la URI de id de aplicación.
URI de id de aplicación

Por último, comprimiremos estos dos archivos en un zip para poder subirlo a Teams.

Subir la aplicación al marketplace de Teams

Ya solo nos queda disponibilizar el empaquetado zip anterior en Teams, y cualquier usuario de nuestro dominio de Microsoft podrá verla e instalarla en su Teams.

Iremos a la aplicación de Teams, al icono de aplicaciones y le daremos a cargar una aplicación personalizada seleccionando el zip del paso anterior:

Cargar una aplicación personalizada

Cuando se cargue, la seleccionaremos y le daremos a agregar, para que se instale correctamente.

Agregar la aplicación

Ahora podremos navegar a nuestra aplicación dentro del Teams, en la barra izquierda, y veremos que al abrirse no nos pide el usuario y nos logea automáticamente 🙂

SSO en Teams

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google photo

Estás comentando usando tu cuenta de Google. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s