مشاركة عبر

استدعاء واجهة برمجة تطبيقات REST باستخدام نهج Azure Active Directory B2C المخصص

  • مقالة

يسمح لك النهج المخصص ل Azure Active Directory B2C (Azure AD B2C) بالتفاعل مع منطق التطبيق الذي تنفذه خارج Azure AD B2C. للقيام بذلك، يمكنك إجراء استدعاء HTTP إلى نقطة نهاية. توفر نهج Azure AD B2C المخصصة ملف تعريف تقني RESTful لهذا الغرض. باستخدام هذه الإمكانية، يمكنك تنفيذ الميزات غير المتوفرة في نهج Azure AD B2C المخصص.

في هذه المقالة، ستتعرف على كيفية:

  • إنشاء تطبيق Node.js نموذجي ونشره لاستخدامه كخدمة RESTful.

  • قم بإجراء استدعاء HTTP إلى خدمة Node.js RESTful باستخدام ملف التعريف الفني RESTful.

  • معالجة أو الإبلاغ عن خطأ ترجعه خدمة RESTful إلى النهج المخصص.

نظرة عامة على السيناريو

في إنشاء تفريع في رحلة المستخدم باستخدام نهج Azure AD B2C المخصصة، يحتاج المستخدمون الذين يحددون الحساب الشخصي إلى توفير رمز وصول دعوة صالح للمتابعة. نستخدم رمز وصول ثابت، ولكن تطبيقات العالم الحقيقي لا تعمل بهذه الطريقة. إذا كانت الخدمة التي تصدر رموز الوصول خارجية لنهجك المخصص، يجب إجراء استدعاء لتلك الخدمة، وتمرير إدخال رمز الوصول من قبل المستخدم للتحقق من الصحة. إذا كان رمز الوصول صالحا، تقوم الخدمة بإرجاع استجابة HTTP 200 OK ، وتصدر Azure AD B2C رمز JWT المميز. وإلا، تقوم الخدمة بإرجاع استجابة HTTP 409 Conflict ، ويجب على المستخدم إعادة إدخال رمز وصول.

A flowchart of calling a R E S T A P I.

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

إشعار

هذه المقالة هي جزء من سلسلة دليل كيفية إنشاء وتشغيل النهج المخصصة الخاصة بك في Azure Active Directory B2C. نوصي ببدء تشغيل هذه السلسلة من المقالة الأولى.

الخطوة 1 - إنشاء تطبيق Node.js ونشره

تحتاج إلى نشر تطبيق، والذي يعمل كتطبيق خارجي. ثم يقوم نهجك المخصص بإجراء استدعاء HTTP لهذا التطبيق.

