@@ -39,9 +39,10 @@ No code change is required when using an environment variable—just register Au
 
 Licensing is enforced via log messages at various levels:
 
-- INFO: Valid license message
+- INFO: Valid license message, or license validation is not supported on this platform (see Client Redistribution Scenarios below)
 - WARNING: Missing license message, or a license term that has ended but is still within its grace period
-- ERROR: Invalid/expired license message
+- ERROR: Invalid/expired license message, or a license key that is incomplete or corrupted
+- CRITICAL: The license key could not be validated (see Troubleshooting License Key Validation below)
 
 ### Renewal grace period
 
@@ -106,4 +107,53 @@ The license key should NOT be set as this would result in secrets transmitted to
 builder.Logging.AddFilter("LuckyPennySoftware.AutoMapper.License", LogLevel.None);
 ```
 
-This will depend on your logging setup. A missing/invalid license key does not affect runtime behavior in any way.
+This will depend on your logging setup. A missing/invalid license key does not affect runtime behavior in any way.
+
+If a license key is set on a platform that does not support RSA cryptography, such as Blazor WASM, AutoMapper skips validation and logs an INFO message linking to this section instead of a validation error.
+
+## Troubleshooting License Key Validation
+
+When a license key can't be validated, AutoMapper logs a message describing the problem. The underlying exception is logged separately at `Debug` level; to see it, enable debug logging for the `LuckyPennySoftware.AutoMapper.License` category:
+
+```csharp
+builder.Logging.AddFilter("LuckyPennySoftware.AutoMapper.License", LogLevel.Debug);
+```
+
+### The license key is incomplete or corrupted
+
+The key is missing characters or contains characters that aren't part of a license key. This usually happens when the key is copied from a PDF or an email, where it can be truncated or wrapped across lines.
+
+AutoMapper removes whitespace (spaces, tabs, and line breaks) from the key before validating it, so line breaks and trailing newlines, such as those in Kubernetes secrets created from files, are not a problem. Missing characters can't be recovered: copy the full key again from your [account page](https://luckypennysoftware.com/account).
+
+### The license key signature does not match
+
+The key is well formed but its contents have been changed, usually by a copy/paste or formatting problem. Copy the full key again from your [account page](https://luckypennysoftware.com/account).
+
+Online JWT decoders such as jwt.io can show a damaged key as valid, because they ignore whitespace and don't check the signature against the Lucky Penny Software key. Use your account page as the source of truth.
+
+### The license key is not a Lucky Penny Software license key
+
+The value is a token, but not one issued by Lucky Penny Software. Check that the value you configured (in code or in the `AUTOMAPPER_LICENSE_KEY` or `LUCKYPENNY_LICENSE_KEY` environment variables) is the license key from your [account page](https://luckypennysoftware.com/account).
+
+### Mismatched Microsoft.IdentityModel package versions
+
+AutoMapper validates license keys with the `Microsoft.IdentityModel.JsonWebTokens` package. If your application references different versions of the `Microsoft.IdentityModel.*` packages (for example, through an authentication library that pins an older `Microsoft.IdentityModel.Tokens`), validation fails with an error such as:
+
+```
+System.MissingMethodException: Method not found: 'Void Microsoft.IdentityModel.Tokens.Base64UrlEncoder.Decode(...)'
+```
+
+To find the versions in use, run:
+
+```
+dotnet list package --include-transitive
+```
+
+Then reference the same version of every `Microsoft.IdentityModel.*` package, for example by adding direct references at the highest version in use:
+
+```xml
+<PackageReference Include="Microsoft.IdentityModel.JsonWebTokens" Version="8.14.0" />
+<PackageReference Include="Microsoft.IdentityModel.Tokens" Version="8.14.0" />
+```
+
+If you use [Central Package Management](https://learn.microsoft.com/nuget/consume-packages/central-package-management), you can enable transitive pinning (`CentralPackageTransitivePinningEnabled`) and pin the versions in `Directory.Packages.props`.
@@ -71,4 +71,8 @@ public License(ClaimsPrincipal claims)
     public bool IsPerpetual { get; }
 
     public bool IsConfigured { get; }
+
+    // Set when this platform can't validate license keys (no RSA, e.g. Blazor WASM). The accessor has
+    // already logged client-platform guidance, so validation logs nothing further.
+    public bool IsValidationUnsupported { get; internal set; }
 }
@@ -12,6 +12,12 @@ internal class LicenseAccessor
     internal const string AutoMapperLicenseKeyEnvVariable = "AUTOMAPPER_LICENSE_KEY";
     internal const string SharedLicenseKeyEnvVariable = "LUCKYPENNY_LICENSE_KEY";
 
+    // Shipped binaries live for years, so messages link through redirects on our own domain that can be
+    // repointed when the docs move. Configure these under https://luckypennysoftware.com/go/.
+    internal const string AccountPageLink = "https://luckypennysoftware.com/go/automapper-license-key";
+    internal const string ClientPlatformsLink = "https://luckypennysoftware.com/go/automapper-client-platforms";
+    internal const string IdentityModelVersionsLink = "https://luckypennysoftware.com/go/automapper-identitymodel-versions";
+
     private readonly IGlobalConfiguration _configuration;
     private readonly ILogger _logger;
 
@@ -23,6 +29,9 @@ public LicenseAccessor(IGlobalConfiguration configuration, ILoggerFactory logger
 
     private License _license;
     private readonly object _lock = new();
+    private bool _validationUnsupported;
+
+    internal bool IsValidationUnsupported => _validationUnsupported;
 
     public License Current => _license ??= Initialize();
 
@@ -42,6 +51,11 @@ private License Initialize()
             }
 
             var licenseClaims = ValidateKey(key);
+            if (_validationUnsupported)
+            {
+                return new License { IsValidationUnsupported = true };
+            }
+
             return licenseClaims.Any()
                 ? new License(new ClaimsPrincipal(new ClaimsIdentity(licenseClaims)))
                 : new License();
@@ -69,20 +83,41 @@ private static string NormalizeLicenseKey(string key)
         return new string(key.Where(c => !char.IsWhiteSpace(c)).ToArray());
     }
 
-    private Claim[] ValidateKey(string licenseKey)
+    // RS256 signature over the 2048-bit Lucky Penny key: 256 bytes, base64url-encoded without padding.
+    private const int SignatureLength = 342;
+
+    private static readonly RSAParameters LicenseKeyParameters = new()
     {
-        try
+        Exponent = Convert.FromBase64String("AQAB"),
+        Modulus = Convert.FromBase64String(
+            "2LTtdJV2b0mYoRqChRCfcqnbpKvsiCcDYwJ+qPtvQXWXozOhGo02/V0SWMFBdbZHUzpEytIiEcojo7Vbq5mQmt4lg92auyPKsWq6qSmCVZCUuL/kpYqLCit4yUC0YqZfw4H9zLf1yAIOgyXQf1x6g+kscDo1pWAniSl9a9l/LXRVEnGz+OfeUrN/5gzpracGUY6phx6T09UCRuzi4YqqO4VJzL877W0jCW2Q7jMzHxOK04VSjNc22CADuCd34mrFs23R0vVm1DVLYtPGD76/rGOcxO6vmRc7ydBAvt1IoUsrY0vQ2rahp51YPxqqhKPd8nNOomHWblCCA7YUeV3C1Q==")
+    };
+
+    internal Claim[] ValidateKey(string licenseKey)
+    {
+        if (!IsWellFormed(licenseKey))
         {
-            var handler = new JsonWebTokenHandler();
+            // Never log the key itself.
+            _logger.LogError(
+                "The Lucky Penny software license key appears to be incomplete or corrupted " +
+                "(it may have been truncated when copied). " +
+                "Copy the full key again from " + AccountPageLink + ".");
+            return [];
+        }
 
-            var rsa = new RSAParameters
+        try
+        {
+            // JsonWebTokenHandler swallows a PlatformNotSupportedException from the RSA provider and
+            // reports it as an IDX10511 signature failure, with the original exception only as (PII-hidden)
+            // message text. Probe RSA directly so client platforms such as Blazor WASM are detected (#4662).
+            using (var rsa = RSA.Create())
             {
-                Exponent = Convert.FromBase64String("AQAB"),
-                Modulus = Convert.FromBase64String(
-                    "2LTtdJV2b0mYoRqChRCfcqnbpKvsiCcDYwJ+qPtvQXWXozOhGo02/V0SWMFBdbZHUzpEytIiEcojo7Vbq5mQmt4lg92auyPKsWq6qSmCVZCUuL/kpYqLCit4yUC0YqZfw4H9zLf1yAIOgyXQf1x6g+kscDo1pWAniSl9a9l/LXRVEnGz+OfeUrN/5gzpracGUY6phx6T09UCRuzi4YqqO4VJzL877W0jCW2Q7jMzHxOK04VSjNc22CADuCd34mrFs23R0vVm1DVLYtPGD76/rGOcxO6vmRc7ydBAvt1IoUsrY0vQ2rahp51YPxqqhKPd8nNOomHWblCCA7YUeV3C1Q==")
-            };
+                rsa.ImportParameters(LicenseKeyParameters);
+            }
+
+            var handler = new JsonWebTokenHandler();
 
-            var key = new RsaSecurityKey(rsa)
+            var key = new RsaSecurityKey(LicenseKeyParameters)
             {
                 KeyId = "LuckyPennySoftwareLicenseKey/bbb13acb59904d89b4cb1c85f088ccf9"
             };
@@ -101,19 +136,93 @@ private Claim[] ValidateKey(string licenseKey)
             var validateResult = handler.ValidateTokenAsync(licenseKey, parms).GetAwaiter().GetResult();
             if (!validateResult.IsValid)
             {
-                _logger.LogCritical(validateResult.Exception, "Error validating the Lucky Penny software license key");
+                LogValidationFailure(validateResult.Exception);
             }
 
             return validateResult.ClaimsIdentity?.Claims.ToArray() ?? [];
         }
         catch (PlatformNotSupportedException)
         {
-            _logger.LogInformation(
-                "RSA cryptography is not supported on this platform. " +
-                "For client redistribution scenarios such as Blazor WASM, see: " +
-                "https://docs.automapper.io/en/latest/License-configuration.html#client-redistribution-scenarios");
+            LogPlatformNotSupported();
             return [];
         }
     }
 
+    /// <summary>
+    /// Cheap structural check of a compact JWS: three dot-separated base64url segments, with a
+    /// signature segment of the expected length. Catches keys truncated or mangled by copy/paste.
+    /// </summary>
+    internal static bool IsWellFormed(string licenseKey)
+    {
+        var segments = licenseKey.Split('.');
+        return segments.Length == 3
+            && segments.All(segment => segment.Length > 0 && segment.All(IsBase64UrlChar))
+            && segments[2].Length == SignatureLength;
+
+        static bool IsBase64UrlChar(char c) =>
+            c is >= 'A' and <= 'Z' or >= 'a' and <= 'z' or >= '0' and <= '9' or '-' or '_';
+    }
+
+    internal void LogValidationFailure(Exception exception)
+    {
+        if (ContainsPlatformNotSupported(exception))
+        {
+            LogPlatformNotSupported();
+            return;
+        }
+
+        // IdentityModel's IDX messages aren't actionable for customers (and hide most details unless PII
+        // logging is on), so log a plain message and keep the exception at debug level for support.
+        _logger.LogCritical(exception switch
+        {
+            SecurityTokenInvalidSignatureException =>
+                "The Lucky Penny software license key is not valid: its signature does not match. " +
+                "If the key was copied from a PDF, email, or file, it may have been corrupted; " +
+                "copy the full key again from " + AccountPageLink + ".",
+            _ when ContainsAssemblyMismatch(exception) =>
+                "The Lucky Penny software license key could not be validated because the Microsoft.IdentityModel " +
+                "packages in this application are different versions. Reference the same version of all " +
+                "Microsoft.IdentityModel.* packages (for example, by referencing Microsoft.IdentityModel.JsonWebTokens directly). " +
+                "See " + IdentityModelVersionsLink + ".",
+            SecurityTokenMalformedException or ArgumentException =>
+                "The Lucky Penny software license key appears to be incomplete or corrupted. " +
+                "Copy the full key again from " + AccountPageLink + ".",
+            SecurityTokenInvalidIssuerException or SecurityTokenInvalidAudienceException =>
+                "The Lucky Penny software license key is not valid: it is not a Lucky Penny Software license key. " +
+                "Copy your license key from " + AccountPageLink + ".",
+            _ =>
+                "Error validating the Lucky Penny software license key. " +
+                "Copy the full key again from " + AccountPageLink + ". " +
+                "If the problem persists, enable debug logging for this category and contact support."
+        });
+        _logger.LogDebug(exception, "License key validation failure details");
+    }
+
+    internal static bool ContainsPlatformNotSupported(Exception exception) =>
+        exception switch
+        {
+            null => false,
+            PlatformNotSupportedException => true,
+            AggregateException aggregate => aggregate.InnerExceptions.Any(ContainsPlatformNotSupported),
+            _ => ContainsPlatformNotSupported(exception.InnerException)
+        };
+
+    // Mixed Microsoft.IdentityModel.* package versions surface as IDX14102 wrapping a MissingMethodException.
+    internal static bool ContainsAssemblyMismatch(Exception exception) =>
+        exception switch
+        {
+            null => false,
+            MissingMemberException or TypeLoadException or FileLoadException => true,
+            AggregateException aggregate => aggregate.InnerExceptions.Any(ContainsAssemblyMismatch),
+            _ => ContainsAssemblyMismatch(exception.InnerException)
+        };
+
+    private void LogPlatformNotSupported()
+    {
+        _validationUnsupported = true;
+        _logger.LogInformation(
+                "RSA cryptography is not supported on this platform. " +
+                "For client redistribution scenarios such as Blazor WASM, see: " +
+                ClientPlatformsLink);
+    }
 }
@@ -25,6 +25,11 @@ public void Validate(License license)
     {
         var errors = new List<string>();
 
+        if (license is { IsValidationUnsupported: true })
+        {
+            return;
+        }
+
         if (license is not { IsConfigured: true })
         {
             var message = "You do not have a valid license key for the Lucky Penny software AutoMapper. " +
Original file line number	Diff line number	Diff line change
`@@ -71,4 +71,8 @@ public License(ClaimsPrincipal claims)`
`71`	`71`	`public bool IsPerpetual { get; }`
`72`	`72`
`73`	`73`	`public bool IsConfigured { get; }`
	`74`	`+`
	`75`	`+ // Set when this platform can't validate license keys (no RSA, e.g. Blazor WASM). The accessor has`
	`76`	`+ // already logged client-platform guidance, so validation logs nothing further.`
	`77`	`+ public bool IsValidationUnsupported { get; internal set; }`
`74`	`78`	`}`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,11 @@ public void Validate(License license)`
`25`	`25`	`{`
`26`	`26`	`var errors = new List<string>();`
`27`	`27`
	`28`	`+ if (license is { IsValidationUnsupported: true })`
	`29`	`+ {`
	`30`	`+ return;`
	`31`	`+ }`
	`32`	`+`
`28`	`33`	`if (license is not { IsConfigured: true })`
`29`	`34`	`{`
`30`	`35`	`var message = "You do not have a valid license key for the Lucky Penny software AutoMapper. " +`