Autorizar o Microsoft Graph com SSO

  • Artigo

Os usuários entrarão no Office usando sua conta pessoal da Microsoft ou sua conta de trabalho ou Microsoft 365 Education. A melhor maneira de um Suplemento do Office receber acesso autorizado ao Microsoft Graph é usar as credenciais de logon do Office do usuário. Isso permite a eles acessar seus dados do Microsoft Graph sem precisar entrar novamente.

Arquitetura de suplemento para SSO e Microsoft Graph

Além de hospedar as páginas e o JavaScript do aplicativo web, o suplemento também deve hospedar, ao mesmo tempo o nome de domínio totalmente qualificado, uma ou mais APIs web que obterá um token de acesso ao Microsoft Graph e fará solicitações a ele.

O manifesto de suplemento contém um <elemento WebApplicationInfo> que fornece informações importantes de registro de aplicativo do Azure para o Office, incluindo as permissões para o Microsoft Graph necessárias para o suplemento.

Como ele funciona em tempo de execução

O diagrama a seguir mostra as etapas envolvidas para entrar e acessar o Microsoft Graph. Todo o processo usa tokens de acesso OAuth 2.0 e JWT.

Diagrama mostrando o processo SSO.

  1. O código do lado do cliente do suplemento chama o getAccessToken Office.js API. Isso informa ao host do Office para obter um token de acesso para o suplemento.

    Se o usuário não estiver conectado, o host do Office em conjunto com o plataforma de identidade da Microsoft fornecerá interface do usuário para que o usuário entre e consenta.

  2. O host do Office solicita um token de acesso do plataforma de identidade da Microsoft.

  3. O plataforma de identidade da Microsoft retorna o token de acesso A para o host do Office. Token de acesso Um só fornece acesso às APIs do próprio servidor do suplemento. Ele não fornece acesso ao Microsoft Graph.

  4. O host do Office retorna o token de acesso A ao código do lado do cliente do suplemento. Agora, o código do lado do cliente pode fazer chamadas autenticadas para as APIs do lado do servidor.

  5. O código do lado do cliente faz uma solicitação HTTP para uma API Web no lado do servidor que requer autenticação. Ele inclui o token de acesso A como prova de autorização. O código do lado do servidor valida o token de acesso A.

  6. O código do lado do servidor usa o OBO (fluxo on-behalf-of) do OAuth 2.0 para solicitar um novo token de acesso com permissões para o Microsoft Graph.

  7. O plataforma de identidade da Microsoft retorna o novo token de acesso B com permissões para o Microsoft Graph (e um token de atualização, se o suplemento solicitar offline_access permissão). Opcionalmente, o servidor pode armazenar em cache o token B de acesso.

  8. O código do lado do servidor faz uma solicitação a um microsoft API do Graph e inclui o token de acesso B com permissões para o Microsoft Graph.

  9. O Microsoft Graph retorna dados ao código do lado do servidor.

  10. O código do lado do servidor retorna os dados para o código do lado do cliente.

Em solicitações subsequentes, o código do cliente sempre passará o token de acesso A ao fazer chamadas autenticadas para o código do lado do servidor. O código do lado do servidor pode armazenar em cache o token B para que ele não precise solicitá-lo novamente em chamadas futuras de API.

Desenvolver um suplemento SSO que acessa o Microsoft Graph

Você desenvolve um suplemento que acessa o Microsoft Graph da mesma forma que qualquer outro aplicativo que usa o SSO. Para obter uma descrição completa, consulte Habilitar logon único para suplementos do Office. A diferença é que é obrigatório que o suplemento tenha uma API Web do lado do servidor.

Dependendo do seu idioma e da estrutura, podem estar disponíveis bibliotecas que simplificarão o código do lado do servidor que você precisa escrever. O código deve fazer o seguinte:

  • Valide o token de acesso A sempre que ele é passado do código do lado do cliente. Para saber mais, confira Validar o token de acesso.
  • Inicie o OBO (fluxo em nome do OBO) do OAuth 2.0 com uma chamada para o plataforma de identidade da Microsoft que inclui o token de acesso, alguns metadados sobre o usuário e as credenciais do suplemento (sua ID e segredo). Para obter mais informações sobre o fluxo OBO, consulte fluxo plataforma de identidade da Microsoft e OAuth 2.0 Em nome do fluxo.
  • Opcionalmente, depois que o fluxo for concluído, armazene o token B de acesso retornado com permissões para o Microsoft Graph. Faça isso se o suplemento fizer mais de uma chamada para o Microsoft Graph. Para obter mais informações, confira Adquirir e cache tokens usando a MSAL (Biblioteca de Autenticação da Microsoft)
  • Crie um ou mais métodos de API Web que obtenham dados do Microsoft Graph passando o token B de acesso (possivelmente armazenado em cache) para o Microsoft Graph.

