Autenticar um usuário em uma guia do Microsoft TeamsAuthenticate a user in a Microsoft Teams tab

Observação

Para que a autenticação funcione para sua guia em clientes móveis, é necessário garantir que você esteja usando a versão 1.4.1 ou posterior do SDK do Microsoft Teams JavaScript.For authentication to work for your tab on mobile clients, you need to ensure you're using version 1.4.1 or later of the Teams JavaScript SDK.

Há muitos serviços que você pode desejar usar dentro do seu aplicativo do Microsoft Teams e a maioria desses serviços requer autenticação e autorização para obter acesso ao serviço.There are many services that you may wish to consume inside your Teams app, and most of those services require authentication and authorization to get access to the service. Os serviços incluem o Facebook, o Twitter e o Microsoft Teams.Services include Facebook, Twitter, and of course Teams. Os usuários de Teams têm informações de perfil de usuário armazenadas no Azure Active Directory (Azure AD) usando o Microsoft Graph, e este artigo se concentrará na autenticação usando o Azure AD para obter acesso a essas informações.Users of Teams have user profile information stored in Azure Active Directory (Azure AD) using Microsoft Graph and this article will focus on authentication using Azure AD to get access to this information.

O OAuth 2,0 é um padrão aberto para autenticação usada pelo Azure AD e muitos outros provedores de serviços.OAuth 2.0 is an open standard for authentication used by Azure AD and many other service providers. A compreensão do OAuth 2,0 é um pré-requisito para trabalhar com autenticação no Teams e no Azure AD.Understanding OAuth 2.0 is a prerequisite for working with authentication in Teams and Azure AD. Os exemplos abaixo usam o fluxo de concessão implícita do OAuth 2,0 com o objetivo de eventualmente ler as informações de perfil do usuário do Azure AD e do Microsoft Graph.The examples below use the OAuth 2.0 Implicit Grant flow with the goal of eventually reading the user's profile information from Azure AD and Microsoft Graph.

O código deste artigo vem do exemplo de aplicativo de exemplo do Microsoft Teams de autenticação de guia do Microsoft Teams (nó).The code in this article comes from the Teams sample app Microsoft Teams tab 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 do perfil básico do usuário atual do Azure AD.It contains a static tab that requests an access token for Microsoft Graph and shows the current user's basic profile information from Azure AD.

Para obter uma visão geral do fluxo de autenticação para guias, consulte o tópico fluxo de autenticação em guias.For a general overview of authentication flow for tabs see the topic Authentication flow in tabs.

O fluxo de autenticação em guias difere ligeiramente do fluxo de autenticação em bots.Authentication flow in tabs differs slightly from authentication flow in bots.

Configurando provedores de identidadeConfiguring identity providers

Consulte o tópico Configure Identity Providers para obter etapas detalhadas sobre como configurar URLs de redirecionamento de retorno de chamada OAuth 2,0 ao usar o Azure Active Directory como um provedor de identidade.See the topic Configure identity providers for detailed steps on configuring OAuth 2.0 callback redirect URL(s) when using Azure Active Directory as an identity provider.

Iniciar o fluxo de autenticaçãoInitiate authentication flow

O fluxo de autenticação deve ser acionado por uma ação do usuário.Authentication flow should be triggered by a user action. Você não deve abrir o pop-up de autenticação automaticamente porque isso provavelmente disparará o bloqueador de pop-ups do navegador, além de confundir o usuário.You should not open the authentication pop-up automatically because this is likely to trigger the browser's pop-up blocker as well as confuse the user.

Adicione um botão à sua página de configuração ou conteúdo para permitir que o usuário entre quando necessário.Add a button to your configuration or content page to enable the user to sign in when needed. Isso pode ser feito na página configuração da guia ou em qualquer página de conteúdo .This can be done in the tab configuration page or any content page.

O Azure AD, como a maioria dos provedores de identidade, não permite que seu conteúdo seja colocado em um iframe.Azure AD, like most identity providers, does not allow its content to be placed in an iframe. Isso significa que você precisará adicionar uma página pop-up para hospedar o provedor de identidade.This means that you will need to add a pop-up page to host the identity provider. No exemplo a seguir, esta página é /tab-auth/simple-start .In the following example this page is /tab-auth/simple-start. Use a microsoftTeams.authenticate() função do Microsoft Teams Client SDK para iniciar esta página quando seu botão estiver selecionado.Use the microsoftTeams.authenticate() function of the Microsoft Teams client SDK to launch this page when your button is selected.

microsoftTeams.authentication.authenticate({
    url: window.location.origin + "/tab-auth/simple-start",
    width: 600,
    height: 535,
    successCallback: function (result) {
        getUserProfile(result.accessToken);
    },
    failureCallback: function (reason) {
        handleAuthError(reason);
    }
});

