المصادقة على Microsoft Graph باستخدام MSAL

مقدمة في مصادقة Graph

Microsoft Graph هو API موحد من نوع REST للوصول إلى البيانات عبر خدمات Microsoft 365 مثل Outlook وOneDrive وTeams. توفر Aspose.Email لـ .NET IGraphClient واجهة تُبسط التفاعل مع Microsoft Graph من خلال تقديم API عالي المستوى ومُعَرَّف بقوة.

باستخدام IGraphClient، يمكنك المصادقة عبر MSAL، ثم تنفيذ عمليات شائعة مثل:

• إدارة مجلدات البريد (قائمة، إنشاء، تحديث، نسخ، حذف)

• العمل مع الرسائل والمرفقات (قراءة، إرسال، نقل، وتعديل المحتوى)

• الوصول إلى وإدارة أحداث التقويم، جهات الاتصال، الفئات، القواعد، المهام، ودفاتر OneNote

توضح الأمثلة التالية كيفية إنشاء وتكوين GraphClient مثيل باستخدام رمز وصول، يتبع ذلك سيناريوهات الاستخدام النموذجية.

مصادقة Microsoft Graph باستخدام MSAL.NET

للعمل مع Microsoft Graph باستخدام Aspose.Email لـ .NET، يجب أولاً توثيق تطبيقك. يمكن ذلك عبر تنفيذ ITokenProvider الواجهة، التي تزود رموز الوصول إلى IGraphClient.

هذا القسم يوجّهك عبر إعداد MSAL.NET للحصول على الرموز وتهيئة IGraphClient لإرسال طلبات موثوقة إلى خدمات Microsoft Graph.

مكتبة Microsoft Authentication (MSAL)

الخطوة 1: تعريف صف AccessParameters

أنشئ صفًا بسيطًا لتخزين بيانات اعتماد Microsoft 365 الخاصة بك والتكوينات المرتبطة.

public class AccessParameters
{
    public string TenantId { get; init; }
    public string ClientId { get; init; }
    public string ClientSecret { get; init; }
    public string UserId { get; init; }
    public Uri Authority => new ($"https://login.microsoftonline.com/{TenantId}");
    public string ApiUrl => "https://graph.microsoft.com/.default";
}

الخطوة 2: تثبيت حزمة MSAL.NET

أضف الـ Microsoft.Identity.Client حزمة NuGet لمشروعك. تحتوي على مكتبة المصادقة من Microsoft (MSAL) المستخدمة للحصول على رموز الوصول.

dotnet add package Microsoft.Identity.Client

الخطوة 3: تنفيذ واجهة ITokenProvider

إنشاء GraphTokenProvider فئة تنفذ الـ ITokenProvider واجهة. ستستخدم هذه الفئة مكتبة MSAL.NET للحصول على رمز وصول.

using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using Aspose.Email.Clients;

public class GraphTokenProvider : ITokenProvider
{
    private readonly IConfidentialClientApplication _app;
    private readonly string[] _scopes;
    private string? _token;

    public GraphTokenProvider(AccessParameters accessParams)
    {
        _app = ConfidentialClientApplicationBuilder.Create(accessParams.ClientId)
            .WithClientSecret(accessParams.ClientSecret)
            .WithAuthority(accessParams.Authority)
            .Build();

        _app.AddInMemoryTokenCache();

        _scopes = new[] { accessParams.ApiUrl };
    }

    public void Dispose()
    {
        throw new NotImplementedException();
    }

    public OAuthToken GetAccessToken()
    {
        return GetAccessToken(false);
    }

    public OAuthToken GetAccessToken(bool ignoreExistingToken)
    {
        if (!ignoreExistingToken && _token != null)
        {
            return new OAuthToken(_token);
        }

        _token = GetAccessTokenAsync().GetAwaiter().GetResult();
        return new OAuthToken(_token);
    }

    private async Task<string?> GetAccessTokenAsync()
    {
        AuthenticationResult? result;

        try
        {
            result = await _app.AcquireTokenForClient(_scopes)
                .ExecuteAsync();

            Console.WriteLine("Token acquired");
        }
        catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
        {
            Console.WriteLine("Scope provided is not supported");
            result = null;
        }

        if (result == null) return null;
        _token = result.AccessToken;
        return result.AccessToken;
    }

الخطوة 4: إنشاء مثيل ITokenProvider

بمجرد أن يكون لديك GraphTokenProvider الصف (class) جاهز، يمكنك إنشاء نسخة منه باستخدام بيانات اعتماد تطبيقك.

var accessParams = new AccessParameters()
{
    TenantId = "Your Tenant ID",
    ClientId = "Your Client ID",
    ClientSecret = "Your Client Secret",
    UserId = "User's Object ID"
};

var tokenProvider = new GraphTokenProvider(accessParams);

الخطوة 5: تهيئة IGraphClient

استخدم مزود التوكن لإنشاء IGraphClient مثيل. اضبط نوع المورد والهوية للبدء بالتفاعل مع Microsoft Graph.

using var client = GraphClient.GetClient(tokenProvider, accessParams.TenantId);

client.Resource = ResourceType.Users;
client.ResourceId = accessParams.UserId;

الآن تم توثيق IGraphClient الخاص بك وهو جاهز لإرسال الطلبات إلى Microsoft Graph نيابةً عن تطبيقك.

الاتصال بنقطة النهاية GCC High في Microsoft Graph

Aspose.Email GraphClient يدعم الاتصال بنقطة النهاية Microsoft Graph GCC High عن طريق ضبط EndPoint الخاصية يدويًا. اضبط الخاصية إلى https://graph.microsoft.us قبل إجراء الطلبات.

يوضح مثال الكود التالي كيفية تكوين GraphClient للاتصال بنقطة النهاية GCC High لعرض المجلدات واسترجاع الرسائل.

client.EndPoint = "https://graph.microsoft.us";

var folders = client.ListFolders();
string folderId = folders.Find(x => x.DisplayName == "Inbox").ItemId;
var msgs = client.ListMessages(folderId);

المصادقة غير المتزامنة على Microsoft Graph

استخدم الـ Aspose.Email.Clients.Graph.IGraphClientAsync واجهة لأداء عمليات غير متزامنة مع GraphClient. الـ GraphClient.GetClientAsync(ITokenProvider, string) و GraphClient.GetClientAsync(IMultipleServicesTokenProvider, string) الطرق تتيح لك تهيئة عملاء Graph غير المتزامنين. يوضح مثال الكود التالي كيفية تكوين عميل Microsoft Graph موثوق باستخدام بيانات اعتماد تطبيق Azure AD حتى يتمكن من العمل على صندوق بريد مستخدم محدد:

var accessParameters = Settings.User1;

var provider = new AzureConfidentialTokenProvider(
    accessParameters.TenantId,
    accessParameters.ClientId,
    accessParameters.ClientSecret);

var client = GraphClient.GetClientAsync(provider, accessParameters.TenantId);

client.Resource = Aspose.Email.Clients.Graph.ResourceType.Users;
client.ResourceId = accessParameters.Username;
client.EndPoint = "https://graph.microsoft.com";