Início rápido logon único (SSO).
Neste artigo, você usará o gerador Yeoman para Suplementos do Office para criar um Suplemento do Office para Excel, Outlook, Word ou PowerPoint que usa o SSO (logon único).
Observação
O modelo SSO fornecido pelo gerador Yeoman para Suplementos do Office é executado apenas em localhost e não pode ser implantado. Se você estiver criando um novo Suplemento do Office com SSO para fins de produção, siga as instruções em Criar uma Node.js Suplemento do Office que usa logon único.
Pré-requisitos
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.
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.
Se você estiver usando um Mac e não tiver a CLI do Azure instalada no computador, instale o 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.
Criar o projeto do suplemento
Dica
O gerador Yeoman pode criar um Suplemento do Office habilitado para SSO para Excel, Outlook, Word ou PowerPoint com o tipo de script javaScript ou 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.
Execute o comando a seguir para criar um projeto de suplemento usando o gerador Yeoman. Uma pasta que contém o projeto será adicionada ao diretório atual.
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 informações a seguir para criar seu projeto de suplemento.
- Escolha um tipo de projeto:
Office Add-in Task Pane project supporting single sign-on (localhost)
- Escolha um tipo de script:
JavaScript
- O que você deseja nomear seu suplemento?
My Office Add-in
- Você gostaria de proporcionar suporte para qual aplicativo cliente do Office? Escolha
Excel
,Outlook
,Word
ouPowerpoint
.
Depois que você concluir o assistente, o gerador criará o projeto e instalará os componentes Node de suporte.
Observação
Se você estiver usando Node.js versão 20.0.0 ou posterior, poderá ver um aviso quando o gerador executar a instalação de que você tem um mecanismo sem suporte. Estamos trabalhando em uma correção para isso. Enquanto isso, o aviso não afeta o gerador ou o projeto que você gera, portanto, ele pode ser ignorado.
Dica
Você pode ignorar as orientações da próximas etapas fornecidas pelo gerador Yeoman após a criação do projeto de suplemento. As instruções passo a passo deste artigo fornecem todas as orientações necessárias para concluir este tutorial.
Explore o projeto
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.
Configuração
Os arquivos a seguir especificam definições de configuração para o suplemento.
O arquivo ./manifest.xml no diretório raiz do projeto define as configurações e os recursos do suplemento.
O arquivo ./.ENV no diretório raiz do projeto define as constantes que são usadas pelo projeto de suplemento.
Painel de tarefas
Os arquivos a seguir definem a interface do usuário e a funcionalidade do painel de tarefas do suplemento.
O arquivo ./src/taskpane/taskpane.html contém a marcação HTML do painel de tarefas.
O arquivo ./src/taskpane/taskpane.css contém o CSS que é aplicado ao conteúdo no painel de tarefas.
O arquivo ./src/taskpane/taskpane.js contém código para inicializar o suplemento e também o código que usa a biblioteca de API JavaScript do Office para adicionar os dados do Microsoft Graph ao documento do Office.
Autenticação
Os arquivos a seguir facilitam o processo de logon único e gravam dados no documento do Office.
Em um projeto JavaScript, o arquivo ./src/helpers/documentHelper.js contém código que encapsula as informações de perfil do usuário para inserção no documento atual do Office. Não há nenhum arquivo desse tipo em um projeto TypeScript. Em vez disso, o código que coleta as informações de perfil está embutido no arquivo ./src/taskpane/taskpane.ts .
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. A
<script>
marca para carregar o JavaScript é inserida no arquivo quando Webpack.config.js é executada.O arquivo ./src/helpers/fallbackauthdialog.js contém o JavaScript para a estratégia de autenticação de fallback que conecta o usuário com msal.js.
O arquivo ./src/helpers/message-helper.js contém JavaScript que mostra ou oculta mensagens de erro para o usuário.
O arquivo ./src/helpers/middle-tier-calls.js contém o JavaScript que chama sua API Web para buscar dados.
O arquivo ./src/helpers/sso-helper.js contém a chamada JavaScript para a API do SSO,
getAccessToken
, recebe o token de acesso e o inclui em uma chamada ao Microsoft Graph para os dados. No caso de um erro ou em cenários em que a autenticação SSO não é compatível, ela invoca a estratégia de fallback.
Configure o SSO
Agora que seu projeto de suplemento é criado e contém o código necessário para facilitar o processo de SSO, conclua as etapas a seguir para configurar o SSO para seu suplemento.
Vá para a pasta raiz do projeto.
cd "My Office Add-in"
Execute o comando a seguir para configurar o SSO do suplemento.
npm run configure-sso
Aviso
Esse comando falhará se o locatário estiver configurado para exigir autenticação de dois fatores. Nesse cenário, você precisará concluir manualmente as etapas de registro do aplicativo do Azure e da configuração do SSO seguindo todas as etapas no Suplemento Criar um Node.js Office que usa o tutorial de logon único .
Uma janela de navegador da Web será exibida e solicitará que você entre no Azure. Entre no Azure com as suas credenciais de administrador do Microsoft 365. Essas credenciais serão usadas para registrar um novo aplicativo no Azure e definir as configurações necessárias para o 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. Portanto, o SSO não estará disponível aos usuários do suplemento e eles serão solicitados a entrar.Depois de inserir suas credenciais, feche a janela do navegador e retorne ao prompt de comando. Durante o processo de configuração do SSO, você verá mensagens de status sendo gravadas no 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.
Testar seu suplemento
Se você criou um suplemento do Excel, Word ou PowerPoint, conclua as etapas na seção a seguir para experimentá-lo. Se você criou um suplemento do Outlook, conclua as etapas na seção Outlook .
Excel, Word e PowerPoint
Conclua as etapas a seguir para testar um suplemento do Excel, Word ou PowerPoint.
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.
Observação
Os suplementos do Office devem usar HTTPS, não HTTP, mesmo enquanto você estiver desenvolvendo. Se você for solicitado a instalar um certificado depois de executar um dos comandos a seguir, aceite o prompt para instalar o certificado que o gerador Yeoman fornece. Você também pode executar o prompt de comando ou terminal como administrador para que as alterações sejam feitas.
npm start
Quando o Excel, Word ou PowerPoint abrir quando você executar o comando anterior, verifique se você está conectado com uma conta de usuário que é membro da mesma organização Microsoft 365 que 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. Isso estabelecerá as condições apropriadas para que o SSO seja bem-sucedido.
No aplicativo cliente do Office, escolha a guia Página Inicial e, em seguida, escolha Mostrar Taskpane para abrir o painel de tarefas de suplemento.
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.
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. Isso pode ocorrer quando o administrador do locatário não concedeu consentimento para que o suplemento acesse o Microsoft Graph ou quando o usuário não está conectado ao Office com uma conta Microsoft válida ou Microsoft 365 Education ou conta work. Escolha Aceitar para continuar.
Observação
Após um usuário aceitar a solicitação de permissões, elas não serão solicitadas novamente no futuro.
O suplemento recupera as informações de perfil do usuário conectado e as grava no documento. A imagem a seguir mostra um exemplo de informações de perfil gravadas em uma planilha do Excel.
Outlook
Execute as etapas a seguir para experimentar um suplemento do Outlook.
Quando concluir o processo de configuração de SSO, execute o seguinte comando para criar o projeto e iniciar o servidor Web local.
Observação
Os suplementos do Office devem usar HTTPS, não HTTP, mesmo enquanto você estiver desenvolvendo. Se você for solicitado a instalar um certificado depois de executar um dos comandos a seguir, aceite o prompt para instalar o certificado que o gerador Yeoman fornece. Você também pode executar o prompt de comando ou terminal como administrador para que as alterações sejam feitas.
npm start
Siga as instruções Realizar sideload dos suplementos do Outlook para testepara realizar o sideload do suplemento do 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. Isso estabelecerá as condições apropriadas para que o SSO seja bem-sucedido.
Escreva uma nova mensagem no Outlook.
Na janela de composição da mensagem, escolha o botão Mostrar Taskpane para abrir o painel de tarefas de suplemento.
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.
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. Isso pode ocorrer quando o administrador do locatário não concedeu consentimento para que o suplemento acesse o Microsoft Graph ou quando o usuário não está conectado ao Office com uma conta Microsoft válida ou Microsoft 365 Education ou conta work. Escolha Aceitar para continuar.
Observação
Após um usuário aceitar a solicitação de permissões, elas não serão solicitadas novamente no futuro.
O suplemento recupera as informações de perfil do usuário conectado e as grava no corpo da mensagem do e-mail.
Próximas etapas
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. 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.
Solução de problemas
Verifique se o ambiente está pronto para o desenvolvimento do Office seguindo as instruções em Configurar seu ambiente de desenvolvimento.
A etapa automática
npm install
que o Yo Office executa pode falhar. Se você vir erros ao tentar executarnpm start
, navegue até a pasta de projeto recém-criada em um prompt de comando e executenpm install
manualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de suplemento do Office usando o Gerador yeoman.Se o suplemento mostrar um erro (por exemplo, "Esse suplemento não pôde ser iniciado. Feche essa caixa de diálogo para ignorar o problema ou clique em "Reiniciar" para tentar novamente.") ao pressionar F5 ou escolher Depurar>Iniciar Depuração no Visual Studio, consulte Depurar suplementos do Office no Visual Studio para outras opções de depuração.
Alguns dos códigos de exemplo usam JavaScript ES6. Isso não é compatível com versões mais antigas do Office que usam o mecanismo do navegador Trident (Internet Explorer 11). Para obter informações sobre como dar suporte a essas plataformas em seu suplemento, consulte Suporte a versões mais antigas da Microsoft webviews e office. Se você ainda não tiver uma assinatura do Microsoft 365 a ser usada para desenvolvimento, poderá se qualificar para uma assinatura de desenvolvedor Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.
Confira também
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de