Compartilhar via

Autorizar o Microsoft Graph com SSO

Os utilizadores iniciam sessão no Office através da respetiva conta Microsoft pessoal ou da respetiva conta Microsoft 365 Educação ou profissional. 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 do suplemento contém um <elemento WebApplicationInfo> que fornece informações importantes de registo de aplicações do Azure ao Office, incluindo as permissões para o Microsoft Graph necessárias para o suplemento.

Como ele funciona em tempo de execução

O diagrama seguinte mostra os passos envolvidos para iniciar sessão e aceder ao Microsoft Graph. Todo o processo utiliza tokens de acesso OAuth 2.0 e JWT.

Diagrama a mostrar o processo de SSO.

  1. O código do lado do cliente do suplemento chama a API de Office.js getAccessToken. Isto indica ao anfitrião do Office para obter um token de acesso para o suplemento.

    Se o utilizador não tiver sessão iniciada, o anfitrião do Office em conjunto com a plataforma de identidades da Microsoft fornece IU para o utilizador iniciar sessão e consentir.

  2. O anfitrião do Office pede um token de acesso a partir da plataforma de identidades da Microsoft.

  3. A plataforma de identidades da Microsoft devolve o token de acesso A ao anfitrião do Office. O token de acesso A só fornece acesso às APIs do lado do servidor do suplemento. Não fornece acesso ao Microsoft Graph.

  4. O anfitrião do Office devolve 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 um pedido 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 utiliza o fluxo OAuth 2.0 On-Behalf-Of (OBO) para pedir um novo token de acesso com permissões para o Microsoft Graph.

  7. A plataforma de identidades da Microsoft devolve o novo token de acesso B com permissões para o Microsoft Graph (e um token de atualização, se os pedidos de suplemento offline_access permissão). Opcionalmente, o servidor pode colocar em cache o token de acesso B.

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

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

  10. O código do lado do servidor devolve os dados ao código do lado do cliente.

Nos pedidos subsequentes, o código de cliente passará sempre 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 colocar em cache o token B para que não precise de o pedir novamente em futuras chamadas à API.

Desenvolver um suplemento SSO que acessa o Microsoft Graph

Desenvolve um suplemento que acede ao Microsoft Graph tal como faria com qualquer outra aplicação que utilize SSO. Para obter uma descrição detalhada, consulte Ativar o início de sessão ú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 for transmitido 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 identidades da Microsoft que inclui o token de acesso, alguns metadados sobre o utilizador e as credenciais do suplemento (o respetivo ID e segredo). Para obter mais informações sobre o fluxo OBO, consulte Plataforma de identidades da Microsoft e fluxo OAuth 2.0 On-Behalf-Of.
  • Opcionalmente, após a conclusão do fluxo, coloque em cache o token de acesso devolvido 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, veja Adquirir e colocar tokens em cache com a Biblioteca de Autenticação da Microsoft (MSAL)
  • Crie um ou mais métodos de API Web que obtêm dados do Microsoft Graph ao transmitir o token de acesso (possivelmente em cache) B para o Microsoft Graph.

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

Distribuir suplementos com SSO ativado no Microsoft AppSource

Quando um administrador do Microsoft 365 adquire um suplemento a partir do AppSource, o administrador pode redistribuí-lo através de Aplicações Integradas e conceder consentimento do administrador ao suplemento para aceder aos âmbitos do Microsoft Graph. No entanto, também é possível que o utilizador final adquira o suplemento diretamente no AppSource, caso em que o utilizador tem de dar consentimento ao suplemento. Isto pode criar um potencial problema de desempenho para o qual fornecemos uma solução.

Se o seu código passar a opção allowConsentPrompt na chamada de getAccessToken, como OfficeRuntime.auth.getAccessToken( { allowConsentPrompt: true } );, o Office pode pedir consentimento ao utilizador se a plataforma de identidades da Microsoft indicar ao Office que o consentimento ainda não foi concedido ao suplemento. No entanto, por motivos de segurança, o Office só pode pedir ao utilizador para dar consentimento ao âmbito do Microsoft Graph profile . O Office não pode pedir consentimento para outros âmbitos do Microsoft Graph, nem mesmo User.Read. Isto significa que, se o utilizador conceder consentimento no pedido, o Office devolve um token de acesso. No entanto, a tentativa de trocar o token de acesso por um novo token de acesso com âmbitos adicionais do Microsoft Graph falha com o erro AADSTS65001, o que significa que o consentimento (para âmbitos do Microsoft Graph) não foi concedido.

Observação

O pedido de consentimento com { allowConsentPrompt: true } ainda pode falhar mesmo para o profile âmbito se o administrador tiver desativado o consentimento do utilizador final. Para obter mais informações, veja Configurar a forma como os utilizadores finais consentem aplicações com o Azure Active Directory.

O código pode, e deve, lidar com este erro ao reverter para um sistema alternativo de autenticação, o que pede ao utilizador o consentimento para os âmbitos do Microsoft Graph. Para obter exemplos de código, consulte Criar um Node.js Suplemento do Office que utiliza o início de sessão único e Criar um ASP.NET Suplemento do Office que utiliza o início de sessão único e os exemplos aos quais se ligam. Todo o processo requer várias viagens de ida e volta para a plataforma de identidades da Microsoft. Para evitar esta penalização de desempenho, inclua a opção forMSGraphAccess na chamada de getAccessToken; por exemplo, OfficeRuntime.auth.getAccessToken( { forMSGraphAccess: true } ). Isto indica ao Office que o seu suplemento precisa de âmbitos do Microsoft Graph. O Office irá pedir à plataforma de identidades da Microsoft para verificar se o consentimento para os âmbitos do Microsoft Graph já foi concedido ao suplemento. Se tiver, é devolvido o token de acesso. Se não tiver sido, a chamada de getAccessToken devolve o erro 13012. O código pode lidar com este erro ao reverter para um sistema alternativo de autenticação imediatamente, sem fazer uma tentativa condenada de trocar tokens com a plataforma de identidades da Microsoft.

Como melhor prática, transmita forMSGraphAccess sempre quando getAccessToken o seu suplemento será distribuído no AppSource e precisa de âmbitos do Microsoft Graph.

Detalhes sobre o SSO com um suplemento do Outlook

Se desenvolver um suplemento do Outlook que utiliza o SSO e o colocar em sideload para testes, o Office devolverá sempre o erro 13012 quando forMSGraphAccess for transmitido, getAccessToken mesmo que tenha sido concedido o consentimento do administrador. Por este motivo, deve comentar a opção forMSGraphAccessao desenvolver um suplemento do Outlook. Certifique-se de que anule o comentário da opção quando implementar para produção. O falso 13012 só acontece quando está a fazer sideload no Outlook.

Para suplementos do Outlook, certifique-se de que ativa a Autenticação Moderna para o inquilino do Microsoft 365. Para obter informações sobre como fazê-lo, consulte Ativar ou desativar a autenticação moderna para o Outlook no Exchange Online.

O Google Chrome está a trabalhar para dar aos utilizadores mais controlo sobre a sua experiência de navegação. Os utilizadores poderão bloquear cookies de terceiros no browser Chrome. Isto impedirá que o seu suplemento utilize esses cookies. Isto pode causar problemas quando o suplemento autentica o utilizador, como vários pedidos de início de sessão ou erros.

Para obter experiências de autenticação melhoradas, veja Utilizar o estado do dispositivo para uma experiência de SSO melhorada em browsers com cookies de terceiros bloqueados.

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

Confira também