Configurar autenticação OAuth IdP de terceiros

Observação

Para que a autenticação funcione para o seu separador em clientes móveis, certifique-se de que está a utilizar a versão 1.4.1 ou posterior da biblioteca de cliente JavaScript (TeamsJS) do Microsoft Teams.

A sua aplicação Microsoft Teams poderá ter de interagir com vários serviços, como Facebook, Twitter e Teams. A maioria destes serviços necessita de autenticação e autorização para acesso. O Teams armazena informações de perfil de utilizador no Microsoft Entra ID com o Microsoft Graph. Este artigo centra-se principalmente na utilização de Microsoft Entra ID para autenticação para aceder a estas informações.

Microsoft Entra ID e vários outros fornecedores de serviços utilizam o OAuth 2.0, um padrão aberto para autenticação. É essencial compreender o OAuth 2.0 ao lidar com a autenticação no Teams e no Microsoft Entra ID. Os exemplos fornecidos utilizam o fluxo de Concessão Implícita OAuth 2.0, que obtém as informações de perfil do utilizador do Microsoft Entra ID e do Microsoft Graph.

O código no artigo é proveniente da aplicação de exemplo do Teams Microsoft Teams Authentication Sample (Node). Contém um separador estático que pede um token de acesso para o Microsoft Graph e mostra as informações básicas do perfil do utilizador atual de Microsoft Entra ID.

Para obter uma descrição geral do fluxo de autenticação para separadores, veja Fluxo de autenticação nos separadores.

O fluxo de autenticação nos separadores difere do fluxo de autenticação nos bots.

Observação

Este tópico reflete a versão 2.0.x da biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS). Se estiver a utilizar uma versão anterior, consulte a descrição geral da biblioteca do TeamsJS para obter orientações sobre as diferenças entre as versões mais recentes do TeamsJS e versões anteriores.

Configurar a sua aplicação para utilizar Microsoft Entra ID como fornecedor de identidade

Os fornecedores de identidade de suporte do OAuth 2.0 não autenticam pedidos de aplicações não registadas. Por conseguinte, é essencial registar as suas aplicações com antecedência. Para registar uma aplicação com Microsoft Entra ID, siga estes passos:

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 pendente e atualize o URL para o ponto final de autenticação. Nas aplicações de exemplo TypeScript/Node.js e C# disponíveis no GitHub, os URLs de redirecionamento seguem um padrão semelhante:

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

Substitua pelo <hostname> seu anfitrião real. Este anfitrião pode ser um site de alojamento dedicado, como o Azure, o Glitch ou um túnel ngrok para localhost no seu computador de desenvolvimento, como abcd1234.ngrok.io. Se não tiver estas informações, certifique-se de que conclui ou aloja a sua aplicação (ou a aplicação de exemplo). Retome este processo quando tiver estas informações.

Observação

Pode escolher qualquer fornecedor OAuth de terceiros, como o LinkedIn, Google e outros. O processo para ativar a autenticação para estes fornecedores é semelhante à utilização de Microsoft Entra ID como um fornecedor OAuth de terceiros. Para obter mais informações sobre como utilizar qualquer fornecedor OAuth de terceiros, visite o site do fornecedor específico.

Iniciar o fluxo de autenticação

Observação

Se a criação de partições de armazenamento experimental de terceiros estiver ativada, a autenticação de terceiros falhará. A aplicação pede autenticação repetidamente, uma vez que os valores não são armazenados localmente.

Acione o fluxo de autenticação por uma ação do utilizador. Evite abrir automaticamente o pop-up de autenticação, pois é provável que isto acione o bloqueador de pop-up do browser e confunda o utilizador.

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 fornecedores de identidade, não permite que os respetivos conteúdos sejam colocados num iframe. Isto significa que tem de adicionar uma página para alojar o fornecedor de identidade que o cliente do Teams apresenta dentro de uma janela de pop-up. No exemplo seguinte, a página é /tab-auth/simple-start. Utilize a authentication.authenticate() função da biblioteca do TeamsJS para iniciar esta página quando o botão estiver selecionado.

TeamsJS v2

import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
    url: window.location.origin + "/tab-auth/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);
});

TeamsJS v1

microsoftTeams.authentication.authenticate({
    url: window.location.origin + "/tab-auth/simple-start-v1",
    width: 600,
    height: 535,
    successCallback: function (result) {
        getUserProfile(result.accessToken);
    },
    failureCallback: function (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. Isto deve corresponder ao que registou no Portal de Registo de Aplicações do 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 ao fazer resulta num pop-up vazio.

• Se não conseguir utilizar authenticate()o , o pop-up poderá não fechar no final do processo de início de sessão, o que causa um problema.

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

Quando a página de pop-up (/tab-auth/simple-start) é apresentada, é executado o seguinte código. O main objetivo da página é redirecionar para o seu fornecedor de identidade para que o utilizador possa iniciar sessão. Este redirecionamento pode ser feito no lado do servidor com HTTP 302, mas neste caso é feito do lado do cliente através de uma chamada para window.location.assign(). Isto também permite app.getContext() ser utilizado para obter informações de sugestão, que podem ser transmitidas para Microsoft Entra ID.

TeamsJS v2

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);
});

