Ativar o início de sessão único num Suplemento do Office com autenticação de aplicações aninhadas

Utilize a biblioteca de MSAL.js com a autenticação de aplicações aninhadas (NAA) para ativar o início de sessão único (SSO) a partir do seu Suplemento do Office. Os procedimentos neste artigo orientam-no ao longo da criação de um registo de aplicações e da adição de código ao seu projeto para utilizar o NAA.

Contas e anfitriões suportados pelo NAA

O NAA suporta contas Microsoft e identidades de Microsoft Entra ID (escolares/profissionais). Não suporta Azure Active Directory B2C para cenários de gestão de identidades empresa-consumidor. Para obter mais informações sobre os requisitos de NAA, veja Conjunto de requisitos de autenticação de aplicações aninhadas.

Registar a sua aplicação de página única

Terá de criar um registo do Microsoft Azure App para o seu suplemento no portal do Azure. O registo da aplicação tem de ter, no mínimo:

• Um nome
• Um tipo de conta suportado
• Redirecionamento de SPA para NAA

Se o suplemento necessitar de um registo de aplicações adicional para além de NAA e SSO, veja Aplicação de página única: Registo de aplicações.

Adicionar um mediador fidedigno através do redirecionamento de SPA

Para ativar o NAA, o registo da aplicação tem de incluir um URI de redirecionamento específico para indicar ao plataforma de identidade da Microsoft que o suplemento se permite ser mediado por anfitriões suportados. O URI de redirecionamento da aplicação tem de ser do tipo Aplicação de Página Única e estar em conformidade com o seguinte esquema.

brk-multihub://your-add-in-domain

O seu domínio tem de incluir apenas a origem e não os respetivos subcaminhos. Por exemplo:

✔️ brk-multihub://localhost:3000
✔️ brk-multihub://www.contoso.com
❌ brk-multihub://www.contoso.com/go

Os grupos de mediadores fidedignos são dinâmicos por predefinição e podem ser atualizados no futuro para incluir anfitriões adicionais onde o suplemento pode utilizar fluxos NAA. Atualmente, o grupo brk-multihub inclui Word, Excel, PowerPoint, Outlook e Teams (para quando o Office está ativado no interior).

Importante

Para Word, Excel e PowerPoint na Web, também precisa de um redirecionamento adicional, uma vez que o browser utiliza um fluxo de autenticação padrão. O URI de redirecionamento de SPA tem de referenciar a página HTML onde irá utilizar a biblioteca de MSAL.js para pedir tokens através de NAA.

Utilize os seguintes passos para configurar um registo de aplicações para o seu Suplemento do Office.

1. Inicie sessão no portal do Azure com as credenciais de administrador para o seu inquilino do Microsoft 365. Por exemplo, MyName@contoso.onmicrosoft.com.

2. Selecione Registros de aplicativos. Se não vir o ícone, procure "registo de aplicações" na barra de pesquisa.

   

   A página Registros de aplicativo é exibida.

3. Selecione Novo registro.

   

   A página Registrar um aplicativo é exibida.

4. Na página Registrar um aplicativo, defina os valores da seguinte forma.

   • Defina Nome para contoso-office-add-in-sso.
   • Defina Tipos de conta suportados como Contas em qualquer diretório organizacional (qualquer diretório Azure AD - multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox).
   • Defina o URI de Redirecionamento para utilizar a aplicação de página única (SPA) da plataforma e o URI como brk-multihub://localhost:3000. Este redirecionamento pressupõe que está a testar o suplemento a partir de um servidor localhost.

   

5. Selecione Registrar. É apresentada uma mensagem a indicar que o registo da aplicação foi criado.

   

6. Copie e guarde o valor do ID da Aplicação (cliente). Você a usará em um procedimento posterior.

   

Se o suplemento suportar Word, Excel ou PowerPoint na Web, tem de adicionar um URI de redirecionamento de SPA para a página do painel de tarefas. Utilize os seguintes passos para adicionar um URI de redirecionamento de SPA para a página do painel de tarefas.

1. No painel esquerdo, selecione Gerir > Autenticação.
2. Na secção Configurações da plataforma , existe uma lista de URIs de Redirecionamento de aplicação de página única.
3. Selecione Adicionar URI.
4. Introduza https://localhost:3000/taskpane.html e selecione Guardar. Este URI de redirecionamento pressupõe que está a utilizar NAA a taskpane.html partir do ficheiro.

