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

  • Artigo

Sempre use a API de caixa de diálogo do Office para autenticar e autorizar usuários com seu Suplemento do Office. Você também deve usar a API de diálogo do Office se estiver implementando a autenticação de fallback quando o SSO (logon único) não puder ser usado.

Os suplementos do Office são executados em um iframe quando abertos em 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. Estes incluem o Google, Facebook e serviços protegidos pelo plataforma de identidade da Microsoft (anteriormente Azure AD V 2.0), como uma conta Microsoft, uma conta de trabalho ou Microsoft 365 Education ou outra conta comum. Além disso, os recursos de segurança implementados na webview quando os Suplementos do Office são executados no Office no Windows ou no Office on 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 uma instância de controle de navegador ou webview separada. É por isso que o Office fornece a API de diálogo do Office, especificamente o método displayDialogAsync .

Observação

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 runtime 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 ser 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 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á posteriormente 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.

Observação

Para configurar a caixa de diálogo a ser aberta em um iframe flutuante, passe a opção displayInIframe: true na chamada para displayDialogAsync. Não fazer isso quando estiver usando a API de caixa de diálogo do Office para entrar.

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

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

Diagrama mostrando a relação entre o painel de tarefas e os processos do navegador de diálogo.

  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 da janela do painel de tarefas. Esta página pode ter uma interface do usuário que diz apenas "Aguarde, estamos redirecionando você para a página em que você pode entrar no NAME-OF-PROVIDER". O código nesta página constrói a URL da página de entrada do provedor de identidade com informações passadas para a caixa de diálogo conforme descrito em Passar informações para a caixa de diálogo ou é codificado 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 da caixa 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 suplemento fornecer ao usuário uma opção de provedores, como uma conta microsoft, Google ou Facebook, você precisará de uma primeira página local (consulte 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, o usuário será solicitado a fazê-lo 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 stringizado ou armazenando o token de acesso em que 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 diferentes instâncias de runtime do navegador, você deve usar bibliotecas de autenticação/autorização de forma 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 é utilizável nos 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 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 em que a instância do navegador do painel de tarefas pode recuperá-lo, como armazenamento local ou um banco de dados do lado do servidor.

Observação

As alterações na segurança do navegador afetarão sua estratégia de tratamento de token.

  • Se o suplemento for executado em Office na Web no navegador Versão Prévia do Microsoft Edge (não Chromium) ou Safari, a caixa de diálogo e o painel de tarefas não compartilharão o mesmo armazenamento local, portanto, ele não poderá ser usado para se comunicar entre eles.
  • A partir da versão 115 de navegadores baseados em Chromium, como Chrome e Edge, a partição de armazenamento está sendo testada para impedir o rastreamento entre sites de canal lateral específico (consulte também políticas de navegador do Microsoft Edge). Isso significa que os dados armazenados por APIs de armazenamento, como o armazenamento local, só estão disponíveis para contextos com a mesma origem e o mesmo site de nível superior. Para contornar isso, no navegador, vá para chrome://flags ou edge://flags e defina o sinalizador Experimental de partição de armazenamento de terceiros (#third-armazenamento-particionamento) como Desabilitado. Sempre que possível, recomendamos passar dados entre a caixa de diálogo e o painel de tarefas usando os métodos messageParent e messageChild , conforme descrito em Usar a API de diálogo do Office em seus Suplementos do Office.

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, você não pode usar o objeto "contexto de auth" 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 de contexto de auth e os métodos que os criam não são utilizáveis nos 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

Além dos objetos monolíticos de "contexto de autenticação", a maioria das bibliotecas fornecem APIs em um nível inferior de abstração que permite que o código crie objetos auxiliares menos monolíticos. Por exemplo, MSAL.NET v. 3.x.x tem uma API para construir uma URL de entrada e outra API que constrói um objeto AuthResult que contém um token de acesso em uma propriedade acessível ao seu código. Para obter exemplos de MSAL.NET em um Suplemento do Office, confira: ASP.NET Microsoft Graph no Suplemento do Office e ASP.NET Microsoft Graph no Suplemento do Outlook. 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

Conferir também