البرنامج التعليمي: الحصول على البيانات باستخدام واجهة برمجة تطبيقات التقارير Azure Active Directory مع الشهادات

تزودك واجهات برمجة تطبيقات Azure Active Directory (Azure AD) Reporting بإمكانية الوصول البرمجي إلى البيانات من خلال مجموعة من واجهات برمجة التطبيقات المستندة إلى REST. يمكنك الحصول على واجهات برمجة التطبيقات هذه من خلال مجموعة متنوعة من لغات البرمجة وأدواتها. في حال كنت ترغب في الوصول إلى واجهة برمجة تطبيقات Azure AD Reporting دون تدخل المستخدم، لا بد من تهيئة وصولك إلى استخدام الشهادات.

في هذا البرنامج التعليمي، تتعلم كيفية استخدام شهادة اختبار للوصول إلى واجهة برمجة تطبيقات Graph MS لإعداد التقارير. لا نوصي باستخدام شهادات الاختبار في بيئة إنتاج ما.

المتطلبات الأساسية

  1. للوصول إلى بيانات تسجيل الدخول، تأكد من أن لديك مستأجر Azure Active Directory مع وجود رخص (P1/P2) المتميزة. راجع البدء باستخدام azure Active Directory Premium لترقية إصدار Azure Active Directory. لاحظ أنه إذا لم تكن لديك أي بيانات عن الأنشطة قبل الترقية، تستغرق البيانات بضعة أيام حتى تظهر في التقارير بعد الترقية إلى رخصة متميزة.

  2. إنشاء حساب مستخدم أو التبديل إليه فيما يخص الإداري العالميأو إداري الأمنأوقارئ معلومات الأمان أو دور قارئ تقارير المستأجر.

  3. إكمال المتطلبات الأساسية للوصول إلى واجهة برامج تطبيقات إعداد تقارير Azure Active Directory.

  4. تحميل Azure AD PowerShell V2 وتثبيته.

  5. تثبيت MSCloudIdUtils. توفر هذه الوحدة النمطية العديد من أوامر الاستخدام، بما في ذلك:

    • مكتبات ADAL المطلوبة مصادقتها
    • أذونات الوصول إلى المستخدم ومفاتيح التطبيق والشهادات باستخدام ADAL
    • واجهة برامج تطبيقات Graph المختصة بمعالجة النتائج المدرجة في صفحات
  6. إذا كانت هذه هي المرة الأولى التي تستخدم فيها تشغيل الوحدة النمطية Install-MSCloudIdUtilsModule، أو استيرادها باستخدام أمر PowerShell فيما يخص الوحدة النمطية للاستيراد. لا بد أن تشبه جلستك هذه الشاشة: Windows PowerShell

  7. استخدم New-SelfSignedCertificate لإنشاء شهادة اختبار.

    $cert = New-SelfSignedCertificate -Subject "CN=MSGraph_ReportingAPI" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
    
  8. استخدم الأمر Export-Certificate لتصدير شهادة ما إلى مجلد شهادة.

    Export-Certificate -Cert $cert -FilePath "C:\Reporting\MSGraph_ReportingAPI.cer"
    
    

الحصول على البيانات باستخدام واجهة برمجة تطبيقات إعداد تقارير Azure Active Directory باستخدام الشهادات

  1. انتقل إلى مدخل Azure، وحدد Azure Active Directory، ثم اختر سجلات التطبيقات، واختر تطبيقك من القائمة.

  2. حدد Certificates & secrets ضمن القسم Manage في شفرة تسجيل التطبيق وحدد Upload Certificate.

  3. حدد ملف الشهادة بإجراء الخطوة السابقة، ثم اختر إضافة.

  4. لاحظ معرف التطبيق وبصمة إبهام الشهادة التي سجلتها مع التطبيق. لإيجاد بصمة الإبهام، انتقل من صفحة التطبيق في المدخل إلى Certificates & secrets الموجودة ضمن القسم Manage. وتكون بصمة الإبهام ضمن قائمة الشهادات.

  5. فتح بيان التطبيق في محرر البيان المضمن والتحقق من أن خاصية keyCredentials محدثة باستخدام معلومات شهادتك الجديدة على النحو الموضح أدناه -

    "keyCredentials": [
         {
             "customKeyIdentifier": "$base64Thumbprint", //base64 encoding of the certificate hash
             "keyId": "$keyid", //GUID to identify the key in the manifest
             "type": "AsymmetricX509Cert",
             "usage": "Verify",
             "value":  "$base64Value" //base64 encoding of the certificate raw data
         }
     ]
    
  6. الآن، يمكنك الحصول على رمز وصول لواجهة برمجة تطبيقات MS Graph باستخدام هذه الشهادة. استخدم أمر cmdlet Get-MSCloudIdMSGraphAccessTokenFromCert من الوحدة النمطية لـ PowerShell MSCloudIdUtils، الموجودة في معرف التطبيق و بصمة الإبهام التي حصلت عليها من الخطوة السابقة.

    Screenshot shows a PowerShell window with a command that creates an access token.

  7. استخدم رمز الوصول المميز في البرنامج النصي لـ PowerShell للاستعلام عن واجهة برمجة تطبيقات API Graph. استخدم أمر cmdlet Invoke-MSCloudIdMSGraphQuery من MSCloudIDUtils لإحصاء عدد مرات تسجيل الدخول ونقاط نهاية directoryAudits. يعالج هذا الأمر نتائج متعددة الصفحات، كما يرسل هذه النتائج إلى خط أنابيب PowerShell.

  8. الاستعلام عن نقطة نهاية directoryAudits لاسترداد سجلات مراجعة الحسابات.

    Screenshot shows a PowerShell window with a command to query the directoryAudits endpoint using the access token from earlier in this procedure.

  9. الاستعلام عن نقطة نهاية عدد مرات تسجيل الدخول لاسترداد سجلات تسجيل الدخول.

    Screenshot shows a PowerShell window with a command to query the signins endpoint using the access token from earlier in this procedure.

  10. يمكنك الآن تصدير هذه البيانات إلى CSV وحفظها في نظام SIEM. يمكنك أيضا تغليف برنامجك النصي في مهمة مجدولة للحصول على بيانات Azure AD من المستأجر بصورة دورية دون الحاجة إلى تخزين مفاتيح التطبيق في التعليمات البرمجية للمصدر.

الخطوات التالية