Configurar a configuração MSAL para utilizar o NAA

Configure o suplemento para utilizar NAA ao chamar a createNestablePublicClientApplication função no MSAL. A MSAL devolve uma aplicação cliente pública que pode ser aninhada num anfitrião de aplicações nativo (por exemplo, o Outlook) para adquirir tokens para a sua aplicação.

Os passos seguintes mostram como ativar o taskpane.js NAA no ficheiro ou taskpane.ts num projeto criado com yo office (projeto do Painel de Tarefas do Suplemento do Office ).

1. Adicione o @azure/msal-browser pacote à dependencies secção do ficheiro do package.json projeto. Para obter mais informações sobre este pacote, veja Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) para aplicações Browser-Based Single-Page. Para instalar a versão mais recente, execute o seguinte comando.

   npm install @azure/msal-browser
   

2. Adicione o seguinte código à parte superior do taskpane.js ficheiro ou taskpane.ts . Esta ação irá importar a biblioteca do browser MSAL.

   import { createNestablePublicClientApplication, InteractionRequiredAuthError } from "@azure/msal-browser";
   

Os passos seguintes são diferentes para o Outlook do que para Word, Excel e PowerPoint. Selecione o separador que corresponde ao tipo de suplemento que está a criar.

Suplementos do Outlook

Inicializar a biblioteca MSAL

Em seguida, tem de inicializar o MSAL e obter uma instância da aplicação cliente pública.

Adicione o seguinte código ao taskpane.js ficheiro ou taskpane.ts . Substitua o marcador Enter_the_Application_Id_Here de posição pelo ID da aplicação Azure que guardou anteriormente. Acerca da seguinte nota de código:

• A initMsal função inicializa a MSAL ao chamar createNestablePublicClientApplication. Esta ação cria uma aplicação cliente pública anómulvel que suporta o SSO com o Outlok.
• A initMsal função define a autoridade como comum, que suporta contas escolares e profissionais ou contas Microsoft pessoais. Se quiser configurar um único inquilino ou outros tipos de conta, veja Opções de configuração da aplicação para opções de autoridade adicionais.

let msalInstance = undefined;

/**
 * Initialize MSAL as a nestable public client application.
  */
async function initMsal() {
  if (!msalInstance) {
    const clientId = "Enter_the_Application_Id_Here";
    const msalConfig = {
      auth: {
        clientId: clientId,
        authority: "https://login.microsoftonline.com/common"
      },
      cache: {
        cacheLocation: "localStorage"
      }
    };
    msalInstance = await createNestablePublicClientApplication(msalConfig);
  }
}

Adquirir o seu primeiro token

Os tokens adquiridos pelo MSAL.js através de NAA serão emitidos para o seu ID de registo de aplicações Azure. Neste exemplo de código, vai adquirir um token para o Microsoft API do Graph. Se o utilizador tiver uma sessão ativa com Microsoft Entra ID o token é adquirido automaticamente. Caso contrário, a biblioteca pede ao utilizador para iniciar sessão interativamente. Em seguida, o token é utilizado para chamar o microsoft API do Graph.

Os passos seguintes mostram o padrão a utilizar para adquirir um token.

1. Especifique os âmbitos. O NAA suporta o consentimento incremental e dinâmico, pelo que solicite sempre os âmbitos mínimos necessários para que o código conclua a tarefa.
2. Chamar acquireTokenSilent. Esta ação irá obter o token sem exigir a interação do utilizador.
3. Se acquireTokenSilent falhar, chame acquireTokenPopup para apresentar uma caixa de diálogo interativa para o utilizador. acquireTokenSilent pode falhar se o token tiver expirado ou se o utilizador ainda não tiver consentido todos os âmbitos pedidos.

O código seguinte mostra como implementar este padrão de autenticação no seu próprio projeto.

1. Substitua a run função em taskpane.js ou taskpane.ts pelo seguinte código. O código especifica os âmbitos mínimos necessários para ler os ficheiros do utilizador.

   export async function run() {
     await initMsal();
     // Specify minimum scopes needed for the access token.
     const tokenRequest = {
       scopes: ["Files.Read", "User.Read"],
     };
     let accessToken = null;
   
     // TODO 1: Use msalInstance to get an access token.
   
     // TODO 2: Call the Microsoft Graph API.
   }
   

   Importante

   O pedido de token tem de incluir âmbitos que não apenas offline_access, openid, profileou email. Pode utilizar qualquer combinação dos âmbitos anteriores, mas tem de incluir, pelo menos, um âmbito adicional. Caso contrário, o pedido de token pode falhar.

