Giải quyết lỗi OrganisationFromTenantGuidNotFound của Microsoft Graph API khi gửi email

Khắc phục lỗi gửi email API Microsoft Graph

Gặp phải Lỗi OrganisationFromTenantGuidNotFound khi cố gắng gửi email bằng API đồ thị của Microsoft có thể gây khó chịu, đặc biệt là khi nó làm dừng các quy trình công việc quan trọng. Lỗi này thường có nghĩa là API không thể định vị đối tượng thuê hợp lệ dựa trên GUID đối tượng thuê được cung cấp.

Sự cố này có vẻ phức tạp nhưng thường liên quan đến cài đặt cấu hình, đặc biệt là xung quanh bạn. Thiết lập đối tượng thuê Azure AD hoặc chi tiết xác thực. Hiểu những gì gây ra lỗi này là chìa khóa để giải quyết nó một cách hiệu quả.

Trong hướng dẫn này, chúng ta sẽ tìm hiểu các nguyên nhân phổ biến gây ra lỗi OrganisationFromTenantGuidNotFound và cách giải quyết chúng. Chúng tôi sẽ khám phá cách xác minh ID người thuê, kiểm tra các tham số xác thực và xác thực quyền.

Với các bước khắc phục sự cố phù hợp, bạn có thể đưa lệnh gọi API của mình trở lại đúng hướng và đảm bảo chức năng gửi email diễn ra suôn sẻ. Hãy cùng tìm hiểu nguyên nhân gây ra lỗi này và các bước để giải quyết nó.

Giải quyết lỗi không tìm thấy đối tượng thuê trong xác thực API Microsoft Graph

Các tập lệnh được cung cấp giải quyết một vấn đề thường gặp khi sử dụng API đồ thị của Microsoft để gửi email: lỗi OrganisationFromTenantGuidNotFound. Lỗi này xảy ra khi API không tìm được đối tượng thuê được liên kết với ID đối tượng thuê đã cho. Để giải quyết vấn đề này, chúng tôi sử dụng PHP Nhà cung cấp chung class từ gói máy khách OAuth2 để xử lý luồng xác thực. GenericProvider rất cần thiết vì nó tóm tắt sự phức tạp của việc kết nối với điểm cuối OAuth2 của Microsoft, cho phép nhà phát triển chỉ định thông tin xác thực ứng dụng khách, ID đối tượng thuê và các URL cần thiết để ủy quyền và truy cập mã thông báo. Cấu hình này sử dụng ID ứng dụng khách, bí mật ứng dụng khách, URI chuyển hướng và các điểm cuối được điều chỉnh cho phù hợp với dịch vụ nhận dạng của Microsoft, giúp đơn giản hóa quy trình thiết lập.

Trong ví dụ đầu tiên, chúng tôi tập trung vào việc tạo URL ủy quyền mà người dùng cần đăng nhập và cấp quyền cho phạm vi gửi email. Hàm getAuthorizationUrl tạo URL này với các phạm vi cụ thể như 'openid', 'email' và 'offline_access'. Tham số 'trạng thái' trong URL, được tạo bằng base64_encode và json_encode, thêm lớp bảo mật bổ sung bằng cách mã hóa thông tin dành riêng cho phiên. Điều này bảo vệ chống lại các cuộc tấn công giả mạo yêu cầu giữa các trang (CSRF), đảm bảo tính toàn vẹn của luồng OAuth. URL ủy quyền kết quả sẽ hướng người dùng đến trang đăng nhập của Microsoft, nhắc họ cho phép các quyền được chỉ định. Sau khi đăng nhập thành công, Microsoft sẽ chuyển hướng người dùng đến URI chuyển hướng bằng mã ủy quyền mà ứng dụng có thể đổi lấy mã thông báo truy cập.

Đối với các trường hợp yêu cầu yêu cầu trực tiếp hơn, tập lệnh thứ hai sử dụng cURL để tương tác API. Bằng cách tạo yêu cầu mã thông báo theo cách thủ công, chúng tôi bỏ qua nhu cầu về thư viện, khiến nó trở nên lý tưởng cho các tình huống thử nghiệm hoặc nhẹ nhàng. Tập lệnh thiết lập các tham số như client_id, client_secret và Grant_type dưới dạng dữ liệu POST bằng cách sử dụng hàm http_build_query, mã hóa dữ liệu thành định dạng an toàn cho URL. Sau đó, yêu cầu mã thông báo sẽ được gửi đến điểm cuối OAuth2 thích hợp bằng cách sử dụng Curl_init và Curl_setopt, được định cấu hình để xử lý tiêu đề, phương thức HTTP và trường dữ liệu. Việc thực thi Curl_exec sẽ gửi yêu cầu và phản hồi thu được (chứa mã thông báo truy cập hoặc chi tiết lỗi) có thể được sử dụng cho các yêu cầu tiếp theo trong Microsoft Graph API.

