الوصول إلى واجهة برمجة تطبيقات Application Insights باستخدام مصادقة Microsoft Entra

مقالة
10/18/2023

يمكنك إرسال طلب استعلام باستخدام نقطة https://api.applicationinsights.ioنهاية Azure Monitor Application Insights . للوصول إلى نقطة النهاية، يجب المصادقة من خلال معرف Microsoft Entra.

إعداد المصادقة

للوصول إلى واجهة برمجة التطبيقات، يمكنك تسجيل تطبيق عميل باستخدام معرف Microsoft Entra وطلب رمز مميز.

تسجيل تطبيق في معرف Microsoft Entra.
في صفحة نظرة عامة على التطبيق، حدد أذونات واجهة برمجة التطبيقات.
حدد إضافة إذن.
في علامة التبويب واجهات برمجة التطبيقات التي تستخدمها مؤسستي، ابحث عن Application Insights وحدد Application Insights API من القائمة.
حدد الأذونات المفوضة.
حدد خانة الاختيار Data.Read .
حدد إضافة أذونات.

الآن بعد أن تم تسجيل تطبيقك ولديه أذونات لاستخدام واجهة برمجة التطبيقات، امنح تطبيقك حق الوصول إلى مورد Application Insights.

من صفحة نظرة عامة على مورد Application Insights، حدد Access control (IAM).
حدد Add role assignment.
حدد دور القارئ ثم حدد الأعضاء.
في علامة التبويب الأعضاء ، اختر تحديد أعضاء.
أدخل اسم تطبيقك في المربع تحديد .
حدد تطبيقك واختر تحديد.
حدد مراجعة + تعيين.
بعد الانتهاء من إعداد Active Directory والأذونات، اطلب رمزا مميزا للتخويل.

إشعار

على سبيل المثال، طبقنا دور القارئ. هذا الدور هو واحد من العديد من الأدوار المضمنة وقد يتضمن أذونات أكثر مما تحتاج. يمكن إنشاء المزيد من الأدوار والأذونات الدقيقة.

طلب رمز تخويل مميز

قبل البدء، تأكد من أن لديك جميع القيم المطلوبة لإجراء الطلب بنجاح. تتطلب جميع الطلبات ما يلي:

معرف مستأجر Microsoft Entra.
معرف تطبيق App Insights - إذا كنت تستخدم حاليا مفاتيح واجهة برمجة التطبيقات، فهذا هو معرف التطبيق نفسه.
معرف عميل Microsoft Entra للتطبيق.
سر عميل Microsoft Entra للتطبيق.

تدعم واجهة برمجة تطبيقات Application Insights مصادقة Microsoft Entra مع ثلاثة تدفقات مختلفة من Microsoft Entra ID OAuth2 :

بيانات اعتماد العميل
التعليمة البرمجية للتخويل
ضمني

تدفق بيانات اعتماد العميل

في تدفق بيانات اعتماد العميل، يتم استخدام الرمز المميز مع نقطة نهاية Application Insights. يتم تقديم طلب واحد لتلقي رمز مميز باستخدام بيانات الاعتماد المتوفرة لتطبيقك في الخطوة السابقة عند تسجيل تطبيق في Microsoft Entra ID.

https://api.applicationinsights.io استخدم نقطة النهاية.

عنوان URL للرمز المميز لبيانات اعتماد العميل (طلب POST)

    POST /<your-tenant-id>/oauth2/token
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=client_credentials
    &client_id=<app-client-id>
    &resource=https://api.applicationinsights.io
    &client_secret=<app-client-secret>

يتلقى الطلب الناجح رمزا مميزا للوصول في الاستجابة:

    {
        token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
    }

استخدم الرمز المميز في الطلبات إلى نقطة نهاية Application Insights:

    POST /v1/apps/yous_app_id/query?timespan=P1D
    Host: https://api.applicationinsights.io
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "requests | take 10"
    }

