المصادقة ضد Microsoft Dataverse استخدام OAuth

مكتمل

Microsoft Dataverse يستخدم OAuth 2.0 كمعيار المصادقة الخاص به. يوفر OAuth 2.0 معيارًا صناعيًا لمصادقة تطبيقات العميل ومنحهم حق الوصول إلى أحد الموارد.

المصادقة مقابل التخويل

المصادقة هي عملية أو إجراء التحقق من هوية المستخدم أو العملية. الحل الذي تقدمه Microsoft لعملية التحقق هذه هو Microsoft Entra ID. يدعم Entra ID العديد من الخيارات للتحقق من هوية المستخدم أو العملية. يسمح تجريد موفر الهوية الخاص بك بالفصل الجيد بين الاهتمامات لأن إدارة أسماء المستخدمين وكلمات المرور قد تكون عملية صعبة (ومحفوفة بالمخاطر).

ملاحظة

Microsoft Entra ID هو الاسم الجديد لـ Azure Active Directory. تبقى جميع التراخيص والوظائف كما هي.

التفويض هو عملية أو إجراء للتحقق مما إذا كان المستخدم المصادق عليهمصرحًا له بالوصول إلى المورّد. في الوقت الحالي، يكون تفويض Dataverse على مستوى مستأجر Entra ID، بينما يتم تفويض إدارة الأذونات التفصيلية إلى التطبيق بناءً على المستخدم الحالي الذي سجل الدخول. ولذلك، لا تستخدم OAuth 2.0 للتحكم فِي الأمان على مستوى التطبيق، والذي ستتعامل معه من خلال أدوار أمان Dataverse وتعيينه للمستخدمين من خلال مركز مسؤولي Power Apps.

إذا كنت تريد معرفة المزيد حول مفاهيم المصادقة والترخيص، راجع أساسيات المصادقة.

تسجيل تطبيقات Dataverse باستخدام Entra ID

للاتصال بنجاح ب Dataverse، يجب عليك أولاً تسجيل تطبيق باستخدام Entra ID، والذي يمكنك إكماله فِي مدخل Azure. اعتمادًا على نوع التطبيق الذي تريد إنشاءه، تتوفر لك بعض الإعدادات المختلفة لتهيئتها (تطبيقات الويب مقابل التطبيقات الأصلية المثبتة محليًا على الجهاز). لمزيد من المعلومات حول الإعدادات المطلوبة لكل نوع، راجع أنواع تسجيل التطبيقات.

لتسجيل تطبيق باستخدام معرف Entra، انتقل إلى قسم تسجيلات التطبيقات فِي قائمة Entra ID (Azure Active Directory) ثم حدد تسجيل جديد.

حدد اسم تطبيقك ونوع الوصول إلى الحساب الذي تحتاجه. إذا كنت تقوم بتسجيل تطبيق ويب، فحدد عنوان URI لإعادة التوجيه بالانتقال إلى قسم المصادقة، وتعيين النوع إلى ويب، ثم إدخال عنوان URI لإعادة التوجيه.

تلخص القائمة التالية وقت استخدام أنواع الحسابات المختلفة:

• الحسابات فِي هذا الدليل التنظيمي فقط (مستأجر واحد)

  يمكن لجميع حسابات المستخدمين والضيوف فِي دليلك استخدام التطبيق أو API الخاص بك.

  استخدم هذا الخيار إذا كان جمهورك المستهدف داخليًا فِي مؤسستك.

• الحسابات فِي أي دليل تنظيمي (أي دليل Entra ID - متعدد المستأجرين)

  يمكن لجميع المستخدمين الذين لديهم حساب عمل أو مدرسة من Microsoft استخدام تطبيقك أو واجهة برمجة التطبيقات (API)، بما فِي ذلك المدارس والشركات التي تستخدم Microsoft 365.

  استخدم هذا الخيار إذا كان جمهورك المستهدف هو العملاء التجاريين أو التعليميين ولتمكين تعدد الإيجارات.

• الحسابات فِي أي دليل تنظيمي (أي دليل Entra ID - متعدد المستأجرين) وحسابات Microsoft الشخصية (على سبيل المثال، Skype وXbox)

  يمكن لجميع المستخدمين الذين لديهم حساب عمل أو مدرسة أو حساب Microsoft شخصي استخدام التطبيق أو API الخاص بك. يتضمن المدارس والشركات التي تستخدم Microsoft 365 والحسابات الشخصية التي يتم استخدامها لتسجيل الدخول إلى خدمات مثل Xbox وSkype.

اعتمادًا على مدى تعقيد إعداد التطبيق الخاص بك، قد ترغب فِي تكوين إعدادات مصادقة أخرى. راجع وثائق Entra ID للحصول على خطوات حول كيفية إكمال هذه المهمة.

الوصول Dataverse باستخدام Web API

يتم كل الوصول إلى Dataverse فِي سياق مستخدم مسجل الدخول. يمكن أن يكون هذا مستخدماً تفاعلياً عادياً أو مستخدماً غير تفاعلي باستخدام مصادقة خادم إلى خادم (S2S).

عندما يصل تطبيق ما نيابة Dataverse عن مستخدم تفاعلي، يجب تكوين التطبيق المسجل بأذونات واجهة برمجة التطبيقات (API) للوصول Dataverse بإذن مفوض. عندما يصل التطبيق مباشرة Dataverse، يجب إنشاء مستخدم التطبيق المرتبط بتسجيل تطبيق Entra ID فِي Dataverse. عند استخدام مصادقة S2S، Dataverse لا تكون الأذونات المفوضة لواجهة برمجة التطبيقات (API) مطلوبة.