Ngoài ra, chúng tôi còn bao gồm các bài kiểm tra đơn vị để xác thực từng tập lệnh. Kiểm tra đơn vị đầu tiên sẽ kiểm tra xem URL ủy quyền được tạo có bao gồm miền đăng nhập của Microsoft hay không, xác minh định dạng URL. Một thử nghiệm khác đảm bảo rằng các yêu cầu cURL không bị lỗi, xác nhận kết nối thành công với điểm cuối xác thực. Các thử nghiệm này mang lại niềm tin rằng các cấu hình được đặt chính xác và các yêu cầu API đều hoạt động bình thường, điều này rất quan trọng trong môi trường sản xuất. Bằng cách xử lý cả yêu cầu thủ công và dựa trên thư viện, các tập lệnh và thử nghiệm này cung cấp các tùy chọn mạnh mẽ để xác thực bằng API đồ thị của Microsoft, cho phép tính linh hoạt, xử lý lỗi và thiết kế mô-đun có thể thích ứng với các nhu cầu khác nhau của dự án.

$provider = new GenericProvider([
    'clientId' => $config['microsoft']['clientId'],
    'clientSecret' => $config['microsoft']['clientSecret'],
    'redirectUri' => $redirectUrl,
    'urlAuthorize' => $config['microsoft']['loginBaseUrl'] . "/" . $config['microsoft']['tenantId'] . "/oauth2/v2.0/authorize",
    'urlAccessToken' => $config['microsoft']['loginBaseUrl'] . "/" . $config['microsoft']['tenantId'] . "/oauth2/v2.0/token",
    'urlResourceOwnerDetails' => "https://graph.microsoft.com/v1.0/me",
]);

$scope = 'openid email profile https://graph.microsoft.com/.default offline_access';
$authUrl = $provider->getAuthorizationUrl([
    'scope' => $scope,
    'state' => base64_encode(json_encode($state))
]);

$tenantId = $config['microsoft']['tenantId'];
$clientId = $config['microsoft']['clientId'];
$clientSecret = $config['microsoft']['clientSecret'];

$url = "https://login.microsoftonline.com/{$tenantId}/oauth2/v2.0/token";
$headers = ['Content-Type: application/x-www-form-urlencoded'];
$body = http_build_query([
    'client_id' => $clientId,
    'client_secret' => $clientSecret,
    'scope' => "https://graph.microsoft.com/.default",
    'grant_type' => "client_credentials"
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

use PHPUnit\Framework\TestCase;
class MicrosoftGraphAPITest extends TestCase {
    public function testAuthorizationUrl() {
        global $provider, $scope, $state;
        $authUrl = $provider->getAuthorizationUrl(['scope' => $scope, 'state' => $state]);
        $this->assertStringContainsString("https://login.microsoftonline.com", $authUrl);
    }

    public function testCurlResponse() {
        global $ch;
        $response = curl_exec($ch);
        $this->assertNotFalse($response);
    }
}

Tìm hiểu các vấn đề về GUID của đối tượng thuê trong Xác thực API Microsoft Graph

các Tổ chứcFromTenantGuidNotFound lỗi trong Microsoft Graph API thường chỉ ra rằng GUID đối tượng thuê được chỉ định trong yêu cầu API không thể nằm trong thư mục Azure AD. Điều này thường xảy ra do ID đối tượng thuê được định cấu hình sai hoặc thiết lập tích hợp API Microsoft Graph không đúng cách. Mỗi đối tượng thuê trong Microsoft Azure có một mã định danh duy nhất được gọi là GUID đối tượng thuê, đảm bảo rằng các yêu cầu được chuyển hướng đến đúng bối cảnh tổ chức. Nếu GUID đối tượng thuê không hợp lệ hoặc bị thiếu, API Microsoft Graph không thể định vị tổ chức, dẫn đến lỗi xác thực. Hiểu vai trò của GUID đối tượng thuê trong các yêu cầu API là chìa khóa để giải quyết các vấn đề đó một cách nhanh chóng.

Việc đảm bảo thiết lập chính xác bao gồm việc xác minh ID người thuê trong Azure Active Directory và xác nhận rằng nó khớp với cấu hình trong cài đặt xác thực ứng dụng của bạn. Đôi khi, các nhà phát triển sử dụng nhầm ID thư mục hoặc ID ứng dụng thay vì GUID đối tượng thuê, dẫn đến sự cố này. Ngoài ra, việc sử dụng thiết lập nhiều đối tượng thuê trong API Microsoft Graph yêu cầu chỉ định quyền truy cập vào dữ liệu của đối tượng thuê khác. Việc không định cấu hình chính xác các quyền hoặc chỉ định GUID phù hợp có thể dẫn đến lỗi khi cố gắng truy cập hoặc gửi dữ liệu qua API.

Việc xem lại các chính sách kiểm soát quyền truy cập trong Azure AD cũng rất hữu ích vì quản trị viên có thể hạn chế quyền truy cập vào một số tài nguyên nhất định dựa trên vai trò của người dùng hoặc chính sách bảo mật. Ví dụ: một số người dùng có thể thiếu quyền thực hiện các hành động cụ thể nếu tài khoản của họ thuộc nhóm truy cập bị hạn chế. Do đó, việc xác minh cả cài đặt GUID và quyền vai trò trong Azure AD là điều cần thiết. Nếu sự cố vẫn tiếp diễn, việc kiểm tra tài liệu của Microsoft về cấu hình đối tượng thuê có thể cung cấp thêm thông tin rõ ràng về các yêu cầu đối với ứng dụng có nhiều đối tượng thuê, giúp nhà phát triển tránh được các lỗi làm gián đoạn quy trình làm việc của họ.