Utiliser le Kit de ressources Microsoft Graph avec Electron

  • Article

Cet article explique comment utiliser le Kit de ressources Microsoft Graph pour créer une application Electron et la connecter à Microsoft 365. Une fois les étapes terminées, vous disposez d’une application Electron qui affiche les rendez-vous à venir de l’utilisateur actuellement connecté à partir de Microsoft 365.

Créer une application Electron

Créez une structure d’une nouvelle application Electron à l’aide d’Electron Forge. Cela crée une application Electron dans TypeScript, qui vous permet d’écrire du code plus robuste et d’éviter les erreurs d’exécution.

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

Changez le répertoire de travail par l’application nouvellement créée.

cd mgt-app

Confirmez que vous pouvez exécuter l’application.

npm start

Ouvrez le package.json fichier et vérifiez que la version de dépendance de développement electron est 28.2.4. 28.2.4 est la version maximale actuelle pour la dépendance d’homologue requise par @microsoft/mgt-electron-provider.

Installez le package « @microsoft/mgt-components » qui contient tous les composants web connectés à Microsoft Graph.

npm i @microsoft/mgt-components

Installez également les @microsoft/mgt-electron-provider packages npm et @microsoft/mgt-element . Ceux-ci vous permettent d’assurer l’authentification de votre application à l’aide de MSAL et d’utiliser les composants du Kit de ressources Microsoft Graph.

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

Créer un ID client/application

Ajouter une nouvelle inscription d’application dans Microsoft Entra ID pour obtenir un ID client

Pour créer une application dans Microsoft Entra ID, vous devez ajouter une nouvelle inscription d’application, puis configurer un nom d’application et un URI de redirection.

Pour créer l’application dans Microsoft Entra ID :

  1. Allez au centre d'administration Microsoft Entra.
  2. Développez Identité>, développez Applications>, sélectionnez inscriptions d'applications.
  3. Dans le menu supérieur, sélectionnez le bouton Nouvelle inscription.
  4. Entrez le nom de votre application ; par exemple, My Electron-App.
  5. Pour le type de types de comptes pris en charge, sélectionnez Comptes dans n’importe quel annuaire organisationnel (n’importe quel annuaire Microsoft Entra - Multilocataire) et comptes Microsoft personnels (par exemple, Skype, Xbox).
  6. Dans le champ URI de redirection, dans la liste déroulante, sélectionnez Client public/natif (bureau mobile &) et dans le champ URL, entrez msal://redirect.
  7. Confirmez les changements en sélectionnant le bouton Inscrire.
  8. Accédez à l’inscription de votre application.
  9. Vérifiez que vous êtes sur la page Vue d’ensemble.
  10. Dans la section Essentials, copiez la valeur de la propriété ID d’application (client).

Configurer le fournisseur d’authentification de la Boîte à outils Microsoft Graph

Initialiser un ContextBridge dans votre script de préchargement

À compter d’Electron v12, l’isolation de contexte est activée par défaut et il s’agit d’un paramètre de sécurité recommandé pour toutes les applications. Avec l’isolation de contexte, les développeurs doivent exposer explicitement des API à partir de leur processus main pour les utiliser dans le processus de renderer via un ContextBridge. Pour plus d’informations, consultez Isolation de contexte dans la documentation Electron.

Ouvrez le fichier src/preload.ts et ajoutez le code suivant :

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),
  },
});

Initialisation d’ElectronContextBridgeProvider dans votre processus de renderer

Le ElectronContextBridgeProvider est chargé de communiquer avec ElectronAuthenticator (dans le processus de main) pour demander des jetons d’accès et recevoir des informations sur l’état connecté requis pour que les composants du kit de ressources fonctionnent.

Pour utiliser les composants du Kit de ressources Microsoft Graph dans vos applications, ils doivent être inscrits dans la fenêtre du navigateur qu’ils ouvrent. Pour ce faire, vous devez importer les fonctions d’inscription pour chaque composant que vous souhaitez utiliser.

Pour initialiser et ElectronContextBridgeProvider inscrire les composants du Kit de ressources Microsoft Graph, ajoutez le code suivant au fichier 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();

Initialisation d’ElectronAuthenticator dans votre processus de main

le ElectronAuthenticator est chargé de configurer les variables de configuration pour l’authentification MSAL, d’acquérir des jetons d’accès et de communiquer avec le ElectronContextBridgeProvider. Le ElectronAuthenticator est initialisé dans le processus main et configure les variables de configuration telles que l’ID client et les étendues requises.

Tout d’abord, ouvrez src/index.ts et importez et MsalElectronConfig à ElectronAuthenticator partir de @microsoft/mgt-electron-provider en haut de la page.

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

Ajoutez ensuite importer la COMMON_AUTHORITY_URL constante.

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

Ensuite, ajoutez ces lignes de code dans la createWindow() fonction pour initialiser l’ElectronAuthenticator, juste après mainWindow où est déclaré. Remplacez par <your_client_id> l’ID client de l’inscription de votre application.

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);

Ajouter une stratégie de sécurité du contenu de développement

L’application générée par Electron Forge inclut une stratégie de sécurité de contenu (CSP) par défaut, qui interdit l’extraction de données à partir d’un serveur distant. À des fins de développement, vous pouvez ajouter un fournisseur de solutions Cloud hautement permissif. Pour les applications de production, vous devez créer un fournisseur de solutions cloud robuste qui permet à votre application de fonctionner tout en réduisant la surface d’attaque pour les acteurs malveillants.

Ouvrez le fichier forge.config.ts et remplacez l’objet config existant passé au constructeur WebpackPlugin par l’objet config suivant.

{
  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',
        },
      },
    ],
  },
}

Ajouter des composants à votre page HTML

Ajoutez du contenu à votre application. Vous pouvez maintenant utiliser les composants du kit de ressources Microsoft Graph dans votre page index.html et afficher l’agenda de l’utilisateur. Remplacez le contenu de la page index.html par ce qui suit.

<!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>

Exécuter votre application

npm start

Ajouter des fonctionnalités de mise en cache de jeton à votre application et activer les connexions silencieuses (avancées)

MsAL Node prend en charge un cache en mémoire par défaut et fournit l’interface ICachePlugin pour effectuer la sérialisation du cache, mais ne fournit pas de moyen par défaut de stocker le cache de jetons sur le disque. Si vous avez besoin d’un stockage de cache persistant pour activer les connexions silencieuses ou la mise en cache multiplateforme, nous vous recommandons d’utiliser l’implémentation par défaut fournie par MSAL Node comme extension. Vous pouvez importer ce plug-in et passer le instance du plug-in de cache lors de l’initialisation ElectronAuthenticatorde .

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

Pour plus d’informations sur la façon d’implémenter cela, consultez l’exemple Bibliothèque d’authentification Microsoft-for-js .

Contenu connexe