Adicionar código para habilitar o logon único

Certifique-se de que regista a sua aplicação no Microsoft Entra ID antes de adicionar código para ativar o SSO.

Registar-se com o Microsoft Entra ID

Tem de configurar o código do lado do cliente da sua aplicação de separador para obter um token de acesso a partir do Microsoft Entra ID. O token de acesso é emitido em nome do aplicativo guia. Se a sua aplicação de separador necessitar de permissões adicionais do Microsoft Graph, terá de transmitir o token de acesso para o lado do servidor e trocá-lo pelo token do Microsoft Graph.

Esta seção cobre:

• Adicionar código do lado do cliente
• Passe o token de acesso para o código ao lado do servidor
• Validar o token de acesso

Adicionar código do lado do cliente

Para obter acesso ao aplicativo para o usuário atual do aplicativo, seu código do lado do cliente deve fazer uma chamada ao Teams para obter um token de acesso. Você precisa de atualizar o código do lado do cliente para usar getAuthToken() para iniciar o processo de validação.

Saiba mais sobre getAuthToken()

getAuthToken() é um método na biblioteca JavaScript do Microsoft Teams. Pede que um token de acesso do Microsoft Entra seja emitido em nome da aplicação. O token é adquirido na cache, se não tiver expirado. Se expirar, será enviado um pedido para o ID do Microsoft Entra para obter um novo token de acesso.

Para obter mais informações, consulte getAuthToken.

Quando chamar getAuthToken

Use getAuthToken() no momento em que você precisar de token de acesso para o usuário atual do aplicativo:

Se o token de acesso for necessário...	Chamar getAuthToken()...
Quando o usuário do aplicativo acessa o aplicativo	Depois de microsoftTeams.app.initialize().
Para usar uma funcionalidade particular do aplicativo	Quando o usuário do aplicativo toma uma ação que requer a assinatura.

Adicionar código para getAuthToken

Adicionar o trecho de código do JavaScript ao aplicativo guia para:

• Chamar getAuthToken().
• Analisar o token de acesso ou passe-o para o código do lado do servidor.

O seguinte trecho de código mostra um exemplo de chamada getAuthToken().

