Habilitar o login único (SSO) em um Suplemento do Office
Os utilizadores iniciam sessão no Office através da respetiva conta Microsoft pessoal ou da respetiva conta Microsoft 365 Educação ou profissional. Aproveite isso e use o SSO (login único) para autenticar e autorizar o usuário ao seu suplemento sem exigir que ele entre uma segunda vez.
Como o SSO funciona em tempo de execução
O diagrama a seguir mostra como funciona o processo de SSO. Os elementos azuis representam o Office ou a plataforma de identidade da Microsoft. Os elementos cinza representam o código que você escreve e incluem o código ao lado do cliente (painel de tarefas) e o código ao lado do servidor no seu suplemento.
- No suplemento, seu código JavaScript chama a API do Office.js getAccessToken. Se o usuário já estiver conectado ao Office, o host do Office retornará o token de acesso com as declarações do usuário conectado.
- Se o usuário não estiver conectado, o aplicativo host do Office abrirá uma caixa de diálogo para o usuário entrar. O Office redireciona para a plataforma de identidade da Microsoft para concluir o processo de entrada.
- Se essa for a primeira vez que o usuário atual usar o seu suplemento, será solicitado que ele consinta.
- O aplicativo host do Office solicita o token de acesso da plataforma de identidade da Microsoft para o usuário atual.
- O plataforma de identidade da Microsoft retorna o token de acesso ao Office. O Office armazenará o token no seu nome para que futuras chamadas do getAccessToken retornem ao token armazenado em cache.
- O aplicativo host do Office retorna o token de acesso ao suplemento como parte do objeto de resultado retornado pela
getAccessTokenchamada. - O token é um token de acesso e um token de identidade. Você pode usá-lo como um token de identidade para analisar e examinar as declarações sobre o usuário, como o nome e o endereço de e-mail do usuário.
- Opcionalmente, o suplemento pode usar o token como um token de acesso para fazer solicitações HTTPS autenticadas nas APIs ao lado do servidor. Como o token de acesso contém declarações de identidade, o servidor pode armazenar informações associadas à identidade do usuário; como as preferências do usuário.
Requisitos e as práticas recomendadas
Não armazenar o token de acesso em cache
Nunca armazene em cache ou armazene o token de acesso no código ao lado do cliente. Sempre chame o getAccessToken quando precisar de um token de acesso. O Office armazenará em cache o token de acesso (ou solicitará um novo se ele tiver expirado). Isso ajudará a evitar o vazamento acidental do token do seu suplemento.
Habilitar a autenticação moderna do Outlook
Se estiver a trabalhar com um suplemento 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.
Implementar um sistema de autenticação de fallback
Você não deve confiar no SSO como único método do suplemento de autenticação. Devem implementar um sistema de autenticação alternativo que o suplemento possa se enquadrar em determinadas situações de erro. Por exemplo, se o seu suplemento for carregado em uma versão mais antiga do Office que não oferece suporte ao SSO, a getAccessToken chamada falhará.
Quanto aos suplementos do Excel, Word e PowerPoint, normalmente você vai querer voltar a usar a plataforma de identidade da Microsoft. Para obter mais informações, consulte Autenticar com a plataforma de identidade da Microsoft.
Quanto aos suplementos do Outlook, há um sistema de fallback recomendado. Para mais informações, confira Cenário: implementar o logon único no serviço em um Suplemento do Outlook.
Você também pode usar um sistema de tabelas e autenticação de usuário, ou pode aproveitar um dos provedores de login social. Para mais informações sobre como fazer isso com um Suplemento do Office, consulte Autorizar serviços externos no Suplemento do Office.
Para obter exemplos de código que usam a plataforma de identidade da Microsoft como o sistema de fallback, consulte Suplemento do Office NodeJS SSO e o suplemento do Office ASP.NET SSO.
Desenvolver um suplemento com SSO
Esta seção descreve as tarefas envolvidas na criação de um suplemento do Office que usa SSO. Essas tarefas são descritas aqui independentemente do idioma ou da estrutura. Para obter instruções passo a passo, consulte:
- Criar um Suplemento do Office com Node.js que usa logon único
- Criar um Suplemento do Office com ASP.NET que usa logon único
Registre seu suplemento com o plataforma de identidade da Microsoft
Para trabalhar com o SSO, você precisa registrar seu complemento com a plataforma de identidade da Microsoft. Isso permitirá que a plataforma de identidade da Microsoft forneça serviços de autenticação e autorização ao seu suplemento. A criação do registro do aplicativo inclui as seguintes tarefas.
- Obter uma ID de aplicativo (cliente) para identificar seu suplemento na plataforma de identidade da Microsoft.
- Gere um segredo do cliente para atuar como uma senha para o seu suplemento ao solicitar um token.
- Especifique as permissões que seu suplemento exige. As permissões do Microsoft Graph "perfil" e "openid" são sempre necessárias. É possível que você precise de permissões adicionais, dependendo do que seu suplemento precisa fazer.
- Conceda a confiança dos aplicativos do Office ao suplemento.
- Autorize previamente os aplicativos do Office ao suplemento com o escopo padrão access_as_user.
Para obter mais detalhes sobre esse processo, consulte Registrar um Suplemento do Office que usa o SSO com a plataforma de identidade da Microsoft.
Configurar o suplemento
O seu manifesto tem de fornecer ao Office determinadas informações sobre como o suplemento está registado no ID do Microsoft Entra. A configuração depende do tipo de manifesto que o suplemento utiliza.
Deve existir uma propriedade "webApplicationInfo" na raiz do manifesto. Tem uma propriedade "id" subordinada necessária que tem de ser definida para o ID da aplicação (um GUID) do suplemento na plataforma de identidades da Microsoft. Para o SSO, também tem de ter uma propriedade "recurso" subordinada definida como o URI do suplemento. Este é o mesmo URI do ID da Aplicação (incluindo o api: protocolo) que definiu quando registou o suplemento na plataforma de identidades da Microsoft. O URI tem de terminar com o ID de cliente especificado na propriedade "webApplicationInfo.id". O que se segue é um exemplo:
"webApplicationInfo": {
"id": "a661fed9-f33d-4e95-b6cf-624a34a2f51d",
"resource": "api://addin.contoso.com/a661fed9-f33d-4e95-b6cf-624a34a2f51d"
},
Observação
Os programadores de suplementos experientes devem ter em atenção que não existe nenhuma propriedade de manifesto unificada correspondente ao <elemento Âmbitos> no manifesto apenas do suplemento. O Microsoft Graph e outras permissões de API são pedidos no runtime no seu código.
Inclua o conjunto de requisitos da API de identidade
Para usar o SSO, seu complemento precisa do conjunto de requisitos da API de Identidade 1.3. Para obter mais informações, consulte IdentityAPI.
Adicionar código do lado do cliente
Adicione o JavaScript ao suplemento para:
- Chamar getAccessToken.
- Analisar o token de acesso ou encaminhá-lo ao código de servidor do suplemento.
O código a seguir mostra um exemplo simples de chamar getAccessToken e analisar o token no nome de usuário e outras credenciais.
Observação
Este exemplo lida explicitamente com apenas um tipo de erro. Para exemplos de tratamento de erro mais elaborados, confira SSO com Suplemento NodeJS do Office e SSO com Suplemento ASP.NET do Office.
async function getUserData() {
try {
let userTokenEncoded = await OfficeRuntime.auth.getAccessToken();
let userToken = jwt_decode(userTokenEncoded); // Using the https://www.npmjs.com/package/jwt-decode library.
console.log(userToken.name); // user name
console.log(userToken.preferred_username); // email
console.log(userToken.oid); // user id
}
catch (exception) {
if (exception.code === 13003) {
// SSO is not supported for domain user accounts, only
// Microsoft 365 Education or work account, or a Microsoft account.
} else {
// Handle error
}
}
}
Quando chamar getAccessToken
Se o seu suplemento exigir um usuário conectado, você deverá ligar para getAccessToken do Office.initialize. Você também deve passar allowSignInPrompt: true no options parâmetro de getAccessToken. Por exemplo, OfficeRuntime.auth.getAccessToken( { allowSignInPrompt: true }); isso garantirá que, se o usuário ainda não estiver conectado, o Office solicitará que o usuário entre na interface do usuário agora.
Se o suplemento tiver algumas funcionalidades que não requerem um utilizador com sessão iniciada, pode ligar getAccessTokenquando o utilizador efetuar uma ação que exija um utilizador com sessão iniciada. Não há degradação significativa de desempenho com as chamadas redundantes do getAccessToken porque o Office armazena em cache o token de acesso e o reusará até expirar, sem fazer outra chamada à plataforma de identidade da Microsoftsempre que getAccessToken for chamado. Portanto, você pode adicionar chamadas de getAccessToken para todas as funções e manipuladores que iniciam uma ação onde o token é necessário.
Importante
Como prática de segurança, sempre chame getAccessToken quando precisar de um token de acesso. O Office armazenará em cache para você. Não armazene ou armazene o token de acesso usando seu próprio código.
Passe o token de acesso para o código ao lado do servidor
Se você precisar acessar as APIs da Web no seu servidor ou serviços adicionais, como o Microsoft Graph, você precisará passar o token de acesso no seu código ao lado do servidor. O token de acesso fornece acesso (para o usuário autenticado) às suas APIs da Web. Além disso, o código ao lado do servidor pode analisar o token para obter informações de identidade, se precisar dele. (Consulte Usar o token de acesso como um token de identidade abaixo.) Há muitas bibliotecas disponíveis para diferentes idiomas e plataformas que podem ajudar a simplificar o código que você escreve. Para obter mais informações, consulte Visão geral da biblioteca de autenticação da Microsoft (MSAL).
Se você precisar acessar os dados do Microsoft Graph, seu código ao lado do servidor deve fazer o seguinte:
- Validar o token de acesso (consulte validar o token de acesso abaixo).
- Inicie o fluxo OAuth 2.0 On-Behalf-Of com uma chamada para a plataforma de identidade da Microsoft que inclui o token de acesso, alguns metadados do usuário e as credenciais do suplemento (sua ID e segredo). A plataforma de identidade da Microsoft retornará um novo token de acesso que pode ser usado para acessar o Microsoft Graph.
- Obter os dados do Microsoft Graph usando o novo token.
- Se você precisar armazenar em cache o novo token de acesso para várias chamadas, recomendamos usar a Serialização do cache de token em MSAL.NET.
Importante
Como prática de segurança, sempre use o código ao lado do servidor para fazer chamadas pelo Microsoft Graph ou outras chamadas que exigem a passagem de um token de acesso. Nunca retorne o token OBO ao cliente para permitir que o cliente faça chamadas diretas ao Microsoft Graph. Isso ajuda a proteger o token de ser interceptado ou vazado. Para obter mais informações sobre o fluxo de protocolo adequado, consulte o Diagrama de protocolo OAuth 2.0
O código a seguir mostra um exemplo de passagem do token de acesso para o lado do servidor. O token é passado em um Authorization cabeçalho ao enviar uma solicitação para uma API da Web do lado do servidor. Este exemplo envia dados JSON, portanto, ele usa o POSTmétodo, mas GETé suficiente para enviar o token de acesso quando você não estiver escrevendo no servidor.
$.ajax({
type: "POST",
url: "/api/DoSomething",
headers: {
"Authorization": "Bearer " + accessToken
},
data: { /* some JSON payload */ },
contentType: "application/json; charset=utf-8"
}).done(function (data) {
// Handle success
}).fail(function (error) {
// Handle error
}).always(function () {
// Cleanup
});
Para saber mais sobre como obter acesso autorizado aos dados do usuário Microsoft Graph, confira Autorizar o Microsoft Graph nos suplementos do Office.
Validar o token de acesso
As APIs da Web no seu servidor devem validar o token de acesso se ele for enviado do cliente. O token é um Token Web JSON (JWT) e isso significa que validação funciona como uma validação de token na maioria dos fluxos padrão do OAuth. Há diversas bibliotecas disponíveis que podem lidar com a validação de JWT. No entanto, as noções básicas incluem:
- Verificar se o token foi bem formado
- Verificar se o token foi emitido pela autoridade desejada
- Verificar se o token está direcionado para a API Web
Tenha em mente as diretrizes a seguir ao validar o token.
- Os tokens SSO válidos serão emitidos pela autoridade do Azure,
https://login.microsoftonline.com. A declaraçãoissno token deve começar com esse valor. - O parâmetro do
audtoken será definido como a ID do aplicativo do registro do aplicativo do Azure do suplemento. - O parâmetro
scpdo token será definido comoaccess_as_user.
Para obter mais informações sobre a validação do token, consulte Tokens de acesso da plataforma de identidade da Microsoft.
User o token de acesso como um token de identidade
Se o suplemento precisar verificar a identidade do usuário, o token de acesso retornado do getAccessToken() contém informações que podem ser usadas para estabelecer a identidade. As seguintes declarações no token estão relacionadas à identidade.
-
name– O nome para exibição do usuário. -
preferred_usernameO endereço de email do usuário. -
oid- Um GUID que representa a ID do usuário no sistema de identidade da Microsoft. -
tid- Um GUID que representa o locatário no qual o usuário está entrando.
Para obter mais detalhes sobre essas e outras declarações, consulte Tokens da ID da plataforma de identidade da Microsoft. Se você precisar construir uma ID exclusiva para representar o usuário no seu sistema, consulte Usar as declarações para identificar um usuário de forma confiável para obter mais informações.
Token de acesso de exemplo
A seguir está uma carga decodificada típica do token de acesso. Para obter informações sobre as propriedades, consulte Tokens de acesso da plataforma de identidade da Microsoft.
{
aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
iat: 1521143967,
nbf: 1521143967,
exp: 1521147867,
aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
azpacr: "0",
e_exp: 262800,
name: "Mila Nikolova",
oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
preferred_username: "milan@contoso.com",
scp: "access_as_user",
sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
uti: "MICAQyhrH02ov54bCtIDAA",
ver: "2.0"
}
Usando o SSO com um suplemento do Outlook
Há algumas diferenças pequenas, mas importantes entre usar o SSO em um suplemento do Outlook e em um suplemento do Excel, PowerPoint ou Word. Não deixe de ler Autenticar o usuário com um token de logon único em um suplemento do Outlook e Cenário: implementar o logon único ao serviço em um suplemento do Outlook.
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.