Использование набора средств Microsoft Graph с Electron

  • Статья

В этой статье описывается, как с помощью microsoft Graph Toolkit создать приложение Electron и подключить его к Microsoft 365. После выполнения этих действий у вас будет приложение Electron, в которое будут отображаться предстоящие встречи текущего пользователя, выполнившего вход из Microsoft 365.

Создание приложения Electron

Формирование нового приложения Electron с помощью Electron Forge. Это создает новое приложение Electron в TypeScript, которое помогает писать более надежный код и избежать ошибок среды выполнения.

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

Измените рабочий каталог на только что созданное приложение.

cd mgt-app

Подтвердите, что вы можете запустить приложение.

npm start

package.json Откройте файл и убедитесь, что версия зависимости electron dev имеет значение 28.2.4. 28.2.4 — это текущая максимальная версия для одноранговой зависимости, требуемой @microsoft/mgt-electron-providerдля .

Установите пакет @microsoft/mgt-components, содержащий все веб-компоненты, подключенные к Microsoft Graph.

npm i @microsoft/mgt-components

@microsoft/mgt-electron-provider Также установите пакеты и @microsoft/mgt-element npm. Они позволяют обеспечить проверку подлинности приложения с помощью MSAL и использовать компоненты Microsoft Graph Toolkit.

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

Создание идентификатора клиента/приложения

Добавление новой регистрации приложения в Microsoft Entra ID для получения идентификатора клиента

Чтобы создать приложение в Microsoft Entra ID, необходимо добавить новую регистрацию приложения, а затем настроить имя приложения и URI перенаправления.

Чтобы создать приложение в Microsoft Entra ID:

  1. Перейдите к Центр администрирования Microsoft Entra.
  2. Разверните узел Удостоверение>Разверните узел Приложения> выберите Регистрация приложений.
  3. В верхнем меню нажмите кнопку Новая регистрация.
  4. Введите имя приложения; например, My Electron-App.
  5. Для типа поддерживаемых типов учетных записей выберите Учетные записи в любом каталоге организации (любой каталог Microsoft Entra — мультитенантный) и личные учетные записи Майкрософт (например, Skype, Xbox).
  6. В поле URI перенаправления в раскрывающемся списке выберите Общедоступный клиент или собственный (мобильный & desktop) и в поле URL-адрес введите msal://redirect.
  7. Подтвердите изменения, нажав кнопку Зарегистрировать.
  8. Перейдите к регистрации приложения.
  9. Убедитесь, что вы находитесь на странице Обзор.
  10. В разделе Essentials скопируйте значение свойства Идентификатор приложения (клиента).

Настройка поставщика проверки подлинности Microsoft Graph Toolkit

Инициализация ContextBridge в скрипте предварительной загрузки

Начиная с Electron версии 12, изоляция контекста включена по умолчанию, и это рекомендуемый параметр безопасности для всех приложений. При изоляции контекста разработчики должны явно предоставлять API-интерфейсы из процесса main для использования в процессе отрисовщика через ContextBridge. Дополнительные сведения см. в разделе Изоляция контекста в документации electron.

Откройте файл src/preload.ts и добавьте следующий код:

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

Инициализация ElectronContextBridgeProvider в процессе отрисовщика

Отвечает ElectronContextBridgeProvider за обмен данными с ElectronAuthenticator (в процессе main) для запроса маркеров доступа и получения сведений о состоянии входа, необходимом для работы компонентов набора средств.

Чтобы использовать компоненты Microsoft Graph Toolkit в приложениях, они должны быть зарегистрированы в открываемом окне браузера. Для этого необходимо импортировать функции register для каждого компонента, который вы хотите использовать.

Чтобы инициализировать ElectronContextBridgeProvider и зарегистрировать компоненты Microsoft Graph Toolkit, добавьте следующий код в файл 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();

Инициализация ElectronAuthenticator в процессе main

Отвечает ElectronAuthenticator за настройку переменных конфигурации для проверки подлинности MSAL, получение маркеров доступа и взаимодействие с ElectronContextBridgeProvider. Инициализируется ElectronAuthenticator в процессе main и настраивается переменные конфигурации, такие как идентификатор клиента и необходимые области.

Сначала откройте src/index.ts и импортируйте ElectronAuthenticator и MsalElectronConfig в @microsoft/mgt-electron-provider верхней части страницы.

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

Затем добавьте константу импорта COMMON_AUTHORITY_URL .

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

Затем добавьте эти строки кода в функцию createWindow() для инициализации ElectronAuthenticator сразу после mainWindow объявления. Замените <your_client_id> идентификатором клиента из регистрации приложения.

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

Добавление политики безопасности содержимого для разработки

Приложение, которое формирует шаблонов Electron Forge, включает политику безопасности содержимого (CSP) по умолчанию, которая запрещает получение данных с удаленного сервера. В целях разработки можно добавить CSP с высоким уровнем разрешений. Для рабочих приложений необходимо создать надежный поставщик служб CSP, который позволит приложению функционировать, уменьшая область атаки для злоумышленников.

Откройте файл forge.config.ts и замените существующий объект конфигурации, передаваемый конструктору WebpackPlugin, следующим объектом конфигурации.

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

Добавление компонентов на HTML-страницу

Добавьте содержимое в приложение. Теперь вы можете использовать компоненты набора средств Microsoft Graph на странице index.html и показывать повестку дня пользователя. Замените содержимое страницыindex.html следующим кодом.

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

Запуск приложения

npm start

Добавление возможностей кэширования маркеров в приложение и включение автоматического входа (дополнительно)

MSAL Node по умолчанию поддерживает кэш в памяти и предоставляет интерфейс ICachePlugin для сериализации кэша, но не предоставляет способ хранения кэша маркеров на диске по умолчанию. Если требуется постоянное хранилище кэша для включения автоматического входа или межплатформенного кэширования, рекомендуется использовать в качестве расширения реализацию по умолчанию, предоставляемую MSAL Node. Вы можете импортировать этот подключаемый модуль и передать экземпляр подключаемого модуля кэша при инициализации ElectronAuthenticator.

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

Дополнительные сведения о реализации этой функции см. в примере библиотеки проверки подлинности Майкрософт для js .

Связанные материалы