Configurar autenticação OAuth IdP de terceiros

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

O Microsoft Entra ID e vários outros provedores de serviços usam o OAuth 2.0, um padrão aberto para autenticação. É essencial entender 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 do OAuth 2.0, que recupera as informações de perfil do usuário do Microsoft Entra ID e do Microsoft Graph.

O código no artigo é proveniente do aplicativo de exemplo do Teams, Exemplo de Autenticação do Microsoft Teams (Nó). Ela contém uma guia estática que solicita um token de acesso para o Microsoft Graph e mostra as informações básicas de perfil do usuário atual do 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 nas guias difere do fluxo de autenticação nos bots.

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

Os provedores de identidade compatíveis com OAuth 2.0 não autenticam solicitações de aplicativos não registrados. Portanto, é essencial registrar suas inscrições com antecedência. Para registrar um aplicativo no 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 seu host real. Esse host pode ser um site de hospedagem dedicado, como o Azure, o Glitch ou um túnel ngrok para o host local em seu computador de desenvolvimento, como abcd1234.ngrok.ioo . Se você não tiver essas informações, certifique-se de concluir ou hospedar seu aplicativo (ou o aplicativo de exemplo). Retome esse processo quando tiver essas informações.

Iniciar o fluxo de autenticação

Dispare o fluxo de autenticação por uma ação do usuário. Evite abrir o pop-up de autenticação automaticamente, pois isso provavelmente acionará o bloqueador de pop-ups 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.

O Microsoft Entra ID, como a maioria dos provedores de identidade, não permite que seu conteúdo seja colocado em um iframearquivo . Isso significa que você precisa adicionar uma página para hospedar o provedor de identidade que o cliente do Teams exibe em uma janela pop-up. No exemplo a seguir, a página é /tab-auth/simple-start. Use a authentication.authenticate() função da biblioteca TeamsJS para iniciar esta página quando o botão for 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. Isso deve corresponder ao que você registrou no Portal de Registro de Aplicativos 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. O não cumprimento resulta em um pop-up vazio.

• Se você não usar authenticate()o , o pop-up pode 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) é exibida, o código a seguir é executado. O principal 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 app.getContext() que ele seja usado para recuperar informações de dicas, que podem ser passadas para o 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);
});

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, você pode usar o nome de logon do usuário como o valor para entrar no Microsoft Entra, o login_hint que significa que talvez o usuário precise 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 que desejar.
• Embora o contexto de guia forneça informações úteis sobre o usuário, não use essas informações para autenticar o usuário, seja como parâmetros de URL para a URL do conteúdo da 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 lista do validDomains arquivo manifest.json do aplicativo.

A página de retorno de chamada

Na última seção, você chamou o serviço de autorização do Microsoft Entra e passou informações de usuário e aplicativo para que o 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 o Microsoft Entra ID chama a página de retorno de chamada que você forneceu (/tab-auth/simple-end).

Nessa página, você precisa determinar o êxito ou a falha com base nas informações retornadas pelo Microsoft Entra ID e chamar authentication.notifySuccess() ou authentication.notifyFailure(). Se o logon tiver sido bem-sucedido, você 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");
}

Esse código analisa os pares de chave-valor recebidos do Microsoft Entra ID usando window.location.hash a 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 valores OR same-origin-allow-popups para Cross-Origin-Opener-Policy o cabeçalho de resposta nas páginas de logon, pois isso interrompe a conexão com a janela pai e faz com que a chamada à API de autenticação retorne prematuramente com um CancelledByUser erro.

• FailedToOpenWindow Não foi possível abrir a janela pop-up. Ao executar o Microsoft Teams em um navegador, isso geralmente significa que um bloqueador de pop-ups 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.

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

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

Exemplo de código

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

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