Azure AD v2迁移后ID Token缺失email声明及备用邮箱获取诉求

我之前也碰到过类似的情况！核心问题其实是Azure AD v2对邮箱声明的返回规则——默认的email声明只会返回用户的主邮箱（Primary Email），如果这个字段是空的，哪怕你申请了email scope、配置了常规的可选声明，都拿不到值。而你看到的Alternate Email对应AAD里的otherMails属性，这个不会自动出现在ID Token里，得单独配置才行。

下面是具体的解决步骤：

1. 在应用注册清单中配置otherMails可选声明 #

登录Azure门户，找到你的应用注册，进入清单编辑页面，找到optionalClaims节点，添加idToken类型的otherMails声明：

"optionalClaims": {
  "idToken": [
    {
      "name": "otherMails",
      "source": null,
      "essential": false,
      "additionalProperties": []
    }
  ],
  // 保留你之前配置的其他可选声明（比如given_name、family_name）
  "accessToken": [],
  "saml2Token": []
}

保存清单后，Azure AD就会在ID Token中返回用户的备用邮箱列表（注意这是一个数组，因为用户可以绑定多个备用邮箱）。

2. 在代码中读取otherMails声明 #

因为原来的逻辑依赖email声明，现在需要调整代码，当email为空时，从otherMails里取备用邮箱。示例代码如下：

// 先尝试获取主邮箱
var email = User.FindFirst(ClaimTypes.Email)?.Value;

if (string.IsNullOrEmpty(email))
{
    // 尝试获取备用邮箱（ID Token中是JSON数组字符串）
    var otherMailsClaim = User.FindFirst("otherMails")?.Value;
    if (!string.IsNullOrEmpty(otherMailsClaim))
    {
        // 反序列化数组，取第一个备用邮箱
        var otherMails = System.Text.Json.JsonSerializer.Deserialize<List<string>>(otherMailsClaim);
        email = otherMails?.FirstOrDefault();
    }
}

// 现在用email来创建/更新本地用户
if (!string.IsNullOrEmpty(email))
{
    // 你的用户创建/更新逻辑
}

3. 补充说明：为什么之前的email声明无效 #

你之前配置的email可选声明不生效，本质原因是用户的主邮箱字段为空。Azure AD v2中，email声明的返回规则很明确：

• 只有当用户的主邮箱（Azure AD用户属性里的“邮箱”字段）已设置时，才会返回email声明
• 如果主邮箱为空，哪怕申请了email scope，这个声明也不会出现在ID Token里

额外建议：如果希望用主邮箱替代备用邮箱 #

作为目录管理员，你可以直接在Azure AD中给用户设置主邮箱：

• 进入Azure AD -> 用户 -> 选择目标用户 -> 联系信息 -> 填写“邮箱”字段并保存
  设置完成后，用户下次登录时，ID Token里就会正常返回email声明，不需要依赖备用邮箱的逻辑。

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