Usar o Microsoft Graph Toolkit com o Electron

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 no momento do Microsoft 365.

Criar um aplicativo Electron

Crie um novo aplicativo Electron usando o Electron Forge. Isso cria um novo aplicativo Electron no TypeScript, que ajuda você a escrever um código mais robusto e evitar erros de tempo de execução.

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 certifique-se de que a package.json versão de dependência do electron dev seja 28.2.4. 28.2.4 é a versão máxima atual para a dependência de peer exigida pelo @microsoft/mgt-electron-provider.

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

npm i @microsoft/mgt-components

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

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

Criar um aplicativo/ID do cliente

Adicione um 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, em seguida, configurar um nome de aplicativo e URI de redirecionamento.

Para criar o aplicativo no Microsoft Entra ID:

1. Vá para o centro de administração do Microsoft Entra.
2. Expanda Identidade, expanda Aplicativos>>, selecione Registros de aplicativo.
3. No menu superior, selecione o botão Novo registro .
4. Insira o nome do seu aplicativo; Por exemplo, My Electron-App.
5. Para os tipos de conta com suporte, selecione Contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra - Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).
6. No campo URI de redirecionamento , no menu suspenso, selecione Cliente público/nativo (celular & desktop) e, no campo URL, insira msal://redirect.
7. Confirme as alterações selecionando o botão Registrar .
8. Vá para o registro do seu 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 um ContextBridge em seu script de pré-carregamento

A partir do Electron v12, o isolamento de contexto é habilitado por padrão e esta é 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 principal para uso no processo de renderização por meio de um 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 renderização

O ElectronContextBridgeProvider é responsável por se comunicar com ElectronAuthenticator (no processo principal) para solicitar tokens de acesso e receber informações sobre o estado conectado que é 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 em que são abertos. Para fazer isso, você deve importar as funções de registro para cada componente que deseja usar.

Para inicializar e ElectronContextBridgeProvider registrar os 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 ElectronAuthenticator em seu processo principal

O ElectronAuthenticator é responsável por definir 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 principal e define as variáveis de configuração, como ID do cliente e escopos necessários.

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

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

Em seguida, adicione import the COMMON_AUTHORITY_URL constant.

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 onde 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 Política de Segurança de Conteúdo (CSP) padrão, que não permite a busca de dados de um servidor remoto. Para fins de desenvolvimento, você pode adicionar um CSP que seja 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 agentes mal-intencionados.

Abra o arquivo forge.config.ts e substitua o objeto de configuração existente que está sendo passado para o construtor WebpackPlugin pelo objeto de configuração 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 à sua página HTML

Adicione algum conteúdo ao seu aplicativo. Agora você pode usar os componentes do kit de ferramentas do Microsoft Graph em sua página deindex.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çado)

O nó MSAL suporta um cache na memória por padrão e fornece a interface ICachePlugin para executar a serialização do cache, mas não fornece uma maneira padrão de armazenar o cache de token no 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 durante a inicialização ElectronAuthenticatordo .

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 de Biblioteca de Autenticação da Microsoft para js .

Conteúdo relacionado

• Experimente os componentes do playground.
• Faça uma pergunta no Microsoft Q&R.
• Relate bugs ou deixe uma solicitação de recurso no GitHub.