Use o gerador Yeoman para criar um Suplemento do Office que utilize o logon único.Use the Yeoman generator to create an Office Add-in that uses single sign-on

Neste artigo, você seguirá pelo processo de uso do gerador Yeoman para criar um Suplemento do Office para Excel, Outlook, Word ou PowerPoint que usa o logon único (SSO) sempre que possível, e usa um método alternativo de autenticação do usuário quando não há suporte ao SSO.In this article, you'll walk through the process of using the Yeoman generator to create an Office Add-in for Excel, Outlook, Word, or PowerPoint that uses single sign-on (SSO) when possible, and uses an alternate method of user authentication when SSO is not supported.

Dica

Antes de tentar concluir o início rápido, revise Habilitar o logon único para Suplementos do Office para aprender conceitos básicos sobre o SSO em Suplementos do Office.Before you attempt to complete this quick start, review Enable single sign-on for Office Add-ins to learn basic concepts about SSO in Office Add-ins.

O gerador Yeoman simplifica o processo de criação de um suplemento de SSO, automatizando as etapas necessárias para configurar o SSO no Azure e gerando o código necessário para um suplemento usar o SSO.The Yeoman generator simplifies the process of creating an SSO add-in, by automating the steps required to configure SSO within Azure and generating the code that's necessary for an add-in to use SSO. Para um passo a passo detalhado descrevendo como concluir manualmente as etapas que o gerador Yeoman automatiza, confira o tutorial Criar um Suplemento do Office com Node.js que usa logon único.For a detailed walkthrough that describes how to manually complete the steps that the Yeoman generator automates, see the Create a Node.js Office Add-in that uses single sign-on tutorial.

Pré-requisitosPrerequisites

  • Node.js (a versão mais recente de LTS).Node.js (the latest LTS version).

  • A versão mais recente do Yeoman e do Yeoman gerador de suplementos do Office. Para instalar essas ferramentas globalmente, execute o seguinte comando por meio do prompt de comando:The latest version of Yeoman and the Yeoman generator for Office Add-ins. To install these tools globally, run the following command via the command prompt:

    npm install -g yo generator-office
    

    Observação

    Mesmo se você já instalou o gerador Yeoman, recomendamos atualizar seu pacote para a versão mais recente do npm.Even if you've previously installed the Yeoman generator, we recommend you update your package to the latest version from npm.

  • Se você estiver usando um Mac e não tiver a CLI do Azure instalada no computador, instale o Homebrew.If you're using a Mac and don't have the Azure CLI installed on your machine, you must install Homebrew. O script de configuração do SSO executado durante o início rápido usará o Homebrew para instalar a CLI do Azure e, em seguida, usará a CLI do Azure para configurar o SSO no Azure.The SSO configuration script that you'll run during this quick start will use Homebrew to install the Azure CLI, and will then use the Azure CLI to configure SSO within Azure.

Criar o projeto do suplementoCreate the add-in project

Dica

O gerador Yeoman pode criar um Suplemento do Office habilitado para SSO do Excel, Outlook, Word ou PowerPoint e pode ser criado com o tipo de script JavaScript ou TypeScript.The Yeoman generator can create an SSO-enabled Office Add-in for Excel, Outlook, Word, or PowerPoint, and can be created with script type of JavaScript or TypeScript. As instruções a seguir especificam o JavaScript e o Excel, mas você deverá escolher o tipo de script e o aplicativo cliente do Office que atendem melhor ao seu cenário.The following instructions specify JavaScript and Excel, but you should choose the script type and Office client application that best suits your scenario.

Execute o seguinte comando para criar um projeto de suplemento usando o gerador Yeoman:Run the following command to create an add-in project using the Yeoman generator:

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.When you run the yo office command, you may receive prompts about the data collection policies of Yeoman and the Office Add-in CLI tools. Use as informações fornecidas para responder às solicitações como achar melhor.Use the information that's provided to respond to the prompts as you see fit.

