Configurar autenticação OAuth IdP de terceiros

  • Artigo

Observação

Para que a autenticação funcione para sua guia em clientes móveis, verifique se você está usando a versão 1.4.1 ou posterior da biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS).

Seu aplicativo do Microsoft Teams pode precisar interagir com vários serviços, como Facebook, Twitter e Teams. A maioria desses serviços requer autenticação e autorização para acesso. O Teams armazena informações de perfil do usuário em Microsoft Entra ID usando o Microsoft Graph. Este artigo se concentra principalmente em usar Microsoft Entra ID para autenticação para acessar essas informações.

O OAuth 2.0, um padrão aberto para autenticação, é utilizado por Microsoft Entra ID e vários outros provedores de serviços. O entendimento do OAuth 2.0 é essencial ao lidar com a autenticação no Teams e Microsoft Entra ID. Os exemplos fornecidos empregam o fluxo de Concessão Implícita do OAuth 2.0, que recupera as informações de perfil do usuário de Microsoft Entra ID e Microsoft Graph.

O código no artigo vem do aplicativo de exemplo do Teams Microsoft Teams Authentication Sample (Node). Ele contém uma guia estática que solicita um token de acesso para o Microsoft Graph e mostra as informações básicas do perfil do usuário atual de Microsoft Entra ID.

Para obter uma visão geral do fluxo de autenticação para guias, consulte Fluxo de autenticação em guias.

O fluxo de autenticação em guias difere do fluxo de autenticação em bots.

Observação

Este tópico reflete a versão 2.0.x da biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Se você estiver usando uma versão anterior, consulte a visão geral da biblioteca do TeamsJS para obter diretrizes sobre as diferenças entre o TeamsJS mais recente e as versões anteriores.

Configurar seu aplicativo para usar Microsoft Entra ID como um provedor de identidade

Os provedores de identidade compatíveis com o OAuth 2.0 não autenticam solicitações de aplicativos não registrados. Portanto, é essencial registrar seus aplicativos com antecedência. Para registrar um aplicativo com Microsoft Entra ID, siga estas etapas:

  1. Abra o Portal de Registro do Aplicativo.

  2. Selecione seu aplicativo para exibir suas propriedades ou selecione o botão "Novo Registro". Localize a seção URI de direcionamento para o aplicativo.

  3. Selecione Web no menu suspenso e atualize a URL para o ponto de extremidade de autenticação. Nos aplicativos de exemplo TypeScript/Node.js e C# disponíveis no GitHub, as URLs de redirecionamento seguem um padrão semelhante:

    URLs de redirecionamento: https://<hostname>/bot-auth/simple-start

Substitua <hostname> pelo host real. Esse host pode ser um site de hospedagem dedicado, como o Azure, o Glitch ou um túnel ngrok para localhost em seu computador de desenvolvimento, como abcd1234.ngrok.io. Se você não tiver essas informações, verifique se você concluiu ou hospedou seu aplicativo (ou o aplicativo de exemplo). Retome esse processo quando tiver essas informações.

Observação

Você pode escolher qualquer provedor OAuth de terceiros, como LinkedIn, Google e outros. O processo para habilitar a autenticação desses provedores é semelhante ao uso Microsoft Entra ID como um provedor OAuth de terceiros. Para obter mais informações sobre como usar qualquer provedor OAuth de terceiros, visite o site do provedor específico.

Iniciar o fluxo de autenticação

Observação

Se a partição de armazenamento experimental de terceiros estiver habilitada, a autenticação de terceiros falhará. O aplicativo solicita a autenticação repetidamente, pois os valores não são armazenados localmente.

Disparar o fluxo de autenticação por uma ação do usuário. Evite abrir o pop-up de autenticação automaticamente, pois isso provavelmente disparará o bloqueador pop-up do navegador e confundirá o usuário.

Adicione um botão à sua configuração ou página de conteúdo para habilitar o usuário a entrar quando necessário. Isso pode ser feito na guia da página de configuração ou em qualquer página de conteúdo.

Microsoft Entra ID, como a maioria dos provedores de identidade, não permite que seu conteúdo seja colocado em um iframe. Isso significa que você precisará adicionar uma página pop-up para hospedar o provedor de identidade. No exemplo a seguir, esta página é /tab-auth/simple-start. Use a authentication.authenticate() função da biblioteca do TeamsJS para iniciar esta página quando o botão estiver selecionado.