استجابة مثال:

  "tables": [
    {
      "name": "PrimaryResult",
      "columns": [
        {
          "name": "timestamp",
          "type": "datetime"
        },
        {
          "name": "id",
          "type": "string"
        },
        {
          "name": "source",
          "type": "string"
        },
        {
          "name": "name",
          "type": "string"
        },
        {
          "name": "url",
          "type": "string"
        },
        {
          "name": "success",
          "type": "string"
        },
        {
          "name": "resultCode",
          "type": "string"
        },
        {
          "name": "duration",
          "type": "real"
        },
        {
          "name": "performanceBucket",
          "type": "string"
        },
        {
          "name": "customDimensions",
          "type": "dynamic"
        },
        {
          "name": "customMeasurements",
          "type": "dynamic"
        },
        {
          "name": "operation_Name",
          "type": "string"
        },
        {
          "name": "operation_Id",
          "type": "string"
        },
        {
          "name": "operation_ParentId",
          "type": "string"
        },
        {
          "name": "operation_SyntheticSource",
          "type": "string"
        },
        {
          "name": "session_Id",
          "type": "string"
        },
        {
          "name": "user_Id",
          "type": "string"
        },
        {
          "name": "user_AuthenticatedId",
          "type": "string"
        },
        {
          "name": "user_AccountId",
          "type": "string"
        },
        {
          "name": "application_Version",
          "type": "string"
        },
        {
          "name": "client_Type",
          "type": "string"
        },
        {
          "name": "client_Model",
          "type": "string"
        },
        {
          "name": "client_OS",
          "type": "string"
        },
        {
          "name": "client_IP",
          "type": "string"
        },
        {
          "name": "client_City",
          "type": "string"
        },
        {
          "name": "client_StateOrProvince",
          "type": "string"
        },
        {
          "name": "client_CountryOrRegion",
          "type": "string"
        },
        {
          "name": "client_Browser",
          "type": "string"
        },
        {
          "name": "cloud_RoleName",
          "type": "string"
        },
        {
          "name": "cloud_RoleInstance",
          "type": "string"
        },
        {
          "name": "appId",
          "type": "string"
        },
        {
          "name": "appName",
          "type": "string"
        },
        {
          "name": "iKey",
          "type": "string"
        },
        {
          "name": "sdkVersion",
          "type": "string"
        },
        {
          "name": "itemId",
          "type": "string"
        },
        {
          "name": "itemType",
          "type": "string"
        },
        {
          "name": "itemCount",
          "type": "int"
        }
      ],
      "rows": [
        [
          "2018-02-01T17:33:09.788Z",
          "|0qRud6jz3k0=.c32c2659_",
          null,
          "GET Reports/Index",
          "http://fabrikamfiberapp.azurewebsites.net/Reports",
          "True",
          "200",
          "3.3833",
          "<250ms",
          "{\"_MS.ProcessedByMetricExtractors\":\"(Name:'Requests', Ver:'1.0')\"}",
          null,
          "GET Reports/Index",
          "0qRud6jz3k0=",
          "0qRud6jz3k0=",
          "Application Insights Availability Monitoring",
          "9fc6738d-7e26-44f0-b88e-6fae8ccb6b26",
          "us-va-ash-azr_9fc6738d-7e26-44f0-b88e-6fae8ccb6b26",
          null,
          null,
          "AutoGen_49c3aea0-4641-4675-93b5-55f7a62d22d3",
          "PC",
          null,
          null,
          "52.168.8.0",
          "Boydton",
          "Virginia",
          "United States",
          null,
          "fabrikamfiberapp",
          "RD00155D5053D1",
          "cf58dcfd-0683-487c-bc84-048789bca8e5",
          "fabrikamprod",
          "5a2e4e0c-e136-4a15-9824-90ba859b0a89",
          "web:2.5.0-33031",
          "051ad4ef-0776-11e8-ac6e-e30599af6943",
          "request",
          "1"
        ],
        [
          "2018-02-01T17:33:15.786Z",
          "|x/Ysh+M1TfU=.c32c265a_",
          null,
          "GET Home/Index",
          "http://fabrikamfiberapp.azurewebsites.net/",
          "True",
          "200",
          "716.2912",
          "500ms-1sec",
          "{\"_MS.ProcessedByMetricExtractors\":\"(Name:'Requests', Ver:'1.0')\"}",
          null,
          "GET Home/Index",
          "x/Ysh+M1TfU=",
          "x/Ysh+M1TfU=",
          "Application Insights Availability Monitoring",
          "58b15be6-d1e6-4d89-9919-52f63b840913",
          "emea-se-sto-edge_58b15be6-d1e6-4d89-9919-52f63b840913",
          null,
          null,
          "AutoGen_49c3aea0-4641-4675-93b5-55f7a62d22d3",
          "PC",
          null,
          null,
          "51.141.32.0",
          "Cardiff",
          "Cardiff",
          "United Kingdom",
          null,
          "fabrikamfiberapp",
          "RD00155D5053D1",
          "cf58dcfd-0683-487c-bc84-048789bca8e5",
          "fabrikamprod",
          "5a2e4e0c-e136-4a15-9824-90ba859b0a89",
          "web:2.5.0-33031",
          "051ad4f0-0776-11e8-ac6e-e30599af6943",
          "request",
          "1"
        ]
      ]
    }
  ]
}

