Compartilhar via

Autenticação de aplicações aninhadas

  • Artigo

Observação

O NAA é um novo protocolo de autenticação para SPAs incorporados em ambientes anfitriões, como o Teams, o Outlook e o Microsoft 365. Simplifica o processo de autenticação para facilitar o início de sessão único (SSO) entre aplicações aninhadas em aplicações anfitriãs suportadas. O modelo NAA suporta uma identidade primária para a aplicação anfitriã que inclui várias identidades de aplicações para aplicações aninhadas. A Microsoft utiliza este modelo em separadores do Teams, aplicações pessoais e Suplementos do Office.

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

  • O NAA requer que utilize apenas a biblioteca de MSAL.js. Não precisa de utilizar a getAuthToken função na biblioteca de cliente JavaScript do Teams (TeamsJS).
  • 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 (permissões).
  • Não precisa de pré-autenticar os anfitriões, como o Teams ou o Microsoft 365, para chamar os seus pontos finais.

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

Passos necessários para o desenvolvimento Teams Entra SSO Tradicional NAA
Expor o URI de redirecionamento Obrigatório Obrigatório
Registar a API no Microsoft Entra ID Obrigatório
Definir um âmbito personalizado no Microsoft Entra ID Obrigatório
Autorizar aplicações cliente do Teams Obrigatório
Rever manifesto da aplicação (anteriormente denominado manifesto de aplicação do Teams) Obrigatório Recomendado*
Adquirir token de acesso através do SDK do TeamsJS Obrigatório
Pedir o consentimento do utilizador para obter mais permissões Obrigatório
Realizar uma troca de OBO no servidor Obrigatório
  • O administrador de TI pode bloquear a aplicação ou consentir apenas determinadas permissões para a aplicação no Microsoft Entra ID. Para o evitar, tem de incluir o ID da aplicação e o recurso predefinido no manifesto da aplicação para que o administrador aprove as permissões no centro de administração do Teams.

Casos de utilização para NAA

Cenário Descrição
Consentir o SSO (e outras permissões) Tom, um novo membro da equipa de design da Contoso, precisa de utilizar a aplicação Contoso em reuniões do Teams para colaborar em quadros. Após a primeira utilização, uma caixa de diálogo pede ao Tom para conceder permissões, incluindo ler o respetivo perfil para o seu avatar (User.Read). Depois de dar consentimento, o Tom pode utilizar a Contoso de forma totalmente integrada em reuniões futuras em todos os dispositivos.
Autenticação ou Autenticação de Acesso Condicional Tom, ao trabalhar a partir da Austrália, encontra um acionador de acesso condicional que requer autenticação multifator (MFA) para aceder à Contoso no Teams. Uma caixa de diálogo informa o Tom de que é necessária mais verificação, o que os leva ao longo do processo de MFA para continuar a utilizar a Contoso.
Erros O Tom enfrenta um erro de início de sessão com a Contoso devido a um problema ao obter informações da conta. O Tom encontra um botão de repetição que pede a reautenticação. No entanto, descobrem que o administrador de sistema tem acesso restrito à Contoso.

Configurar NAA

Observação

  • Uma vez que a NAA está em pré-visualização do programador e não é suportada por todos os ambientes de anfitrião, certifique-se de que marcar o suporte status com a função isNAAChannelRecommended() e fornece uma experiência de contingência para ambientes não suportados.
  • Se a API devolver o valor como true, chame a Biblioteca de Autenticação da Microsoft (MSAL) para o fluxo de NAA. Se devolver false, continue a utilizar o método de obtenção de tokens existente.

Para configurar a autenticação aninhada, siga estes passos:

  1. Registar o SPA
  2. Adicionar mediadores fidedignos
  3. Inicializar a aplicação cliente pública
  4. Adquirir o seu primeiro token
  5. Chamar uma API

Registar o SPA

Tem de criar um registo de aplicação Microsoft Entra ID para o seu suplemento no portal do Azure. O registo da aplicação tem de ter um nome, um tipo de conta suportado e um redirecionamento de SPA. Após o registo da sua aplicação, portal do Azure gera um ID de registo de aplicações Microsoft Entra. Se o suplemento necessitar de um registo de aplicações adicional para além de NAA e SSO, veja Registar a aplicação de página única..

Adicionar mediadores fidedignos

Para configurar a autenticação de aplicações aninhadas, a aplicação tem de configurar ativamente um URI de redirecionamento para a sua aplicação. O URI de redirecionamento indica ao plataforma de identidade da Microsoft que a sua aplicação pode ser mediada 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_domain>

Onde

  • brk-multihub permite que a sua autenticação seja mediada por quaisquer anfitriões suportados pelo Microsoft 365 que esteja configurado para serem executados em, por exemplo, Teams, Outlook ou Microsoft365.com.
  • < > your_domain é o nome de domínio completamente qualificado onde a sua aplicação está alojada. Por exemplo, brk-multihub://contoso.com.

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

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

