Autenticar e autorizar com a API da Caixa de Diálogo do Office

Para cenários em que você não deseja usar SSO (logon único) ou não pode usar SSO, use a API de diálogo do Office para autenticar e autorizar usuários com seu suplemento do Office.

Os suplementos do Office são executados em um iframe quando abertos no Office na Web. Muitas autoridades de identidade, também chamadas de STS (Secure Token Services), impedem que sua página de entrada seja aberta em um iframe. Isso inclui Google, Facebook e serviços protegidos pelo Microsoft Entra ID, como uma conta Microsoft, uma conta corporativa ou do Microsoft 365 Education ou outra conta comum. Além disso, os recursos de segurança implementados no modo de exibição da Web quando os Suplementos do Office são executados no Office no Windows ou no Office no Mac podem impedir que as páginas de entrada funcionem corretamente.

Para que a autorização funcione corretamente, a página de entrada deve ser aberta em um navegador separado ou em uma instância de controle de modo de exibição da Web. É por isso que o Office fornece a API de caixa de diálogo do Office, especificamente o método displayDialogAsync .

A caixa de diálogo aberta com essa API tem as seguintes características.

• Não é restrita.
• É uma instância do navegador completamente separada do painel de tarefas, ou seja:
  • Ele tem seu próprio ambiente de tempo de execução e objeto de janela e variáveis globais.
  • Não há nenhum ambiente de execução compartilhado com o painel de tarefas.
  • Ele não compartilha o mesmo armazenamento de sessão (a propriedade Window.sessionStorage ) que o painel de tarefas.
• A primeira página aberta na caixa de diálogo deve estar hospedada no mesmo domínio que o painel de tarefas, incluindo protocolo, subdomínios e porta, se houver.
• A caixa de diálogo pode enviar informações de volta ao painel de tarefas usando o método messageParent . Recomendamos que esse método seja chamado somente de uma página hospedada no mesmo domínio que o painel de tarefas, incluindo protocolo, subdomínios e porta. Caso contrário, haverá complicações em como você chama o método e processa a mensagem. Para obter mais informações, mensagens entre domínios para o runtime do host.

Por padrão, a caixa de diálogo é aberta em um novo controle de modo de exibição da Web, não em um iframe. Isso garante que ele possa abrir a página de entrada de um provedor de identidade. Como você verá mais adiante neste artigo, as características da caixa de diálogo do Office têm implicações sobre como você usa bibliotecas de autenticação ou autorização, como a MSAL (Biblioteca de Autenticação da Microsoft) e o Passport.

Fluxo de autenticação com a caixa de diálogo do Office

A seguir está um fluxo de autenticação típico.

1. A primeira página que é aberta na caixa de diálogo é uma página (ou outro recurso) hospedada no domínio do suplemento; ou seja, o mesmo domínio que a janela do painel de tarefas. Essa página pode ter uma interface do usuário que diz apenas "Aguarde, estamos redirecionando você para a página onde você pode entrar no NOME DO PROVEDOR". O código nesta página constrói a URL da página de entrada do provedor de identidade com informações que são passadas para a caixa de diálogo, conforme descrito em Passar informações para a caixa de diálogo , ou são codificadas em um arquivo de configuração do suplemento, como um arquivo web.config.
2. A janela de diálogo redireciona então para a página de entrada. A URL inclui um parâmetro de consulta que informa o provedor de identidade para redirecionar a janela de diálogo a uma página específica depois que o usuário entrar. Nesse artigo, chamaremos essa página de redirectPage.html. Nesta página, os resultados da tentativa de entrada podem ser passados para o painel de tarefas com uma chamada de messageParent. Recomendamos que esta seja uma página no mesmo domínio que a janela do host.
3. O serviço do provedor de identidade processa a solicitação GET recebida da janela de diálogo. Se o usuário já estiver conectado, ele imediatamente redirecionará a janela para redirectPage.html e incluirá os dados do usuário como um parâmetro de consulta. Se o usuário ainda não tiver entrado, a página de entrada do provedor aparecerá na janela para que o usuário possa entrar. Para a maioria dos provedores, se o usuário não conseguir entrar com êxito, o provedor mostrará uma página de erro na janela de diálogo e não redirecionará para redirectPage.html. O usuário precisa fechar a janela selecionando o X no canto. Se o usuário entrar com êxito, a janela de diálogo será redirecionada para redirectPage.html e os dados do usuário serão incluídos como um parâmetro de consulta.
4. Quando a página redirectPage.html é aberta, ela chama a messageParent para relatar o êxito ou a falha na página do painel de tarefas e opcionalmente também pode informar os dados do usuário ou os dados de erro. Outras mensagens possíveis incluem passar um token de acesso ou informar ao painel de tarefas que o token está no armazenamento.
5. O evento DialogMessageReceived é acionado na página do painel de tarefas, seu manipulador fecha a janela de diálogo e assim, a mensagem pode ser processada.

