Configurar autenticação OAuth IdP de terceiros

A sua aplicação Microsoft Teams poderá ter de interagir com vários serviços, como o 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 do Microsoft Entra ID para autenticação para aceder a estas informações.

O 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 empregam 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 do 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.

Configurar a sua aplicação para utilizar o 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 o 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.

Iniciar o fluxo de autenticação

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.

O Microsoft Entra ID, tal 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.

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

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 principal 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 o ID do Microsoft Entra.

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

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 valor para o login_hint início de sessão do Microsoft Entra, 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 o 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 o ID do Microsoft Entra 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 ID do Microsoft Entra 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 do ID do Microsoft Entra 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.

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 do separador com o ID do Microsoft Entra:

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