Uso del kit de herramientas de Microsoft Graph con Electron

  • Artículo

En este artículo se describe cómo usar Microsoft Graph Toolkit para crear una aplicación Electron y conectarla a Microsoft 365. Después de completar los pasos, tendrá una aplicación Electron que muestra las próximas citas del usuario que ha iniciado sesión actualmente desde Microsoft 365.

Creación de una aplicación de Electron

Aplica scaffolding a una nueva aplicación electron usando Electron Forge. Al hacerlo, se crea una nueva aplicación Electron en TypeScript, que le ayuda a escribir código más sólido y a evitar errores en tiempo de ejecución.

npm init electron-app@latest mgt-app -- --template=webpack-typescript

Cambie el directorio de trabajo a la aplicación recién creada.

cd mgt-app

Confirme que puede ejecutar la aplicación.

npm start

Abra el package.json archivo y asegúrese de que la versión de dependencia de desarrollo de electrones es 28.2.4. 28.2.4 es la versión máxima actual de la dependencia del mismo nivel requerida por @microsoft/mgt-electron-provider.

Instale el paquete "@microsoft/mgt-components" que contiene todos los componentes web conectados a Microsoft Graph.

npm i @microsoft/mgt-components

Instale también los @microsoft/mgt-electron-provider paquetes y @microsoft/mgt-element npm. Esto le permite proporcionar autenticación para la aplicación mediante MSAL y usar los componentes del kit de herramientas de Microsoft Graph.

npm i @microsoft/mgt-element @microsoft/mgt-electron-provider

Creación de un identificador de aplicación o cliente

Agregar nuevo registro de aplicación en Microsoft Entra ID para obtener un identificador de cliente

Para crear una aplicación en Microsoft Entra ID, debe agregar un nuevo registro de aplicación y, a continuación, configurar un nombre de aplicación y un URI de redirección.

Para crear la aplicación en Microsoft Entra ID:

  1. Ve al Centro de administración Microsoft Entra.
  2. Expanda Identidad> y seleccione Aplicaciones>Registros de aplicaciones.
  3. En el menú superior, seleccione el botón Nuevo registro .
  4. Escriba el nombre de la aplicación; por ejemplo, My Electron-App.
  5. Para el tipo de tipos de cuenta admitidos, seleccione Cuentas en cualquier directorio organizativo (cualquier directorio Microsoft Entra : multiinquilino) y cuentas personales de Microsoft (por ejemplo, Skype, Xbox).
  6. En el campo URI de redirección , en la lista desplegable, seleccione Cliente público o nativo (escritorio de & móvil) y, en el campo DIRECCIÓN URL, escriba msal://redirect.
  7. Para confirmar los cambios, seleccione el botón Registrar .
  8. Vaya al registro de la aplicación.
  9. Compruebe que se encuentra en la página Información general .
  10. En la sección Essentials, copie el valor de la propiedad Application (client) ID.

Configuración del proveedor de autenticación de Microsoft Graph Toolkit

Inicialización de ContextBridge en el script de carga previa

A partir de Electron v12, el aislamiento de contexto está habilitado de forma predeterminada y se trata de una configuración de seguridad recomendada para todas las aplicaciones. Con el aislamiento de contexto, los desarrolladores deben exponer explícitamente las API de su proceso principal para su uso en el proceso del representador a través de ContextBridge. Para obtener más información, consulte Aislamiento de contexto en la documentación de Electron.

Abra el archivo src/preload.ts y agregue el código siguiente:

import { type IpcRendererEvent, contextBridge, ipcRenderer } from 'electron';
import { AuthenticationProviderOptions } from '@microsoft/microsoft-graph-client';

contextBridge.exposeInMainWorld("main", {
  electronProvider: {
    mgtAuthState: (callback: (event: IpcRendererEvent, authState: string) => void) => ipcRenderer.on('mgtAuthState', callback),
    token: (options?: AuthenticationProviderOptions) => ipcRenderer.invoke('token', options),
    login: () => ipcRenderer.invoke('login'),
    logout: () => ipcRenderer.invoke('logout'),
    approvedScopes: (callback: (event: IpcRendererEvent, scopes: string[]) => void) => ipcRenderer.on('approvedScopes', callback),
  },
});

Inicialización de ElectronContextBridgeProvider en el proceso del representador

es ElectronContextBridgeProvider responsable de comunicarse con ElectronAuthenticator (en el proceso principal) para solicitar tokens de acceso y recibir información sobre el estado de sesión iniciada que es necesario para que funcionen los componentes del kit de herramientas.

Para usar componentes de Microsoft Graph Toolkit en las aplicaciones, deben registrarse en la ventana del explorador que abran. Para ello, debe importar las funciones de registro para cada componente que quiera usar.

Para inicializar ElectronContextBridgeProvider y registrar los componentes de Microsoft Graph Toolkit, agregue el código siguiente al archivo src/renderer.ts .

import { Providers } from "@microsoft/mgt-element";
import { registerMgtAgendaComponent, registerMgtLoginComponent } from '@microsoft/mgt-components';
import {
  type IContextBridgeImpl,
} from "@microsoft/mgt-electron-provider/dist/Provider";
import { ElectronContextBridgeProvider } from "@microsoft/mgt-electron-provider/dist/Provider/ElectronContextBridgeProvider";

