How to check if Microsoft Graph API access token has expired?

You can determine if a Microsoft Graph API access token has expired by decoding the JSON Web Token (JWT) payload and comparing its exp (expiration time) claim against the current UTC time. This approach avoids making unnecessary HTTP requests and allows your WPF application to proactively refresh tokens before they fail, ensuring seamless API interactions.

Understanding JWT Structure

A Microsoft Graph access token is a JSON Web Token (JWT), which consists of three parts separated by dots: the header, the payload, and the signature. The header contains metadata about the token type, while the signature ensures the token has not been tampered with. The payload carries the claims, including critical information such as the user identifier, scopes granted, and most importantly, the expiration timestamp.

To check for expiration, you only need to inspect the payload. Since the signature is used for validation rather than data extraction, you do not need to verify the cryptographic signature unless you are building a custom authentication service. For client-side applications like WPF apps using Microsoft.Identity.Client, reading the raw payload is safe and efficient because the token was issued by Microsoft's identity provider.

Decoding the Token in C#

The most reliable way to decode the token without external dependencies is to use the built-in System.Text.Json namespace available in modern .NET versions. You must split the token string by the period character (.) to isolate the middle segment, which holds the base64url-encoded payload. Once isolated, this segment requires standard base64url decoding to convert it into a readable JSON string.

Base64url encoding differs slightly from standard Base64; it uses hyphens instead of plus signs and underscores instead of forward slashes, and it omits padding characters. Your decoding logic must handle these substitutions to ensure the resulting byte array converts correctly to a UTF-8 string. If you miss these steps, the JSON parser will throw an exception due to invalid characters.

using System;
using System.Text;
using System.Text.Json;

public bool IsTokenExpired(string accessToken)
{
    var parts = accessToken.Split('.');
    if (parts.Length != 3)
        throw new ArgumentException("Invalid token format");

    var payloadBase64Url = parts[1];
    
    // Replace URL-safe characters with standard Base64 characters
    var payloadBase64 = payloadBase64Url.Replace('-', '+').Replace('_', '/');
    
    // Add padding if necessary
    switch (payloadBase64.Length % 4)
    {
        case 2: payloadBase64 += "=="; break;
        case 3: payloadBase64 += "="; break;
    }

    var bytes = Convert.FromBase64String(payloadBase64);
    var jsonPayload = Encoding.UTF8.GetString(bytes);

    using var doc = JsonDocument.Parse(jsonPayload);
    var root = doc.RootElement;
    
    // Get the 'exp' claim as a numeric value
    if (!root.TryGetProperty("exp", out var expElement))
        return true; // Treat missing expiry as expired for safety

    long expirationTimestamp = expElement.GetInt64();
    long currentTimestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();

    return currentTimestamp >= expirationTimestamp;
}

Integrating with WPF and MSAL

In a WPF application, you typically acquire tokens using the Microsoft Authentication Library (MSAL). While MSAL caches tokens and automatically handles refreshes, there are scenarios where you need explicit control, such as when passing the token to a background service or logging token lifecycle events. By implementing the decoding method above, you can wrap your token acquisition logic to check status before usage.

It is crucial to compare the token's expiration against DateTimeOffset.UtcNow rather than local time. Servers operate on UTC, and any discrepancy between local system time and server time can lead to premature or delayed expiration checks. Additionally, consider adding a small buffer, such as subtracting 5 minutes from the expiration time, to account for clock skew between your machine and Microsoft's servers.

If you are dealing with large datasets, remember that frequent token checks do not impact performance significantly, but excessive API calls do. For pagination strategies, refer to our guide on optimizing record counts to maintain efficiency alongside token management.

Handling Expiration Scenarios

When the IsTokenExpired method returns true, your application should trigger a silent login flow using MSAL's AcquireTokenSilentAsync. This method attempts to retrieve a new access token using the cached refresh token without prompting the user. If the refresh token is also expired or invalid, the method will fail, requiring you to fall back to AcquireTokenInteractive to prompt the user for credentials again.

Never store the decoded expiration state globally without re-checking, as token lifetimes can change based on security policies enforced by the administrator. Always perform the check immediately before making the Graph API call. This ensures that even if the token was valid seconds ago, it remains valid at the moment of transmission.

Common Pitfalls

One common error is attempting to parse the entire token as JSON directly. This fails because the header and signature are not valid JSON objects on their own. Another pitfall is ignoring the timezone; using DateTime.Now introduces daylight saving time complications that can cause unexpected failures during seasonal transitions. Stick strictly to Unix timestamps and UTC comparisons for consistency.

For developers encountering database connectivity issues during these flows, ensure that network configurations allow MSAL to reach Microsoft's endpoints. Troubleshooting connection errors often involves checking proxy settings similar to those discussed when diagnosing containerized database connections.

Frequently Asked Questions

Can I verify the token signature in my WPF app?

Verifying the signature requires fetching Microsoft's public keys from the well-known OpenID configuration endpoint. This adds significant complexity and latency, so it is generally recommended to trust the token issued by MSAL unless you are building a backend service that receives tokens from external clients.

What happens if the exp claim is missing?

If the exp claim is absent, the token technically never expires according to the JWT standard, but Microsoft always includes it. For safety, treat missing claims as expired and force a re-authentication to prevent potential security vulnerabilities or indefinite session states.

Does refreshing a token invalidate the old one immediately?

No, MSAL maintains a cache of both access and refresh tokens. When you acquire a new access token, the old one remains valid until its natural expiration. However, relying on the old token is risky if the user's session is revoked server-side, so always use the newly acquired token for subsequent requests.

How do I handle multiple tenants in a single WPF app?

If your app supports multi-tenant access, ensure that the token decoding logic is tenant-agnostic. The exp claim structure is identical across all Microsoft Entra ID tenants, so the same decoding method works regardless of the organization issuing the token.

Is there a simpler library for decoding JWTs?

You can use third-party libraries like System.IdentityModel.Tokens.Jwt which provide a JwtSecurityTokenHandler class. This simplifies parsing by handling base64url decoding and JSON serialization internally, reducing the amount of boilerplate code required in your project.