2. Substitua TODO 1 pelo código a seguir. Este código chama acquireTokenSilent para obter o token de acesso.

   try {
     const userAccount = await msalInstance.acquireTokenSilent(tokenRequest);
     console.log("Acquired token silently.");
     accessToken = userAccount.accessToken;
   } catch (silentError) {
     // TODO 1a: Handle acquireTokenSilent failure.
   
   }
   

3. Substitua TODO 1a pelo código a seguir. Este código verifica se acquireTokenSilent atirou um InteractionRequiredAuthError. Se assim for, o código chama acquireTokenPopup para que a MSAL possa utilizar uma caixa de diálogo de pop-up para interagir com o utilizador. A interação pode ser necessária por vários motivos, como a conclusão da autorização multifator.

   if (silentError instanceof InteractionRequiredAuthError) {
     console.log(`Unable to acquire token silently: ${silentError}`);
     // Silent acquisition failed. Continue to interactive acquisition.
     try {
       const userAccount = await msalInstance.acquireTokenPopup(tokenRequest);
       console.log("Acquired token interactively.");
       accessToken = userAccount.accessToken;
     } catch (popupError) {
       // Acquire token interactive failure.
       console.error(`Unable to acquire token interactively: ${popupError}`);
       return;
     }
   } else {
     // Acquire token silent failure. Error can't be resolved through interaction.
     console.error(`Unable to acquire token silently: ${silentError}`);
     return;
   }
   

Chamar uma API

Depois de adquirir o token, utilize-o para chamar uma API. O exemplo seguinte mostra como chamar o microsoft API do Graph ao chamar fetch com o token anexado no cabeçalho Autorização.

• Substitua TODO 2 pelo código a seguir.

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: `Bearer ${accessToken}` },
    }
  );
  
  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);
  
    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");
  
    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
  

Assim que todo o código anterior for adicionado à run função, certifique-se de que um botão no painel de tarefas chama a run função. Em seguida, pode colocar o suplemento em sideload e experimentar o código.

Word, Excel e suplementos do PowerPoint

Inicializar a biblioteca MSAL

Em seguida, tem de inicializar o MSAL e obter uma instância da aplicação cliente pública. Isto é utilizado para obter tokens de acesso quando necessário. Recomendamos que coloque o código que cria a aplicação cliente pública no Office.onReady método .

1. Adicione a seguinte initMsal função ao taskpane.js ficheiro ou taskpane.ts . createNestablePublicClientApplication Chama para inicializar uma instância MSAL para utilizar NAA.
2. Substitua o marcador Enter_the_Application_Id_Here de posição pelo ID da aplicação Azure que guardou anteriormente.

let msalInstance = null; // MSAL instance

/**
 * Initialize MSAL as a nestable public client application.
 */
async function initMsal() {
  if (!msalInstance) {
    const clientId = "Enter_the_Application_Id_Here";
    const msalConfig = {
      auth: {
        clientId: clientId,
        authority: "https://login.microsoftonline.com/common"
      },
      cache: {
        cacheLocation: "localStorage"
      }
    };
    msalInstance = await createNestablePublicClientApplication(msalConfig);
  }
}

Observação

O exemplo de código anterior define a autoridade como comum, que suporta contas escolares e profissionais ou contas Microsoft pessoais. Se quiser configurar um único inquilino ou outros tipos de conta, veja Opções de configuração da aplicação para opções de autoridade adicionais.

Adicionar uma função para obter a sugestão de início de sessão

Ao executar no Word, Excel ou PowerPoint no browser, tem de fornecer uma sugestão de início de sessão à MSAL para identificar a conta correta. Pode obter a sugestão de início de sessão na propriedade do Office authContext.userPrincipalName . Adicione a seguinte função que pode ser chamada em qualquer altura para obter a sugestão de início de sessão.

Adicione a seguinte função ao taskpane.js ficheiro ou taskpane.ts .

/**
 * Get the login hint from Office.AuthContext for a better SSO experience.
 * This is especially important for Office in a browser.
 */
async function getLoginHint() {
    try {
        if (typeof Office !== "undefined" && Office.context) {
            const authContext = await Office.auth.getAuthContext();
            if (authContext?.userPrincipalName) return authContext.userPrincipalName;
        }
    } catch (error) {
        console.warn("Could not get login hint:", error);
    }
    return null;
}