تدفق تعليمات التفويض البرمجية

تدفق OAuth2 الرئيسي المدعوم من خلال التعليمات البرمجية للتخويل. يتطلب هذا الأسلوب طلبي HTTP للحصول على رمز مميز لاستدعاء واجهة برمجة تطبيقات Azure Monitor Application Insights. هناك عنوانا URL، مع نقطة نهاية واحدة لكل طلب. يتم وصف تنسيقاتها في الأقسام التالية.

عنوان URL لرمز التخويل (طلب GET)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.applicationinsights.io

عند تقديم طلب إلى عنوان URL للتخويل، فإن client_id هو معرف التطبيق من تطبيق Microsoft Entra، المنسخ من قائمة خصائص التطبيق. redirect_uri هو عنوان URL للصفحة الرئيسية/تسجيل الدخول من نفس تطبيق Microsoft Entra. عند نجاح الطلب، تعيد نقطة النهاية هذه توجيهك إلى صفحة تسجيل الدخول التي قدمتها عند التسجيل باستخدام رمز التخويل الملحق بعنوان URL. راجع المثال التالي:

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

عند هذه النقطة، حصلت على رمز تخويل، والذي تحتاج إليه الآن لطلب رمز مميز للوصول.

عنوان URL لرمز التخويل (طلب POST)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.applicationinsights.io
    &client_secret=<app-client-secret>

جميع القيم هي كما كانت من قبل، مع بعض الإضافات. التعليمة البرمجية للتخويل هي نفس التعليمة البرمجية التي تلقيتها في الطلب السابق بعد إعادة توجيه ناجحة. يتم دمج التعليمات البرمجية مع المفتاح الذي تم الحصول عليه من تطبيق Microsoft Entra. إذا لم تحفظ المفتاح، يمكنك حذفه وإنشاء مفتاح جديد من علامة تبويب المفاتيح في قائمة تطبيق Microsoft Entra. الاستجابة هي سلسلة JSON تحتوي على الرمز المميز مع المخطط التالي. تتم الإشارة إلى الأنواع لقيم الرمز المميز.

مثال الاستجابة:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_app_insights",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.applicationinsights.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

جزء الرمز المميز للوصول من هذه الاستجابة هو ما تقدمه إلى واجهة برمجة تطبيقات Application Insights في Authorization: Bearer العنوان. يمكنك أيضا استخدام الرمز المميز للتحديث في المستقبل للحصول على access_token جديد refresh_token عندما يكون رمز التحديث الخاص بك قديما. بالنسبة لهذا الطلب، يكون التنسيق ونقطة النهاية هما:

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.applicationinsights.io
    &client_secret=<app-client-secret>

مثال الاستجابة:

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.applicationinsights.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

تدفق التعليمات البرمجية الضمنية

تدعم واجهة برمجة تطبيقات Application Insights التدفق الضمني OAuth2. لهذا التدفق، مطلوب طلب واحد فقط، ولكن لا يمكن الحصول على رمز تحديث مميز.

عنوان URL لتخويل التعليمات البرمجية الضمنية

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.applicationinsights.io

ينتج عن الطلب الناجح إعادة توجيه إلى عنوان URI لإعادة التوجيه باستخدام الرمز المميز في عنوان URL:

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

يمكن استخدام هذه access_token كقيمة Authorization: Bearer رأس عند تمريرها إلى واجهة برمجة تطبيقات Application Insights لتخويل الطلبات.

Share via