Prestar suporte a vários provedores de identidade

Se o seu suplemento oferecer ao usuário uma opção de provedores, como uma conta Microsoft, o Google ou o Facebook, você precisará de uma primeira página local (consulte a seção anterior) que forneça uma interface do usuário para o usuário selecionar um provedor. A escolha do provedor acionará a construção da URL de entrada e seu redirecionamento.

Autorização do suplemento para um recurso externo

Na Web moderna, os usuários e aplicativos da Web são entidades de segurança. O aplicativo tem sua própria identidade e permissões para recursos online, como o Microsoft 365, o Google Plus, o Facebook ou o LinkedIn. O aplicativo é registrado no provedor de recursos antes da implantação. O registro inclui:

• Uma lista das permissões que o aplicativo precisa.
• Uma URL para a qual o serviço do recurso deve retornar um token de acesso quando o aplicativo acessa o serviço.

Quando um usuário invoca uma função no aplicativo que acessa os dados do usuário no serviço do recurso, ele é solicitado a entrar no serviço e a conceder ao aplicativo as permissões necessárias para os recursos do usuário. Em seguida, o serviço redireciona a janela de entrada para a URL previamente registrada e transmite o token de acesso. O aplicativo usa o token de acesso para acessar os recursos do usuário.

Você pode usar a API da Caixa de Diálogo do Office para gerenciar esse processo usando um fluxo semelhante àquele descrito para os usuários entrarem. As únicas diferenças são:

• Se o usuário não tiver concedido anteriormente ao aplicativo as permissões necessárias, ele será solicitado a fazer isso na caixa de diálogo após entrar.
• Seu código na janela de diálogo envia o token de acesso para a janela do host usando messageParent para enviar o token de acesso stringificado ou armazenando o token de acesso onde a janela do host pode recuperá-lo (e usando messageParent para informar à janela do host que o token está disponível). O token tem um limite de tempo, mas enquanto durar, a janela do host poder usá-lo para acessar recursos do usuário de forma direta, sem outras solicitações.

Alguns suplementos de exemplo de autenticação que usam a API da Caixa de Diálogo do Office para essa finalidade estão listados em Amostras.

Usar bibliotecas de autenticação com a caixa de diálogo

Como a caixa de diálogo do Office e o painel de tarefas são executados em instâncias de tempo de execução do navegador diferentes, você deve usar bibliotecas de autenticação/autorização de maneira diferente de como elas são usadas quando a autenticação e a autorização ocorrem na mesma janela. As seções a seguir descrevem as maneiras pelas quais você pode ou não usar essas bibliotecas.

Normalmente, você não pode usar o cache interno da biblioteca para armazenar tokens

Normalmente, as bibliotecas relacionadas à autenticação fornecem um cache na memória para armazenar o token de acesso. Se chamadas subsequentes para o provedor de recursos (por exemplo, Google, Microsoft Graph, Facebook, etc.) forem feitas, a biblioteca primeiro verificará se o token no cache está expirado. Caso não tenha expirado, a biblioteca retornará o token em cache, em vez de retornar ao STS para obter um novo token. Mas esse padrão não pode ser usado em Suplementos do Office. Como o processo de entrada ocorre na instância do navegador da caixa de diálogo do Office, o cache de token está nessa instância.

