Ativar o SSO num Suplemento do Office com a autenticação de aplicações aninhadas (pré-visualização)

Pode utilizar a biblioteca MSAL.js com a autenticação de aplicações aninhadas para utilizar o SSO a partir do seu Suplemento do Office. A utilização da autenticação de aplicações aninhadas oferece várias vantagens sobre o fluxo On-Behalf-Of (OBO).

• Só tem de utilizar a biblioteca de MSAL.js e não precisa da getAccessToken função no Office.js.
• Pode chamar serviços como o Microsoft Graph com um token de acesso do seu código de cliente como SPA. Não é necessário um servidor de camada média.
• Pode utilizar o consentimento incremental e dinâmico para âmbitos.
• Não precisa de pré-autenticar os anfitriões (por exemplo, Teams, Office) para chamar os seus pontos finais.

Contas e anfitriões suportados pelo NAA

O NAA suporta contas Microsoft e identidades de Microsoft Entra ID (escolares/profissionais). Não suporta o Azure Active Directory B2C para cenários de gestão de identidades empresa-consumidor. A tabela seguinte explica o suporte atual por plataforma. Tudo o que estiver listado como "Brevemente" será suportado quando a NAA for disponibilizada em geral.

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

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

Por exemplo, se estivesse a testar o suplemento na porta 3000 no servidor localhost, utilizaria brk-multihub://localhost:3000 como o valor de redirecionamento.

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 o Office Word, Excel, PowerPoint, Outlook e Teams (para quando o Office está ativado no interior).

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. Recomendamos que utilize a versão mais recente do pacote (no momento da última atualização do artigo era a 3.26.0).

   "dependencies": {
       "@azure/msal-browser": "^3.26.0",
       ...
   

2. Guarde e execute npm install para instalar @azure/msal-browsero .

3. 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 } from "@azure/msal-browser";
   

Inicializar a aplicação cliente pública

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 .

• Na sua Office.onReady função, adicione uma chamada para createNestablePublicClientApplication , conforme mostrado abaixo. Substitua o Enter_the_Application_Id_Here marcador de posição pelo ID da aplicação do Azure que guardou anteriormente.

  let pca = undefined;
  Office.onReady(async (info) => {
    if (info.host) {
      document.getElementById("sideload-msg").style.display = "none";
      document.getElementById("app-body").style.display = "flex";
      document.getElementById("run").onclick = run;
  
      // Initialize the public client application
      pca = await createNestablePublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
          authority: "https://login.microsoftonline.com/common"
        },
      });
    }
  });
  

Adquirir o seu primeiro token

Os tokens adquiridos pelo MSAL.js através de NAA serão emitidos para o ID de registo de aplicações do 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.

   async function run() {
   // Specify minimum scopes needed for the access token.
   const tokenRequest = {
     scopes: ["Files.Read", "User.Read", "openid", "profile"],
   };
   let accessToken = null;
   
   // TODO 1: Call acquireTokenSilent.
   
   // TODO 2: Call acquireTokenPopup.
   
   // TODO 3: Log error if token still null.
   
   // TODO 4: Call the Microsoft Graph API.
   
   }
   

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

   try {
     console.log("Trying to acquire token silently...");
     const userAccount = await pca.acquireTokenSilent(tokenRequest);
     console.log("Acquired token silently.");
     accessToken = userAccount.accessToken;
   } catch (error) {
     console.log(`Unable to acquire token silently: ${error}`);
   }
   

3. Substitua TODO 2 pelo código a seguir. Este código verifica se o token de acesso foi adquirido. Caso contrário, tenta obter interativamente o token de acesso ao chamar acquireTokenPopup.

   if (accessToken === null) {
     // Acquire token silent failure. Send an interactive request via popup.
     try {
       console.log("Trying to acquire token interactively...");
       const userAccount = await pca.acquireTokenPopup(tokenRequest);
       console.log("Acquired token interactively.");
       accessToken = userAccount.accessToken;
     } catch (popupError) {
       // Acquire token interactive failure.
       console.log(`Unable to acquire token interactively: ${popupError}`);
     }
   }
   

4. Substitua TODO 3 pelo código a seguir. Se o início de sessão silencioso e interativo falhar, registe o erro e volte.

   // Log error if both silent and popup requests failed.
   if (accessToken === null) {
     console.error(`Unable to acquire access token.`);
     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 4 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: 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. Em geral, vai querer utilizar o padrão de autenticação MSAL SPA com a API de caixa de diálogo do Office JS.

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.

• 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

MSAL.js APIs suportadas pelo NAA

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

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

Confira também

• NAA FAQ