Autenticação de aplicativo aninhado

O NAA é um novo protocolo de autenticação para SPAs inseridos em ambientes de host, como Teams, Outlook e Microsoft 365. Ele simplifica o processo de autenticação para facilitar o logon único (SSO) em aplicativos aninhados em aplicativos host compatíveis. O modelo NAA dá suporte a uma identidade primária para o aplicativo host que inclui várias identidades de aplicativo para aplicativos aninhados. A Microsoft utiliza esse modelo em guias do Teams, aplicativos pessoais e suplementos do Office.

O modelo NAA oferece várias vantagens sobre o fluxo On-Behalf-Of (OBO):

• O NAA exige que você use apenas a biblioteca MSAL.js. Você não precisa usar a getAuthToken função na biblioteca de cliente JavaScript do Teams (TeamsJS).

• Você pode chamar serviços como o Microsoft Graph com um token de acesso do código do cliente como um SPA. Não há necessidade de um servidor de camada intermediária.

• Você pode usar o consentimento incremental e dinâmico para escopos (permissões).

• Você não precisa pré-autorizar seus hosts, como Teams ou Microsoft 365, para chamar seus pontos de extremidade.

  A tabela a seguir descreve a diferença entre o SSO e o NAA do Microsoft Entra do Teams:

  Etapas necessárias para o desenvolvimento	O Teams Tradicional Entra no SSO	NAA
  Expor URI de redirecionamento	Obrigatório	Obrigatório
  Registrar API no Microsoft Entra ID	Obrigatório
  Definir um escopo personalizado no Microsoft Entra ID	Obrigatório
  Autorizar aplicativos cliente do Teams	Obrigatório
  Revisar manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo do Teams)	Obrigatório	Recomendado*
  Adquirir token de acesso por meio do SDK do TeamsJS	Obrigatório
  Solicitar o consentimento do usuário para obter mais permissões	Obrigatório
  Realizar uma troca OBO no servidor	Obrigatório

• O administrador de TI pode bloquear o aplicativo ou consentir apenas determinadas permissões para o aplicativo no Microsoft Entra ID. Para evitá-lo, você deve incluir a ID do aplicativo e o recurso padrão no manifesto do aplicativo para que o administrador aprove as permissões no Centro de administração do Teams.

Casos de uso para NAA

Configurar NAA

Para configurar a autenticação aninhada, siga estas etapas:

1. Registre seu SPA
2. Adicionar agentes confiáveis
3. Inicializar aplicativo cliente público
4. Adquira seu primeiro token
5. Chamar uma API

Registre seu SPA

Você deve criar um registro de aplicativo do Microsoft Entra ID para seu suplemento no portal do Azure. O registro do aplicativo deve ter um nome, tipo de conta com suporte e redirecionamento de SPA. Após o registro do seu aplicativo, o portal do Azure gera uma ID de registro do aplicativo Microsoft Entra. Se o suplemento exigir registro de aplicativo adicional além do NAA e do SSO, consulte registrar seu aplicativo de página única.

Adicionar agentes confiáveis

Para configurar a autenticação de aplicativo aninhado, seu aplicativo deve configurar ativamente um URI de redirecionamento para seu aplicativo. O URI de redirecionamento indica para a plataforma de identidade da Microsoft que seu aplicativo pode ser intermediado por hosts com suporte. O URI de redirecionamento do aplicativo deve ser do tipo Aplicativo de página única e estar em conformidade com o esquema a seguir:

brk-multihub://<your_domain>

Onde

• brk-multihub permite que sua autenticação seja intermediada por qualquer host compatível com o Microsoft 365 configurado para execução, como Teams, Outlook ou Microsoft365.com.
• < > your_domain é o nome de domínio totalmente qualificado onde seu aplicativo está hospedado. Por exemplo, brk-multihub://contoso.com.

Seu domínio deve incluir apenas a origem e não seus subcaminhos. Por exemplo:

✔️ brk-multihub://myapp.teams.microsoft.com
❌ brk-multihub://myapp.teams.microsoft.com/go

Para obter mais informações sobre como atualizar seu aplicativo do Teams para ser executado no Outlook e no Microsoft365.com, consulte estender aplicativos do Teams no Microsoft 365.

Inicializar aplicativo cliente público

Inicialize a MSAL e obtenha uma instância do aplicativo cliente público para obter tokens de acesso, quando necessário.

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

