Utilizar o Microsoft Graph Toolkit com Electron

Este artigo descreve como utilizar o Microsoft Graph Toolkit para criar uma aplicação Electron e ligá-la ao Microsoft 365. Depois de concluir os passos, terá uma aplicação Electron que mostra os compromissos futuros do utilizador com sessão iniciada atualmente do Microsoft 365.

Criar uma aplicação Electron

Esqueque uma nova aplicação Electron com a Electron Forge. Ao fazê-lo, cria uma nova aplicação Electron no TypeScript, que o ajuda a escrever código mais robusto e a evitar erros de runtime.

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

Altere o diretório de trabalho para a aplicação recentemente criada.

cd mgt-app

Confirme que pode executar a aplicação.

npm start

Abra o package.json ficheiro e certifique-se de que a versão de dependência de desenvolvimento de electrões é 28.2.4. 28.2.4 é a versão máxima atual para a dependência do elemento da rede exigida pelo @microsoft/mgt-electron-provider.

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

npm i @microsoft/mgt-components

Instale também os @microsoft/mgt-electron-provider pacotes e @microsoft/mgt-element npm. Estes permitem-lhe fornecer autenticação para a sua aplicação através do MSAL e utilizar os componentes do Microsoft Graph Toolkit.

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

Criar um ID de aplicação/cliente

Adicionar novo registo de aplicação no Microsoft Entra ID para obter um ID de cliente

Para criar uma aplicação no Microsoft Entra ID, tem de adicionar um novo registo de aplicação e, em seguida, configurar um nome de aplicação e redirecionar o URI.

Para criar a aplicação no Microsoft Entra ID:

1. Aceda ao centro de administração do Microsoft Entra.
2. Expanda Identidade> expanda Aplicações> selecione Registros de aplicativo.
3. No menu superior, selecione o botão Novo registo .
4. Introduza o nome da sua aplicação; por exemplo, My Electron-App.
5. Para o tipo de tipos de conta suportados, selecione Contas em qualquer diretório organizacional (Qualquer diretório de Microsoft Entra - Multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox).
6. No campo URI de Redirecionamento , na lista pendente, selecione Cliente público/nativo (móvel & ambiente de trabalho) e, no campo URL, introduza msal://redirect.
7. Confirme as alterações ao selecionar o botão Registar .
8. Aceda ao registo da sua aplicação.
9. Verifique se está na página Descrição geral .
10. Na secção Essentials, copie o valor da propriedade ID da Aplicação (cliente).

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

Inicializar um ContextBridge no script de pré-carregamento

A partir do Electron v12, o isolamento de contexto está ativado por predefinição e esta é uma definição de segurança recomendada para todas as aplicações. Com o isolamento de contexto, os programadores têm de expor explicitamente as APIs do processo principal para utilização no processo de composição através de um ContextBridge. Para obter mais informações, veja Isolamento de Contexto nos documentos do Electron.

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

Inicializar o ElectronContextBridgeProvider no processo de composição

O ElectronContextBridgeProvider é responsável por comunicar com ElectronAuthenticator (no processo principal) para pedir tokens de acesso e receber informações sobre o estado de início de sessão necessário para que os componentes do toolkit funcionem.

Para utilizar componentes do Microsoft Graph Toolkit nas suas aplicações, estes têm de estar registados na janela do browser que abrirem. Para tal, tem de importar as funções de registo para cada componente que pretende utilizar.

Para inicializar e ElectronContextBridgeProvider registar os componentes do Microsoft Graph Toolkit, adicione o seguinte código ao ficheiro 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();

Inicializar o ElectronAuthenticator no processo principal

O ElectronAuthenticator é responsável pela configuração das variáveis de configuração para autenticação MSAL, aquisição de tokens de acesso e comunicação com o ElectronContextBridgeProvider. O ElectronAuthenticator é inicializado no processo principal e configura as variáveis de configuração, como o ID de cliente e os âmbitos necessários.

Em primeiro lugar, abra src/index.ts e importe ElectronAuthenticator e MsalElectronConfig a partir da @microsoft/mgt-electron-provider parte superior da página.

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

Em seguida, adicione a COMMON_AUTHORITY_URL constante de importação.

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

Em seguida, adicione estas linhas de código na createWindow() função para inicializar o ElectronAuthenticator, logo após a declaração mainWindow . Substitua <your_client_id> pelo ID de cliente do registo da aplicação.

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

A aplicação que a Electron Forge estrutura inclui uma Política de Segurança de Conteúdo (CSP) predefinida, que não permite a obtenção de dados de um servidor remoto. Para fins de desenvolvimento, pode adicionar um CSP altamente permissivo. Para aplicações de produção, tem de criar um CSP robusto que permita que a sua aplicação funcione enquanto reduz a superfície de ataque para maus atores.

Abra o ficheiro forge.config.ts e substitua o objeto de configuração existente que está a ser transmitido para o construtor WebpackPlugin pelo seguinte objeto de configuração.

{
  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 à sua aplicação. Agora, pode utilizar os componentes do Toolkit do Microsoft Graph na sua página deindex.html e mostrar a agenda do utilizador. 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 capacidades de colocação em cache de tokens à sua aplicação e ativar inícios de sessão silenciosos (avançado)

O Nó MSAL suporta uma cache dentro da memória por predefinição e fornece a interface ICachePlugin para executar a serialização da cache, mas não fornece uma forma predefinida de armazenar a cache de tokens no disco. Se precisar de armazenamento em cache persistente para ativar inícios de sessão silenciosos ou colocação em cache entre plataformas, recomendamos que utilize a implementação predefinida fornecida pelo Nó MSAL como uma extensão. Pode importar este plug-in e transmitir a instância do plug-in da 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 implementá-lo, consulte o exemplo Microsoft Authentication Library-for-js .

Conteúdo relacionado

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