迁移至Azure.Storage.Blobs后写入Blob元数据报AuthenticationFailed错误

核心原因 #

从服务端返回的待签名字符串可以直接定位问题：待签名内容包含x-ms-meta-testmetadata:Test Data，元数据值中存在空格，新旧SDK的签名处理逻辑差异直接导致签名不匹配：

• 已弃用的旧版WindowsAzure.Storage库在计算签名前，会自动对元数据的键值做标准化处理：自动修剪首尾空白、对特殊字符做编码适配后再参与签名计算。
• 新版Azure.Storage.Blobs（v12系列SDK）默认直接使用传入的元数据原始值拼接待签名字符串，不会自动做标准化修正。
• 普通Blob上传、下载、删除等读写操作不会将自定义元数据加入签名计算范围，因此不会触发认证错误；只有SetMetadata接口会把所有x-ms-meta-*请求头全量纳入签名计算，一旦元数据内容存在不符合签名规则的字符，就会出现MAC签名不匹配的403错误。
  你提到测试前几小时运行正常，是因为前期测试写入的元数据都是无空格、无特殊字符的纯文本内容，后续写入带空格的Test Data时才触发了该问题。

排查思路 #

• 第一步检查传入SetMetadata的字典内容：确认元数据键是否仅包含字母、数字、下划线，无特殊符号、空格；元数据值是否包含非ASCII字符、首尾空格、换行、制表符等特殊内容。
• 第二步开启SDK的诊断日志，拿到本地SDK生成的待签名字符串，和服务端返回的待签名字符串逐行比对x-ms-meta-开头的行，定位字符不一致、空白字符数量不匹配的具体位置。
• 第三步检查是否自定义了请求管道策略：如果在SDK完成签名计算后，通过自定义策略修改了任何x-ms-meta-相关请求头，也会直接导致签名和服务端计算结果不一致。

解决方案 #

• 写入元数据前主动对键值做标准化处理，参考实现代码如下：

public IDictionary<string, string> MetaData
{
    get
    {
        IDictionary<string, string> Result = new Dictionary<string, string>();
        Retry( () =>
               {
                   var Props = BlobClient.GetProperties();
                   Result = Props.Value.Metadata;
               } );
        return Result;
    }

    set
    {
        var safeMetadata = new Dictionary<string, string>();
        foreach (var kvp in value)
        {
            // 元数据键不区分大小写，统一转小写、修剪首尾空白，避免大小写/空白导致的签名差异
            string safeKey = kvp.Key.Trim().ToLowerInvariant();
            // 修剪元数据值首尾空白，移除不可见控制字符
            string safeValue = new string(kvp.Value?.Trim().Where(c => !char.IsControl(c)).ToArray());
            safeMetadata.Add(safeKey, safeValue);
        }
        Retry( () =>
               {
                   BlobClient.SetMetadata(safeMetadata);
               } );
    }
}

• 如果你当前使用的Azure.Storage.Blobs版本低于12.10.0，直接升级到最新稳定版，早期v12版本存在元数据含特殊字符时签名计算错误的已知问题，后续版本已完成修复。
• 不要在SDK签名流程完成后，通过自定义HttpPipelinePolicy修改任何x-ms-前缀的请求头，避免破坏签名一致性。

内容的提问来源于stack exchange，提问作者Terry151151