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.

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.

Quando chamar getAuthToken

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

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.

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.

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.

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.

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.

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

Próxima etapa

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