الخطوة 1.1 - إنشاء تطبيق Node.js

  1. قم بإنشاء مجلد لاستضافة تطبيق العقدة الخاص بك، مثل access-code-app.

  2. في المحطة الطرفية، قم بتغيير الدليل إلى مجلد تطبيق العقدة، مثل cd access-code-app، ثم قم بالتشغيل npm init -y. ينشئ هذا الأمر ملف افتراضي package.json للمشروع Node.js.

  3. في محطتك الطرفية، قم بـ «تشغيل npm install express body-parser». يقوم هذا الأمر بتثبيت إطار عمل Express وحزمة محلل النص الأساسي.

  4. في مشروعك، قم بإنشاء index.js ملف.

  5. في VS Code، افتح index.js الملف، ثم أضف التعليمات البرمجية التالية:

        const express = require('express');
    let bodyParser = require('body-parser')
    //Create an express instance
    const app = express();

    app.use( bodyParser.json() );       // to support JSON-encoded bodies
    app.use(bodyParser.urlencoded({     // to support URL-encoded bodies
      extended: true
    }));


    app.post('/validate-accesscode', (req, res) => {
        let accessCode = '88888';
        if(accessCode == req.body.accessCode){
            res.status(200).send();
        }else{
            let errorResponse = {
                "version" :"1.0",
                "status" : 409,
                "code" : "errorCode",
                "requestId": "requestId",
                "userMessage" : "The access code you entered is incorrect. Please try again.",
                "developerMessage" : `The provided code ${req.body.accessCode} does not match the expected code for user.`,
                "moreInfo" :"https://docs.microsoft.com/en-us/azure/active-directory-b2c/string-transformations"
            };
            res.status(409).send(errorResponse);                
        }
    });

    app.listen(80, () => {
        console.log(`Access code service listening on port !` + 80);
    });

    يمكنك ملاحظة أنه عندما يرسل مستخدم رمز وصول خاطئ، يمكنك إرجاع خطأ مباشرة من واجهة برمجة تطبيقات REST. تسمح لك النهج المخصصة بإرجاع رسالة خطأ HTTP 4xx، مثل رمز حالة استجابة 400 (طلب غير صحيح) أو 409 (تعارض) مع نص JSON استجابة منسق كما هو موضح في errorResponse المتغير. يمكن قراءة مصدر accessCode في التطبيق من قاعدة بيانات. تعرف على المزيد حول إرجاع رسالة خطأ التحقق من الصحة.

  6. لاختبار عمل التطبيق كما هو متوقع، استخدم الخطوات التالية:

    1. في المحطة الطرفية، قم بتشغيل node index.js الأمر لبدء تشغيل خادم التطبيق الخاص بك.
    2. لجعل طلب POST مشابها للطلب الموضح في هذا المثال، يمكنك استخدام عميل HTTP مثل Microsoft PowerShell أو Postman:
        POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

    استبدل user-code-code بإدخال رمز الوصول من قبل المستخدم، مثل 54321. إذا كنت تستخدم PowerShell، فقم بتشغيل البرنامج النصي التالي.

        $accessCode="54321"
    $endpoint="http://localhost/validate-accesscode"
    $body=$accessCode
    $response=Invoke-RestMethod -Method Post -Uri $endpoint -Body $body
    echo $response

    إذا كنت تستخدم رمز وصول غير صحيح، تبدو الاستجابة مشابهة لمقتطف JSON التالي:

        {
        "version": "1.0",
        "status": 409,
        "code": "errorCode",
        "requestId": "requestId",
        "userMessage": "The access code you entered is incorrect. Please try again.",
        "developerMessage": "The provided code 54321 does not match the expected code for user.",
        "moreInfo": "https://docs.microsoft.com/en-us/azure/active-directory-b2c/string-transformations"
    }

في هذه المرحلة، أنت مستعد لنشر تطبيق Node.js الخاص بك.

الخطوة 1.2 - نشر تطبيق Node.js في Azure App Service

لكي يصل نهجك المخصص إلى تطبيق Node.js الخاص بك، يجب أن يكون قابلا للوصول، لذلك، تحتاج إلى نشره. في هذه المقالة، يمكنك نشر التطبيق باستخدام Azure App Service، ولكن يمكنك استخدام نهج استضافة بديل.

اتبع الخطوات الواردة في نشر تطبيقك إلى Azure لنشر تطبيق Node.js إلى Azure. بالنسبة إلى اسم التطبيق، استخدم اسما وصفيا مثل custompolicyapi. وب التالي:

  • يبدو عنوان URL للتطبيق مشابها ل https://custompolicyapi.azurewebsites.net.

  • تبدو نقطة نهاية الخدمة مشابهة ل https://custompolicyapi.azurewebsites.net/validate-accesscode.

يمكنك اختبار التطبيق الذي قمت بنشره باستخدام عميل HTTP مثل Microsoft PowerShell أو Postman. هذه المرة، استخدم https://custompolicyapi.azurewebsites.net/validate-accesscode عنوان URL كنقطة نهاية.

الخطوة 2 - استدعاء واجهة برمجة تطبيقات REST

الآن بعد أن أصبح تطبيقك قيد التشغيل، تحتاج إلى إجراء مكالمة HTTP من نهجك المخصص. يوفر نهج Azure AD B2C المخصص ملف تعريف تقني RESTful الذي تستخدمه لاستدعاء خدمة خارجية.

الخطوة 2.1 - تحديد ملف تعريف تقني RESTful

في ملفك ContosoCustomPolicy.XML ، حدد موقع ClaimsProviders القسم، وحدد ملف تعريف تقني RESTful جديد باستخدام التعليمات البرمجية التالية:

    <!--<ClaimsProviders>-->
        <ClaimsProvider>
            <DisplayName>HTTP Request Technical Profiles</DisplayName>
            <TechnicalProfiles>
                <TechnicalProfile Id="ValidateAccessCodeViaHttp">
                    <DisplayName>Check that the user has entered a valid access code by using Claims Transformations</DisplayName>
                    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
                    <Metadata>
                        <Item Key="ServiceUrl">https://custompolicyapi.azurewebsites.net/validate-accesscode</Item>
                        <Item Key="SendClaimsIn">Body</Item>
                        <Item Key="AuthenticationType">None</Item>
                        <Item Key="AllowInsecureAuthInProduction">true</Item>
                    </Metadata>
                    <InputClaims>
                        <InputClaim ClaimTypeReferenceId="accessCode" PartnerClaimType="accessCode" />
                    </InputClaims>
                </TechnicalProfile>
            </TechnicalProfiles>
        </ClaimsProvider>
    <!--</ClaimsProviders>-->