const msalConfig = {
  auth: {
    clientId: "your_client_id",
    authority: "https://login.microsoftonline.com/{your_tenant_id}",
    supportsNestedAppAuth: true
  },
};

let pca: IPublicClientApplication;

export function initializePublicClient() {
  console.log("Starting initializePublicClient");
  return createNestablePublicClientApplication(msalConfig).then(
    (result) => {
      console.log("Client app created");
      pca = result;
      return pca;
    }
  );
}

Adquira seu primeiro token

Os tokens adquiridos pelo MSAL.js por meio da autenticação de aplicativo aninhado são emitidos para sua ID de registro do aplicativo Microsoft Entra. MSAL.js lida com a aquisição de token para autenticação de usuário. Ele tenta obter um token de acesso silenciosamente. Se isso não for bem-sucedido, ele solicitará o consentimento do usuário. O token é então usado para chamar a API do Graph Microsoft ou outros recursos protegidos pelo Microsoft Entra ID. Ao contrário do fluxo OBO, você não precisa pré-autorizar seus hosts a chamar os pontos de extremidade.

Para adquirir um token, siga estas etapas:

1. Use MSAL.js para adquirir tokens para sua ID do aplicativo. Para obter mais informações, consulte adquirir e usar um token de acesso.

2. Use getActiveAccount a API para verificar se há uma conta ativa para chamar o publicClientApplication. Se não houver nenhuma conta ativa, tente recuperar uma do cache com getAccount, usando parâmetros de filtro adicionais, como tenantID, homeAccountIde loginHint da interface de contexto.

   Observação

   A homeAccountId propriedade é equivalente a userObjectId em TeamsJS.

3. Chamada publicClientApplication.acquireTokenSilent(accessTokenRequest) para adquirir o token silenciosamente sem interação do usuário. accessTokenRequest Especifica os escopos para os quais o token de acesso é solicitado. A NAA dá suporte ao consentimento incremental e dinâmico. Certifique-se de sempre solicitar os escopos mínimos necessários para que seu código conclua sua tarefa.

4. Se nenhuma conta disponível, MSAL.js retornará um InteractionRequiredAuthError. Chame publicClientApplication.acquireTokenPopup(accessTokenRequest) para exibir uma caixa de diálogo interativa para o usuário. acquireTokenSilent poderá falhar se o token expirar ou se o usuário não consentir com todos os escopos solicitados.

   O trecho de código a seguir mostra um exemplo para acessar um token:

   
     // MSAL.js exposes several account APIs, logic to determine which account to use is the responsibility of the developer
     const account = publicClientApplication.getActiveAccount();
   
     const accessTokenRequest = {
     scopes: ["user.read"],
     account: account,
     };
   
     publicClientApplication
       .acquireTokenSilent(accessTokenRequest)
       .then(function (accessTokenResponse) {
         // Acquire token silent success
         let accessToken = accessTokenResponse.accessToken;
         // Call your API with token
         callApi(accessToken);
       })
       .catch(function (error) {
         //Acquire token silent failure, and send an interactive request
         if (error instanceof InteractionRequiredAuthError) {
           publicClientApplication
             .acquireTokenPopup(accessTokenRequest)
             .then(function (accessTokenResponse) {
               // Acquire token interactive success
               let accessToken = accessTokenResponse.accessToken;
               // Call your API with token
               callApi(accessToken);
             })
             .catch(function (error) {
               // Acquire token interactive failure
               console.log(error);
             });
         }
         console.log(error);
       });
   
   

Chamar uma API

Depois de receber o token, use-o para chamar a API. Isso garante que a API seja chamada com um token válido para fazer solicitações autenticadas ao servidor.

O exemplo a seguir mostra como fazer uma solicitação autenticada à API do Graph para acessar dados do Microsoft 365:

var headers = new Headers();
var bearer = "Bearer " + access_token;
headers.append("Authorization", bearer);
var options = {
    method: "GET",
    headers: headers
};

var graphEndpoint = "<https://graph.microsoft.com/v1.0/me>";

fetch(graphEndpoint, options)
    .then(function (response) {
        //do something with response
    });

Pré-busca de token para autenticação de aplicativo aninhado (NAA)

Para melhorar o desempenho e reduzir a latência de autenticação, a autenticação de aplicativo aninhado (NAA) dá suporte à pré-busca de token. Esse recurso permite que o host adquira tokens de autenticação proativamente antes da inicialização do aplicativo, permitindo acesso mais rápido a recursos protegidos.