في جميع الحالات، يجب أن يكون لدى المستخدمين الذين تمت مصادقتهم أدوار Dataverse أمان مرتبطة بالمستخدم، مما يسمح بالعمليات التي تقوم بها باستخدام Web API.

تكوين أذونات API

إذا كان تطبيقك يصل Dataverse بالنيابة عن مستخدم قام بتسجيل الدخول، فانتقل إلى علامة تبويب أذونات واجهة برمجة التطبيقات (API) فِي التطبيق المسجل وتأكد من منح وصول انتحال هوية مستخدم التطبيق إلى Dataverse بيئتك.

تقول التسمية Dynamics CRM، وهو الاسم التاريخي للمنتج السابق لـ Dataverse.

تكوين Dataverse مستخدم التطبيق

عند استخدام مصادقة S2S، يجب تكوين Dataverse مستخدم التطبيق فِي كل Dataverse بيئة تصل إليها باستخدام Web API.

يتم تكوين مستخدمي تطبيق Dataverse من مركز مسؤولي Power Platform كمسؤول النظام.

من مركز المسؤولين، يمكنك تنفيذ الخطوات التالية:

• إنشاء مستخدم جديد للتطبيق

• قم بربط مستخدم التطبيق بتطبيق Entra ID أو الهوية المُدارة

• قم بتكوين أدوار Dataverse الأمان التي سيتم تطبيقها

لمزيد من المراجعة التفصيلية خطوة بخطوة إدارة مستخدمي التطبيق فِي مركز مسؤولي Power Platform.

استخدم مكتبات المصادقة للاتصال

بمجرد تسجيل التطبيق الخاص بك، استخدم إحدى مكتبات مصادقة النظام الأساسي لهوية Microsoft لإجراء المصادقة والحصول على رمز وصول لاستخدامه مع Web API.

التعليمة البرمجية التالية مقتطف من نموذج التشغيل السريع المحسّن الذي يستخدم مكتبة مصادقة Microsoft (MSAL). تطبق فئة OAuthMessageHandler التالية فئة مشتقة من DelegatingHandler، والتي تقوم بتمريرها إلى مُنشئ HttpClient. يسمح لك هذا المعالج بتجاوز HttpClient.SendAsync الطريقة بحيث يتم تحديث رمز الوصول من خلال استدعاءات أسلوب AcquireToken* مع كل طلب يرسله عميل Http.

class OAuthMessageHandler : DelegatingHandler
{
  private AuthenticationHeaderValue authHeader;
  public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl, string username, string password, HttpMessageHandler innerHandler)
  : base(innerHandler)
  {
    //Build Microsoft.Identity.Client (MSAL) OAuth Token Request
    var clientApplication = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUrl)
    .Build();
    var scope = serviceUrl + "//.default";
    string[] scopes = { scope };
    AuthenticationResult authBuilderResult;
    if (username != string.Empty && password != string.Empty)
    {
      //Make silent Microsoft.Identity.Client (MSAL) OAuth Token Request
      var securePassword = new SecureString();
      foreach (char ch in password) securePassword.AppendChar(ch);
      authBuilderResult = clientApplication.AcquireTokenByUsernamePassword(scopes, username, securePassword).ExecuteAsync().Result;
    }
    else
    {
      //Popup authentication dialog box to get token
      authBuilderResult = clientApplication.AcquireTokenInteractive(scopes).ExecuteAsync().Result;
    }
      //Note that an Entra ID access token has a finite lifetime, default expiration is 60 minutes.
      authHeader = new AuthenticationHeaderValue("Bearer", authBuilderResult.AccessToken);
    }
  protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
  {
    request.Headers.Authorization = authHeader;
    return base.SendAsync(request, cancellationToken);
  }
}

يمكن أن يكون لديك بعد ذلك طريقة مساعدة للحصول على مثيل HttpClient باستخدام المعالج:

static HttpClient GetHttpClient(string url, string clientId, string redirectUrl, string version = "v9.2")
{
  try
  {
    HttpMessageHandler messageHandler = new OAuthMessageHandler(url, clientId, redirectUrl, "", "",
    new HttpClientHandler());
    HttpClient httpClient = new HttpClient(messageHandler)
    {
      BaseAddress = new Uri(string.Format("{0}/api/data/{1}/", url, version)),
      Timeout = new TimeSpan(0, 2, 0) //2 minutes
    };
  return httpClient;
  }
  catch (Exception)
  {
    throw;
  }
}

وأخيرًا، استخدم نسخة العميل لإجراء استدعاء Web API:

using (HttpClient client = GetHttpClient("https://yourenvname.api.crm.dynamics.com", "51f81489-12ee-4a9e-aaae-a2591f45987d", "http://localhost:8080"))
{
  // Use the WhoAmI function
  var response = client.GetAsync("WhoAmI").Result;
  if (response.IsSuccessStatusCode)
  {
    //Get the response content and parse it.
    JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
    Guid userId = (Guid)body["UserId"];
    Console.WriteLine("Your UserId is {0}", userId);
  }
  else
  {
    Console.WriteLine("The request failed with a status of '{0}'", response.ReasonPhrase);
  }
  Console.WriteLine("Press any key to exit.");
  Console.ReadLine();
}

يجب أن يكون لديك الآن تطبيق مسجل يمكنه الاتصال Dataverse ببيئتك بنجاح. لديك أيضًا مثال بسيط للاتصال بالتطبيق المسجل واستخدامه للوصول إلى عملية Web API.