Validar un token de identidad de Exchange

  • Artículo

Importante

Los tokens de identidad de usuario y los tokens de devolución de llamada heredados de Exchange se desactivarán para todos los inquilinos de Exchange Online en octubre de 2024 como parte de la Iniciativa de futuro seguro de Microsoft, que proporciona a las organizaciones las herramientas necesarias para responder al panorama actual de amenazas. Los tokens de identidad de usuario de Exchange seguirán funcionando para Exchange local. La autenticación de aplicaciones anidadas es el enfoque recomendado para los tokens en el futuro. Para obtener más información, consulte nuestra entrada de blog sobre la autenticación de aplicaciones anidadas y los tokens de Exchange heredados.

El complemento de Outlook puede enviarle un token de identidad de usuario de Exchange, pero antes de confiar en la solicitud debe validar el token para asegurarse de que procede del servidor de Exchange esperado. Los tokens de identidad de usuario de Exchange son Tokens Web de JSON (JWT). Se describen los pasos necesarios para validar un JWT en RFC 7519 JSON Web Token (JWT).

Le sugerimos que use un proceso de cuatro pasos para validar el token de identidad y obtener el identificador único del usuario. Primero, extraiga el Token de Web de JSON (JWT) de una cadena URL codificada de base 64. Después, asegúrese de que el token está bien formado, que es para su complemento de Outlook, que no ha expirado y que puede extraer una dirección URL válida para el documento de metadatos de autenticación. A continuación, recupere el documento de metadatos de autenticación del servidor Exchange y valide la firma adjunta al token de identidad. Por último, calcule un identificador único para el usuario concatenando el identificador de Exchange del usuario con la dirección URL del documento de metadatos de autenticación.

Extracción del token web JSON

El token devuelto desde getUserIdentityTokenAsync es una representación de cadena codificada del token. De esta forma, según RFC 7519, todos los JWT tienen tres partes, separadas por un punto. El formato es el siguiente.

{header}.{payload}.{signature}

Encabezado y carga deberían descodificarse con base 64 para obtener una representación de JSON de cada parte. La firma debería descodificarse con base 64 para obtener una matriz de bytes que contiene la firma binaria.

Para obtener más información sobre el contenido del token, consulte Contenido del token de identidad de Exchange.

Una vez que los tres componentes estén descodificados, puede continuar validando el contenido del token.

Validar el contenido del token

Para validar el contenido del token, debe comprobar lo siguiente:

  • Compruebe el encabezado y compruebe que:

    • typ la notificación se establece en JWT.
    • alg la notificación se establece en RS256.
    • x5t la notificación está presente.

  • Compruebe la carga útil y compruebe que:

    • amurl la notificación dentro de appctx se establece en la ubicación de un archivo de manifiesto de clave de firma de token autorizado. Por ejemplo, el valor esperado amurl para Microsoft 365 es https://outlook.office365.com:443/autodiscover/metadata/json/1. Consulte la siguiente sección Comprobación del dominio para obtener información adicional.
    • La hora actual se encuentra entre las horas especificadas en las nbf notificaciones y exp . La notificación nbf especifica la primera hora en que el token se considera válido, y la notificación exp especifica la fecha de expiración del token. Se recomienda permitir una variación de la configuración del reloj entre los servidores.
    • aud claim es la dirección URL esperada para el complemento.
    • version la notificación dentro de la appctx notificación está establecida en ExIdTok.V1.

Comprobación del dominio

Al implementar la lógica de comprobación descrita en la sección anterior, también debe requerir que el dominio de la amurl notificación coincida con el dominio de detección automática para el usuario. Para ello, deberá usar o implementar la detección automática para Exchange.

Si el complemento no puede comprobar el amurl uso de cualquiera de estas opciones, puede optar por que el complemento se cierre correctamente con una notificación adecuada al usuario si es necesaria la autenticación para el flujo de trabajo del complemento.

Validar la firma del token de identidad

Después de saber que la JWT contiene las notificaciones necesarias, puede continuar con la validación de la firma de token.

Recuperar la clave pública de firma

El primer paso es recuperar la clave pública que corresponde con el certificado que el servidor de Exchange usó para firmar el token. En el documento de metadatos de autenticación se encuentra la clave. Este documento es un archivo JSON hospedado en la dirección URL especificada en la notificación amurl.

El documento de metadatos de autenticación utiliza el siguiente formato.