ObservaçõesNotes

  • A URL para a qual você passa microsoftTeams.authentication.authenticate() é a página inicial do fluxo de autenticação.The URL you pass to microsoftTeams.authentication.authenticate() is the start page of the authentication flow. Neste exemplo /tab-auth/simple-start .In this example that is /tab-auth/simple-start. Isso deve corresponder ao que você registrou no portal de registro de aplicativo do Azure ad.This should match what you registered in the Azure AD Application Registration Portal.

  • O fluxo de autenticação deve começar em uma página que está no seu domínio.Authentication flow must start on a page that's on your domain. Esse domínio também deve ser listado na validDomains seção do manifesto.This domain should also be listed in the validDomains section of the manifest. Se isso não for feito, resultará em um pop-up vazio.Failure to do so will result in an empty pop-up.

  • A não utilização causará microsoftTeams.authentication.authenticate() um problema com o pop-up que não está fechando no final do processo de entrada.Failing to use microsoftTeams.authentication.authenticate() will cause a problem with the popup not closing at the end of the sign in process.

Quando a página pop-up ( /tab-auth/simple-start ) é exibida, o código a seguir é executado.When your popup page (/tab-auth/simple-start) is displayed the following code is run. O objetivo principal desta página é redirecionar para seu provedor de identidade para que o usuário possa entrar.The main goal of this page is to redirect to your identity provider so the user can sign in. 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() .This redirection could be done on the server side using HTTP 302, but in this case it is done on the client side using with a call to window.location.assign(). Isso também permite que microsoftTeams.getContext() seja usado para recuperar informações de dicas que podem ser passadas para o Azure AD.This also allows microsoftTeams.getContext() to be used to retrieve hinting information which can be passed to Azure AD.

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",
        resource: "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, o usuário será redirecionado para a página de retorno de chamada que você especificou para seu aplicativo em /tab-auth/simple-end .After the user completes authorization, the user is redirected to the callback page you specified for your app at /tab-auth/simple-end.

ObservaçõesNotes

  • Consulte obter informações de contexto de usuário para ajudar a criar solicitações de autenticação e URLs.See get user context information for help building authentication requests and URLs. Por exemplo, você pode usar o nome de logon do usuário como o login_hint valor para a entrada do Azure AD, o que significa que o usuário pode precisar digitar menos.For example, you can use the user's login name as the login_hint value for Azure AD sign-in, which means the user might need to type less. Lembre-se de que você não deve usar esse contexto diretamente como prova de identidade, uma vez que um invasor pode carregar sua página em um navegador mal-intencionado e fornecer qualquer informação que desejar.Remember that you should not use this context directly as proof of identity since an attacker could load your page in a malicious browser and provide it with any information they want.
  • Embora o contexto de tabulação forneça informações úteis sobre o usuário, não use essas informações para autenticar o usuário se você o recebe como parâmetros de URL para a URL de conteúdo da sua guia ou chamando a microsoftTeams.getContext() função no SDK do cliente do Microsoft Teams.Although the tab context provides useful information regarding the user, don't use this information to authenticate the user whether you get it as URL parameters to your tab content URL or by calling the microsoftTeams.getContext() function in the Microsoft Teams client SDK. Um ator mal-intencionado pode invocar a URL de conteúdo da guia com seus próprios parâmetros, e uma página da Web representando o Microsoft Teams pode carregar sua URL de conteúdo de tabulação em um iframe e retornar seus próprios dados para a getContext() função.A malicious actor could invoke your tab content URL with its own parameters, and a web page impersonating Microsoft Teams could load your tab content URL in an iframe and return its own data to the getContext() function. Você deve tratar as informações relacionadas à identidade no contexto da guia simplesmente como dicas e validá-las antes de usar.You should treat the identity-related information in the tab context simply as hints and validate them before use.
  • O state parâmetro é usado para confirmar se o serviço que está chamando o URI de retorno de chamada é o serviço que você chamou.The state parameter is used to confirm that the service calling the callback URI is the service you called. Se o state parâmetro no retorno de chamada não corresponder ao parâmetro que você enviou durante a chamada, a chamada de retorno não é verificada e deve ser encerrada.If the state parameter in the callback does not match the parameter you sent during the call the return call is not verified and should be terminated.
  • Não é necessário incluir o domínio do provedor de identidade na validDomains lista na manifest.jsdo aplicativo no arquivo.It is not necessary to include the identity provider's domain in the validDomains list in the app's manifest.json file.

A página de retorno de chamadaThe callback page

Na última seção que você chamou o serviço de autorização do Azure AD e passou as informações do usuário e do aplicativo para que o Azure AD possa apresentar ao usuário sua própria experiência de autorização monolítica.In the last section you called the Azure AD authorization service and passed in user and app information so that Azure AD could present the user with its own monolithic authorization experience. Seu aplicativo não tem controle sobre o que acontece nesta experiência.Your app has no control over what happens in this experience. Tudo o que ele sabe é o que é retornado quando o Azure AD chama a página de retorno de chamada fornecida ( /tab-auth/simple-end ).All it knows is what is returned when Azure AD calls the callback page that you provided (/tab-auth/simple-end).

