MRBS中Azure AD组织邮箱登录认证问题及调试求助

我正在为PHP会议室预订系统（MRBS）实现Azure AD企业邮箱登录认证，已按项目文档配置Azure AD客户端ID、密钥、重定向URI和租户ID，但点击登录后无法跳转到Azure AD登录页。当前使用项目提供的AuthAzuread类处理认证流程，怀疑认证逻辑或回调处理存在问题，同时需要了解如何正确调试该流程并处理错误。

相关代码如下：

<?php
namespace MRBS\Auth;

/*
 * Authentication scheme that uses Azure AD for user authentication.
 * Main file: https://github.com/meeting-room-booking-system/mrbs-code/tree/main
 *
 * For Authentication documentation: https://github.com/meeting-room-booking-system/mrbs-code/blob/main/AUTHENTICATION
 *
 * To use this authentication scheme, set the following in config.inc.php:
 *
 * $auth["type"] = "azuread";
 * $auth["azuread_client_id"] = "YOUR_AZUREAD_CLIENT_ID";
 * $auth["azuread_client_secret"] = "YOUR_AZUREAD_CLIENT_SECRET";
 * $auth["azuread_redirect_uri"] = "https://your-mrbs-url.com/login.php"; // Redirect URI configured in Azure AD
 * $auth["azuread_tenant_id"] = "YOUR_AZUREAD_TENANT_ID";
 *
 */

use MRBS\User;

class AuthAzuread extends Auth
{
    private $auth;

    public function __construct($auth)
    {
        $this->auth = $auth;
        // Check if azuread_tenant_id, azuread_client_id, and azuread_client_secret are provided
        if (!isset($this->auth['azuread_tenant_id'])) {
            throw new \Exception("Azure AD Tenant ID is missing.");
        }
        if (!isset($this->auth['azuread_client_id'])) {
            throw new \Exception("Azure AD Client ID is missing.");
        }
        if (!isset($this->auth['azuread_client_secret'])) {
            throw new \Exception("Azure AD Client Secret is missing.");
        }
    }

    public function validateUser(?string $user, ?string $pass)
    {
        // Encode the redirect URI
        $redirectUri = urlencode($this->auth["azuread_redirect_uri"]);

        // Redirect users to Azure AD sign-in page
        $azureADSignInUrl = "https://login.microsoftonline.com/{$this->auth['azuread_tenant_id']}/oauth2/v2.0/authorize?" . http_build_query([
            "client_id" => $this->auth["azuread_client_id"],
            "response_type" => "code",
            "redirect_uri" => $redirectUri, // Include the encoded redirect URI
            "scope" => "openid profile email",
        ]);

        header("Location: $azureADSignInUrl");
        exit;
    }

    public function handleCallback()
    {
        if (isset($_GET['code'])) {
            $authorizationCode = $_GET['code'];

            // Exchange authorization code for access token
            $tokenEndpoint = "https://login.microsoftonline.com/{$this->auth['azuread_tenant_id']}/oauth2/v2.0/token";
            $tokenParams = [
                "grant_type" => "authorization_code",
                "client_id" => $this->auth["azuread_client_id"],
                "client_secret" => $this->auth["azuread_client_secret"],
                "scope" => "openid profile email",
                "redirect_uri" => $this->auth["azuread_redirect_uri"],
                "code" => $authorizationCode,
            ];

            $tokenData = $this->getToken($tokenEndpoint, $tokenParams);

            if (isset($tokenData['access_token'])) {
                $accessToken = $tokenData['access_token'];
                $userInfo = $this->getUserInfo($accessToken);

                if ($userInfo) {
                    return new User($userInfo['email'], $userInfo['name']);
                } else {
                    throw new \Exception('Failed to retrieve user information from Microsoft Graph API');
                }
            } elseif (isset($tokenData['error'])) {
                // Token request failed with error response
                $error = $tokenData['error'];
                $errorDescription = isset($tokenData['error_description']) ? $tokenData['error_description'] : '';

                throw new \Exception("Token request failed with error: $error. Description: $errorDescription");
            } else {
                throw new \Exception('Failed to obtain access token from Azure AD');
            }
        }

        return null;
    }

