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

Sempre use a API de caixa de diálogo do Office para autenticar e autorizar usuários com seu Suplemento do Office. Também tem de utilizar a API de caixa de diálogo do Office se estiver a implementar a autenticação de contingência quando não for possível utilizar o início de sessão único (SSO).

Os Suplementos do Office são executados num iframe quando abertos no Office na Web. Muitas autoridades de identidade, também denominadas Secure Token Services (STS), impedem que a respetiva página de início de sessão seja aberta num iframe. Estes incluem o Google, Facebook e serviços protegidos pela plataforma de identidades da Microsoft (anteriormente Azure AD V 2.0), como uma conta Microsoft, uma conta Microsoft 365 Educação ou profissional, ou outra conta comum. Também as funcionalidades de segurança implementadas na webview quando os Suplementos do Office são executados no Office no Windows ou o Office no Mac pode impedir que as páginas de início de sessão funcionem corretamente.

Para que a autorização funcione corretamente, a página de início de sessão tem de ser aberta numa instância de controlo do browser ou da webview separada. É por este motivo 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 esta API tem as seguintes características.

• Não é restrita.
• É uma instância do navegador completamente separada do painel de tarefas, ou seja:
  • Tem o 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.
  • Não partilha 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 tem de estar alojada no mesmo domínio que o painel de tarefas, incluindo protocolo, subdomínios e porta, se existir.
• A caixa de diálogo pode enviar informações de volta para o painel de tarefas com 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 predefinição, a caixa de diálogo é aberta num novo controlo de vista Web, não num iframe. Isso garante que ele possa abrir a página de entrada de um provedor de identidade. Como verá mais adiante neste artigo, as características da caixa de diálogo do Office têm implicações na forma como utiliza bibliotecas de autenticação ou autorização, como a Biblioteca de Autenticação da Microsoft (MSAL) 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) alojada no domínio do suplemento; ou seja, o mesmo domínio que a janela do painel de tarefas. Esta página pode ter uma IU que diz apenas "Aguarde, estamos a redirecioná-lo para a página onde pode iniciar sessão no NOME DO FORNECEDOR". O código nesta página constrói o URL da página de início de sessão do fornecedor de identidade com informações que são transmitidas para a caixa de diálogo conforme descrito em Transmitir informações para a caixa de diálogo ou está codificado para um ficheiro de configuração do suplemento, como um ficheiro de 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 fornecedores, se o utilizador não conseguir iniciar sessão com êxito, o fornecedor apresenta uma página de erro na janela da caixa de diálogo e não redireciona 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 der ao utilizador uma escolha de fornecedores, como uma conta Microsoft, Google ou Facebook, precisa de uma primeira página local (ver secção anterior) que forneça uma IU para o utilizador selecionar um fornecedor. 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 utilizador não tiver concedido anteriormente à aplicação as permissões necessárias, é pedido ao utilizador que o faça na caixa de diálogo depois de iniciar sessão.
• O código na janela de diálogo envia o token de acesso para a janela do anfitrião, utilizando messageParent para enviar o token de acesso stringified ou armazenando o token de acesso onde a janela do anfitrião pode obtê-lo (e utilizando messageParent para indicar à janela do anfitrião 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.

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

Uma vez que a caixa de diálogo do Office e o painel de tarefas são executados em diferentes instâncias de runtime do browser, tem de utilizar bibliotecas de autenticação/autorização de forma diferente da forma como são utilizadas 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, não pode utilizar a cache interna 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. No entanto, este padrão não é utilizável nos Suplementos do Office. Uma vez que o processo de início de sessão ocorre na instância do browser da caixa de diálogo do Office, a cache de tokens 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 o início de sessão do STS. Após a conclusão do início de sessão, o método interativo devolve o token, mas também o coloca 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 browser de caixa de diálogo do suplemento pode chamar diretamente o método interativo da biblioteca. Quando esse método devolve um token, o código tem de armazenar explicitamente o token num local onde a instância do browser do painel de tarefas o possa obter, como o armazenamento local ou uma base 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 pode utilizar 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.).

Estes objetos de contexto de autenticação e os métodos que os criam não são utilizáveis nos Suplementos do Office. Uma vez que o início de sessão ocorre na instância do browser da caixa de diálogo do Office, o objeto teria de ser criado aí. 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 um URL de início de sessão e outra API que constrói um objeto AuthResult que contém um token de acesso numa 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

• 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