Adicionar código para habilitar o logon único
Antes de adicionar código para habilitar o SSO, verifique se você registrou seu aplicativo com Microsoft Entra ID.
Você precisa configurar o código do lado do cliente do aplicativo de guia para obter um token de acesso de Microsoft Entra ID. O token de acesso é emitido em nome do aplicativo guia. Se seu aplicativo guia exigir permissões adicionais do Microsoft Graph, você precisará passar o token de acesso para o lado do servidor e trocá-lo por um 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. Ele solicita uma Microsoft Entra token de acesso a ser emitido em nome do aplicativo. O token pode ser adquirido através do armazenamento em cache, caso não tenha expirado. Se tiver expirado, uma solicitação será enviada para Microsoft Entra ID 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.
Aqui está 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. Esse token pode ser usado sempre que getAuthToken() for chamado, até que expire, sem fazer outra chamada para Microsoft Entra ID.
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 armazenará em cache o token de acesso para você. Não o armazene em cache ou no código de seu aplicativo.
Caixa de diálogo de consentimento para obter o token de acesso
Quando você chama getAuthToken() e o consentimento do usuário do aplicativo é necessário para permissões no nível do usuário, uma caixa de diálogo Microsoft Entra é mostrada ao usuário do aplicativo que está conectado no momento.
A caixa de diálogo de consentimento exibida é para escopos de id aberto definidos em Microsoft Entra ID. O usuário do aplicativo deve dar consentimento apenas uma vez. Após o consentimento, o usuário do aplicativo pode acessar e usar seu aplicativo guia para as permissões concedidas e escopos.
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 seu aplicativo Microsoft Entra estiver registrado no mesmo locatário do qual você está solicitando uma autenticação no Teams, o usuário do aplicativo não poderá ser solicitado a consentir e receberá imediatamente um token de acesso. Os usuários do aplicativo só consentem com essas permissões se o aplicativo Microsoft Entra estiver registrado em um locatário 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 você precisar acessar as APIs da Web em seu servidor, você precisará passar o token de acesso para seu 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 você não receber o UPN (Nome da Entidade de Usuário) no token de acesso retornado, adicione-o como uma declaração opcional em Microsoft Entra ID. 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, consulte validar tokens.
Token de acesso de exemplo
A seguir está uma carga decodificada típica do 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 | Aplicativo de exemplo do Microsoft Teams para guias Microsoft Entra SSO | View | Exibição, Kit de Ferramentas do Teams | NA |
| SSO de guia, bot e extensão de mensagem (ME) | Este exemplo mostra o SSO para Tab, Bot e ME – pesquisa, ação, linkunfurl. | View | View | View |
Próxima etapa
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de