Azure ACS SMTP用户关联App Registration失败排查求助

核心问题排查与修复步骤 #

1. 补全App Registration的API权限配置 #

IAM角色仅控制资源访问权限，App Registration还需配置ACS的API权限才能正常关联：

• 进入Entra ID的「应用注册」→ 目标应用 →「API权限」；
• 添加权限，选择「Azure Communication Service」，勾选应用权限下的Mail.Send；
• 点击「授予管理员同意」（必须完成，否则应用无法调用ACS邮件服务）。

2. 确认App Registration的合规性 #

• 确保应用为单租户类型（ACS SMTP目前对多租户应用支持有限）；
• 检查应用状态为「已启用」，客户端密钥/证书未过期且有效。

3. 验证IAM角色分配的正确性 #

不要仅在资源组层级分配角色，需确保ACS资源直接关联服务主体：

• 用CLI查询应用对应的服务主体ID：

  az ad sp list --display-name "你的应用名称" --query "[].id"
  

• 查询ACS资源的IAM角色分配，对比服务主体ID是否匹配：

  az role assignment list --resource-group "你的资源组名" --resource-type "Microsoft.Communication/communicationServices" --resource-name "你的ACS资源名" --query "[].principalId"
  

• 确保分配的角色为Communication Service Email Send Owner或Communication Service Email Sender（Sender为最小权限，按需选择）。

4. 用CLI正确创建SMTP用户 #

UI创建可能存在缓存问题，改用CLI创建时需指定服务主体ID（而非应用注册的Application ID）：

az communication email smtp-user create --resource-group "你的资源组名" --communication-service-name "你的ACS资源名" --name "自定义SMTP用户名" --password "符合要求的强密码" --app-id "查询到的服务主体ID"

5. 验证关联有效性 #

• 门户验证：进入ACS资源→「IAM」→「角色分配」，确认目标服务主体的角色状态为「已分配」；
• CLI验证：查询SMTP用户详情，确认appId和role字段无异常：

  az communication email smtp-user show --resource-group "你的资源组名" --communication-service-name "你的ACS资源名" --name "SMTP用户名"
  

Laravel配置验证 #

确保.env中的SMTP配置正确：

MAIL_MAILER=smtp
MAIL_HOST=smtp.communication.azure.com
MAIL_PORT=587
MAIL_USERNAME=你的SMTP用户名
MAIL_PASSWORD=你的SMTP密码
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=已验证域名下的邮箱（如no-reply@yourdomain.com）
MAIL_FROM_NAME="${APP_NAME}"

执行测试命令排查发送问题：

php artisan mail:send "测试邮件" --to=your-test-email@example.com

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