Exercício – Criar um suplemento do Office para o Outlook que implementa o logon único
Neste exercício, você criará um suplemento do Outlook que adiciona uma lista de eventos de calendário futuros ao corpo de um email pelo usuário conectado com o Microsoft Graph. Esse processo usa o esquema de autenticação de SSO (logon único).
Pré-requisitos
O desenvolvimento de Suplementos do Office para o Microsoft Outlook requer o cliente Web ou os seguintes clientes da área de trabalho:
- Windows v16.0.12215.20006 (ou superior)
- macOS v16.32.19102902 (ou superior)
Você usará o Node.js para criar o suplemento personalizado do Outlook neste módulo. Os exercícios neste módulo presumem que você tenha as seguintes ferramentas instaladas em sua estação de trabalho de desenvolvedor:
Importante
Na maioria dos casos, instalar a versão mais recente das ferramentas a seguir é a melhor opção. As versões listadas aqui foram usadas quando este módulo foi publicado e testado pela última vez.
- Node.js: (a versãomais recente do LTS)
- NPM (instalado com Node.js) – v6.x (ou superior)
- Yeoman - v3.x (ou superior)
- Gerador yeoman para Microsoft Office - v1.8.8
- Visual Studio Code
Você deve ter as versões mínimas desses pré-requisitos instaladas em sua estação de trabalho.
Importante
Este exercício é escrito para trabalhar com o Gerador yeoman para o Microsoft Office v1.8.8. Verifique se você está usando essa versão instalando uma versão específica usando o comando npm install generator-office@1.8.8 --global. Versões posteriores do gerador foram removidas e, em seguida, alteraram os scaffolding do projeto SSO que não correspondem às etapas neste laboratório.
Importante
O exemplo neste exercício destina-se a ser usado apenas como um recurso de aprendizado e não se destina a ser usado em um cenário de produção porque passa o token OAuth usado para enviar solicitações ao Microsoft Graph de volta ao cliente para fazer a chamada diretamente.
Como prática de segurança, sempre use o código ao lado do servidor para fazer chamadas pelo Microsoft Graph ou outras chamadas que exigem a passagem de um token de acesso. Nunca retorne o token OBO ao cliente para permitir que o cliente faça chamadas diretas ao Microsoft Graph. Isso ajuda a proteger o token de ser interceptado ou vazado. Para obter mais informações sobre o fluxo de protocolo adequado, consulte o diagrama de protocolo OAuth 2.0.
Criar seu projeto do suplemento
Execute o seguinte comando para criar um projeto de suplemento usando o gerador Yeoman:
yo office
Observação
Ao executar o comando yo office, você receberá informações sobre as políticas de coleta de dados de Yeoman e as ferramentas da CLI do suplemento do Office. Use as informações fornecidas para responder às solicitações como achar melhor.
Quando solicitado, forneça as seguintes informações para criar seu projeto de suplemento:
- Selecione um tipo de projeto: projeto do painel de tarefas do suplemento do Office com suporte para logon único
- Selecione um tipo de script: JavaScript
- Qual será o nome do suplemento? MyOutlookSsoAddin
- Você gostaria de proporcionar suporte para qual aplicativo cliente do Office? Outlook
Depois que você concluir o prompt, o gerador criará o projeto e instalará os componentes Node de suporte.
Registrar o aplicativo Microsoft Entra
Em seguida, registre o aplicativo Microsoft Entra e atualize o projeto para usar o aplicativo Microsoft Entra.
Dica
Para obter detalhes sobre como registrar o aplicativo Microsoft Entra manualmente, confira: Criar um suplemento do Office Node.js que usa logon único: registre o suplemento com Azure AD ponto de extremidade v2.0.
No prompt de comando, verifique se você está na pasta raiz do projeto. Em seguida, execute o seguinte comando:
npm run configure-sso
O comando iniciará um navegador e solicitará que você entre no Microsoft Entra ID. Verifique se você entra como um usuário que tem permissões para registrar um aplicativo Microsoft Entra, como um usuário atribuído à função de Administrador Global.
Após a autenticação, o script executará as seguintes tarefas:
- Registrar o aplicativo Microsoft Entra
- Definir as configurações de audiência e permissões do aplicativo
- Criar um novo segredo do cliente e salvá-lo no repositório secreto de estações de trabalho do desenvolvedor
- Atualizar o projeto com a ID do cliente do aplicativo Microsoft Entra
Aviso
O comando configure-sso falhará se o locatário Microsoft Entra estiver configurado para autenticação multifator (MFA)/autenticação de dois fatores. Nesse caso, você precisará criar manualmente o registro do aplicativo Microsoft Entra conforme descrito no artigo Criar um suplemento do Office Node.js que usa logon único: registre o suplemento com Azure AD artigo do ponto de extremidade v2.0.
Criar e testar o aplicativo
Execute o seguinte comando em um prompt de comando para transpilar e iniciar o processo de depuração:
npm start
Testar o suplemento no cliente Web do Outlook
Abra um navegador e navegue até o Outlook (https://outlook.office.com). Entre usando uma Conta Corporativa ou de Estudante.
Crie uma nova mensagem selecionando o botão Nova mensagem.
Na nova seção de mensagem, localize o botão ... na parte inferior da nova mensagem, no mesmo rodapé com os botões Enviar e Descartar.
Selecione o item de menu Obter suplementos.
Na caixa Suplementos do Outlook, selecione Meus suplementos no menu à esquerda.
Na tela Meus suplementos, selecione o botão Adicionar um suplemento personalizado>Adicionar do arquivo....
Selecione o arquivo manifest.xml na raiz da pasta do seu projeto e selecione Carregar.
Quando solicitado, selecione o botão Instalar na caixa de diálogo Aviso.
Feche a caixa de diálogo e selecione o botão ...na parte inferior do email. Observe que seu suplemento personalizado agora é exibido:
Selecione o suplemento para abrir o painel de tarefas. Quando o painel de tarefas for exibido, selecione o botão Obter informações de perfil do usuário.
Como você já está conectado, após alguns instantes, você verá as informações básicas do perfil do usuário aparecerem no email sem precisar entrar.
Atualize o aplicativo para mostrar as próximas reuniões
Agora, vamos atualizar o aplicativo do painel de tarefas para exibir para o usuário conectado uma lista de reuniões futuras. Essas informações serão coletadas com o Microsoft Graph.
Atualizar o painel de tarefas
Localize e abra ./src/taskpane/taskpane.html.
Substitua o elemento <body> pelo HTML a seguir. Isso atualizará a renderização do painel de tarefas:
<body class="ms-font-m ms-welcome ms-Fabric">
<header class="ms-welcome__header ms-bgColor-neutralLighter">
<img width="90" height="90" src="../../assets/logo-filled.png" alt="Contoso" title="Contoso" />
<h1 class="ms-font-su">My upcoming meetings... </h1>
</header>
<main class="ms-firstrun-instructionstep">
<ul class="ms-List ms-welcome__features">
<li class="ms-ListItem">
<i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
<span class="ms-font-m">Share your day with others...</span>
</li>
</ul>
<section class="ms-firstrun-instructionstep__header">
<h2 class="ms-font-m">This add-in adds a list of your upcoming meetings to the current email.</h2>
<div class="ms-firstrun-instructionstep__header--image"></div>
</section>
<p align="center">
<button id="getGraphDataButton" class="popupButton ms-Button ms-Button--primary"><span class="ms-Button-label">Add
upcoming schedule to email</span></button>
</p>
</div>
</main>
</body>
Atualizar o código do painel de tarefas
Agora, atualize o código que receberá os próximos eventos de calendário do usuário.
Localize e abra o arquivo ./src/helpers/ssoauthhelper.js.
Encontre a seguinte linha no método getGraphData():
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Exclua essa linha e a substitua pelo código a seguir. Esse código usa um método diferente no auxiliar de logon único para enviar uma solicitação específica para o Microsoft Graph.
Esta consulta obterá todas as reuniões na agenda do usuário atual a partir do horário atual pelas próximas 24 horas:
const startDate = new Date();
let endDate = new Date(startDate);
endDate.setDate(startDate.getDate() + 1);
const endpoint = "/me/calendarview";
const urlParams = `?startdatetime=${ startDate.toISOString() }&enddatetime=${ endDate.toISOString() }&$select=subject,start,end`;
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Em seguida, localize e abra o arquivo ./src/helpers/documentHelper.js.
Localize o método writeDataToOutlook(). Você substituirá o conteúdo desse método para criar uma cadeia de caracteres HTML das reuniões futuras retornadas da solicitação de Microsoft Graph e adicionará a lista ao email atual.
Substitua o conteúdo do método writeDataToOutlook() pelo seguinte código:
let emailMessage = "";
result.value.forEach(function(meeting){
let startDateTime = new Date(meeting.start.dateTime + "Z");
let endDateTime = new Date(meeting.end.dateTime + "Z");
emailMessage += `<li><strong><em>${startDateTime.toLocaleTimeString()}-${endDateTime.toLocaleTimeString()}</em></strong><br />${meeting.subject}</li>`;
});
// wrap meeting
emailMessage = `Here's what my upcoming calendar looks like for the rest of the day: <ul>${emailMessage}</ul>`;
Office.context.mailbox.item.body.setSelectedDataAsync(emailMessage, { coercionType: Office.CoercionType.Html });
Criar um novo aplicativo Microsoft Entra para o suplemento
Os exercícios anteriores neste módulo usaram o script utilitário configure-sso incluído em todos os projetos criados com o Gerador Yeoman para Microsoft Office. Para este exercício, você aprenderá a registrar manualmente um aplicativo Microsoft Entra e configurar seu ambiente de desenvolvedor para usar o aplicativo criado manualmente.
Abra um navegador e navegue até o centro de administração Microsoft Entra (https://aad.portal.azure.com). Entre usando uma Conta Corporativa ou de Estudante que tenha direitos de administrador global para os locatários.
Selecione Microsoft Entra ID na navegação mais à esquerda.
Registro do aplicativo
Selecione Gerenciar>Registros de aplicativo na navegação mais à esquerda.
Na página Registros de aplicativo, selecione Novo registro e defina os seguintes valores na tela Registrar um aplicativo. Quando terminar, selecione o botão Registrar.
- Nome: MyOutlookSsoAddin2
- Tipos de conta com suporte: Contas em qualquer diretório organizacional (Qualquer diretório Microsoft Entra – Multilocatário)
- URI de redirecionamento (opção): valor padrão em branco
Autenticação de aplicativo
A próxima etapa é configurar os detalhes de registro do aplicativo.
Em seguida, na navegação mais à esquerda, selecione Gerenciar>Autenticação.
Na tela Autenticação, selecione Adicionar uma plataforma. Em seguida, selecione Web na lista de opções:
Para os URIs de redirecionamento, insira https://localhost:3000/taskpane.html.
Para concessão implícita e fluxos híbridos, selecione as opções a seguir e selecione Configurar:
- Tokens de acesso (usados para fluxos implícitos)
- Tokens de ID (usados para fluxos implícitos e híbridos)
Depois que a tela for recarregada, selecione Adicionar URI na plataforma Web e insira https://localhost:3000/fallbackauthdialog.html.
Selecione Salvar na parte superior da tela para salvar as alterações.
Certificados e segredos do aplicativo
Agora você precisa criar um segredo do cliente para o aplicativo
Selecione Segredos de certificados & no painel de navegação mais à esquerda.
Selecionar o botão Novo segredo do cliente:
Quando solicitado, dê uma descrição ao segredo e selecionar uma das opções de duração de expiração fornecidas e selecionar Adicionar. O que você inserir e selecionar não importa para o exercício.
A páginaCertificados & Segredos exibirá o novo segredo.
Importante
É importante copiar esse valor, pois ele é mostrado apenas uma vez. Se você sair da página e voltar, ela apenas mostrará como um valor máscara.
Depois de copiar o segredo do cliente, vamos copiar a ID do cliente também. Na navegação mais à esquerda, selecione Gerenciar>Visão Geral.
Permissões de API
Em seguida, você precisa conceder as permissões de aplicativo para o Microsoft Graph.
Na navegação mais à esquerda, selecione Gerenciar>permissões da API.
É uma boa prática solicitar apenas as permissões de que seu aplicativo precisa. Portanto, vamos remover a permissão inicial User.Read selecionando-a e, em seguida, selecione Remover permissão, seguido por Sim, remover para confirmar.
Em seguida, vamos adicionar as permissões mínimas necessárias para que os usuários se conectem usando o logon único.
Adicione uma nova permissão selecionando Adicionar permissão.
Na tela Selecionar uma API, selecione Microsoft Graphe, em seguida, selecione Permissões delegadas. Selecione as seguintes permissões nas seções a seguir ou use a caixa de pesquisa para encontrar essas permissões:
- Permissões do OpenID
- openid
- perfil
- Calendários
- Calendars.Read
Depois de selecionar essas permissões, selecione o botão Adicionar permissões.
Em seguida, selecione Conceder consentimento do administrador para a Contoso seguido de aceitar o prompt de confirmação selecionando Sim.
Expor uma API: URI da ID do Aplicativo
Por fim, selecione Gerenciar>Expor uma API na navegação mais à esquerda. Há várias coisas a fazer nesta página:
Primeiro, selecione Definir ao lado do URI ID do Aplicativo. Essa é a ID exclusiva do nosso aplicativo. Adicione localhost:3000/ logo antes do protocolo e da ID do aplicativo para que ele seja semelhante ao seguinte e selecione Salvar:
api://localhost:3000/f7b53c32-c205-40d8-84dc-0c15b662054c
Observação
O GUID é a ID exclusiva para cada aplicativo. Sua ID não corresponderá à mostrada neste exercício.
Expor uma API: escopos definidos pela API
A próxima seção contém os escopos definidos pela API. Eles podem ser escopos personalizados que permitem restringir o acesso a dados e funcionalidades protegidas pela API.
Selecione Adicionar um escopo e use os seguintes valores para concluir o formulário:
- Nome do escopo: access_as_user
- Quem pode consentir? Administradores e usuários
- Nome de exibição do consentimento do administrador: O Office pode atuar como se fosse o usuário
- Descrição de autorização de administrador: Permite ao Office chamar os APIs de suplemento da web com os mesmos direitos que o usuário atual.
- Nome de exibição de consentimento do usuário: O Office pode agir como se fosse você
- Descrição de autorização de usuário: Permite ao Office chamar os APIs de suplemento da web com os mesmos direitos que você possui.
- Estado: Habilitado
Expor uma API: aplicativos cliente autorizados
A última seção indica que a API confiará automaticamente em aplicativos específicos e não solicitará o consentimento do usuário quando o aplicativo chamar essa API.
Isso autoriza os aplicativos web e de área de trabalho do Office a chamar a API do suplemento.
Selecione Adicionar um aplicativo cliente para adicionar os aplicativos a seguir. Os aplicativos são adicionados como GUIDs. Para cada um deles, certifique-se de selecionar os Escopos autorizados listados para conceder ao aplicativo acesso ao escopo definido anteriormente:
d3590ed6-52b3-4102-aeff-aad2292ab01c(Microsoft Office)ea5a67f6-b6f3-4338-b240-c655ddc3cc8e(Microsoft Office)57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office na Web)08e18876-6177-487e-b8b5-cf950c1e598c(Office na Web)bc59ab01-8403-45c6-8796-ac3ef710b3e3(Outlook na Web)93d53678-613d-4013-afc1-62e9e444a0a5(Office na Web)
Se você selecionar um desses aplicativos, cada um deles terá o escopo definido anteriormente como um escopo autorizado.
Atualizar o projeto e a estação de trabalho do desenvolvedor
Com o aplicativo Microsoft Entra criado, a última etapa é atualizar seu projeto e estação de trabalho para usar o novo aplicativo.
No seu projeto, localize e abra o arquivo .ENV.
Atualize o CLIENT_ID para usar a ID do cliente que você copiou do processo de registro do aplicativo.
Localize e abra o arquivo ./manifest.xml. No final do arquivo, localize o elemento <WebApplicationInfo>. Dentro desse elemento, atualize os elementos <ID> e <Resource> para usar a nova ID do cliente.
Localize e abra o arquivo ./src/helpers/fallbackauthdialog.js. Localize a linha que começa com const msalConfig. Este é o objeto de configuração MSAL.js. Atualize a propriedade clientId do objeto para ser a nova ID do cliente.
Em seguida, você precisa salvar o segredo do cliente para o aplicativo no repositório de credenciais na estação de trabalho do desenvolvedor. O trabalho que você executará depende da sua plataforma.
Windows
Execute o seguinte PowerShell, depois de atualizar os três primeiros valores:
$ssoAppName: o nome do seu projeto, como MyOutlookSsoAddin$user: seu nome de usuário de login do Windows, como MyDomain\MyUserName$secret: o segredo do cliente copiado ao registrar o aplicativo Microsoft Entra
$ssoAppName = "MyOutlookSsoAddin"
$user = "MyDomain\MyUserName"
$secret = "....."
[void][Windows.Security.Credentials.PasswordVault, Windows.Security.Credentials, ContentType = WindowsRuntime]
$creds = New-Object Windows.Security.Credentials.PasswordCredential
$creds.Resource = $ssoAppName
$creds.UserName = $user
$creds.Password = $secret
$vault = New-Object Windows.Security.Credentials.PasswordVault
$vault.Add($creds)
macOS
Execute o seguinte no console, depois de atualizar os três primeiros valores:
SSOAPPNAME: o nome do seu projeto, como MyOutlookSsoAddinUSER: seu nome de usuário de entrada do macOS, como myusernameSECRET: o segredo do cliente copiado ao registrar o aplicativo Microsoft Entra
SSOAPPNAME="MyOutlookSsoAddin"
USER="myusername"
SECRET="...."
sudo security add-generic-password -a $USER -s $SSOAPPNAME -w $SECRET -U
Compilar e testar novamente o aplicativo
Execute o seguinte comando em um prompt de comando para transpilar e iniciar o processo de depuração:
npm start
Teste novamente o suplemento no cliente Web do Outlook
Abra um navegador e navegue até o Outlook (https://outlook.office.com). Entre usando uma Conta Corporativa ou de Estudante.
Repita o processo de teste do suplemento que você fez no início deste exercício. No entanto, antes de ativar o suplemento, você precisa removê-lo porque o suplemento atualmente instalado ainda está usando o arquivo antigomanifest.xml com o registro antigo do aplicativo Microsoft Entra.
Para remover o suplemento, siga as mesmas etapas para instalar um novo suplemento, mas antes de carregar o arquivo personalizado manifest.xml, remova o suplemento instalado anteriormente:
Depois de instalar o arquivo manifest.xml do suplemento atualizado, conclua o processo de teste para testar a nova lógica do seu suplemento.