Estritamente relacionado a isso está o fato de que uma biblioteca normalmente fornece métodos interativos e "silenciosos" para obter um token. Quando for possível fazer tanto a autenticação quanto as chamadas de dados ao recurso na mesma instância do navegador, o código chamará o método silencioso para obter um token imediatamente antes do código adicionar o token à chamada de dados. O método silencioso procurará por um token não expirado no cache e o retornará, caso haja um. Caso contrário, o método silencioso chama o método interativo que redireciona para a entrada do STS. Após a conclusão da entrada, o método interativo retorna o token, mas também o armazena em cache na memória. No entanto, quando a API da Caixa de Diálogo do Office está sendo usada, as chamadas de dados do recurso, que chamam o método silencioso, estão na instância do navegador do painel de tarefas. O cache de token da biblioteca não existe nessa instância.

Como alternativa, a instância do navegador de caixa de diálogo do suplemento pode chamar diretamente o método interativo da biblioteca. Quando esse método retorna um token, seu código deve armazenar explicitamente o token em algum lugar onde a instância do navegador do painel de tarefas possa recuperá-lo, como armazenamento local ou um banco de dados do lado do servidor.

Outra opção é passar o token para o painel de tarefas com o método messageParent. Essa alternativa só é possível se o método interativo armazenar o token de acesso em um local onde o código possa lê-lo. Às vezes, o método interativo de uma biblioteca é projetado para armazenar o token em uma propriedade particular de um objeto que está inacessível ao código.

Normalmente, não é possível usar o objeto "contexto de autenticação" da biblioteca

Frequentemente, uma biblioteca relacionada à autenticação possui um método que obtém tanto um token de forma interativa, como também cria um objeto de "contexto de autenticação" retornado pelo método. O token é uma propriedade do objeto (possivelmente particular e inacessível diretamente do código). Esse objeto tem os métodos que recebem os dados do recurso. Esses métodos incluem o token nas Solicitações HTTP feitas ao provedor de recursos (por exemplo, Google, Microsoft Graph, Facebook, etc.).

Esses objetos auth-context e os métodos que os criam não podem ser usados em Suplementos do Office. Como a entrada ocorre na instância do navegador da caixa de diálogo do Office, o objeto teria que ser criado lá. Mas as chamadas de dados do recurso estão na instância do navegador do painel de tarefas e não há como enviar o objeto de uma instância para outra. Por exemplo, não é possível passar o objeto pelo messageParent porque messageParent só pode passar valores de cadeia de caracteres. Um objeto do JavaScript com métodos não pode ser transformado em cadeia de caracteres de maneira confiável.

Como usar as bibliotecas através da API da Caixa de Diálogo do Office

Em vez de depender de grandes objetos monolíticos de "contexto de autenticação", a maioria das bibliotecas fornece APIs de nível inferior que permitem criar objetos auxiliares menores e criados para fins específicos. Por exemplo, MSAL.NET fornece uma API que retorna um objeto AuthResult, que expõe o token de acesso por meio de uma propriedade que seu código pode usar diretamente. Para MSAL.NET exemplos em Suplementos do Office, consulte: Suplemento do Office Microsoft Graph ASP.NET e Suplemento do Outlook Microsoft Graph ASP.NET. Para ver um exemplo de como usar o msal.js em um suplemento, confira Microsoft Graph React no Suplemento do Office.

Para saber mais sobre as bibliotecas de autenticação e autorização, confira Microsoft Graph: bibliotecas recomendadas e Outros serviços externos: bibliotecas.

Exemplos

• ASP.NET Microsoft Graph no Suplemento do Office: um suplemento com base em ASP.NET (Excel, Word ou PowerPoint) que usa a biblioteca MSAL.NET e o Fluxo de Código de Autorização para efetuar logon, e obter um token de acesso para dados do Microsoft Graph.
• ASP.NET Microsoft Graph no Suplemento do Outlook: semelhante a exibida acima, mas o aplicativo do Office sendo o Outlook.
• Microsoft Graph React no Suplemento do Office: um suplemento com base em NodeJS (Excel, Word ou PowerPoint) que usa a biblioteca msal.js e o Fluxo Implícito para efetuar logon, e obter um token de acesso para dados do Microsoft Graph.

Conferir também

• Autorizar serviços externos no Suplemento do Office
• Usar a API da Caixa de Diálogo do Office nos suplementos do Office