Para obter exemplos detalhados passo a passo de cenários, confira:

Distribuição de suplementos habilitados para SSO no Microsoft AppSource

Quando um administrador do Microsoft 365 adquire um suplemento do AppSource, o administrador pode redistribuí-lo por meio de Aplicativos Integrados e conceder consentimento de administrador ao suplemento para acessar escopos do Microsoft Graph. No entanto, também é possível que o usuário final adquira o suplemento diretamente do AppSource, nesse caso, o usuário deve conceder consentimento ao suplemento. Isso pode criar um problema de desempenho potencial para o qual fornecemos uma solução.

Se o código passar a opção allowConsentPrompt na chamada de getAccessToken, como OfficeRuntime.auth.getAccessToken( { allowConsentPrompt: true } );, o Office poderá solicitar consentimento ao usuário se o plataforma de identidade da Microsoft relatar ao Office que o consentimento ainda não foi concedido ao suplemento. No entanto, por motivos de segurança, o Office só pode solicitar que o usuário consenta com o escopo do Microsoft Graph profile . O Office não pode solicitar consentimento para outros escopos do Microsoft Graph, nem mesmo User.Read. Isso significa que, se o usuário conceder consentimento no prompt, o Office retornará um token de acesso. Mas a tentativa de trocar o token de acesso por um novo token de acesso com escopos adicionais do Microsoft Graph falha com AADSTS65001 de erro, o que significa que o consentimento (para escopos do Microsoft Graph) não foi concedido.

Observação

A solicitação de consentimento com { allowConsentPrompt: true } ainda pode falhar mesmo para o profile escopo se o administrador tiver desativado o consentimento do usuário final. Para obter mais informações, consulte Configurar como os usuários finais consentem com aplicativos usando o Azure Active Directory.

Seu código pode e deve lidar com esse erro recuando para um sistema alternativo de autenticação, o que solicita o consentimento do usuário para os escopos do Microsoft Graph. Para obter exemplos de código, consulte Criar uma Node.js Suplemento do Office que usa logon único e Criar um suplemento do Office ASP.NET que usa logon único e os exemplos aos quais eles vinculam. Todo o processo requer várias viagens de ida e volta para o plataforma de identidade da Microsoft. Para evitar essa penalidade de desempenho, inclua a opção forMSGraphAccess na chamada de getAccessToken; por exemplo, OfficeRuntime.auth.getAccessToken( { forMSGraphAccess: true } ). Isso sinaliza ao Office que seu suplemento precisa de escopos do Microsoft Graph. O Office pedirá ao plataforma de identidade da Microsoft para verificar se o consentimento para escopos do Microsoft Graph já foi concedido ao suplemento. Se tiver, o token de acesso será retornado. Se não tiver, a chamada de getAccessToken retorna o erro 13012. Seu código pode lidar com esse erro recuando para um sistema alternativo de autenticação imediatamente, sem fazer uma tentativa condenada de trocar tokens com o plataforma de identidade da Microsoft.

Como prática recomendada, sempre passe forMSGraphAccess para getAccessToken quando seu suplemento será distribuído no AppSource e precisa de escopos do Microsoft Graph.

Detalhes sobre o SSO com um suplemento do Outlook

Se você desenvolver um suplemento do Outlook que usa o SSO e o carregar de lado para testes, o Office sempre retornará o erro 13012 quando forMSGraphAccess for passado para getAccessToken mesmo se o consentimento do administrador tiver sido concedido. Por esse motivo, você deve comentar a opção forMSGraphAccessao desenvolver um suplemento do Outlook. Certifique-se de descompactar a opção ao implantar para produção. O falso 13012 só acontece quando você está carregando sideload no Outlook.

Para suplementos do Outlook, habilite a Autenticação Moderna para a locação do Microsoft 365. Para obter informações sobre como fazer isso, consulte Habilitar ou desabilitar a autenticação moderna para o Outlook em Exchange Online.

O Google Chrome está eliminando cookies de terceiros em 2024 e introduzindo um recurso chamado Prevenção de Rastreamento. Se a Prevenção de Rastreamento estiver habilitada no navegador Chrome, seu suplemento não poderá usar cookies de terceiros. Seu suplemento pode encontrar problemas ao autenticar o usuário, como várias solicitações de logon ou erros.

Para obter experiências de autenticação aprimoradas, consulte Usar o estado do dispositivo para obter uma experiência de SSO aprimorada em navegadores com cookies de terceiros bloqueados.

Para obter mais informações sobre a distribuição do Google Chrome, confira os seguintes recursos:

Confira também