Verwenden des Microsoft Graph-Toolkits mit Electron

  • Artikel

In diesem Artikel wird beschrieben, wie Sie das Microsoft Graph-Toolkit verwenden, um eine Electron-App zu erstellen und mit Microsoft 365 zu verbinden. Nach Abschluss der Schritte verfügen Sie über eine Electron-App, die die bevorstehenden Termine des aktuell angemeldeten Benutzers von Microsoft 365 anzeigt.

Erstellen einer Electron-App

Erstellen Sie ein Gerüst für eine neue Electron-App mithilfe von Electron Forge. Dadurch wird eine neue Electron-App in TypeScript erstellt, mit der Sie stabileren Code schreiben und Laufzeitfehler vermeiden können.

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

Ändern Sie das Arbeitsverzeichnis in die neu erstellte App.

cd mgt-app

Vergewissern Sie sich, dass Sie die App ausführen können.

npm start

Öffnen Sie die package.json Datei, und stellen Sie sicher, dass die Electron Dev-Abhängigkeitsversion lautet 28.2.4. 28.2.4 ist die aktuelle maximale Version für die Peerabhängigkeit, die von benötigt wird @microsoft/mgt-electron-provider.

Installieren Sie das Paket "@microsoft/mgt-components", das alle mit Microsoft Graph verbundenen Webkomponenten enthält.

npm i @microsoft/mgt-components

Installieren Sie auch die @microsoft/mgt-electron-provider npm-Pakete und @microsoft/mgt-element . Diese ermöglichen es Ihnen, die Authentifizierung für Ihre App mithilfe von MSAL bereitzustellen und die Komponenten des Microsoft Graph-Toolkits zu verwenden.

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

Erstellen einer App-/Client-ID

Hinzufügen einer neuen Anwendungsregistrierung in Microsoft Entra ID zum Abrufen einer Client-ID

Um eine Anwendung in Microsoft Entra ID zu erstellen, müssen Sie eine neue Anwendungsregistrierung hinzufügen und dann einen App-Namen und einen Umleitungs-URI konfigurieren.

So erstellen Sie die App in Microsoft Entra ID

  1. Wechseln Sie zum Microsoft Entra Admin Center.
  2. Erweitern Sie Identität>, erweitern Sie Anwendungen> und wählen Sie App-Registrierungen aus.
  3. Wählen Sie im oberen Menü die Schaltfläche Neue Registrierung aus.
  4. Geben Sie den Namen für Ihre App ein. Beispiel: My Electron-App.
  5. Wählen Sie für den Typ der unterstützten KontotypenKonten in einem beliebigen Organisationsverzeichnis (Beliebiges Microsoft Entra Verzeichnis – mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) aus.
  6. Wählen Sie im Feld Umleitungs-URI in der Dropdownliste Die Option Öffentlicher Client/nativ (mobiler & Desktop) aus, und geben Sie im Feld URL ein msal://redirect.
  7. Bestätigen Sie Änderungen, indem Sie auf die Schaltfläche Registrieren klicken.
  8. Wechseln Sie zu Ihrer Anwendungsregistrierung.
  9. Vergewissern Sie sich, dass Sie sich auf der Seite Übersicht befinden .
  10. Kopieren Sie im Abschnitt Essentials den Wert der Eigenschaft Anwendungs-ID (Client-ID).

Konfigurieren des Microsoft Graph-Toolkit-Authentifizierungsanbieters

Initialisieren einer ContextBridge in Ihrem Vorabladeskript

Ab Electron v12 ist die Kontextisolation standardmäßig aktiviert, und dies ist eine empfohlene Sicherheitseinstellung für alle Anwendungen. Bei der Kontextisolation müssen Entwickler APIs aus ihrem Standard Prozess explizit verfügbar machen, um sie im Rendererprozess über contextBridge zu verwenden. Weitere Informationen finden Sie unter Kontextisolation in der Electron-Dokumentation.

Öffnen Sie die Datei src/preload.ts , und fügen Sie den folgenden Code hinzu:

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

Initialisieren von ElectronContextBridgeProvider in Ihrem Rendererprozess

