Validar um token de identidade do Exchange

Artigo
11/13/2024

Importante

Os tokens legados do Exchange foram preteridos. A partir de fevereiro de 2025, vamos começar a desativar a identidade de utilizador e os tokens de chamada de retorno legados do Exchange para Exchange Online inquilinos. Para obter os detalhes e linha do tempo, consulte a nossa página de FAQ. Isto faz parte da Iniciativa Secure Future da Microsoft, que fornece às organizações as ferramentas necessárias para responder ao cenário de ameaças atual. Os tokens de identidade de utilizador do Exchange continuarão a funcionar para o Exchange no local. A autenticação de aplicações aninhadas é a abordagem recomendada para tokens em curso.

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, calcule um identificador exclusivo para o utilizador ao concatenar o ID do Exchange do utilizador com o 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, deve marcar o seguinte:

Verifique o cabeçalho e verifique se:
- typ A afirmação está definida como JWT.
- alg A afirmação está definida como RS256.
- x5t a afirmação está presente.
Verifique o payload e verifique se:
- amurl A afirmação dentro do appctx está definida como a localização de um ficheiro 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 secção seguinte Verificar o domínio para obter informações adicionais.
- A hora atual é entre as horas especificadas nas nbf afirmaçõ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 claim é o URL esperado para o seu suplemento.
- version A afirmação dentro da appctx afirmação está definida como ExIdTok.V1.

Verificar o domínio

Ao implementar a lógica de verificação descrita na secção anterior, também tem de exigir que o domínio da amurl afirmação corresponda ao domínio de Deteção Automática do utilizador. Para tal, terá de utilizar ou implementar a Deteção Automática para o Exchange.

Por Exchange Online, confirme se amurl é um domínio conhecido (https://outlook.office365.com:443/autodiscover/metadata/json/1) ou pertence a uma cloud geográfica específica ou especializada (Office 365 URLs e intervalos de endereços IP).
Se o seu serviço de suplemento tiver uma configuração pré-existente com o inquilino do utilizador, pode determinar se é amurl fidedigno.
Para uma implementação híbrida do Exchange, utilize a Deteção Automática baseada em OAuth para verificar o domínio esperado para o utilizador. No entanto, embora o utilizador tenha de se autenticar como parte do fluxo de Deteção Automática, o suplemento nunca deve recolher as credenciais do utilizador e efetuar a autenticação básica.

Se o seu suplemento não conseguir verificar a amurl utilização de nenhuma destas opções, pode optar por encerrar o suplemento corretamente com uma notificação adequada ao utilizador se for necessária autenticação 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 o URL do documento de metadados de autenticação com o identificador do Exchange para a conta. Quando tiver este identificador exclusivo, utilize-o para criar um sistema de início de sessão único (SSO) para o seu serviço Web de suplementos 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 utilizada para validar os tokens de identidade de utilizador do Exchange.

Importante

Já não recomendamos a API Gerida dos Serviços Web exchange porque a Microsoft.Exchange.WebServices.Auth.dll, embora ainda disponível, é obsoleta e depende de bibliotecas não suportadas, 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.

Partilhar via