// this provides typings for the object added to the renderer window by the preload script
declare global {
  interface Window {
    // can be named anything, like "electronApi"
    main: {
      electronProvider: IContextBridgeImpl;
    };
  }
}

// initialize the auth provider globally
const init = () => {
  Providers.globalProvider = new ElectronContextBridgeProvider(window.main.electronProvider);
  registerMgtLoginComponent();
  registerMgtAgendaComponent();
};

init();

Inicialización de ElectronAuthenticator en el proceso principal

ElectronAuthenticator es responsable de configurar las variables de configuración para la autenticación de MSAL, adquirir tokens de acceso y comunicarse con ElectronContextBridgeProvider. ElectronAuthenticator se inicializa en el proceso principal y configura las variables de configuración, como el identificador de cliente y los ámbitos necesarios.

En primer lugar, abra src/index.ts e importe ElectronAuthenticator y MsalElectronConfig desde @microsoft/mgt-electron-provider en la parte superior de la página.

import {
  ElectronAuthenticator,
  MsalElectronConfig,
} from "@microsoft/mgt-electron-provider/dist/Authenticator";

A continuación, agregue importar la COMMON_AUTHORITY_URL constante.

import { COMMON_AUTHORITY_URL } from '@microsoft/mgt-electron-provider/dist/Authenticator/Constants';

A continuación, agregue estas líneas de código en la createWindow() función para inicializar el ElectronAuthenticator, justo después de donde mainWindow se declara. Reemplace por <your_client_id> el identificador de cliente del registro de la aplicación.

const config: MsalElectronConfig = {
  clientId: "<your_client_id>",
  authority: COMMON_AUTHORITY_URL, // Uses the common auth endpoint
  mainWindow: mainWindow, //This is the BrowserWindow instance that requires authentication
  scopes: [
    "user.read",
    "user.read",
    "people.read",
    "user.readbasic.all",
    "contacts.read",
    "presence.read.all",
    "presence.read",
    "user.read.all",
    "calendars.read",
  ],
};
ElectronAuthenticator.initialize(config);

Agregar una directiva de seguridad de contenido de desarrollo

La aplicación que electron Forge scaffolds incluye una directiva de seguridad de contenido (CSP) predeterminada, que no permite capturar datos de un servidor remoto. Con fines de desarrollo, puede agregar un CSP muy permisivo. En el caso de las aplicaciones de producción, debe crear un CSP sólido que permita que la aplicación funcione y, al mismo tiempo, reducir la superficie expuesta a ataques para los actores incorrectos.

Abra el archivo forge.config.ts y reemplace el objeto de configuración existente que se pasa al constructor WebpackPlugin por el siguiente objeto de configuración.

{
  mainConfig,
  devContentSecurityPolicy: "default-src * self blob: data: gap:; style-src * self 'unsafe-inline' blob: data: gap:; script-src * 'self' 'unsafe-eval' 'unsafe-inline' blob: data: gap:; object-src * 'self' blob: data: gap:; img-src * self 'unsafe-inline' blob: data: gap:; connect-src self * 'unsafe-inline' blob: data: gap:; frame-src * self blob: data: gap:;",
  renderer: {
    config: rendererConfig,
    entryPoints: [
      {
        html: './src/index.html',
        js: './src/renderer.ts',
        name: 'main_window',
        preload: {
          js: './src/preload.ts',
        },
      },
    ],
  },
}

Agregar componentes a la página HTML

Agregue contenido a la aplicación. Ahora puede usar los componentes del kit de herramientas de Microsoft Graph en la página deindex.html y mostrar la agenda del usuario. Reemplace el contenido de la página index.html por lo siguiente.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Hello World!</title>
  </head>
  <body>
    <h1>❤️ Hello World! 🦒</h1>
    <p>Welcome to your MGT Electron application.</p>
    <mgt-login></mgt-login>
    <mgt-agenda group-by-day></mgt-agenda>
  </body>
</html>

Ejecutar la aplicación

npm start

Adición de funcionalidades de almacenamiento en caché de tokens a la aplicación y habilitación de inicios de sesión silenciosos (avanzado)

El nodo MSAL admite una caché en memoria de forma predeterminada y proporciona la interfaz ICachePlugin para realizar la serialización de caché, pero no proporciona una forma predeterminada de almacenar la caché de tokens en el disco. Si necesita almacenamiento en caché persistente para habilitar inicios de sesión silenciosos o almacenamiento en caché multiplataforma, se recomienda usar la implementación predeterminada proporcionada por MSAL Node como extensión. Puede importar este complemento y pasar la instancia del complemento de caché al inicializar ElectronAuthenticator.

let config: MsalElectronConfig = {
  ...
  cachePlugin: new PersistenceCachePlugin(filePersistence) //filePersistence is the instance of type IPersistence that you will need to create
};

Para obtener más información sobre cómo implementar esto, consulte el ejemplo Biblioteca de autenticación de Microsoft para js .

Contenido relacionado