من البروتوكول، يمكنك ملاحظة أننا نقوم بتكوين ملف التعريف الفني لاستخدام RestfulProvider. يمكنك أيضا مراقبة المعلومات التالية في قسم بيانات التعريف:

  • ServiceUrl يمثل نقطة نهاية واجهة برمجة التطبيقات. قيمته هي https://custompolicyapi.azurewebsites.net/validate-accesscode. إذا قمت بنشر تطبيق Node.js الخاص بك باستخدام أسلوب بديل، فتأكد من تحديث قيمة نقطة النهاية.

  • SendClaimsIn يحدد كيفية إرسال مطالبات الإدخال إلى موفر مطالبات RESTful. القيم المحتملة: Body (default)أو HeaderFormأو Url أو .QueryString عند استخدام Body، كما هو الحال في هذه المقالة، يمكنك استدعاء فعل POST HTTP والبيانات التي ترسلها إلى واجهة برمجة التطبيقات إذا تم تنسيقها كمفتاح، وأزواج القيم في نص الطلب. تعرف على كيفية استدعاء فعل GET HTTP وتمرير البيانات كسلسلة استعلام.

  • AuthenticationType يحدد نوع المصادقة التي يقوم بها موفر مطالبات RESTful. يستدعي موفر مطالبات RESTful نقطة نهاية غير محمية، لذلك قمنا بتعيين إلى AuthenticationTypeبلا. إذا قمت بتعيين نوع المصادقة إلى Bearer، فستحتاج إلى إضافة عنصر CryptographicKeys ، والذي يحدد تخزين الرمز المميز للوصول الخاص بك. تعرف على المزيد حول أنواع المصادقة التي يدعمها موفر مطالبات RESTful.

  • تحدد السمة InputClaim PartnerClaimType في كيفية تلقي بياناتك في واجهة برمجة التطبيقات.

الخطوة 2.2 - تحديث ملف التعريف الفني للتحقق من الصحة

في إنشاء تفريع في رحلة المستخدم باستخدام نهج Azure AD B2C المخصص، قمت بالتحقق من صحة accessCode باستخدام تحويل المطالبات. في هذه المقالة، يمكنك التحقق من صحة accessCode عن طريق إجراء مكالمة HTTP إلى خدمة خارجية. لذلك، ستحتاج إلى تحديث نهجك المخصص ليعكس النهج الجديد.

حدد موقع ملف التعريف التقني AccessCodeInputCollector، وقم بتحديث ReferenceId الخاص بعنصر ValidationTechnicalProfile إلى ValidateAccessCodeViaHttp:

من:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

لكي تتمكن من:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

عند هذه النقطة، ملف التعريف الفني مع IdCheckAccessCodeViaClaimsTransformationChecker غير مطلوب، ويمكن إزالته.

الخطوة 3 - تحميل ملف نهج مخصص

تأكد من تشغيل تطبيق Node.js، ثم اتبع الخطوات الواردة في تحميل ملف النهج المخصص لتحميل ملف النهج الخاص بك. إذا كنت تقوم بتحميل ملف بنفس اسم الملف الموجود بالفعل في المدخل، فتأكد من تحديد الكتابة فوق النهج المخصص إذا كان موجودا بالفعل.

الخطوة 4 - اختبار النهج المخصص

اتبع الخطوات الواردة في اختبار النهج المخصص لاختبار النهج المخصص:

  1. بالنسبة إلى نوع الحساب، حدد حساب شخصي
  2. أدخل بقية التفاصيل كما هو مطلوب، ثم حدد متابعة. ترى شاشة جديدة.
  3. بالنسبة إلى Access Code، أدخل 88888، ثم حدد Continue. بعد انتهاء النهج من التنفيذ، تتم إعادة توجيهك إلى https://jwt.ms، وترى رمز JWT المميز الذي تم فك ترميزه. إذا كررت الإجراء، وأدخلت رمز وصول مختلفا، بخلاف 88888، فسترى خطأ، رمز الوصول الذي أدخلته غير صحيح. الرجاء المحاولة مرة أخرى.