microsoftTeams.app.initialize().then(() => {
    getClientSideToken()
        .then((clientSideToken) => {
            return getServerSideToken(clientSideToken);
        })
        .then((profile) => {
            return useServerSideToken(profile);
        })
        .catch((error) => {
            ...
        })
}

    function getClientSideToken() {

        return new Promise((resolve, reject) => {
            display("1. Get auth token from Microsoft Teams");
            
            microsoftTeams.authentication.getAuthToken().then((result) => {
                display(result);

                resolve(result);
            }).catch((error) => {
                reject("Error getting token: " + error);
            });
        });
    }

Você pode adicionar chamadas de getAuthToken() para todas as funções e manipuladores que iniciam uma ação quando o token é necessário.

Eis um exemplo do código do lado do cliente:

Quando o Teams recebe o token de acesso, ele é armazenado em cache e reutilizado conforme necessário. Este token pode ser utilizado sempre que getAuthToken() for chamado, até expirar, sem fazer outra chamada para o ID do Microsoft Entra.

Importante

Como melhores práticas para a segurança do token de acesso:

• Sempre chame getAuthToken() quando você precisar de um token de acesso.
• O Teams coloca automaticamente o token de acesso em cache, pelo que não é necessário colocar em cache ou armazená-lo no código da sua aplicação.

Caixa de diálogo de consentimento para obter o token de acesso

Quando chama getAuthToken() e o consentimento do utilizador da aplicação é necessário para permissões ao nível do utilizador, é apresentada uma caixa de diálogo Do Microsoft Entra ao utilizador da aplicação com sessão iniciada.

A caixa de diálogo de consentimento apresentada destina-se a âmbitos open-id definidos no ID do Microsoft Entra. O usuário do aplicativo deve dar consentimento apenas uma vez. O utilizador da aplicação pode aceder e utilizar a sua aplicação de separador para as permissões e âmbitos concedidos após o consentimento.

Importante

Cenários onde as caixas de diálogo de consentimento não são necessárias:

• Se o administrador de locatários tiver concedido consentimento em nome do locatário, os usuários do aplicativo não precisarão ser solicitados a dar consentimento. Isto significa que os usuários do aplicativo não veem as caixas de diálogo de consentimento e podem acessar o aplicativo diretamente.
• Se a sua aplicação Microsoft Entra estiver registada no mesmo inquilino a partir do qual está a pedir uma autenticação no Teams, o utilizador da aplicação não pode ser convidado a consentir e é-lhe concedido imediatamente um token de acesso. Os utilizadores da aplicação só consentem estas permissões se a aplicação Microsoft Entra estiver registada num inquilino diferente.

Se você encontrar qualquer erro, consulte Solução de problemas de autenticação de logon único no Teams.

User o token de acesso como um token de identidade

O token devolvido para o aplicativo guia é um token de acesso e um token de ID. O aplicativo guia pode usar o token como um token de acesso para fazer solicitações HTTPS autenticadas para APIs no lado do servidor.

O token de acesso devolvido getAuthToken() pode ser usado para estabelecer a identidade de usuário do aplicativo usando as seguintes declarações no token:

• name: O nome de exibição do usuário do aplicativo.
• preferred_username: O endereço de email do usuário do aplicativo.
• oid: Um GUID que representa a ID do usuário do aplicativo.
• tid: Um GUID que representa o locatário ao qual o usuário do aplicativo está se conectando.

O Teams pode armazenar em cache esta informação associada à identidade do usuário do aplicativo, tal como as preferências do usuário.

Observação

Se você precisar de construir uma ID única para representar o usuário do aplicativo no seu sistema, consulte Usando declarações para identificar um usuário de forma confiável.

Passe o token de acesso para o código ao lado do servidor

Se precisar de aceder às APIs Web no servidor, terá de transmitir o token de acesso ao código do lado do servidor. As APIs da Web devem decodificar o token de acesso para exibir declarações para esse token.

Observação

Se não receber o Nome Principal de Utilizador (UPN) no token de acesso devolvido, adicione-o como uma afirmação opcional no ID do Microsoft Entra. Para obter mais informações, consulte Tokens de acesso.

O token de acesso recebido com sucesso pelo getAuthToken() fornece acesso (para o usuário autenticado como usuário do aplicativo) às suas APIs da Web. O código ao lado do servidor também pode analisar o token para informações de identidade, se necessário.

Se você precisar passar o token de acesso para obter dados do Microsoft Graph, consulte Estender o aplicativo guia com as permissões do Microsoft Graph.

Código para passar o token de acesso para o lado do servidor

O código a seguir mostra um exemplo de passagem do token de acesso para o lado do servidor. O token é passado em um Authorization cabeçalho ao enviar uma solicitação para uma API da Web do lado do servidor. Este exemplo envia dados JSON, por isso usa o método POST. O GET é suficiente para enviar o token de acesso quando você não está escrevendo para o servidor.

function getServerSideToken(clientSideToken) {
        return new Promise((resolve, reject) => {
            microsoftTeams.app.getContext().then((context) => {
                fetch('/getProfileOnBehalfOf', {
                    method: 'post',
                    headers: {
                        'Content-Type': 'application/json'
                    },
                    body: JSON.stringify({
                        'tid': context.user.tenant.id,
                        'token': clientSideToken
                    }),
                    mode: 'cors',
                    cache: 'default'
                })
                .then((response) => {
                    if (response.ok) {
                        return response.json();
                    } else {
                        reject(response.error);
                    }
                })
                .then((responseJson) => {
                    if (responseJson.error) {
                        reject(responseJson.error);
                    } else {
                        const profile = responseJson;

                        resolve(profile);
                    }
                });
            });
        });
    }

Validar o token de acesso

Para obter mais informações sobre como validar o token de acesso, veja Validar tokens.

Token de acesso de exemplo

O código seguinte é um payload normal descodificado de um token de acesso:

{
    aud: "2c3caa80-93f9-425e-8b85-0745f50c0d24",
    iss: "https://login.microsoftonline.com/fec4f964-8bc9-4fac-b972-1c1da35adbcd/v2.0",
    iat: 1521143967,
    nbf: 1521143967,
    exp: 1521147867,
    aio: "ATQAy/8GAAAA0agfnU4DTJUlEqGLisMtBk5q6z+6DB+sgiRjB/Ni73q83y0B86yBHU/WFJnlMQJ8",
    azp: "e4590ed6-62b3-5102-beff-bad2292ab01c",
    azpacr: "0",
    e_exp: 262800,
    name: "Mila Nikolova",
    oid: "6467882c-fdfd-4354-a1ed-4e13f064be25",
    preferred_username: "milan@contoso.com",
    scp: "access_as_user",
    sub: "XkjgWjdmaZ-_xDmhgN1BMP2vL2YOfeVxfPT_o8GRWaw",
    tid: "fec4f964-8bc9-4fac-b972-1c1da35adbcd",
    uti: "MICAQyhrH02ov54bCtIDAA",
    ver: "2.0"
}

Exemplos de código

Nome do exemplo	Descrição	.NET	Node.js	Manifesto
SSO de guia	Aplicação de exemplo do Microsoft Teams para separadores Microsoft Entra SSO	View	Ver, Toolkit do Teams	NA
SSO de tecla de tabulação, bot e extensão de mensagem (ME)	Este exemplo mostra o SSO para separador, bot e ME – pesquisa, ação e desfraldamento de ligações.	View	View	View

Próxima etapa

Atualizar o manifesto do aplicativo do Teams e pré-visualizar o aplicativo

Confira também

• jwt.ms
• Declaração opcional do Azure Active Directory
• Tokens de acesso
• Visão geral da Biblioteca de Autenticação da Microsoft (MSAL)
• Tokens de iD da plataforma de identidade da Microsoft
• Tokens de acesso da plataforma de identidade da Microsoft