Ist ElectronContextBridgeProvider für die Kommunikation mit ElectronAuthenticator (im Standard Prozess) verantwortlich, um Zugriffstoken anzufordern und Informationen über den angemeldeten Zustand zu erhalten, der erforderlich ist, damit die Toolkitkomponenten funktionieren.

Um Microsoft Graph Toolkit-Komponenten in Ihren Anwendungen verwenden zu können, müssen sie in dem Browserfenster registriert werden, das sie öffnen. Dazu müssen Sie die Registerfunktionen für jede Komponente importieren, die Sie verwenden möchten.

Um die Komponenten des ElectronContextBridgeProvider Microsoft Graph-Toolkits zu initialisieren und zu registrieren, fügen Sie der Datei src/renderer.ts den folgenden Code hinzu.

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

Initialisieren von ElectronAuthenticator in Ihrem Standard-Prozess

Ist ElectronAuthenticator für das Einrichten der Konfigurationsvariablen für die MSAL-Authentifizierung, das Abrufen von Zugriffstoken und die Kommunikation mit verantwortlich ElectronContextBridgeProvider. Wird ElectronAuthenticator im Standard-Prozess initialisiert und richtet die Konfigurationsvariablen wie Client-ID und erforderliche Bereiche ein.

Öffnen Sie zuerst src/index.ts , und importieren Sie ElectronAuthenticator und MsalElectronConfig von @microsoft/mgt-electron-provider oben auf der Seite.

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

Fügen Sie dann die Importkonstante COMMON_AUTHORITY_URL hinzu.

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

Fügen Sie als Nächstes diese Codezeilen in der createWindow() Funktion hinzu, um den ElectronAuthenticator direkt nach mainWindow dem Deklarationsort zu initialisieren. Ersetzen Sie durch <your_client_id> die Client-ID aus Ihrer App-Registrierung.

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

Hinzufügen einer Inhaltssicherheitsrichtlinie für die Entwicklung

Die Anwendung, die Electron Forge Gerüste erstellt, enthält eine Standard-Inhaltssicherheitsrichtlinie (Content Security Policy, CSP), die das Abrufen von Daten von einem Remoteserver untersagt. Zu Entwicklungszwecken können Sie einen CSP hinzufügen, der sehr freizügig ist. Für Produktions-Apps müssen Sie einen robusten CSP erstellen, der es Ihrer Anwendung ermöglicht, zu funktionieren und gleichzeitig die Angriffsfläche für bösgläubige Akteure zu reduzieren.

Öffnen Sie die forge.config.ts-Datei , und ersetzen Sie das vorhandene Konfigurationsobjekt, das an den WebpackPlugin-Konstruktor übergeben wird, durch das folgende Config-Objekt.

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

Hinzufügen von Komponenten zu Ihrer HTML-Seite

Fügen Sie Ihrer App Inhalte hinzu. Sie können jetzt die Komponenten des Microsoft Graph-Toolkits auf Ihrer index.html-Seite verwenden und die Agenda des Benutzers anzeigen. Ersetzen Sie den Inhalt der seiteindex.html durch Folgendes.

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

Ausführen Ihrer App

npm start

Hinzufügen von Tokenzwischenspeicherungsfunktionen zu Ihrer App und Aktivieren von automatischen Anmeldungen (erweitert)

MSAL Node unterstützt standardmäßig einen In-Memory-Cache und stellt die ICachePlugin-Schnittstelle bereit, um die Cacheserialisierung durchzuführen, bietet jedoch keine Standardoption zum Speichern des Tokencaches auf dem Datenträger. Wenn Sie beständigen Cachespeicher benötigen, um automatische Anmeldungen oder plattformübergreifendes Zwischenspeichern zu ermöglichen, empfiehlt es sich, die von MSAL Node bereitgestellte Standardimplementierung als Erweiterung zu verwenden. Sie können dieses Plug-In importieren und die instance des Cache-Plug-Ins übergeben, während Sie initialisierenElectronAuthenticator.

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

Weitere Informationen zur Implementierung finden Sie im Beispiel microsoft Authentication Library-for-js .

Verwandte Inhalte

  • Testen Sie die Komponenten im Spielplatz aus.
  • Stellen Sie eine Frage auf Microsoft Q&A.
  • Melden Sie Bugs oder hinterlassen Sie eine Feature-Anforderung auf GitHub.