    private function getToken($tokenEndpoint, $tokenParams)
    {
        // Send POST request to token endpoint with client secret
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $tokenEndpoint);
        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($tokenParams));
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }

    private function getUserInfo($accessToken)
    {
        // Make a request to Microsoft Graph API using the access token
        $graphApiEndpoint = 'https://graph.microsoft.com/v1.0/me';
        $headers = [
            'Authorization: Bearer ' . $accessToken,
            'Accept: application/json'
        ];

        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $graphApiEndpoint);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($ch);
        curl_close($ch);

        $userInfo = json_decode($response, true);

        // Check if user info retrieval was successful
        if (isset($userInfo['mail']) && isset($userInfo['displayName'])) {
            return [
                'email' => $userInfo['mail'],
                'name' => $userInfo['displayName']
            ];
        } else {
            // User info retrieval failed
            throw new \Exception('Failed to retrieve user information from Microsoft Graph API');
        }
    }
}
?>

一、无法跳转Azure AD登录页的排查点 #

1. 配置项校验 #

• 确认config.inc.php中$auth["azuread_redirect_uri"]与Azure AD应用注册中配置的重定向URI完全一致，包括HTTP/HTTPS、域名、路径，大小写敏感。
• 检查$auth["azuread_tenant_id"]、client_id、client_secret是否复制正确，无多余空格或特殊字符。

2. validateUser方法核心问题 #

代码中手动urlencode重定向URI，但http_build_query会自动编码，导致双重编码，Azure AD会识别为无效的重定向URI，直接阻止跳转。修复方式：

// 移除手动urlencode，直接传入原URI
$redirectUri = $this->auth["azuread_redirect_uri"];

同时检查header("Location: $azureADSignInUrl")是否在任何输出（包括空格、HTML标签）之前执行，可在方法开头添加ob_start();开启输出缓冲，避免意外输出导致header失效。

3. 异常捕获缺失 #

AuthAzuread构造函数抛出的异常如果未被MRBS框架捕获，会直接导致白屏而非跳转。建议添加异常处理：

try {
    $auth_instance = new AuthAzuread($auth);
} catch (\Exception $e) {
    error_log("Azure AD Auth Init Error: " . $e->getMessage());
    die("认证初始化失败：" . $e->getMessage());
}

二、Azure AD认证流程调试方法 #

1. 关键步骤日志记录 #

在核心方法中添加日志，定位问题：

// 在validateUser中记录生成的授权URL
error_log("Azure AD Auth URL: " . $azureADSignInUrl);
// 在getToken中记录请求参数和响应
error_log("Token Request Params: " . print_r($tokenParams, true));
error_log("Token Response: " . $response);
// 在getUserInfo中记录Graph API响应
error_log("Graph API Response: " . $response);

查看PHP错误日志（通常在/var/log/php/或Web服务器日志目录），获取具体错误信息。

2. 直接测试授权URL #

将日志中生成的azureADSignInUrl复制到浏览器直接访问，观察是否跳转至Azure AD登录页，或返回具体错误（如invalid_request、redirect_uri_mismatch）。

3. CURL请求调试 #

在getToken和getUserInfo中添加CURL错误捕获，排查网络或请求问题：

// 在getToken中添加
if(curl_errno($ch)) {
    $error_msg = curl_error($ch);
    error_log("CURL Error: " . $error_msg);
    throw new \Exception("CURL请求失败：" . $error_msg);
}

同时确保服务器能访问login.microsoftonline.com和graph.microsoft.com，可通过curl -I https://login.microsoftonline.com测试网络连通性。

三、错误处理优化 #

1. 回调错误捕获 #

Azure AD认证失败时会返回error和error_description参数，在handleCallback中添加处理逻辑：

if (isset($_GET['error'])) {
    $error = $_GET['error'];
    $errorDesc = $_GET['error_description'] ?? '';
    error_log("Azure AD Auth Error: $error - $errorDesc");
    throw new \Exception("认证失败：$error - $errorDesc");
}

2. 用户信息 fallback #

部分Azure AD用户mail字段为空，可使用userPrincipalName作为备选：

if (isset($userInfo['mail']) && isset($userInfo['displayName'])) {
    return [
        'email' => $userInfo['mail'],
        'name' => $userInfo['displayName']
    ];
} elseif (isset($userInfo['userPrincipalName']) && isset($userInfo['displayName'])) {
    return [
        'email' => $userInfo['userPrincipalName'],
        'name' => $userInfo['displayName']
    ];
} else {
    throw new \Exception('无法获取用户邮箱和名称');
}

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