Usar o Kit de Ferramentas do Microsoft Graph com o Electron

  • Artigo

Este artigo descreve como usar o Microsoft Graph Toolkit para criar um aplicativo Electron e conectá-lo ao Microsoft 365. Depois de concluir as etapas, você terá um aplicativo Electron que mostra os próximos compromissos do usuário conectado atualmente do Microsoft 365.

Criar um aplicativo Electron

Scaffold um novo aplicativo Electron usando Electron Forge. Fazer isso cria um novo aplicativo Electron no TypeScript, que ajuda você a escrever um código mais robusto e evitar erros de runtime.

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

Altere o diretório de trabalho para o aplicativo recém-criado.

cd mgt-app

Confirme se você pode executar o aplicativo.

npm start

Abra o arquivo e verifique se a package.json versão de dependência de desenvolvimento eletrônico é 28.2.4. 28.2.4 é a versão máxima atual para a dependência de par exigida por @microsoft/mgt-electron-provider.

Instale o pacote '@microsoft/mgt-components' que contém todos os componentes da Web conectados ao Microsoft Graph.

npm i @microsoft/mgt-components

Instale os @microsoft/mgt-electron-provider pacotes e @microsoft/mgt-element npm também. Isso permite que você forneça autenticação para seu aplicativo usando o MSAL e use os componentes do Kit de Ferramentas do Microsoft Graph.

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

Criar uma ID de aplicativo/cliente

Adicionar novo registro de aplicativo no Microsoft Entra ID para obter uma ID do cliente

Para criar um aplicativo no Microsoft Entra ID, você precisa adicionar um novo registro de aplicativo e configurar um nome de aplicativo e redirecionar o URI.

Para criar o aplicativo no Microsoft Entra ID:

  1. Vá para o centro de administração do Microsoft Entra.
  2. Expandir Aplicativos de expansão de>identidade> selecione Registros de aplicativo.
  3. No menu superior, selecione o botão Novo registro .
  4. Insira o nome do aplicativo; por exemplo, My Electron-App.
  5. Para o tipo de tipos de conta com suporte, selecione Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra – Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).
  6. No campo URI de redirecionamento , na lista suspensa, selecione Cliente público/nativo (mobile & desktop)e, no campo URL, insira msal://redirect.
  7. Confirme as alterações selecionando o botão Registrar .
  8. Acesse o registro do aplicativo.
  9. Verifique se você está na página Visão geral .
  10. Na seção Essentials, copie o valor da propriedade ID do aplicativo (cliente).

Configurar o provedor de autenticação do Microsoft Graph Toolkit

Inicializar uma ContextBridge no script de pré-carregamento

A partir do Electron v12, o isolamento de contexto é habilitado por padrão e essa é uma configuração de segurança recomendada para todos os aplicativos. Com o isolamento de contexto, os desenvolvedores devem expor explicitamente AS APIs de seu processo de main para uso no processo de renderizador por meio de uma ContextBridge. Para obter mais informações, consulte Isolamento de Contexto nos documentos do Electron.

Abra o arquivo src/preload.ts e adicione o seguinte código:

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

Inicializando ElectronContextBridgeProvider em seu processo de renderizador

O ElectronContextBridgeProvider é responsável por se comunicar com ElectronAuthenticator (no processo main) para solicitar tokens de acesso e receber informações sobre o estado conectado necessário para que os componentes do kit de ferramentas funcionem.

Para usar componentes do Microsoft Graph Toolkit em seus aplicativos, eles devem ser registrados na janela do navegador que eles abrem. Para fazer isso, você deve importar as funções de registro para cada componente que deseja usar.

Para inicializar e registrar os ElectronContextBridgeProvider componentes do Kit de Ferramentas do Microsoft Graph, adicione o código a seguir ao arquivo 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();

Inicializando o ElectronAuthenticator em seu processo de main

O ElectronAuthenticator é responsável por configurar as variáveis de configuração para autenticação MSAL, adquirir tokens de acesso e se comunicar com o ElectronContextBridgeProvider. O ElectronAuthenticator é inicializado no processo main e configura as variáveis de configuração, como ID do cliente e escopos necessários.

Primeiro, abra src/index.ts e importe ElectronAuthenticator e MsalElectronConfig na @microsoft/mgt-electron-provider parte superior da página.

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

Em seguida, adicione importar a COMMON_AUTHORITY_URL constante.

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

Em seguida, adicione essas linhas de código na createWindow() função para inicializar o ElectronAuthenticator, logo após o local em que mainWindow é declarado. Substitua <your_client_id> pela ID do cliente do registro do aplicativo.

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

Adicionar uma política de segurança de conteúdo de desenvolvimento

O aplicativo que o Electron Forge scaffolds inclui uma CSP (Política de Segurança de Conteúdo) padrão, que não permite buscar dados de um servidor remoto. Para fins de desenvolvimento, você pode adicionar um CSP altamente permissivo. Para aplicativos de produção, você precisa criar um CSP robusto que permita que seu aplicativo funcione enquanto reduz a superfície de ataque para maus atores.

Abra o arquivo forge.config.ts e substitua o objeto de configuração existente que está sendo passado para o construtor WebpackPlugin pelo objeto config a seguir.

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

Adicionar componentes à página HTML

Adicione algum conteúdo ao seu aplicativo. Agora você pode usar os componentes do kit de ferramentas do Microsoft Graph na página index.html e mostrar a agenda do usuário. Substitua o conteúdo da página index.html pelo seguinte.

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

Execute seu aplicativo

npm start

Adicionar recursos de cache de token ao seu aplicativo e habilitar entradas silenciosas (avançadas)

O Nó MSAL dá suporte a um cache na memória por padrão e fornece a interface ICachePlugin para executar a serialização de cache, mas não fornece uma maneira padrão de armazenar o cache de token em disco. Se você precisar de armazenamento em cache persistente para habilitar entradas silenciosas ou cache entre plataformas, recomendamos usar a implementação padrão fornecida pelo Nó MSAL como uma extensão. Você pode importar esse plug-in e passar a instância do plug-in de cache ao inicializar ElectronAuthenticator.

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

Para obter mais informações sobre como implementar isso, consulte o exemplo biblioteca de autenticação da Microsoft para js .

Conteúdo relacionado