الخطوة 5 - تمكين وضع التصحيح

في التطوير، قد تحتاج إلى رؤية أخطاء مفصلة تم إرسالها بواسطة واجهة برمجة التطبيقات، مثل developerMessage و moreInfo. في هذه الحالة، تحتاج إلى تمكين وضع التصحيح في موفر RESTful التقني.

  1. حدد موقع الموفر التقني ValidateAccessCodeViaHttp، وأضف العنصر التالي في :metadata

        <Item Key="DebugMode">true</Item>

  2. احفظ التغييرات وحمل ملف النهج الخاص بك.

  3. اختبر نهجك المخصص. تأكد من استخدام إدخال خاطئ ل Access Code. ترى خطأ مشابها للخطأ الموضح في لقطة الشاشة هذه:

    A screenshot error when you enable debug mode.

معالجة حمولات JSON للطلب المعقد

إذا كانت واجهة برمجة تطبيقات REST التي تستدعيها تتطلب منك إرسال حمولة JSON معقدة، يمكنك إنشاء الحمولة باستخدام تحويلات مطالبات GenerateJson JSON. بمجرد إنشاء الحمولة، يمكنك بعد ذلك استخدام ClaimUsedForRequestPayload خيار بيانات التعريف لاسم المطالبة التي تحتوي على حمولة JSON.

على سبيل المثال، استخدم تحويل المطالبات التالي لإنشاء حمولة JSON:

    <ClaimsTransformation Id="GenerateRequestBodyClaimsTransformation" TransformationMethod="GenerateJson">
        <InputClaims>
            <InputClaim ClaimTypeReferenceId="email" TransformationClaimType="customerEntity.email" />
            <InputClaim ClaimTypeReferenceId="objectId" TransformationClaimType="customerEntity.userObjectId" />
            <InputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="customerEntity.firstName" />
            <InputClaim ClaimTypeReferenceId="surname" TransformationClaimType="customerEntity.lastName" />
            <InputClaim ClaimTypeReferenceId="accessCode" TransformationClaimType="customerEntity.accessCode" />
        </InputClaims>
        <InputParameters>
            <InputParameter Id="customerEntity.role.name" DataType="string" Value="Administrator" />
            <InputParameter Id="customerEntity.role.id" DataType="long" Value="1" />
        </InputParameters>
        <OutputClaims>
            <OutputClaim ClaimTypeReferenceId="requestBodyPayload" TransformationClaimType="outputClaim" />
        </OutputClaims>
    </ClaimsTransformation>

ينشئ ClaimsTransformation كائن JSON التالي:

{
   "customerEntity":{
      "email":"john.s@contoso.com",
      "userObjectId":"01234567-89ab-cdef-0123-456789abcdef",
      "firstName":"John",
      "lastName":"Smith",
      "accessCode":"88888",
      "role":{
         "name":"Administrator",
         "id": 1
      }
   }
}

بعد ذلك، قم بتحديث بيانات التعريف وInputClaimsTransformations وInputClaims لموفر RESTful التقني كما هو موضح أدناه:

    <Metadata>
        <Item Key="ClaimUsedForRequestPayload">requestBodyPayload</Item>
        <!--Other Metadata items -->
    </Metadata>
    
    <!--Execute your InputClaimsTransformations to generate your request Payload-->
    <InputClaimsTransformations>
        <InputClaimsTransformation ReferenceId="GenerateRequestBodyClaimsTransformation" />
    </InputClaimsTransformations>
    
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="requestBodyPayload" />
    </InputClaims>

تلقي البيانات من واجهة برمجة تطبيقات REST

إذا قامت واجهة برمجة تطبيقات REST بإرجاع البيانات، والتي تريد تضمينها كمطالبات في نهجك، يمكنك تلقيها عن طريق تحديد المطالبات في OutputClaims عنصر ملف التعريف الفني RESTful. إذا كان اسم المطالبة المحددة في نهجك مختلفا عن الاسم المحدد في واجهة برمجة تطبيقات REST، فستحتاج إلى تعيين هذه الأسماء باستخدام السمة PartnerClaimType .

استخدم الخطوات الواردة في تلقي البيانات لمعرفة كيفية تنسيق البيانات التي يتوقعها النهج المخصص، وكيفية التعامل مع قيم القيم الخالية، وكيفية تحليل REST لنص JSON المتداخل لواجهة برمجة التطبيقات.

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

بعد ذلك، تعرف على: