Validar um token de identidade do Exchange

Artigo
04/11/2024

Importante

Tokens de identidade de usuário do Exchange Herdado e tokens de retorno de chamada serão desativados para todos os locatários Exchange Online em outubro de 2024 como parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário atual de ameaças. Os tokens de identidade do usuário do Exchange ainda funcionarão para o Exchange local. A autenticação de aplicativo aninhada é a abordagem recomendada para tokens daqui para frente. Para obter mais informações, confira nossa postagem no blog sobre autenticação de aplicativo aninhado e tokens herdados do Exchange.

O suplemento do Outlook pode enviar um token de identidade do usuário do Exchange, mas, antes de você confiar na solicitação, deve validar o token para garantir que tenha sido enviado pelo servidor Exchange solicitado. Os tokens de identidade do usuário do Exchange são JSON Web Tokens (JWT). As etapas necessárias para validar um JWT estão descritas em RFC 7519 Token Web JSON (JWT).

Sugerimos que você use um processo de quatro etapas para validar o token de identidade e obter o identificador exclusivo do usuário. Em primeiro lugar, extraia o Token Web JSON (JWT) de uma cadeia de caracteres codificada como URL em Base64. Em segundo lugar, verifique se o token foi bem elaborado, se foi criado para um suplemento do Outlook e se não expirou. Além disso, verifique se é possível extrair uma URL válida para o documento dos metadados de autenticação. Em seguida, recupere o documento dos metadados de autenticação do servidor Exchange e valide a assinatura anexada ao token de identidade. Por fim, compute um identificador exclusivo para o usuário concatenando a ID do Exchange do usuário com a URL do documento de metadados de autenticação.

Extrair o Token Web JSON

O token retornado de getUserIdentityTokenAsync é uma representação da cadeia de caracteres codificada do token. Neste formulário, de acordo com o 7519 RFC, todos os JWTs têm três partes separadas por um ponto. O formato deve ser o seguinte.

{header}.{payload}.{signature}

O cabeçalho e a carga devem estar decodificados em Base64 para obter uma representação JSON de todas as partes. A assinatura deverá estar codificada em Base64 para obter uma matriz de bytes contendo a assinatura binária.

Para saber mais sobre o conteúdo do token, confira Dentro do token de identidade do Exchange.

Depois que tiver os três componentes decodificados, prossiga com a validação do conteúdo do token.

Validar o conteúdo do token

Para validar o conteúdo do token, você deve marcar o seguinte:

Verifique o cabeçalho e verifique se:
- typ a declaração está definida como JWT.
- alg a declaração está definida como RS256.
- x5t a declaração está presente.
Verifique a carga e verifique se:
- amurl a declaração dentro do appctx é definida como o local de um arquivo de manifesto de chave de assinatura de token autorizado. Por exemplo, o valor esperado amurl para o Microsoft 365 é https://outlook.office365.com:443/autodiscover/metadata/json/1. Consulte a próxima seção Verificar o domínio para obter informações adicionais.
- O tempo atual é entre os horários especificados nas nbf declarações e exp . A declaração nbf especifica a primeira hora que o token é considerado válido e a declaração exp especifica a hora de expiração do token. Isso é recomendável para permitir algumas variações nas configurações do relógio entre servidores.
- aud a declaração é a URL esperada para seu suplemento.
- version a declaração dentro da appctx declaração está definida como ExIdTok.V1.

Verificar o domínio

Ao implementar a lógica de verificação descrita na seção anterior, você também deve exigir que o domínio da amurl declaração corresponda ao domínio Autodiscover para o usuário. Para fazer isso, você precisará usar ou implementar o Autodiscover para Exchange.

Para Exchange Online, confirme se o amurl é um domínio bem conhecido (https://outlook.office365.com:443/autodiscover/metadata/json/1) ou pertence a uma nuvem específica ou especialidade geográfica (Office 365 URLs e intervalos de endereços IP).
Se o serviço de suplemento tiver uma configuração pré-existente com o locatário do usuário, você poderá estabelecer se isso amurl é confiável.
Para uma implantação híbrida do Exchange, use Autodiscover baseada em OAuth para verificar o domínio esperado para o usuário. No entanto, enquanto o usuário precisará se autenticar como parte do fluxo de Descoberta Automática, o suplemento nunca deve coletar as credenciais do usuário e fazer a autenticação básica.

Se o suplemento não puder verificar o amurl uso de nenhuma dessas opções, você poderá optar por desligar o suplemento normalmente com uma notificação apropriada ao usuário se a autenticação for necessária para o fluxo de trabalho do suplemento.

Validar a assinatura do token de identidade

Após saber que o JWT contém as declarações necessárias, prossiga com a validação da assinatura do token.

Recuperar a chave de assinatura pública

A primeira etapa é recuperar a chave pública que corresponde ao certificado que o servidor do Exchange usou para assinar o token. A chave está localizada no documento dos metadados de autenticação. Este documento é um arquivo JSON hospedado na URL especificada na declaração amurl.

O documento dos metadados de autenticação utiliza o seguinte 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"
        }
    ]
}

As teclas de assinatura disponíveis estão na matriz keys. Escolha a chave correta, garantindo que o valor x5t na propriedade keyinfo corresponda ao valor x5t no cabeçalho do token. A chave pública está dentro da propriedade value na propriedade keyvalue armazenada como uma matriz de bytes codificada em Base64.

Quando você tiver a chave pública correta, verifique a assinatura. Os dados assinados são as duas primeiras partes do token codificado, separados por um ponto:

{header}.{payload}

Calcular a ID exclusiva para uma conta do Exchange

Crie um identificador exclusivo para uma conta do Exchange ao concatenar a URL do documento de metadados de autenticação com o identificador do Exchange para a conta. Quando você tiver esse identificador exclusivo, use-o para criar um sistema SSO (logon único) para seu serviço Web de suplemento do Outlook. Para obter detalhes sobre como usar o identificador exclusivo para SSO, confira Autenticar um usuário com um token de identidade do Exchange.

Usar uma biblioteca para validar o token

Há diversas bibliotecas que podem fazer a análise e validação de um JWT geral. A Microsoft fornece a System.IdentityModel.Tokens.Jwt biblioteca que pode ser usada para validar tokens de identidade de usuário do Exchange.

Importante

Não recomendamos mais a API Gerenciada dos Serviços Web do Exchange porque o Microsoft.Exchange.WebServices.Auth.dll, embora ainda disponível, agora está obsoleto e depende de bibliotecas sem suporte, como Microsoft.IdentityModel.Extensions.dll.

System.IdentityModel.Tokens.Jwt

A biblioteca System.IdentityModels.Tokens.Jwt pode analisar o token e também fazer a validação necessária para analisar a declaração appctx por conta própria e recuperar a chave de assinatura pública.

// 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
}

A classe ExchangeAppContext é definida da seguinte maneira:

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 obter um exemplo que usa essa biblioteca para validar tokens do Exchange e tem uma implementação de GetSigningKeys, confira Outlook-Add-In-Token-Viewer.

Compartilhar via