Agregar código para habilitar el inicio de sesión único
Asegúrese de registrar la aplicación con el identificador de Microsoft Entra antes de agregar código para habilitar el inicio de sesión único.
Debe configurar el código del lado cliente de la aplicación de pestaña para obtener un token de acceso de Microsoft Entra ID. El token de acceso se emite en nombre de la aplicación de pestaña. Si la aplicación de pestaña requiere permisos adicionales de Microsoft Graph, debe pasar el token de acceso al lado servidor e intercambiarlo por el token de Microsoft Graph.
En esta sección se describen estos temas:
- Agregar código del lado cliente
- Pasar el token de acceso al código del lado servidor
- Validar el token de acceso
Agregar código del lado cliente
Para obtener acceso a la aplicación para el usuario de la aplicación actual, el código del lado cliente debe realizar una llamada a Teams para obtener un token de acceso. Debe actualizar el código del lado cliente para usar getAuthToken() para iniciar el proceso de validación.
Más información sobre getAuthToken()
getAuthToken() es un método de la biblioteca JavaScript de Microsoft Teams. Solicita que se emita un token de acceso de Microsoft Entra en nombre de la aplicación. El token se adquiere de la memoria caché, si no ha expirado. Si expira, se envía una solicitud a Microsoft Entra ID para obtener un nuevo token de acceso.
Para más información, vea getAuthToken.
Cuándo llamar a getAuthToken
Use getAuthToken() en el momento en que necesite un token de acceso para el usuario de la aplicación actual:
| Si se necesita un token de acceso... | Llame a getAuthToken()... |
|---|---|
| Cuando el usuario de la aplicación accede a la aplicación | Después de microsoftTeams.app.initialize(). |
| Para usar una funcionalidad determinada de la aplicación | Cuando el usuario de la aplicación realiza una acción que requiere el inicio de sesión. |
Agregar código para getAuthToken
Agregue un fragmento de código JavaScript a la aplicación de pestaña a:
- Llamar a
getAuthToken(). - Analice el token de acceso o páselo al código del lado del servidor.
El fragmento de código siguiente muestra un ejemplo de llamada 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);
});
});
}
Por lo que puede agregar llamadas de getAuthToken() a todas las funciones y controladores que inician una acción en la que se requiere el token.
Este es un ejemplo del código del lado cliente:
Cuando Teams recibe el token de acceso, se almacena en caché y se reutiliza según sea necesario. Este token se puede usar siempre que getAuthToken() se llame a , hasta que expire, sin realizar otra llamada a Microsoft Entra ID.
Importante
Como procedimiento recomendado para la seguridad del token de acceso:
- Llame siempre a
getAuthToken()cuando necesite un token de acceso. - Teams almacena automáticamente en caché el token de acceso, por lo que no es necesario almacenarlo en caché ni almacenarlo en el código de la aplicación.
Cuadro de diálogo consentimiento para obtener el token de acceso
Cuando se llama getAuthToken() y se requiere el consentimiento del usuario de la aplicación para los permisos de nivel de usuario, se muestra un cuadro de diálogo de Microsoft Entra al usuario de la aplicación que ha iniciado sesión.
El cuadro de diálogo de consentimiento que aparece es para los ámbitos de id. abierto definidos en Microsoft Entra ID. El usuario de la aplicación solo debe dar su consentimiento una vez. El usuario de la aplicación puede acceder y usar la aplicación de pestaña para los permisos y ámbitos concedidos después de dar su consentimiento.
Importante
Escenarios en los que no se necesitan cuadros de diálogo de consentimiento:
- Si el administrador de inquilinos ha concedido el consentimiento en nombre del inquilino, no es necesario solicitar consentimiento a los usuarios de la aplicación. Esto significa que los usuarios de la aplicación no ven los cuadros de diálogo de consentimiento y pueden acceder a la aplicación sin problemas.
- Si la aplicación Microsoft Entra está registrada en el mismo inquilino desde el que solicita una autenticación en Teams, no se puede pedir al usuario de la aplicación que dé su consentimiento y se le conceda un token de acceso de inmediato. Los usuarios de la aplicación dan su consentimiento a estos permisos solo si la aplicación Microsoft Entra está registrada en un inquilino diferente.
Si encuentra algún error, consulte Solución de problemas de autenticación de SSO en Teams.
Usar el token de acceso como token de identidad
El token devuelto a la aplicación de pestaña es un token de acceso y un token de identificador. La aplicación de pestaña puede usar el token como un token de acceso para realizar solicitudes HTTPS autenticadas a las API en el lado del servidor.
El token de acceso devuelto desde getAuthToken() se puede usar para establecer la identidad del usuario de la aplicación mediante las siguientes notificaciones en el token:
-
name: el nombre para mostrar del usuario de la aplicación -
preferred_username: la dirección de correo electrónico del usuario de la aplicación. -
oid- Un GUID que representa el identificador del usuario de la aplicación. -
tid- Un GUID que representa el inquilino en el que el usuario de la aplicación está iniciando sesión.
Teams puede almacenar en caché esta información asociada a la identidad del usuario de la aplicación, como las preferencias del usuario.
Nota:
Si necesita crear un identificador único para representar al usuario de la aplicación en el sistema, consulte Uso de notificaciones para identificar de forma fiable a un usuario.
Pasar el token de acceso al código del lado servidor
Si necesita acceder a las API web en el servidor, debe pasar el token de acceso al código del lado servidor. Las API web deben descodificar el token de acceso para ver las notificaciones de ese token.
Nota:
Si no recibe el nombre principal de usuario (UPN) en el token de acceso devuelto, agréguelo como una notificación opcional en Microsoft Entra ID. Para obtener más información, consulte tokens de acceso.
El token de acceso recibido en la devolución de llamada correcta de getAuthToken() proporciona acceso (para el usuario de aplicación autenticado) a las API web. También el código del lado servidor puede analizar el token para obtener información de identidad, si lo necesita.
Si necesita pasar el token de acceso para obtener datos de Microsoft Graph, consulte Extensión de la aplicación de pestaña con permisos de Microsoft Graph.
Código para pasar el token de acceso al lado servidor
El código siguiente muestra un ejemplo de pasar el token de acceso al lado del servidor. El token se pasa en un encabezado Authorization al enviar una solicitud a una API web del lado servidor. En este ejemplo se envían datos JSON, por lo que se usa el método POST.
GET es suficiente para enviar el token de acceso cuando no escribe en el 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 el token de acceso
Para obtener más información sobre cómo validar el token de acceso, consulte Validación de tokens.
Ejemplo de token de acceso
El código siguiente es una carga descodificada típica de un token de acceso:
{
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"
}
Ejemplos de código
| Ejemplo de nombre | Descripción | .NET | Node.js | Manifiesto |
|---|---|---|---|---|
| Inicio de sesión único de pestaña | Aplicación de ejemplo de Microsoft Teams para pestañas Microsoft Entra SSO | View |
Ver, Kit de herramientas de Teams |
ND |
| Inicio de sesión único de pestaña, bot y extensión de mensaje (ME) | En este ejemplo se muestra el inicio de sesión único para tab, bot y ME: búsqueda, acción y desplegamiento de vínculos. | View | View | View |