Para obter mais informações sobre como atualizar a sua aplicação Teams para ser executada no Outlook e Microsoft365.com, consulte Expandir aplicações do Teams no Microsoft 365.

Inicializar a aplicação cliente pública

Observação

Para garantir uma autenticação bem-sucedida, inicialize o TeamsJS antes de inicializar a MSAL.

Inicialize a MSAL e obtenha uma instância da aplicação cliente pública 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;
    }
  );
}

Adquirir o seu primeiro token

Os tokens adquiridos pelo MSAL.js através da autenticação de aplicações aninhadas são emitidos para o seu ID de registo de aplicações Microsoft Entra. MSAL.js processa a aquisição de tokens para autenticação de utilizador. Tenta obter um token de acesso silenciosamente. Se não for bem-sucedido, pede consentimento ao utilizador. Em seguida, o token é utilizado para chamar o microsoft API do Graph ou outros recursos protegidos Microsoft Entra ID. Ao contrário do fluxo OBO, não precisa de pré-autenticar os anfitriões para chamar os pontos finais.

Para adquirir um token, siga estes passos:

  1. Utilize MSAL.js para adquirir tokens para o ID da aplicação. Para obter mais informações, veja Adquirir e utilizar um token de acesso.

  2. Utilize getActiveAccount a API para verificar se existe uma conta ativa para chamar o publicClientApplication. Se não existir uma conta ativa, tente obter uma da cache com getAccount, utilizando parâmetros de filtro adicionais, como tenantID, homeAccountIde loginHint a partir da interface de contexto.

    Observação

    A homeAccountId propriedade é equivalente a userObjectId no TeamsJS.

  3. Chame publicClientApplication.acquireTokenSilent(accessTokenRequest) para adquirir o token silenciosamente sem interação do utilizador. accessTokenRequest especifica os âmbitos para os quais o token de acesso é pedido. O NAA suporta o consentimento incremental e dinâmico. Certifique-se de que pede sempre os âmbitos mínimos necessários para que o código conclua a tarefa.

  4. Se não estiver disponível nenhuma conta, MSAL.js devolve um InteractionRequiredAuthError. Chamada publicClientApplication.acquireTokenPopup(accessTokenRequest) para apresentar uma caixa de diálogo interativa para o utilizador. acquireTokenSilent pode falhar se o token tiver expirado ou se o utilizador não tiver consentido todos os âmbitos pedidos.

O fragmento de código seguinte mostra um exemplo para aceder a 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, utilize-o para chamar a API. Isto garante que a API é chamada com um token válido para fazer pedidos autenticados ao servidor.

O exemplo seguinte mostra como fazer um pedido autenticado ao Microsoft API do Graph para aceder aos 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áticas recomendadas

  • Utilize 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 no armazenamento do browser. Se não encontrar um, a biblioteca efetua um pedido silencioso para Microsoft Entra ID e, se existir uma sessão de utilizador ativa (determinada por um conjunto de cookies no browser no domínio Microsoft Entra), Microsoft Entra ID devolve um novo token. A biblioteca não invoca automaticamente o acquireTokenSilent método . Recomendamos que chame acquireTokenSilent na sua aplicação antes de efetuar uma chamada à API para obter um token válido.

    Em determinados casos, a tentativa de obter o token com o acquireTokenSilent método falha. Por exemplo, quando existe uma sessão de utilizador expirada com Microsoft Entra ID ou uma alteração de palavra-passe por parte do utilizador da aplicação, acquireTokenSilent falha. Chame o método de token de aquisição interativo (acquireTokenPopup).

  • Ter uma contingência: os fluxos de NAA oferecem compatibilidade em todo o ecossistema da Microsoft. No entanto, a sua aplicação pode aparecer em clientes de nível inferior ou legados que não são atualizados para suportar o NAA. Nesses casos, a sua aplicação não consegue suportar o SSO totalmente integrado e poderá ter de invocar APIs especiais para interagir com o utilizador para abrir caixas de diálogo de autenticação. Para obter mais informações, veja Ativar o SSO para a aplicação de separador.

    Observação

    Se estiver a utilizar um fornecedor de identidade não Microsoft Entra, não pode utilizar a autenticação pop-up.

  • Suporte para NAA: o NAA pode não ser suportado em todos os ambientes de aplicações anfitriãs. Para verificar se o cliente atual suporta esta funcionalidade, pode invocar a API especificada para determinar o respetivo status. Um valor devolvido de true indica suporte para NAA, ao passo false que sugere que não é suportado.

  • Testar a aplicação em vários ambientes: se se espera que a aplicação funcione tanto na vista Web como nas implementações do browser, recomendamos que teste a sua aplicação em ambos os ambientes de implementação para garantir que se comporta como esperado. Determinadas APIs que funcionam no browser podem não funcionar em vistas Web.

Exemplo de código

Nome do exemplo Descrição .NET Node.js
Autenticação de aplicações aninhadas Este exemplo mostra como criar um protocolo NAA para SPA incorporado em ambientes anfitriões, como o Teams, o Outlook e o Microsoft 365. View Exibir

Confira também