Creating a custom model binder for encrypted query strings in MVC

Query strings are convenient for search filters, invitations, report parameters and deep links. They are also visible in browser history, server logs, analytics tools, proxy records and referrer headers. If a URL carries an internal customer identifier, pricing rule or workflow state, ordinary query-string binding exposes more information than the application may intend.

A custom model binder provides a clean boundary between that URL token and the strongly typed object used by an ASP.NET MVC action. The controller receives a validated request model instead of manually decoding, decrypting and deserialising values in every action.

This pattern fits well with the practical, cross-platform themes found in the C# Corner conference, particularly sessions covering Microsoft Azure, web development, DevOps and application security. The implementation below focuses on classic ASP.NET MVC, while noting the corresponding choices for ASP.NET Core.

Why protect values in a query string

Encoding is not encryption. URL encoding changes characters so that a value can travel safely in a URL, while Base64 changes its representation. Neither prevents someone from reading or modifying the content. A signed token can reveal its contents while proving that it has not been altered; an encrypted token provides confidentiality as well as integrity.

A useful Australian example is a customer portal serving users in Sydney, Melbourne and Perth. A report link may contain an account number, date range and permission context. Even when the portal uses HTTPS, those values can still appear in application diagnostics or a copied browser URL. Encryption reduces exposure, although it does not make a URL a suitable place for passwords, payment details or large documents.

The binder should therefore enforce a narrow contract. It should read one parameter, reject malformed or oversized input, decrypt with an authenticated protection mechanism, deserialise into a known type and leave business validation to the model or service layer. It should never silently fall back to an unprotected version of the same data.

Select authenticated protection and a safe token format

For ASP.NET MVC on .NET Framework, MachineKey.Protect is a practical option when the application is configured consistently across its servers. It provides encryption and tamper detection, and the application can isolate tokens by assigning a specific purpose string. In a web farm, every node must share the relevant machine-key configuration; otherwise, a link created on one node may fail when opened on another.

The protected bytes need a URL-safe representation. HttpServerUtility.UrlTokenEncode is suitable for classic MVC because it avoids characters such as +, / and = that can be awkward in query strings. A short lifetime, a version marker and an optional audience value can be included in the protected payload. Do not put the encryption key in web.config source control or in the URL itself.

using System.Text;
using System.Web;
using System.Web.Security;
using Newtonsoft.Json;

public static class QueryToken
{
    private const string Purpose = "Portal.EncryptedQuery.v1";

    public static string Create<T>(T value)
    {
        var json = JsonConvert.SerializeObject(value);
        var plainBytes = Encoding.UTF8.GetBytes(json);
        var protectedBytes = MachineKey.Protect(plainBytes, Purpose);

        return HttpServerUtility.UrlTokenEncode(protectedBytes);
    }

    public static T Read<T>(string token)
    {
        var protectedBytes = HttpServerUtility.UrlTokenDecode(token);
        if (protectedBytes == null)
            throw new InvalidOperationException("The token is not valid.");

        var plainBytes = MachineKey.Unprotect(protectedBytes, Purpose);
        if (plainBytes == null)
            throw new InvalidOperationException("The token cannot be authenticated.");

        var json = Encoding.UTF8.GetString(plainBytes);
        return JsonConvert.DeserializeObject<T>(json);
    }
}

MachineKey.Unprotect authenticates the ciphertext before returning plaintext, so an attacker cannot safely alter an account ID or permission flag. For Azure-hosted systems, keep key management aligned across instances and deployment slots. A production application may instead use an external key-management service, provided the protection library still offers authenticated encryption and reliable key rotation.

Define a small request model

The model should contain only values needed by the endpoint. A report link might use a customer reference, a date range and a display mode, rather than serialising an entire domain entity. Smaller payloads produce shorter URLs and reduce the effect of accidental disclosure.

public sealed class ReportQuery
{
    public string CustomerReference { get; set; }
    public DateTime From { get; set; }
    public DateTime To { get; set; }
    public string Format { get; set; }
}

Avoid accepting arbitrary .NET types or enabling Newtonsoft.Json TypeNameHandling for a token supplied by a browser. Deserialise into a fixed model and apply allow-lists to fields such as Format. A user might change a valid token only by breaking its authentication, but authorised users can still create links with values that are valid cryptographically and inappropriate for the business.

Expiry and replay controls belong in the payload or in server-side state. For example, include IssuedAt, ExpiresAt and a random token identifier, then reject expired values and optionally record used identifiers. Encryption does not automatically prevent a legitimate token from being copied and replayed.

Build the MVC model binder

The binder retrieves the encrypted value through MVC’s value provider, which means it works with the normal query-string pipeline. It should use the parameter name supplied by the action, impose a length limit and convert all expected failures into model-state errors. Returning a detailed cryptographic exception to the browser would disclose implementation information.