Como habilitar a pré-busca de token

Para habilitar a pré-busca de token, atualize o manifesto do aplicativo do Teams para a versão 1.22 ou posterior e inclua a nestedAppAuthInfo seção dentro webApplicationInfo.

{
 "webApplicationInfo": {
   "id": "33333ddd-0000-0000-0000-88888757bbbb",
   "resource": "api://app.com/botid-33333ddd-0000-0000-0000-88888757bbbb",
   "nestedAppAuthInfo": [
     {
       "redirectUri": "brk-multihub://app.com",
       "scopes": ["openid", "profile", "offline_access"],
       "claims": "{\"access_token\":{\"xms_cc\":{\"values\":[\"CP1\"]}}}"
     }
   ]
 }
}

Como funciona

Quando a pré-busca de token está habilitada, o ambiente do host tenta adquirir e armazenar em cache os tokens necessários antes que o aplicativo seja renderizado. Esses tokens são armazenados na memória e disponibilizados para o aplicativo imediatamente após a inicialização.

Esse comportamento é semelhante ao recurso de pré-busca no modelo de SSO herdado do Teams, em que a API era disparada automaticamente durante o carregamento da getAuthToken tabulação. Com a Autenticação de Aplicativos Aninhados (NAA), essa funcionalidade é introduzida por meio da configuração de manifesto, melhorando o desempenho sem exigir uma troca de token de back-end.

Benefícios da pré-busca de token no NAA

• Melhore o desempenho reduzindo os atrasos de autenticação durante a inicialização do aplicativo
• Habilitar logon único (SSO) em aplicativos aninhados sem entradas repetidas

Práticas recomendadas

• Use autenticação silenciosa sempre que possível: MSAL.js fornece o método, que lida com a acquireTokenSilent renovação de token fazendo solicitações silenciosas de token sem solicitar ao usuário. Primeiro, o método procura um token válido em cache no armazenamento do navegador. Se não encontrar uma, a biblioteca faz uma solicitação silenciosa ao Microsoft Entra ID e, se houver uma sessão de usuário ativa (determinada por um cookie definido no navegador no domínio do Microsoft Entra), o Microsoft Entra ID retornará um novo token. A biblioteca não invoca automaticamente o acquireTokenSilent método. Recomendamos que você chame acquireTokenSilent seu aplicativo antes de fazer uma chamada à API para obter um token válido.

  Em determinados casos, a tentativa de obter o token usando o acquireTokenSilent método falha. Por exemplo, quando há uma sessão de usuário expirada com o Microsoft Entra ID ou uma alteração de senha pelo usuário do aplicativo, acquireTokenSilent falha. Chame o método de token de aquisição interativo (acquireTokenPopup).

• Tenha um fallback: os fluxos NAA oferecem compatibilidade em todo o ecossistema da Microsoft. No entanto, seu aplicativo pode aparecer em clientes de nível inferior ou herdados que não são atualizados para dar suporte à NAA. Nesses casos, seu aplicativo não pode dar suporte ao SSO contínuo e talvez seja necessário invocar APIs especiais para interagir com o usuário para abrir caixas de diálogo de autenticação. Para obter mais informações, consulte Habilitar o SSO para o aplicativo de guia.

  Observação

  Você não deve usar o NAA se estiver usando um provedor de identidade que não seja do Microsoft Entra. Em vez disso, você pode usar a autenticação pop-up.

• Suporte para NAA: o NAA pode não ter suporte em todos os ambientes de aplicativo host. Para verificar se o cliente atual dá suporte a esse recurso, você pode invocar a API especificada para determinar seu status. Um valor retornado de true indica suporte para NAA, embora false sugira que não há suporte.

• Teste seu aplicativo em vários ambientes: se seu aplicativo deve funcionar em implantações de modo de exibição da Web e navegador, recomendamos testar seu aplicativo em ambos os ambientes de implantação para garantir que ele se comporte conforme o esperado. Determinadas APIs que funcionam no navegador podem não operar em exibições da Web.

Exemplo de código

Confira também

• Plataforma de identidade da Microsoft e Fluxo On-Behalf-Of do OAuth 2.0
• Armazenamento em cache no MSAL
• Apresentando a Autenticação de Aplicativos Aninhados: um protocolo de autenticação aprimorado para seu aplicativo do Teams