Autorizar para o Microsoft Graph com SSO herdado do Office

Os usuários entram no Office usando sua conta pessoal da Microsoft ou sua conta do Microsoft 365 Education ou corporativa. 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 herdado do Office 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 do suplemento contém marcação que fornece informações importantes de registro de aplicativo do Azure para o Office.

• Manifesto somente do suplemento: as <WebApplicationInfo> informações estão no elemento e incluem as permissões para o Microsoft Graph que o suplemento exige.
• Manifesto unificado para o Microsoft 365: as "webApplicationInfo" informações estão na propriedade. O valor dessa propriedade não inclui as permissões. Quando o manifesto unificado é usado, o Office obtém as informações necessárias sobre permissões do registro do aplicativo Web no Microsoft Entra.

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.

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

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

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

3. A plataforma de identidade da Microsoft retorna o token de acesso A para o host do Office. O token de acesso A fornece acesso apenas às próprias APIs do lado do 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. 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 fluxo OAuth 2.0 On-Behalf-Of (OBO) 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 de acesso B.

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

9. O Microsoft Graph retorna dados de volta para o código do lado do servidor.

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

Nas 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 futuras chamadas à API.

Desenvolver um suplemento de SSO herdado do Office que acesse o Microsoft Graph

Você desenvolve um suplemento que acessa o Microsoft Graph da mesma forma que faria com qualquer outro aplicativo que usa 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 for passado do código do lado do cliente. Para saber mais, confira Validar o token de acesso.
• Inicie o fluxo OAuth 2.0 On-Behalf-Of (OBO) com uma chamada para a 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 plataforma de identidade da Microsoft e fluxo OAuth 2.0 em nome de.
• Opcionalmente, após a conclusão do fluxo, armazene em cache o token de acesso retornado B 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, consulte Adquirir e armazenar tokens em cache 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 de acesso B (possivelmente armazenado em cache) para o Microsoft Graph.

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

• Criar um Suplemento do Office com Node.js que usa logon único
• Criar um Suplemento do Office com ASP.NET que usa logon único

Distribuição de suplementos herdados habilitados para SSO do Office no Microsoft Marketplace

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

Se o código passar a opção na chamada de getAccessToken, como OfficeRuntime.auth.getAccessToken( { allowConsentPrompt: true } );, o Office poderá solicitar o allowConsentPrompt consentimento do usuário se a plataforma de identidade da Microsoft informar 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 dê seu consentimento ao 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 o erro AADSTS65001, o que significa que o consentimento (para os escopos do Microsoft Graph) não foi concedido.

Seu código pode lidar com esse erro retornando a um sistema alternativo de autenticação que solicita que o usuário conceda consentimento para os escopos do Microsoft Graph. Para obter exemplos, consulte Criar um suplemento do Office do Node.js que usa logon único e Criar um suplemento do Office do ASP.NET que usa logon único e os exemplos aos quais eles vinculam. Esse fluxo pode envolver várias viagens de ida e volta para a plataforma de identidade da Microsoft. Para reduzir o impacto no desempenho, inclua a forMSGraphAccess opção ao chamar getAccessToken; por exemplo, OfficeRuntime.auth.getAccessToken( { forMSGraphAccess: true } ). Essa opção indica que o suplemento requer escopos do Microsoft Graph. O Office solicitará à plataforma de identidade da Microsoft para determinar se o consentimento já foi concedido. Se houver consentimento, o token de acesso será retornado. Caso contrário, getAccessToken retorna o erro 13012. Seu código pode lidar com esse erro retornando a um sistema alternativo de autenticação imediatamente, sem tentar trocar tokens com a plataforma de identidade da Microsoft.

Como prática recomendada, sempre informe forMSGraphAccess quando getAccessToken o suplemento será distribuído no Microsoft Marketplace e precisará de escopos do Microsoft Graph.

Detalhes sobre o SSO herdado do Office com um suplemento do Outlook

Se você desenvolver um suplemento do Outlook que usa SSO e carregá-lo para teste, o Office sempre retornará o erro 13012 quando forMSGraphAccess for passado para getAccessToken , mesmo que o consentimento do administrador tenha sido concedido. Por esse motivo, você deve comentar a forMSGraphAccess opção ao desenvolver um suplemento do Outlook. Certifique-se de remover o comentário da opção ao implantar para produção. O falso 13012 só acontece quando você está fazendo sideload no Outlook.

Para suplementos do Outlook, certifique-se de habilitar 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 Outlook no Exchange Online.

Suporte a cookies de terceiros do Google Chrome

O Google Chrome está trabalhando para dar aos usuários mais controle sobre sua experiência de navegação. Os usuários poderão bloquear cookies de terceiros no navegador Chrome. Isso impedirá que o suplemento use qualquer um desses cookies. Isso pode causar problemas quando o suplemento autentica 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 uma experiência de SSO aprimorada em navegadores com cookies de terceiros bloqueados.

Para obter mais informações sobre a versão do Google Chrome, consulte Um novo caminho para o Privacy Sandbox na Web.

Confira também

• Troca de token OAuth2
• Plataforma de identidade da Microsoft e Fluxo On-Behalf-Of do OAuth 2.0
• Conjuntos de requisitos da IdentityAPI