using System;
using System.Text;
using System.Web;
using System.Web.Mvc;
using Newtonsoft.Json;

public sealed class EncryptedQueryModelBinder : IModelBinder
{
    private const string Purpose = "Portal.EncryptedQuery.v1";
    private const int MaximumTokenLength = 4096;

    public object BindModel(
        ControllerContext controllerContext,
        ModelBindingContext bindingContext)
    {
        var value = bindingContext.ValueProvider
            .GetValue(bindingContext.ModelName);

        if (value == null || String.IsNullOrWhiteSpace(value.AttemptedValue))
        {
            bindingContext.ModelState.AddModelError(
                bindingContext.ModelName, "A query token is required.");
            return null;
        }

        var token = value.AttemptedValue;
        if (token.Length > MaximumTokenLength)
        {
            bindingContext.ModelState.AddModelError(
                bindingContext.ModelName, "The query token is too large.");
            return null;
        }

        try
        {
            var protectedBytes = HttpServerUtility.UrlTokenDecode(token);
            var plainBytes = MachineKey.Unprotect(protectedBytes, Purpose);

            if (plainBytes == null)
                throw new InvalidOperationException();

            var json = Encoding.UTF8.GetString(plainBytes);
            return JsonConvert.DeserializeObject(
                json, bindingContext.ModelType);
        }
        catch (Exception ex) when (
            ex is ArgumentException ||
            ex is InvalidOperationException ||
            ex is JsonException)
        {
            bindingContext.ModelState.AddModelError(
                bindingContext.ModelName, "The query token is invalid.");
            return null;
        }
    }
}

In a real application, catch only the exceptions expected from malformed input and log a safe event identifier rather than the token or decrypted JSON. A null protected byte array should be handled before calling the unprotect method if the selected framework version does not accept null input. Add data annotations or a separate validator after binding so that date ranges, customer access and permitted formats are checked consistently.

Register and consume the binder

The global registration option is straightforward:

public static class MvcConfig
{
    public static void RegisterBinders()
    {
        ModelBinders.Binders.Add(
            typeof(ReportQuery),
            new EncryptedQueryModelBinder());
    }
}

Call the registration method during application startup. An action can then receive a typed object:

public ActionResult Report(ReportQuery query)
{
    if (!ModelState.IsValid)
        return new HttpStatusCodeResult(400);

    // Authorise query.CustomerReference before loading report data.
    return View(query);
}

For a binder used by only one endpoint, an attribute can make the dependency explicit:

public ActionResult Report(
    [ModelBinder(typeof(EncryptedQueryModelBinder))]
    ReportQuery query)
{
    if (!ModelState.IsValid)
        return new HttpStatusCodeResult(400);

    return View(query);
}

The URL generator must use the same parameter name expected by the action. For example, ?query=... binds naturally to ReportQuery query, while ?token=... requires a matching parameter name or a binder that deliberately reads token. This small detail often causes confusion during testing, especially when a developer is switching between local IIS Express and a hosted environment in Brisbane or Canberra.

Test the boundary and operational behaviour

Tests should cover a valid token, a modified character, an expired payload, an empty value, invalid Base64-like input, oversized input and JSON with an unexpected property. Verify that each invalid case produces a model-state error and a controlled HTTP response. Test links generated by every deployment node when the application runs behind a load balancer.

Logging needs special care. Record the route, outcome, correlation ID and perhaps a hash of the token, but never the raw query string or decrypted object. Australian organisations handling personal information should consider the Privacy Act and the Australian Privacy Principles when deciding what appears in logs, support tickets and analytics platforms. This is especially important for health, education and financial services.

The following approaches solve different problems and should not be treated as interchangeable:

Keep tokens short enough for browsers, email clients and reverse proxies. An encrypted query string is still part of a URL, and URLs can be truncated or copied. Where a link becomes too large, store the state server-side and send an opaque, expiring identifier instead.

Adapt the pattern for ASP.NET Core

ASP.NET Core uses a different dependency-injection model and normally combines IModelBinder, IModelBinderProvider and IDataProtector. The conceptual flow remains the same: obtain the named value, unprotect it with a purpose, deserialise to a known request type, validate it and add a model-state error when the token fails.

IDataProtectionProvider.CreateProtector("Portal.EncryptedQuery.v1") is preferable to implementing cryptography directly. In Azure App Service or a container platform, persist and share the data-protection key ring across instances and deployment changes. Otherwise, a restart or slot swap can invalidate links unexpectedly. Key rotation should be planned so that old tokens remain readable only for their intended lifetime.

A custom binder is most useful when the encrypted value represents a coherent request object. It should not become a general-purpose bypass around authorisation. The controller or service must still check the current user’s permissions against the decrypted customer reference, enforce expiry, apply business rules and avoid placing secrets in URLs. With those boundaries in place, encrypted query binding gives MVC applications a predictable way to handle protected links across Australian networks, cloud regions and multi-server deployments.