Adquirir o token de acesso

Crie uma função para adquirir o token de acesso.

Adicione a seguinte função ao taskpane.js ficheiro ou taskpane.ts . Acerca da seguinte nota de código:

• Obtém a sugestão de início de sessão que é necessária quando é executada no Word, Excel ou PowerPoint num browser.
• ssoSilent Chama (não acquireTokenSilent) para obter um token de acesso.
• Se ssoSilent falhar, verifica se a interação é necessária. Nesse caso, chama acquireTokenPopup para que a MSAL possa interagir com o utilizador.

/**
 * Acquire an access token silently, or interactively if needed.
 * @param {Array} scopes - The scopes for which the token is requested.
 * @returns {Promise<string>} - The acquired access token.
 */
async function acquireAccessToken(scopes) {
  await initMsal();

  const request = {
    scopes: scopes,
    loginHint: await getLoginHint()
  }

  let authResult = null;
  try {
    authResult = await msalInstance.ssoSilent(request);
  } catch (error) {
    if (error instanceof InteractionRequiredAuthError) {
      authResult = await msalInstance.acquireTokenPopup(request);
    } else {
      console.error("Silent token acquisition failed:", error);
    }
  }
  if (!authResult) {
    throw new Error("Could not acquire access token");
  }
  console.log(authResult);
  return authResult.accessToken;

}

Obter token e chamar o API do Graph

Depois de adquirir o token, utilize-o para chamar uma API. O exemplo seguinte mostra como chamar o microsoft API do Graph ao chamar fetch com o token anexado no cabeçalho Autorização.

Atualize a run função no taskpane.js ficheiro ou taskpane.ts para corresponder ao seguinte código. Acerca da seguinte nota de código:

• Chama a acquireAccessToken função que criou anteriormente e transmite os Files.Read âmbitos e User.Read . O pedido de token tem de incluir âmbitos que não apenas offline_access, openid, profileou email. Pode utilizar qualquer combinação dos âmbitos anteriores, mas tem de incluir, pelo menos, um âmbito adicional. Caso contrário, o pedido de token pode falhar.
• Utiliza o token de acesso para fazer uma chamada ao Microsoft API do Graph para obter 10 dos nomes de ficheiro do utilizador a partir do OneDrive.

export async function run() {
  let accessToken;
  try {
    // Acquire an access token for Microsoft Graph.
    accessToken = await acquireAccessToken(["Files.Read", "User.Read"]);
    console.log("Access token acquired:", accessToken);
  }
  catch (error) {
    console.error("Error acquiring access token:", error);
    return;
  }

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: `Bearer ${accessToken}` },
    }
  );

  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);

    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");

    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
}

Assim que todo o código anterior for adicionado à run função, certifique-se de que um botão no painel de tarefas chama a run função. Em seguida, pode colocar o suplemento em sideload e experimentar o código.

O que é a autenticação de aplicações aninhadas

A autenticação de aplicações aninhadas permite o SSO para aplicações aninhadas dentro de aplicações suportadas da Microsoft. Por exemplo, o Excel no Windows executa o seu suplemento dentro de uma vista Web. Neste cenário, o suplemento é uma aplicação aninhada em execução no Excel, que é o anfitrião. O NAA também suporta aplicações aninhadas no Teams. Por exemplo, se um separador do Teams estiver a alojar o Excel e o seu suplemento for carregado, este será aninhado no Excel, que também está aninhado no Teams. Mais uma vez, o NAA suporta este cenário aninhado e pode aceder ao SSO para obter a identidade do utilizador e os tokens de acesso do utilizador com sessão iniciada.

Práticas recomendadas

Recomendamos as seguintes melhores práticas ao utilizar MSAL.js com NAA.

Utilizar a autenticação silenciosa sempre que possível

MSAL.js fornece o acquireTokenSilent método que processa a renovação de tokens ao fazer pedidos de token silenciosos sem pedir ao utilizador. O método procura primeiro um token em cache válido. Se não encontrar uma, a biblioteca efetua o pedido silencioso para Microsoft Entra ID e, se existir uma sessão de utilizador ativa, é devolvido um novo token.