import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
    url: window.location.origin + "/tab/simple-start-v2",
    width: 600,
    height: 535})
.then((result) => {
    console.log("Login succeeded: " + result);
    let data = localStorage.getItem(result);
    localStorage.removeItem(result);
    let tokenResult = JSON.parse(data);
    showIdTokenAndClaims(tokenResult.idToken);
    getUserProfile(tokenResult.accessToken);
})
.catch((reason) => {
    console.log("Login failed: " + reason);
    handleAuthError(reason);
});

Observações

  • O URL que você passa para authenticate() é a página inicial do fluxo de autenticação. Neste exemplo que é /tab-auth/simple-start. Isso deve corresponder ao que você registrou no Portal de Registro de Aplicativo Microsoft Entra.

  • O fluxo de autenticação deve começar em uma página que esteja no seu domínio. Este domínio também deve ser listado na seção validDomains do manifesto. A falha em fazer resulta em um pop-up vazio.

  • Se você não usar authenticate(), o pop-up poderá não fechar no final do processo de entrada, causando um problema.

Navegue até a página de autorização da sua página pop-up

Quando sua página pop-up (/tab-auth/simple-start) for exibida, o seguinte código será executado. O main objetivo da página é redirecionar para o provedor de identidade para que o usuário possa entrar. Esse redirecionamento pode ser feito no lado do servidor usando HTTP 302, mas, nesse caso, é feito no lado do cliente usando uma chamada para window.location.assign(). Isso também permite ser usado para recuperar informações de dica, que podem ser passadas app.getContext() para Microsoft Entra ID.

app.getContext().then((context) => {
    // Generate random state string and store it, so we can verify it in the callback
    let state = _guid(); // _guid() is a helper function in the sample
    localStorage.setItem("simple.state", state);
    localStorage.removeItem("simple.error");

    // Go to the Azure AD authorization endpoint
    let queryParams = {
        client_id: "{{appId}}",
        response_type: "id_token token",
        response_mode: "fragment",
        scope: "https://graph.microsoft.com/User.Read openid",
        redirect_uri: window.location.origin + "/tab/simple-end",
        nonce: _guid(),
        state: state,
        // The context object is populated by Teams; the loginHint attribute
        // is used as hinting information
        login_hint: context.user.loginHint,
    };

    let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
    window.location.assign(authorizeEndpoint);
});

Depois que o usuário concluir a autorização, ele será redirecionado para a página de retorno de chamada que você especificou para seu aplicativo em /tab-auth/simple-end.

Observações

  • Consulte obter as informações de contexto do usuário para obter ajuda para criar solicitações de autenticação e URLs. Por exemplo, você pode usar o nome de logon do usuário como o login_hint valor para Microsoft Entra entrada, o que significa que o usuário pode precisar digitar menos. Lembre-se de que você não deve usar esse contexto diretamente como prova de identidade, pois um invasor pode carregar sua página em um navegador mal-intencionado e fornecer qualquer informação desejada.
  • Embora o contexto da guia forneça informações úteis sobre o usuário, não use essas informações para autenticar o usuário se você obtê-lo como parâmetros de URL para sua URL de conteúdo de guia ou chamando a app.getContext() função na biblioteca de clientes JavaScript do Microsoft Teams (TeamsJS). Um ator mal-intencionado pode invocar o URL do conteúdo da guia com seus próprios parâmetros, e uma página da Web que representa o Microsoft Teams pode carregar o URL do conteúdo da guia em um iframe e retornar seus próprios dados para a função getContext(). Você deve tratar as informações relacionadas à identidade no contexto da guia simplesmente como dicas e validá-las antes de usá-las.
  • O parâmetro state é utilizado para confirmar que o serviço que chama o URI de retorno de chamada é o serviço que você chamou. Se o state parâmetro no retorno de chamada não corresponder ao parâmetro enviado durante a chamada, a chamada de retorno não será verificada e deverá ser encerrada.
  • Não é necessário incluir o domínio do provedor de identidade na validDomains lista no arquivo manifest.json do aplicativo.

A página de retorno de chamada

Na última seção, você chamou o serviço de autorização Microsoft Entra e passou informações de usuário e aplicativo para que Microsoft Entra ID pudesse apresentar ao usuário sua própria experiência de autorização monolítica. Seu aplicativo não tem controle sobre o que acontece nesta experiência. Tudo o que ele sabe é o que é retornado quando Microsoft Entra ID chama a página de retorno de chamada que você forneceu (/tab-auth/simple-end).

