Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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.
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.
O anfitrião do Office pede um token de acesso a partir da plataforma de identidades da Microsoft.
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.
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.
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.
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.
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.
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.
O Microsoft Graph devolve os dados ao código do lado do servidor.
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:
- Criar um Suplemento do Office com Node.js que usa logon único
- Criar um Suplemento do Office com ASP.NET que usa logon único
- Cenário: implementar o logon único no serviço em um suplemento do Outlook
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 forMSGraphAccess
ao 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.
Suporte para cookies de terceiros do Google Chrome
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.