Quando solicitado, forneça as seguintes informações para criar seu projeto de suplemento:When prompted, provide the following information to create your add-in project:

  • Escolha o tipo de projeto: Office Add-in Task Pane project supporting single sign-onChoose a project type: Office Add-in Task Pane project supporting single sign-on
  • Escolha o tipo de script: JavascriptChoose a script type: Javascript
  • Qual será o nome do suplemento?What do you want to name your add-in? My SSO Office Add-in
  • Você gostaria de proporcionar suporte para qual aplicativo cliente do Office?Which Office client application would you like to support? Excel

Uma captura de tela dos prompts e respostas do gerador Yeoman

Depois que você concluir o assistente, o gerador criará o projeto e instalará os componentes Node de suporte.After you complete the wizard, the generator creates the project and installs supporting Node components.

Dica

Você pode ignorar as orientações da próximas etapas fornecidas pelo gerador Yeoman após a criação do projeto de suplemento.You can ignore the next steps guidance that the Yeoman generator provides after the add-in project's been created. As instruções passo a passo deste artigo fornecem todas as orientações necessárias para concluir este tutorial.The step-by-step instructions within this article provide all of the guidance you'll need to complete this tutorial.

Explore o projetoExplore the project

O projeto de suplemento que você criou com o gerador do Yeoman contém um código para um suplemento de painel de tarefas habilitado para SSO.The add-in project that you've created with the Yeoman generator contains code for an SSO-enabled task pane add-in.

ConfiguraçãoConfiguration

Os seguintes arquivos especificam definições de configuração para o suplemento.The following files specify configuration settings for the add-in.

  • O arquivo ./manifest.xml no diretório raiz do projeto define as configurações e os recursos do suplemento.The ./manifest.xml file in the root directory of the project defines the settings and capabilities of the add-in.

  • O ./. ENV arquivo no diretório raiz do projeto define constantes que são usadas pelo projeto do suplemento.The ./.ENV file in the root directory of the project defines constants that are used by the add-in project.

Painel de tarefasTask pane

Os seguintes arquivos definem a interface do usuário e a funcionalidade do painel de tarefas do suplemento.The following files define the add-in's task pane UI and functionality.

  • O arquivo ./src/taskpane/taskpane.html contém a marcação HTML do painel de tarefas.The ./src/taskpane/taskpane.html file contains the HTML markup for the task pane.

  • O arquivo ./src/taskpane/taskpane.css contém o CSS que é aplicado ao conteúdo no painel de tarefas.The ./src/taskpane/taskpane.css file contains the CSS that's applied to content in the task pane.

  • Em um projeto JavaScript, o arquivo ./src/TaskPane/TaskPane.js contém código para inicializar o suplemento.In a JavaScript project, the ./src/taskpane/taskpane.js file contains code to initialize the add-in. Em um projeto TypeScript, o arquivo ./src/TaskPane/TaskPane.TS contém código para inicializar o suplemento e também o código que usa a biblioteca da API JavaScript do Office para adicionar os dados do Microsoft Graph ao documento do Office.In a TypeScript project, the ./src/taskpane/taskpane.ts file contains code to initialize the add-in and also code that uses the Office JavaScript API library to add the data from Microsoft Graph to the Office document.

AutenticaçãoAuthentication

