elsa-workflows/elsa-core · error · InvalidOperationException

The External Authentication shared handle-hashing key must…

Error message

The External Authentication shared handle-hashing key must be valid base64 containing at least 32 bytes.

What it means

When HandleHashing.SharedKeyBase64 is set, GetKey decodes it and requires at least 32 bytes (256 bits) of key material for HMAC-SHA-256. If the value is not valid base64, or decodes to fewer than 32 bytes, the hasher throws this InvalidOperationException rather than hashing with a weak or malformed key. An empty/whitespace value is allowed and means 'use a process-local random key'.

Solutions

Generate a correct key and reconfigure: openssl rand -base64 32 (or RandomNumberGenerator.GetBytes(32)), then set ExternalAuthentication:HandleHashing:SharedKeyBase64 to that value — it must decode to exactly 32+ bytes.
If you only run a single node or develop locally, remove the SharedKeyBase64 value entirely so the hasher falls back to a process-local random key.
Fix base64 formatting: strip quotes/newlines/whitespace and confirm the string round-trips (Convert.FromBase64String succeeds and yields >= 32 bytes).
Check the startup options validator output, which reports the actionable configuration error before the hasher throws.

Example fix

// before (16-byte key, too short)
"HandleHashing": { "SharedKeyBase64": "c2hvcnRrZXkxMjM0NTY3OA==" }

// after (32-byte key)
// generated via: openssl rand -base64 32
"HandleHashing": { "SharedKeyBase64": "qU9uHm3P8Zo7v2sL0kXwRbJcN1dEfGhIjKlMnOpQrStUvWxYz=" }

Defensive patterns

Strategy: validation

Validate before calling

// validate SharedKeyBase64 before configuring
var value = configuration["ExternalAuthentication:HandleHashing:SharedKeyBase64"];
if (!string.IsNullOrWhiteSpace(value))
{
    byte[] key;
    try { key = Convert.FromBase64String(value); }
    catch (FormatException) { throw new InvalidOperationException("SharedKeyBase64 is not valid base64."); }
    if (key.Length < 32)
        throw new InvalidOperationException($"SharedKeyBase64 must decode to >= 32 bytes (got {key.Length}).");
}
// generate: Convert.ToBase64String(RandomNumberGenerator.GetBytes(32))

Type guard

static bool IsValidSharedKey(string? sharedKeyBase64)
{
    if (string.IsNullOrWhiteSpace(sharedKeyBase64)) return true; // empty means process-local key
    try { return Convert.FromBase64String(sharedKeyBase64).Length >= 32; }
    catch (FormatException) { return false; }
}

Try / catch

try
{
    var hasher = new HmacExternalAuthenticationHandleHasher(optionsAccessor);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("valid base64 containing at least 32 bytes"))
{
    logger.LogError(ex, "Invalid ExternalAuthentication:HandleHashing:SharedKeyBase64 — must be base64 of >= 32 bytes.");
    throw;
}

Prevention

Generate keys only with openssl rand -base64 32 or RandomNumberGenerator.GetBytes(32) — never hand-type or reuse a 128-bit key.
Keep the value free of quotes, newlines, and trailing whitespace when injecting via environment variables or secrets managers.
Enable the options validator on startup so config errors surface with an actionable message before the hasher throws.
Use the same 32-byte key on every node of a multi-node deployment so hashed handles remain stable.

When it happens

Trigger: Setting ExternalAuthentication:HandleHashing:SharedKeyBase64 to a string that is not valid base64 (FormatException swallowed, then thrown), or to valid base64 that decodes to under 32 bytes (e.g. a 16-byte key). Thrown when the hasher is constructed (options evaluated in the constructor), typically at application startup.

Common situations: Typing a hex or plain-text secret into SharedKeyBase64 instead of base64; generating a key with a 128-bit tool (e.g. openssl rand -base64 16) instead of 32 bytes; copy/paste introducing whitespace, quotes, or line breaks; changing config between multi-node deployments without re-generating a proper shared key.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/0bf9ac63292cf5a9. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.ExternalAuthentication/Services/HmacExternalAuthenticationHandleHasher.cs:62

            throw new InvalidOperationException("External Authentication handle-hashing settings are required.");

        if (string.IsNullOrWhiteSpace(options.SharedKeyBase64))
            return RandomNumberGenerator.GetBytes(32);

        try
        {
            var key = Convert.FromBase64String(options.SharedKeyBase64);
            if (key.Length >= 32)
                return key;

            CryptographicOperations.ZeroMemory(key);
        }
        catch (FormatException)
        {
            // The options validator reports the actionable configuration error at startup.
        }

        throw new InvalidOperationException("The External Authentication shared handle-hashing key must be valid base64 containing at least 32 bytes.");
    }
}

View on GitHub (pinned to fe9217bdfa)