Nesta página, você precisa determinar o êxito ou falha com base nas informações retornadas por Microsoft Entra ID e chamada authentication.notifySuccess() ou authentication.notifyFailure(). Se o logon tiver sido bem-sucedido, você terá acesso aos recursos de serviço.

// Split the key-value pairs passed from Azure AD
// getHashParameters is a helper function that parses the arguments sent
// to the callback URL by Azure AD after the authorization call
let hashParams = getHashParameters();
if (hashParams["error"]) {
    // Authentication/authorization failed
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
} else if (hashParams["access_token"]) {
    // Get the stored state parameter and compare with incoming state
    let expectedState = localStorage.getItem("simple.state");
    if (expectedState !== hashParams["state"]) {
        // State does not match, report error
        localStorage.setItem("simple.error", JSON.stringify(hashParams));
        authentication.notifyFailure("StateDoesNotMatch");
    } else {
        // Success -- return token information to the parent page.
        // Use localStorage to avoid passing the token via notifySuccess; instead we send the item key.
        let key = "simple.result";
        localStorage.setItem(key, JSON.stringify({
            idToken: hashParams["id_token"],
            accessToken: hashParams["access_token"],
            tokenType: hashParams["token_type"],
            expiresIn: hashParams["expires_in"]
        }));
        authentication.notifySuccess(key);
    }
} else {
    // Unexpected condition: hash does not contain error or access_token parameter
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
    authentication.notifyFailure("UnexpectedFailure");
}

Esse código analisa os pares de valor-chave recebidos de Microsoft Entra ID no window.location.hash uso da getHashParameters() função auxiliar. Se encontrar um access_token e o valor state for o mesmo que o fornecido no início do fluxo de autenticação, ele retornará o token de acesso para a guia chamando notifySuccess(); caso contrário, ele relatará um erro com notifyFailure().

Observações

NotifyFailure() tem os seguintes motivos de falha predefinidos:

  • CancelledByUser o usuário fechou a janela pop-up antes de concluir o fluxo de autenticação.

    Observação

    Recomendamos não usar same-origin ou same-origin-allow-popups valores para cabeçalho de Cross-Origin-Opener-Policy resposta nas páginas de logon, pois ele interrompe a conexão com a janela pai e faz com que a chamada de API autenticada retorne prematuramente com um CancelledByUser erro.

  • FailedToOpenWindow a janela pop-up não pôde ser aberta. Ao executar o Microsoft Teams em um navegador, isso geralmente significa que a janela foi bloqueada por um bloqueador de pop-ups.

Se for bem-sucedido, você poderá atualizar ou recarregar a página e mostrar conteúdos relevantes para o usuário agora autenticado. Se a autenticação falhar, ela exibirá uma mensagem de erro.

Seu aplicativo pode definir seu próprio cookie de sessão para que o usuário não precise entrar novamente quando retornar à sua guia no dispositivo atual.

Observação

  • O Chrome 80, agendado para lançamento no início de 2020, apresenta novos valores de cookie e impõe políticas de cookie por padrão. É recomendável que você defina o uso pretendido para seus cookies em vez de depender do comportamento padrão do navegador. ConsulteAtributo de cookie SameSite (atualização 2020).
  • Para obter o token apropriado para usuários do Microsoft Teams Free e convidados, verifique se seus aplicativos utilizam o ponto https://login.microsoftonline.com/**{tenantId}**de extremidade específico do locatário . Você pode adquirir o tenantId no contexto de mensagem de bot ou guia. Se seus aplicativos usarem https://login.microsoftonline.com/common, os usuários poderão receber tokens incorretos, fazendo com que eles façam logon no locatário "home" em vez do locatário em que estão conectados no momento.

Para obter mais informações sobre o SSO (logon único), consulte o artigo Autenticação silenciosa.

Exemplo de código

Código de exemplo mostrando o processo de autenticação de guia usando Microsoft Entra ID:

Nome do exemplo Descrição .NET Node.js Manifesto
SSO de guia Este aplicativo de exemplo mostra Microsoft Entra SSO para guias no Teams. View Exibição,
Kit de Ferramentas do Teams		 NA
SSO de Guia, Bot e Extensão de Mensagem (ME) Este exemplo mostra o SSO for Tab, Bot e ME- search, action, link unfurl. View View Exibir

Confira também