Laravel 9集成Azure邮件服务遇权限拒绝问题求助

已完成的配置 #

1. 环境与依赖

   • 采用Azure通信服务邮件功能，使用Azure默认子域名
   • 集成指定的Laravel Azure邮件驱动包

2. .env配置

MAIL_MAILER=azure

AZURE_MAIL_RESOURCE_NAME=lab_rg
AZURE_MAIL_ENDPOINT={my-endpoint}
AZURE_MAIL_KEY={my-key}
# AZURE_MAIL_API_VERSION=2023-03-31 #optional
# AZURE_MAIL_DISABLE_TRACKING=false #optional

3. config/mail.php配置

'mailers' => [
    //...other drivers

    'azure' => [
        'transport'             => 'azure',
        'resource_name'         => env('AZURE_MAIL_RESOURCE_NAME'),
        'endpoint'              => env('AZURE_MAIL_ENDPOINT', 'https://my-acs-resource-name.communication.azure.com'),
        'access_key'            => env('AZURE_MAIL_KEY'),
        'api_version'           => env('AZURE_MAIL_API_VERSION', '2023-03-31'),
        'disable_user_tracking' => env('AZURE_MAIL_DISABLE_TRACKING', false),
    ],
]

4. 测试邮件类

<?php

namespace App\Mail;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class AzureTestMail extends Mailable
{
    use Queueable, SerializesModels;

    public function __construct()
    {
        //
    }

    public function envelope()
    {
        return new Envelope(
            subject: 'Azure Test Mail',
        );
    }

    public function content()
    {
        return new Content(
            view: 'emails.test',
        );
    }

    public function attachments()
    {
        return [];
    }
}

5. 测试路由

Route::get('/mail', function () {
    Mail::to('receiver@gmail.com')->send(new AzureTestMail());
    return 'Email sent!';
});

问题现象 #

• Laravel调用邮件发送时返回权限拒绝，请求失败
• Postman直接调用Azure邮件API（{endpointURL}/emails:send?api-version=2023-03-31），无论使用access-key还是通过az communication identity token issue获取的token，均返回权限拒绝
• Azure控制台内置的邮件测试功能可正常发送邮件，排除服务本身故障

排查与解决方案 #

1. 核心问题：认证方式错误 #

Azure通信服务邮件API不支持直接使用access-key或identity token作为Authorization头，必须使用HMAC-SHA256签名认证：

• 驱动包应自动处理签名逻辑，但配置错误会导致签名生成失败
• 手动Postman测试时，需严格按规则生成签名头：
  • 生成符合RFC1123格式的Date头
  • 计算请求体的SHA256哈希作为x-ms-content-sha256头
  • 构造签名字符串并用access-key进行HMAC-SHA256加密，转Base64得到签名
  • 组装Authorization头：HMAC-SHA256 SignedHeaders=date;host;x-ms-content-sha256&Signature={base64签名}

2. 配置项错误（高频踩坑点） #

• AZURE_MAIL_RESOURCE_NAME应为Azure通信服务的资源名称，而非资源组名称
  • 当前配置中lab_rg是资源组名，需替换为Azure通信服务概述页面显示的资源名称（格式如your-acs-resource）
• 检查AZURE_MAIL_ENDPOINT格式是否正确，应为https://{resource-name}.communication.azure.com

3. 驱动包兼容性验证 #

• 确认驱动包版本与当前Laravel版本兼容，尝试更新驱动包到最新版本

4. 权限验证 #

• 检查Azure通信服务的访问密钥是否为主密钥或辅助密钥，确保密钥未过期或被撤销
• 确认资源的IAM权限配置正确，当前密钥拥有Communication Mail Sender等必要权限

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