Os seguintes arquivos facilitam o processo de SSO e gravam dados no documento do Office.The following files facilitate the SSO process and write data to the Office document.

  • Em um projeto JavaScript, o arquivo ./src/Helpers/documentHelper.js contém código que usa a biblioteca da API JavaScript do Office para adicionar os dados do Microsoft Graph ao documento do Office.In a JavaScript project, the ./src/helpers/documentHelper.js file contains code that uses the Office JavaScript API library to add the data from Microsoft Graph to the Office document. Não há nenhum arquivo em um projeto TypeScript; o código que usa a biblioteca da API JavaScript do Office para adicionar os dados do Microsoft Graph ao documento do Office existe em ./src/TaskPane/TaskPane.TS em vez disso.There is no such file in a TypeScript project; the code that uses the Office JavaScript API library to add the data from Microsoft Graph to the Office document exists in ./src/taskpane/taskpane.ts instead.

  • O arquivo ./src/Helpers/fallbackauthdialog.html é a página sem interface do usuário que carrega o JavaScript para a estratégia de autenticação de fallback.The ./src/helpers/fallbackauthdialog.html file is the UI-less page that loads the JavaScript for the fallback authentication strategy.

  • O arquivo ./src/Helpers/fallbackauthdialog.js contém o JavaScript para a estratégia de autenticação de fallback que entra no usuário com o MSAL. js.The ./src/helpers/fallbackauthdialog.js file contains the JavaScript for the fallback authentication strategy that signs in the user with msal.js.

  • O arquivo ./src/Helpers/fallbackauthhelper.js contém o painel de tarefas JavaScript que invoca a estratégia de autenticação de fallback em cenários em que a autenticação SSO não é suportada.The ./src/helpers/fallbackauthhelper.js file contains the task pane JavaScript that invokes the fallback authentication strategy in scenarios when SSO authentication is not supported.

  • O arquivo ./src/helpers/ssoauthhelper.js contém a chamada JavaScript à API de SSO, getAccessToken, recebe o token de inicialização, inicia a troca do token de inicialização por um token de acesso ao Microsoft Graph e chama o Microsoft Graph para obter os dados.The ./src/helpers/ssoauthhelper.js file contains the JavaScript call to the SSO API, getAccessToken, receives the bootstrap token, initiates the swap of the bootstrap token for an access token to Microsoft Graph, and calls to Microsoft Graph for the data.

Configure o SSOConfigure SSO

Nesse ponto, seu projeto de suplemento foi criado e contém o código necessário para facilitar o processo de SSO.At this point, your add-in project has been created and contains the code that's necessary to facilitate the SSO process. Depois, execute as etapas a seguir para configurar o SSO do seu suplemento.Next, complete the following steps to configure SSO for your add-in.

  1. Navegue até a pasta raiz do projeto.Navigate to the root folder of the project.

    cd "My SSO Office Add-in"
    
  2. Execute o comando a seguir para configurar o SSO do suplemento.Run the following command to configure SSO for the add-in.

    npm run configure-sso
    

    Aviso

    Esse comando falhará se o locatário estiver configurado para exigir autenticação de dois fatores.This command will fail if your tenant is configured to require two-factor authentication. Nesse cenário, será necessário concluir manualmente as etapas de configuração do SSO e registro do aplicativo Azure, conforme descrito no tutorial Criar um Suplemento do Office com Node.js que usa logon único.In this scenario, you'll need to manually complete the Azure app registration and SSO configuration steps, as described in the Create a Node.js Office Add-in that uses single sign-on tutorial.

  3. Uma janela de navegador da Web será exibida e solicitará que você entre no Azure. A web browser window will open and prompt you to sign in to Azure. Entre no Azure com as suas credenciais de administrador do Microsoft 365.Sign in to Azure using your Microsoft 365 administrator credentials. Essas credenciais serão usadas para registrar um novo aplicativo no Azure e definir as configurações necessárias para o SSO.These credentials will be used to register a new application in Azure and configure the settings required by SSO.

    Observação

    Se você entrar no Azure usando credenciais de não administrador durante essa etapa, o script configure-sso não conseguirá fornecer consentimento de administrador para o suplemento aos usuários da organização.If you sign in to Azure using non-administrator credentials during this step, the configure-sso script won't be able to provide administrator consent for the add-in to users within your organization. Portanto, o SSO não estará disponível aos usuários do suplemento e eles serão solicitados a entrar.SSO will therefore not be available to users of the add-in and they'll be prompted to sign-in.

  4. Depois de inserir suas credenciais, feche a janela do navegador e retorne ao prompt de comando.After you enter your credentials, close the browser window and return to the command prompt. Durante o processo de configuração do SSO, você verá mensagens de status sendo gravadas no console.As the SSO configuration process continues, you'll see status messages being written to the console. Conforme descrito nas mensagens do console, os arquivos no projeto do suplemento que o gerador Yeoman criou são atualizados automaticamente com os dados necessários ao processo de SSO.As described in the console messages, files within the add-in project that the Yeoman generator created are automatically updated with data that's required by the SSO process.

ExperimenteTry it out

Se você tiver criado um suplemento do Excel, do Word ou do PowerPoint, conclua as etapas na seção a seguir para testá-lo. Se você criou um suplemento do Outlook, conclua as etapas na seção Outlook.If you've created an Excel, Word, or PowerPoint add-in, complete the steps in the following section to try it out. If you've created an Outlook add-in, complete the steps in the Outlook section instead.