TeamsJS v1

microsoftTeams.getContext(function (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: "YOUR_APP_ID_HERE",
        response_type: "id_token token",
        response_mode: "fragment",
        scope: "https://graph.microsoft.com/User.Read openid",
        redirect_uri: window.location.origin + "/tab-auth/simple-end",
        nonce: _guid(),
        state: state,
        // The context object is populated by Teams; the loginHint attribute
         // is used as hinting information
        login_hint: context.loginHint,
    };

    let authorizeEndpoint = "https://login.microsoftonline.com/" + context.tid + "/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, pode utilizar o nome de início de sessão do utilizador como o login_hint valor para Microsoft Entra início de sessão, o que significa que o utilizador poderá ter de escrever menos. Lembre-se de que não deve utilizar este contexto diretamente como prova de identidade, uma vez que um atacante pode carregar a sua página num browser malicioso e fornecer-lhe todas as informações pretendidas.
• Embora o contexto de separador forneça informações úteis sobre o utilizador, não utilize estas informações para autenticar o utilizador, quer o obtenha como parâmetros de URL para o URL do conteúdo do separador ou ao chamar a app.getContext() função na biblioteca de cliente JavaScript (TeamsJS) do Microsoft Teams. 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 na chamada de retorno não corresponder ao parâmetro que enviou durante a chamada, a chamada de retorno não é verificada e deve ser terminada.
• Não é necessário incluir o domínio do fornecedor de identidade na validDomains lista no ficheiro de manifest.json da aplicação.

A página de retorno de chamada

Na última secção, chamou o serviço de autorização Microsoft Entra e transmitiu as informações do utilizador e da aplicação para que Microsoft Entra ID pudesse apresentar ao utilizador a 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 sabe é o que é devolvido quando Microsoft Entra ID chama a página de chamada de retorno que forneceu (/tab-auth/simple-end).

Nesta página, tem de determinar o êxito ou a falha com base nas informações devolvidas pelo Microsoft Entra ID e chamar authentication.notifySuccess() ou authentication.notifyFailure(). Se o início de sessão tiver sido bem-sucedido, terá acesso aos recursos do 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");
}

Este código analisa os pares chave-valor recebidos de Microsoft Entra ID na window.location.hash utilização 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 que não utilize same-origin ou same-origin-allow-popups valores para Cross-Origin-Opener-Policy o cabeçalho de resposta nas páginas de início de sessão, uma vez que interrompe a ligação à janela principal e faz com que a chamada à API de autenticação devolva prematuramente com um CancelledByUser erro.

• FailedToOpenWindow não foi possível abrir a janela de pop-up. Ao executar o Microsoft Teams num browser, isto normalmente significa que um bloqueador de janelas de pop-up bloqueou a janela.

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.

A sua aplicação pode definir o seu próprio cookie de sessão para que o utilizador não precise de iniciar sessão novamente quando voltar ao seu separador no dispositivo atual.

Observação

• O Chrome 80 introduz novos valores de cookies e impõe políticas de cookies por predefinição. Recomendamos que defina a utilização pretendida para os cookies em vez de depender do comportamento predefinido do browser. Para obter mais informações, confira Atributos do cookie SameSite.
• Para obter o token adequado para utilizadores convidados e Gratuitos do Microsoft Teams, certifique-se de que as suas aplicações utilizam o ponto https://login.microsoftonline.com/**{tenantId}**final específico do inquilino. Pode adquirir o tenantId a partir da mensagem do bot ou do contexto do separador. Se as suas aplicações utilizarem https://login.microsoftonline.com/commono , os utilizadores poderão receber tokens incorretos, fazendo com que iniciem sessão no inquilino "home" em vez do inquilino no qual têm sessão iniciada.

Para obter mais informações sobre o início de sessão único (SSO), veja o artigo Autenticação silenciosa.

Exemplo de código

Código de exemplo que mostra o processo de autenticação de separadores com Microsoft Entra ID:

Nome do exemplo	Descrição	.NET	Node.js	Manifesto
SSO de guia	Esta aplicação de exemplo mostra Microsoft Entra SSO para separadores no Teams.	View	Ver, Toolkit do Teams	NA
SSO de Tecla de Tabulação, Bot e Extensão de Mensagens (ME)	Este exemplo mostra o SSO para Tabulação, Bot e ME– pesquisa, ação, unfurl de ligação.	View	View	Exibir

Confira também

• Planejar a autenticação do usuário
• Projete sua guia para o Microsoft Teams
• Autenticação silenciosa
• Adicionar autenticação à sua extensão de mensagens
• Suporte de Logon Único (SSO) para bots