Em determinados casos, a acquireTokenSilent tentativa do método de obter o token falha. Alguns exemplos disto são quando existe uma sessão de utilizador expirada com Microsoft Entra ID ou uma alteração de palavra-passe por parte do utilizador, o que requer a interação do utilizador. Quando o acquireTokenSilent falhar, terá de chamar o método de token interativo acquireTokenPopup .

Ter uma contingência quando o NAA não é suportado

Embora nos esforcemos por fornecer um elevado grau de compatibilidade com estes fluxos em todo o ecossistema da Microsoft, o seu suplemento pode ser carregado num anfitrião do Office mais antigo que não suporta NAA. Nestes casos, o seu suplemento não suportará o SSO totalmente integrado e poderá ter de reverter para um método alternativo de autenticação do utilizador. Veja os exemplos de código neste artigo para obter exemplos que mostram como lidar com um cenário de contingência.

Utilize o seguinte código para marcar se o NAA for suportado quando o suplemento for carregado.

   Office.context.requirements.isSetSupported("NestedAppAuth", "1.1");

Para obter mais informações, veja os seguintes recursos.

• Autenticar e autorizar com a API de caixa de diálogo do Office.
• Exemplo de identidade da Microsoft para SPA e JavaScript
• Exemplos de identidade da Microsoft para vários tipos e arquiteturas de aplicações

MSAL.js APIs suportadas pelo NAA

A tabela seguinte mostra que APIs são suportadas quando o NAA está ativado na configuração MSAL.

Método	Suportado pelo NAA
acquireTokenByCode	Não (gera exceção)
acquireTokenPopup	Sim
acquireTokenRedirect	Não (gera exceção)
acquireTokenSilent	Sim
addEventCallback	Sim
addPerformanceCallback	Não (gera exceção)
disableAccountStorageEvents	Não (gera exceção)
enableAccountStorageEvents	Não (gera exceção)
getAccountByHomeId	Sim
getAccountByLocalId	Sim
getAccountByUsername	Sim
getActiveAccount	Sim
getAllAccounts	Sim
getConfiguration	Sim
getLogger	Sim
getTokenCache	Não (gera exceção)
handleRedirectPromise	Não
initialize	Sim
initializeWrapperLibrary	Sim
loginPopup	Sim
loginRedirect	Não (gera exceção)
logout	Não (gera exceção)
logoutPopup	Não (gera exceção)
logoutRedirect	Não (gera exceção)
removeEventCallback	Sim
removePerformanceCallback	Não (gera exceção)
setActiveAccount	Não
setLogger	Sim
ssoSilent	Sim

Relatórios de segurança

Se encontrar um problema de segurança com as nossas bibliotecas ou serviços, comunique o problema secure@microsoft.com com o máximo de detalhes que puder fornecer. A sua submissão pode ser elegível para uma recompensa através do programa Microsoft Bounty . Não publique problemas de segurança no GitHub ou em qualquer outro site público. Iremos contactá-lo pouco depois de receber o relatório de problemas. Recomendamos que receba novas notificações de incidentes de segurança ao visitar notificações de segurança técnica da Microsoft para subscrever Alertas de Aviso de Segurança.

Exemplos de código

Nome do exemplo	Descrição
Suplemento do Office com SSO através da autenticação de aplicações aninhadas	Mostra como utilizar o NAA num Suplemento do Office para aceder às APIs do Microsoft Graph para o utilizador com sessão iniciada.
Suplemento do Outlook com SSO através da autenticação de aplicações aninhadas	Mostra como utilizar o NAA num Suplemento do Outlook para aceder às APIs do Microsoft Graph para o utilizador com sessão iniciada.
Implementar o SSO em eventos num suplemento do Outlook com a autenticação de aplicações aninhadas	Mostra como utilizar o NAA e o SSO em eventos de suplementos do Outlook.
Enviar afirmações de identidade para recursos com autenticação de aplicações aninhadas (NAA) e SSO	Mostra como enviar as afirmações de identidade do utilizador com sessão iniciada (como o nome, o e-mail ou um ID exclusivo) para um recurso, como uma base de dados. Este exemplo substitui um padrão obsoleto para tokens de Exchange Online legados.

Confira também

• NAA FAQ
• Autenticação de aplicações aninhadas no Microsoft Teams.
• Exemplo do Outlook: Como reverter e suportar a Internet Explorer 11
• Autenticar e autorizar com a API de caixa de diálogo do Office.
• Exemplo de identidade da Microsoft para SPA e JavaScript
• Exemplos de identidade da Microsoft para vários tipos e arquiteturas de aplicações