Excel, Word e PowerPointExcel, Word, and PowerPoint

Execute as etapas a seguir para experimentar um suplemento do Excel, do Word ou do PowerPoint.Complete the following steps to try out an Excel, Word, or PowerPoint add-in.

  1. Quando o processo de configuração do SSO for concluído, execute o seguinte comando para criar o projeto: inicie o servidor Web local e sideload o suplemento no aplicativo cliente do Office selecionado anteriormente.When the SSO configuration process completes, run the following command to build the project, start the local web server, and sideload your add-in in the previously selected Office client application.

    Observação

    Os Suplementos do Office devem usar HTTPS, e não HTTP, mesmo durante o desenvolvimento.Office Add-ins should use HTTPS, not HTTP, even when you are developing. Se for solicitado a instalação de um certificado após executar um dos seguintes comandos, aceite a solicitação para instalar o certificado que o gerador do Yeoman fornecer.If you are prompted to install a certificate after you run the following command, accept the prompt to install the certificate that the Yeoman generator provides.

    npm start
    
  2. No aplicativo cliente do Office que é aberto ao executar o comando anterior (por exemplo, Excel, Word ou PowerPoint), certifique-se de estar conectado com um usuário que seja membro da mesma organização do Microsoft 365, como uma conta de administrador do Microsoft 365 que você usou para se conectar ao Azure ao configurar o SSO na etapa 3 da seção anterior.In the Office client application that opens when you run the previous command (i.e., Excel, Word or PowerPoint), make sure that you're signed in with a user that's a member of the same Microsoft 365 organization as the Microsoft 365 administrator account that you used to connect to Azure while configuring SSO in step 3 of the previous section. Isso estabelecerá as condições apropriadas para que o SSO seja bem-sucedido.Doing so establishes the appropriate conditions for SSO to succeed.

  3. No aplicativo cliente do Office, escolha a guia Página Inicial e o botão Mostrar Painel de Tarefas na faixa de opções para abrir o painel de tarefas do suplemento.In the Office client application, choose the Home tab, and then choose the Show Taskpane button in the ribbon to open the add-in task pane. A imagem a seguir mostra esse botão no Excel.The following image shows this button in Excel.

    Botão do suplemento do Excel

  4. Na parte inferior do painel de tarefas, escolha o botão Obter Informações do Meu Perfil de Usuário para iniciar o processo de SSO.At the bottom of the task pane, choose the Get My User Profile Information button to initiate the SSO process.

  5. Se uma janela de diálogo for exibida solicitando permissões em nome do suplemento, isso significa que não há suporte ao SSO no seu cenário e, em vez disso, o suplemento voltou para um método alternativo de autenticação do usuário.If a dialog window appears to request permissions on behalf of the add-in, this means that SSO is not supported for your scenario and the add-in has instead fallen back to an alternate method of user authentication. Isso poderá ocorrer quando o administrador do locatário não tiver dado ao suplemento uma permissão de acesso ao Microsoft Graph, ou quando o usuário não estiver logado no Office com uma conta válida da Microsoft ou uma conta corporativa ou de estudante do Microsoft 365.This may occur when the tenant administrator hasn't granted consent for the add-in to access Microsoft Graph, or when the user isn't signed into Office with a valid Microsoft account or Microsoft 365 Education or Work account. Escolha o botão Aceitar na janela de diálogo para continuar.Choose the Accept button in the dialog window to continue.

    Caixa de diálogo Solicitação de permissões

    Observação

    Após um usuário aceitar a solicitação de permissões, elas não serão solicitadas novamente no futuro.After a user accepts this permissions request, they won't be prompted again in the future.

  6. O suplemento recupera as informações de perfil do usuário conectado e as grava no documento.The add-in retrieves profile information for the signed-in user and writes it to the document. A imagem a seguir mostra um exemplo de informações de perfil gravadas em uma planilha do Excel.The following image shows an example of profile information written to an Excel worksheet.

    Informações de perfil de usuário na planilha do Excel

OutlookOutlook