{
    "id": "_70b34511-d105-4e2b-9675-39f53305bb01",
    "version": "1.0",
    "name": "Exchange",
    "realm": "*",
    "serviceName": "00000002-0000-0ff1-ce00-000000000000",
    "issuer": "00000002-0000-0ff1-ce00-000000000000@*",
    "allowedAudiences": [
        "00000002-0000-0ff1-ce00-000000000000@*"
    ],
    "keys": [
        {
            "usage": "signing",
            "keyinfo": {
                "x5t": "enh9BJrVPU5ijV1qjZjV-fL2bco"
            },
            "keyvalue": {
                "type": "x509Certificate",
                "value": "MIIHNTCC..."
            }
        }
    ],
    "endpoints": [
        {
            "location": "https://by2pr06mb2229.namprd06.prod.outlook.com:444/autodiscover/metadata/json/1",
            "protocol": "OAuth2",
            "usage": "metadata"
        }
    ]
}

Las claves de firmas disponibles están en la matriz keys. Selecciona la clave correcta, compruebe que el valor x5t de la propiedad keyinfo coincide con el valor x5t en el encabezado del token. La clave pública está dentro de la propiedad value en la propiedad keyvalue, almacenada como una matriz de bytes codificada con base 64.

Una vez que tenga la clave pública correcta, compruebe la firma. Los datos firmados son las dos primeras partes del token codificado, separadas por puntos:

{header}.{payload}

Calcular el identificador exclusivo para una cuenta de Exchange

Cree un identificador único para una cuenta de Exchange concatenando la dirección URL del documento de metadatos de autenticación con el identificador de Exchange para la cuenta. Cuando tenga este identificador único, úselo para crear un sistema de inicio de sesión único (SSO) para el servicio web del complemento de Outlook. Para obtener más información sobre el uso del identificador único para SSO, consulte Autenticar a un usuario con un token de identidad para Exchange.

Usar una biblioteca para validar el token

Hay una serie de bibliotecas que pueden hacer el análisis y la validación general de JWT. Microsoft proporciona la System.IdentityModel.Tokens.Jwt biblioteca que se puede usar para validar los tokens de identidad de usuario de Exchange.

Importante

Ya no se recomienda la API administrada de Exchange Web Services porque el Microsoft.Exchange.WebServices.Auth.dll, aunque sigue disponible, ya está obsoleto y se basa en bibliotecas no admitidas, como Microsoft.IdentityModel.Extensions.dll.

System.IdentityModel.Tokens.Jwt

La biblioteca System.IdentityModels.Tokens.Jwt puede analizar el token y realizar la validación, aunque debe analizar la notificación appctx usted mismo y recuperar la clave pública de firma.

// Load the encoded token
string encodedToken = "...";
JwtSecurityToken jwt = new JwtSecurityToken(encodedToken);

// Parse the appctx claim to get the auth metadata url
string authMetadataUrl = string.Empty;
var appctx = jwt.Claims.FirstOrDefault(claim => claim.Type == "appctx");
if (appctx != null)
{
    var AppContext = JsonConvert.DeserializeObject<ExchangeAppContext>(appctx.Value);

    // Token version check
    if (string.Compare(AppContext.Version, "ExIdTok.V1", StringComparison.InvariantCulture) != 0) {
        // Fail validation
    }

    authMetadataUrl = AppContext.MetadataUrl;
}

// Use System.IdentityModel.Tokens.Jwt library to validate standard parts
JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler();
TokenValidationParameters tvp = new TokenValidationParameters();

tvp.ValidateIssuer = false;
tvp.ValidateAudience = true;
tvp.ValidAudience = "{URL to add-in}";
tvp.ValidateIssuerSigningKey = true;
// GetSigningKeys downloads the auth metadata doc and
// returns a List<SecurityKey>
tvp.IssuerSigningKeys = GetSigningKeys(authMetadataUrl);
tvp.ValidateLifetime = true;

try
{
    var claimsPrincipal = tokenHandler.ValidateToken(encodedToken, tvp, out SecurityToken validatedToken);

    // If no exception, all standard checks passed
}
catch (SecurityTokenValidationException ex)
{
    // Validation failed
}

La clase ExchangeAppContext se define como sigue:

using Newtonsoft.Json;

/// <summary>
/// Representation of the appctx claim in an Exchange user identity token.
/// </summary>
public class ExchangeAppContext
{
    /// <summary>
    /// The Exchange identifier for the user
    /// </summary>
    [JsonProperty("msexchuid")]
    public string ExchangeUid { get; set; }

    /// <summary>
    /// The token version
    /// </summary>
    public string Version { get; set; }

    /// <summary>
    /// The URL to download authentication metadata
    /// </summary>
    [JsonProperty("amurl")]
    public string MetadataUrl { get; set; }
}

Para ver un ejemplo que utiliza esta biblioteca para validar tokens de Exchange y tiene una implementación de GetSigningKeys, consulte Complemento de Outlook: visor de tokens.

Vea también