Compartilhar via

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

  • Artigo

Pode utilizar a biblioteca de MSAL.js com a autenticação de aplicações aninhadas para utilizar o início de sessão único (SSO) a partir do seu Suplemento do Office. A utilização da autenticação de aplicações aninhadas (NAA) 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. As plataformas listadas como disponibilidade geral (GA) estão prontas para utilização de produção no seu suplemento.

Application Web Windows Mac iOS/iPad Android
Excel Na pré-visualização Na pré-visualização Na pré-visualização Em pré-visualização no iPad Não aplicável
Outlook GA Disponibilidade Geral no Canal Atual e Via de Atualizações Mensais, Pré-visualização nos Canais Semi-Annual GA Disponibilidade Geral (iOS) GA
PowerPoint Na pré-visualização Na pré-visualização Na pré-visualização Em pré-visualização no iPad Não aplicável
Word Na pré-visualização Na pré-visualização Na pré-visualização Em pré-visualização no iPad Não aplicável

Importante

Para utilizar o NAA em plataformas que ainda estão em pré-visualização (Word, Excel e PowerPoint), adira ao Programa Insider do Microsoft 365 (https://insider.microsoft365.com/join) e selecione Canal Atual (Pré-visualização). Não utilize NAA em suplementos de produção para plataformas de pré-visualização. Convidamo-lo a experimentar o NAA em ambientes de teste ou de desenvolvimento e a receber feedback sobre a sua experiência através do GitHub (consulte a secção Feedback no final desta página).

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

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 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.27.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"
      },
    });
  }
});

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.

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.

}

    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 {
  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.

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 MSAL.js autenticação de aplicações aninhadas (NAA) num Suplemento do Office para aceder às APIs do Microsoft Graph para o utilizador com sessão iniciada. O exemplo apresenta o nome e o e-mail do utilizador com sessão iniciada. Também insere os nomes dos ficheiros da conta do Microsoft OneDrive do utilizador no documento.
Suplemento do Outlook com SSO através da autenticação de aplicações aninhadas Mostra como utilizar MSAL.js autenticação de aplicações aninhadas (NAA) num Suplemento do Outlook para aceder às APIs do Microsoft Graph para o utilizador com sessão iniciada. O exemplo apresenta o nome e o e-mail do utilizador com sessão iniciada. Também insere os nomes dos ficheiros da conta do Microsoft OneDrive do utilizador num novo corpo de mensagem.

Confira também