Execute as etapas a seguir para experimentar um suplemento do Outlook.Complete the following steps to try out an Outlook add-in.

  1. Quando concluir o processo de configuração de SSO, execute o seguinte comando para criar o projeto e iniciar o servidor Web local.When the SSO configuration process completes, run the following command to build the project and start the local web server.

    Observação

    Os Suplementos do Office devem usar HTTPS, e não HTTP, mesmo durante o desenvolvimento.Office Add-ins should use HTTPS, not HTTP, even when you are developing. Se for solicitado a instalação de um certificado após executar um dos seguintes comandos, aceite a solicitação para instalar o certificado que o gerador do Yeoman fornecer.If you are prompted to install a certificate after you run the following command, accept the prompt to install the certificate that the Yeoman generator provides.

    npm start
    
  2. Siga as instruções Realizar sideload dos suplementos do Outlook para testepara realizar o sideload do suplemento do Outlook.Follow the instructions in Sideload Outlook add-ins for testing to sideload the add-in in Outlook. Certifique-se de que você está conectado ao Outlook com um usuário que seja membro da mesma organização do Microsoft 365, como a conta de administrador do Microsoft 365 que você usou para se conectar ao Azure, ao configurar o SSO na etapa 3 da seção anterior.Make sure that you're signed in to Outlook with a user that's a member of the same Microsoft 365 organization as the Microsoft 365 administrator account that you used to connect to Azure while configuring SSO in step 3 of the previous section. Isso estabelecerá as condições apropriadas para que o SSO seja bem-sucedido.Doing so establishes the appropriate conditions for SSO to succeed.

  3. Escreva uma nova mensagem no Outlook.In Outlook, compose a new message.

  4. Na janela redigir mensagem, escolha o botão Exibir painel de tarefas na faixa de opções para abrir o painel de tarefas de suplemento.In the message compose window, choose the Show Taskpane button in the ribbon to open the add-in task pane.

    Botão do suplemento do Outlook

  5. Na parte inferior do painel de tarefas, escolha o botão Obter Informações do Meu Perfil de Usuário para iniciar o processo de SSO.At the bottom of the task pane, choose the Get My User Profile Information button to initiate the SSO process.

  6. Se uma janela de diálogo for exibida solicitando permissões em nome do suplemento, isso significa que não há suporte ao SSO no seu cenário e, em vez disso, o suplemento voltou para um método alternativo de autenticação do usuário.If a dialog window appears to request permissions on behalf of the add-in, this means that SSO is not supported for your scenario and the add-in has instead fallen back to an alternate method of user authentication. Isso poderá ocorrer quando o administrador do locatário não tiver dado ao suplemento uma permissão de acesso ao Microsoft Graph, ou quando o usuário não estiver logado no Office com uma conta válida da Microsoft ou uma conta corporativa ou de estudante do Microsoft 365.This may occur when the tenant administrator hasn't granted consent for the add-in to access Microsoft Graph, or when the user isn't signed into Office with a valid Microsoft account or Microsoft 365 Education or Work account. Escolha o botão Aceitar na janela de diálogo para continuar.Choose the Accept button in the dialog window to continue.

    Caixa de diálogo Solicitação de permissões

    Observação

    Após um usuário aceitar a solicitação de permissões, elas não serão solicitadas novamente no futuro.After a user accepts this permissions request, they won't be prompted again in the future.

  7. O suplemento recupera as informações de perfil do usuário conectado e as grava no corpo da mensagem do e-mail.The add-in retrieves profile information for the signed-in user and writes it to the body of the email message.

    Informações de perfil de usuário na mensagem do Outlook

Próximas etapasNext steps

Parabéns, você criou com êxito um suplemento do painel de tarefas que usa SSO sempre que possível; e usa um método alternativo de autenticação de usuário quando não há suporte ao SSO.Congratulations, you've successfully created a task pane add-in that uses SSO when possible, and uses an alternate method of user authentication when SSO is not supported. Para saber como personalizar seu suplemento para adicionar novas funcionalidades que requerem permissões diferentes, consulte Personalizar o suplemento habilitado para SSO do Node.js.To learn about customizing your add-in to add new functionality that requires different permissions, see Customize your Node.js SSO-enabled add-in.

Confira tambémSee also