Implementar o SSO (logon único) para suplementos do Office

  • 11 minutos

O logon único (SSO) fornece uma maneira perfeita para que seu suplemento autentique os usuários. Usando esse método, seu suplemento poderá autenticar o usuário para recuperar informações de identidade ou obter a partir de outro ponto de extremidade seguro, como o Microsoft Graph. Para fazer isso, seu suplemento deverá chamar uma API Web do lado do servidor registrada no Microsoft Azure AD.

Nesta unidade, você aprenderá como funciona a autenticação com os Suplementos do Office e como usar o SSO para seus Suplementos do Office.

Autenticação e autorização nos Suplementos do Office

Os aplicativos da Web e os Suplementos do Office permitem acesso anônimo por padrão, mas você pode exigir que os usuários se autentiquem com um login. Por exemplo, você pode exigir que seus usuários se conectem com uma conta da Microsoft, uma conta corporativa ou de estudante do Microsoft 365 ou outra conta comum. Essa tarefa é chamada de autenticação do usuário, pois permite que o suplemento saiba quem é o usuário.

Seu suplemento também pode obter consentimento do usuário para acessar seus dados do Microsoft Graph (como seu perfil do Microsoft 365, arquivos do OneDrive e dados do SharePoint) ou para dados de outras fontes externas, como Google, Facebook, LinkedIn, SalesForce e GitHub. A tarefa é chamada de autorização de suplemento (ou aplicativo), porque é o suplemento que está sendo autorizado, não o usuário.

Há duas maneiras de realizar a autentificação e autorização.

  • SSO (Logon Único) do Office: um sistema que permite que a entrada do usuário no Office também funcione como uma entrada para o suplemento. Opcionalmente, o suplemento também pode usar as credenciais do usuário do Office para autorizar o suplemento para o Microsoft Graph.
  • Autenticação e Autorização de Aplicativo Web com o Azure Active Directory (Azure AD): é assim que os suplementos do Office (e outros aplicativos Web) autenticaram usuários e aplicativos autorizados antes de haver um sistema SSO do Office e ele ainda é usado em cenários em que o SSO do Office não pode ser. Além disso, há cenários em que você deseja que seus usuários façam logon em seu suplemento separadamente, mesmo quando o SSO estiver disponível; por exemplo, se você quiser que eles tenham a opção de fazer logon no suplemento com uma ID diferente daquela com a qual estão atualmente conectados no Office.

Suplementos do Office e Logon único

A Microsoft adicionou suporte para o SSO para os Suplementos do Office em 2020. Essa funcionalidade reduz a frequência com que um usuário é solicitado a fazer login em serviços de terceiros.

O suporte ao SSO do Office é implementado em combinação com o código em seus suplementos personalizados, suporte para o SSO no SDK do JavaScript em tempo de execução do Office e o Microsoft Azure AD. Para oferecer suporte ao SSO, um suplemento do Office deve ter um registro de aplicativo do Microsoft Azure AD correspondente. Este registro de aplicativo define quais permissões o suplemento oferece suporte e confia nos aplicativos cliente do Office para agirem em nome do usuário.

Usando esse suporte para o SSO, os suplementos podem solicitar as informações de perfil do usuário ou informações do Microsoft Graph.

Os usuários podem consentir, por eles mesmos, com os Suplementos do Office para permitir que o suplemento obtenha suas informações de perfil. O suplemento pode usar essas informações de perfil fornecidas pelo Microsoft Azure AD e o Office como a ID do usuário conectado no momento.

Os administradores podem consentir em nome de uma organização inteira através de um processo de implantação centralizado para que cada usuário não tenha que passar individualmente pelo processo de consentimento.

O SSO de Suplementos do Office oferece suporte a ambos os tipos de contas suportadas pela Microsoft: contas de Corporativas e de Estudante (contas do Azure AD) e contas da Microsoft (MSA).

O SSO de Suplementos do Office é suportado em clientes do Office na web e os seguintes clientes de área de trabalho:

  • Windows v16.0.12215.20006 ( ou superior )
  • macOS v16.32.19102902 ( ou superior )

Entenda o fluxo de autenticação do SSO

Vejamos como o processo de SSO funciona em tempo de execução.

Diagrama de visão geral do fluxo de processo de runtime de SSO.

  1. No suplemento, o JavaScript chama uma nova API do Office.js: getAccessToken(). Esse método instrui o aplicativo cliente do Office a obter um token de acesso para o suplemento.
  2. Se o usuário não estiver conectado, o aplicativo cliente do Office abrirá uma janela pop-up para o usuário entrar.
  3. O usuário será solicitado a consentir se for a primeira vez que o usuário atual usa seu suplemento.
  4. O aplicativo cliente do Office solicita o token do suplemento do ponto de extremidade do Microsoft Azure AD v2.0 para o usuário atual.
  5. O Microsoft Azure AD envia o token do suplemento para o aplicativo cliente do Office.
  6. O aplicativo cliente do Office envia o token do suplemento para o suplemento como parte do objeto de resultado devolvido pela chamada getAccessToken().
  7. O JavaScript no suplemento pode analisar o token e extrair as informações necessárias.
  8. Opcionalmente, o suplemento pode enviar uma solicitação HTTP para o lado do servidor para obter mais dados sobre o usuário; como as preferências do usuário. Em vez disso, o próprio token de acesso poderia ser enviado ao servidor para análise e validação.

Implementando o SSO em Suplementos do Office

Para que um Suplementos do Office ofereça suporte ao SSO, você deve fazer o seguinte:

  1. Registrar um aplicativo do Microsoft Azure AD
  2. Associar um Suplemento do Office ao aplicativo do Microsoft Azure AD
  3. Implemente o código do lado do cliente para obter um token de acesso do cliente Office de hospedagem

Vamos examinar cada uma dessas coisas.

Registrar um aplicativo do Microsoft Azure AD

A primeira etapa é registrar um aplicativo do Microsoft Azure AD para o suplemento.

Os aplicativos do Microsoft Azure AD usados para oferecer suporte ao SSO em Suplementos do Office têm muitos requisitos. Por exemplo, eles devem ser aplicativos multilocatários, eles expõem a permissão access_as_user e também devem confiar em todos os aplicativos cliente do Office que chamam o aplicativo.

As ferramentas de desenvolvedor fornecidas pela Microsoft incluem o utilitário configure-sso que registrará o aplicativo Azure AD com todas as configurações necessárias durante o processo de desenvolvimento.

Outra unidade neste módulo aprofundará como criar um novo aplicativo do Microsoft Azure AD para uso por um Suplemento do Office que implemente o SSO.

Associe o Suplemento do Office ao aplicativo do Microsoft Azure AD

Após a criação do aplicativo do Microsoft Azure AD, ele deve ser associado ao Suplemento do Office. Isso é feito no arquivo manifest.xml do suplemento na seção <WebApplicationInfo>:

<WebApplicationInfo>
  <Id>056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Id>
  <Resource>api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e</Resource>
  <Scopes>
    <Scope>User.Read</Scope>
    <Scope>profile</Scope>
    <Scope>openid</Scope>
  </Scopes>
</WebApplicationInfo>

Existem três partes desta seção que devem ser atualizadas no seu aplicativo:

  • Id: esta é a ID do cliente do aplicativo Azure AD registrado
  • Recurso: essa é a URL do suplemento, que é a mesma coisa que o URI usado ao registrar o suplemento Azure AD. A parte do domínio do URI deve corresponder ao domínio utilizado em qualquer um dos URLs na seção <Resources> do arquivo manifest.xml do suplemento.
  • Escopos: essas são as permissões ou escopos que o suplemento precisa de Azure AD.

Importante

As permissões OpenID profile e openid são sempre necessárias para seu suplemento. Essas podem ser as únicas permissões necessárias, a menos que seu suplemento precise chamar outro serviço, como o Microsoft Graph.

Além disso, algumas bibliotecas que seu suplemento usa podem exigir permissões adicionais. Por exemplo, MSAL.NET requer a permissão offline_access.

Implementar o código do lado do cliente

Por fim, um suplemento deve implementar o código do lado do cliente para implementar e oferecer suporte ao SSO. Se você usar as ferramentas fornecidas pela Microsoft, seu projeto de suplemento incluirá a maior parte do código clichê para oferecer suporte ao SSO. Isso é verdade se você usar as Ferramentas pra Desenvolvedores do Office para o Visual Studio 2019 para um suplemento ASP.NET ou o Gerador Yeoman para o Microsoft Office para o Código VS para um Node.js baseado em suplemento.

O método da API [OfficeRuntime.Auth.getAccessToken()](/javascript/api/office-runtime/officeruntime.auth) é usado pelo suplemento para solicitar um token de acesso do cliente Office de hospedagem.

O cliente do Office solicitará um token de acesso do Azure AD usando o aplicativo registrado anteriormente no Microsoft Azure AD.

O token devolvido pelo Azure AD pode ser usado para identificar o usuário, mas também pode ser usado como um token de inicialização para obter um token de acesso que pode ser usado para enviar solicitações ao Microsoft Graph (assumindo que o suplemento e o usuário tenham recebido permissões específicas do Microsoft Graph).

Use o token de acesso para identificar o usuário

Seu suplemento pode precisar identificar o usuário. Nesse caso, seu suplemento normalmente fornece esse token para seu próprio sistema de back-end que usa o token para armazenar as preferências do usuário ou outras informações específicas do usuário atualmente assinado.

Nesse cenário, o token devolvido inclui algumas propriedades que podem ser úteis para seu aplicativo:

  • name: este é o nome de exibição do usuário
  • preferred_username: este é o UPN do usuário ou o endereço de email
  • oid: este é a única ID de objeto do usuário - isto deve ser usado para identificar o usuário em seu sistema back-end como as propriedades nome e preferred_username podem ser alteradas pelo usuário ou por um administrador
  • tid: esta é a ID de locatário exclusiva à qual o usuário pertence

Use o token de acesso em sua própria API

Se utilizar o token de acesso em sua própria API, você deve implementar as práticas recomendadas aceitas ao encaminhar o token recebido do Office. Isto inclui a validação do token para garantir que foi criado pelo Microsoft Azure AD, é da autoridade esperada, o suplemento é a audiência pretendida do token, o token não expirou, e o escopo está definido como access_as_user.

Use o token de acesso para acessar o Microsoft Graph

No cenário em que seu suplemento precisa acessar o Microsoft Graph, seu código pode usar esse token fornecido pelo Office para seu suplemento para iniciar o fluxo OAuth2 em nome de (OBO). Quando o token é usado dessa forma, ele é chamado de "token de inicialização" porque é usado apenas para obter um token de acesso que pode ser usado para chamar o Microsoft Graph.