Nesta página, você precisa determinar o sucesso ou a falha com base nas informações retornadas pelo Azure AD e Call microsoftTeams.authentication.notifySuccess() ou microsoftTeams.authentication.notifyFailure() .In this page you need to determine success or failure based on the information returned by Azure AD and call microsoftTeams.authentication.notifySuccess() or microsoftTeams.authentication.notifyFailure(). Se o logon tiver sido bem-sucedido, você terá acesso a recursos de serviço.If the login was successful you will have access to service resources.

// 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
    microsoftTeams.authentication.notifyFailure(hashParams["error"]);
} else if (hashParams["access_token"]) {
    // Get the stored state parameter and compare with incoming state
    // This validates that the data is coming from Azure AD
    let expectedState = localStorage.getItem("simple.state");
    if (expectedState !== hashParams["state"]) {
        // State does not match, report error
        microsoftTeams.authentication.notifyFailure("StateDoesNotMatch");
    } else {
        // Success: return token information to the tab
        microsoftTeams.authentication.notifySuccess({
            idToken: hashParams["id_token"],
            accessToken: hashParams["access_token"],
            tokenType: hashParams["token_type"],
            expiresIn: hashParams["expires_in"]
        })
    }
} else {
    // Unexpected condition: hash does not contain error or access_token parameter
    microsoftTeams.authentication.notifyFailure("UnexpectedFailure");
}

Este código analisa os pares chave-valor recebidos do Azure AD window.location.hash usando a getHashParameters() função auxiliar.This code parses the key-value pairs received from Azure AD in window.location.hash using the getHashParameters() helper function. Se encontrar um access_token , e o state valor for igual ao fornecido no início do fluxo de autenticação, ele retornará o token de acesso à guia chamando notifySuccess() ; caso contrário, ele informa um erro com notifyFailure() .If it finds an access_token, and the state value is the same as the one provided at the start of the authentication flow, it returns the access token to the tab by calling notifySuccess(); otherwise it reports an error with notifyFailure().

ObservaçõesNotes

NotifyFailure() o tem os seguintes motivos de falha predefinidos:NotifyFailure() has the following predefined failure reasons:

  • CancelledByUser o usuário fechou a janela pop-up antes de concluir o fluxo de autenticação.CancelledByUser the user closed the popup window before completing the authentication flow.
  • FailedToOpenWindow Não foi possível abrir a janela pop-up.FailedToOpenWindow the popup window could not be opened. Ao executar o Microsoft Teams em um navegador, isso normalmente significa que a janela foi bloqueada por um bloqueador de pop-up.When running Microsoft Teams in a browser, this typically means that the window was blocked by a popup blocker.

Se tiver êxito, você poderá atualizar ou recarregar a página e mostrar o conteúdo relevante para o usuário autenticado agora.If successful, you can refresh or reload the page and show content relevant to the now-authenticated user. Se a autenticação falhar, exiba uma mensagem de erro.If authentication fails, display an error message.

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.Your app can set its own session cookie so that the user need not sign in again when they return to your tab on the current device.

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 cookies por padrão.Chrome 80, scheduled for release in early 2020, introduces new cookie values and imposes cookie policies by default. É recomendável que você defina o uso pretendido para seus cookies, em vez de confiar no comportamento padrão do navegador.It's recommended that you set the intended use for your cookies rather than rely on default browser behavior. Confira o atributo SameSite cookie (atualização 2020).See SameSite cookie attribute (2020 update).

Observação

Para obter o token correto para os usuários gratuitos e convidados do Microsoft Teams, é importante que os aplicativos usem o ponto de extremidade específico do locatário https://login.microsoftonline.com/ {tenantid}.To get the correct token for Microsoft Teams Free and guest users, it is important that the apps use tenant specific endpoint https://login.microsoftonline.com/**{tenantId}**. Você pode obter tenantid da mensagem do bot ou do contexto da guia.You can get tenantId from the bot message or tab context. Se os aplicativos usarem https://login.microsoftonline.com/common , os usuários receberão tokens incorretos e farão logon no locatário "Home", em vez do locatário que estão atualmente conectados.If the apps use https://login.microsoftonline.com/common, the users will get incorrect tokens and will log on to the "home" tenant instead of the tenant that they are currently signed into.

Para obter mais informações sobre logon único (SSO), confira o artigo autenticação silenciosa.For more information on Single Sign-On (SSO) see the article Silent authentication.

ExemplosSamples

Para obter um exemplo de código mostrando o processo de autenticação de guia usando o Azure AD, confira:For sample code showing the tab authentication process using Azure AD see: