استخدام رموز OAuth المميزة التابعة لجهات خارجية

أنت الآن بصدد الاطّلاع على مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. info

في هذا الموضوع، سنتناول كيفية استيراد رموز الدخول أو رموز التحديث أو رموز المصادقة التي تم إنشاؤها خارجيًا إلى متجر الرموز المميزة في Edge. يمكنك استخدام هذه الطريقة إذا أردت ضبط Apigee Edge للتحقّق من صحة الرموز المميزة التي يتم إنشاؤها خارج Apigee Edge.

في الحالة العادية، ستنشئ Apigee Edge رمز OAuth وتخزّنه، ثم ستعيد إرساله إلى التطبيق الذي طلب الرمز. بعد ذلك، يعرض التطبيق الذي يطلب الخدمة الرمز المميّز مرة أخرى إلى Apigee Edge، وستتحقّق Apigee Edge من صلاحية الرمز المميّز من خلال سياسة OAuthV2 مع Operation = VerifyAccessToken. يوضّح هذا الموضوع كيف يمكنك ضبط Apigee Edge لتخزين رمز OAuth مميّز تم إنشاؤه في مكان آخر، مع إبقاء جزء التحقّق من الرمز المميّز كما هو، كما لو أنّ الرمز المميّز تم إنشاؤه بواسطة Edge.

مثال

إذا أردت الاطّلاع على مثال عملي يوضّح الأسلوب المذكور في هذا الموضوع، يمكنك الاطّلاع على نموذج إدارة الرموز المميزة المفوضة في Apigee.

What is this?‎

لنفترض أنّ لديك نظام تفويض حالي، وتريد استخدام قيم الرموز المميزة أو الرموز التي ينشئها هذا النظام بدلاً من قيم الرموز المميزة أو الرموز التي ينشئها Edge باستخدام بروتوكول OAuth2. يمكنك بعد ذلك تقديم طلبات آمنة لخادم وكيل لواجهة برمجة التطبيقات باستخدام الرمز المميز أو الرمز البديل، وستتحقّق Edge من صحة هذه الطلبات كما لو أنّها تم إنشاؤها بواسطة Edge.

بعض المعلومات الأساسية

في الحالة العادية، تنشئ Apigee Edge رمزًا مميزًا من خلال إنشاء سلسلة عشوائية من الأحرف والأرقام. يرتبط رمز الدخول في Apigee Edge ببيانات أخرى، مثل وقت إصدار الرمز وتاريخ انتهاء صلاحيته وقائمة منتجات واجهة برمجة التطبيقات التي يكون الرمز صالحًا لها ونطاقها. يمكن عرض كل هذه المعلومات في ردّ يتم إنشاؤه تلقائيًا بواسطة سياسة OAuthV2 التي تم ضبطها على Operation = GenerateAccessToken. تظهر الاستجابة بالشكل التالي:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

قيمة السمة access_token هي في الواقع مفتاح البحث عن بيانات الاستجابة. يمكن أن يرسل تطبيق طلبًا إلى خادم وكيل لواجهة برمجة التطبيقات مستضاف في Edge، ويحمل الرمز المميز لحامل الإذن zBC90HhCGmGlaMBWeZAai2s3za5j، وسيبحث Edge عن الرمز المميز باستخدام سياسة OAuthV2 التي تتضمّن Operation = VerifyAccessToken، وسيسترد جميع المعلومات، وسيستخدم هذه المعلومات لتحديد ما إذا كان الرمز المميز صالحًا أم لا لخادم وكيل لواجهة برمجة التطبيقات المطلوب. يُطلق على هذه العملية اسم التحقّق من صحة الرمز المميّز. تتضمّن الرمز المميز جميع المعلومات المذكورة أعلاه. قيمة access_token هي مجرد طريقة للبحث عن هذه المعلومات.

من ناحية أخرى، باتّباع الخطوات الموضّحة هنا، يمكنك ضبط Edge لتخزين رمز مميّز، وبالتالي تكون قيمة access_token هي قيمة تم إنشاؤها بواسطة خدمة خارجية. قد تكون جميع البيانات الوصفية الأخرى متطابقة. على سبيل المثال، لنفترض أنّ لديك نظامًا خارجيًا عن Apigee Edge ينشئ رموزًا مميّزة بالتنسيق "TOKEN-<16 رقمًا عشوائيًا>" . في هذه الحالة، قد تكون البيانات الوصفية الكاملة للرمز المميز التي تخزّنها Apigee Edge هي:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

في هذه الحالة، يمكن أن يقدّم تطبيق طلبًا إلى خادم وكيل لواجهة برمجة التطبيقات مستضاف في Edge، ويحمل الرمز المميز لحامل الإذن TOKEN-1092837373654221، وسيتمكّن Edge من التحقّق من صحة الرمز المميز من خلال سياسة OAuthV2 مع Operation = VerifyAccessToken. يمكنك تطبيق نمط استيراد مشابه على رموز التفويض ورموز التحديث المميزة.

لنتحدّث عن التحقّق من صحة بيانات اعتماد العميل

من المتطلبات الأساسية لإنشاء رمز مميّز هو التحقّق من صحة العميل الذي يقدّم الطلب. تتحقّق سياسة OAuthV2/GenerateAccessToken في Apigee Edge ضمنيًا من بيانات اعتماد العميل بشكل تلقائي. في العادة، عند طلب رمز مميّز OAuthV2، يتم تمرير client_id وclient_secret في عنوان Authorization، ويتم ترميزهما باستخدام HTTP Basic Authorization (يتم ربطهما بنقطتين، ثم يتم ترميزهما باستخدام base64). تعمل سياسة OAuthV2/GenerateAccessToken في Apigee Edge على فك ترميز هذا العنوان والبحث عن client_id، ثم التحقّق من أنّ client_secret الذي تم تمريره صالح لمعرّف العميل هذا. يعمل ذلك إذا كانت بيانات الاعتماد معروفة في Apigee Edge، أي إذا كان هناك تطبيق مطوّر مخزّن في Apigee Edge يحتوي على بيانات اعتماد تتضمّن client_id وclient_secret المحدّدين.

في حال عدم التحقّق من صحة بيانات اعتماد العميل من خلال Apigee Edge، عليك تصميم خادم وكيل لواجهة برمجة التطبيقات قبل إنشاء الرمز المميّز، وذلك للتحقّق من صحة بيانات العميل بشكل صريح من خلال بعض الوسائل الأخرى. ويتم ذلك غالبًا من خلال سياسة ServiceCallout التي تتصل بنقطة نهاية بعيدة في شبكتك.

في كلتا الحالتين، سواء بشكل ضمني أو صريح، عليك التأكّد من أنّ خادم وكيل واجهة برمجة التطبيقات الذي ينشئ الرموز المميّزة يتحقّق أولاً من صحة بيانات اعتماد العميل. يُرجى العِلم أنّ عملية التحقّق من صحة بيانات العميل مستقلة عن عملية إنشاء رمز الدخول. يمكنك ضبط Apigee Edge لتنفيذ كليهما أو أحدهما أو لا شيء منهما.

إذا كنت تريد أن تتحقّق سياسة OAuthV2/GenerateAccessToken في Apigee Edge من صحة بيانات اعتماد العميل استنادًا إلى متجر Edge، اضبط العنصر <ExternalAuthorization> على false ضِمن إعدادات السياسة، أو احذفه بالكامل. إذا أردت استخدام خدمة تفويض خارجية للتحقّق من صحة بيانات اعتماد العميل بشكل صريح، اضبط قيمة <ExternalAuthorization> على true.

على الرغم من أنّ Apigee Edge قد لا يتحقّق من صحة بيانات اعتماد العميل، إلا أنّه لا يزال من الضروري أن يكون معرّف العميل معروفًا ومُدارًا من خلال Apigee Edge. يجب ربط كل access_token في Apigee Edge بتطبيق عميل، سواء تم إنشاؤه بواسطة Apigee Edge أو بواسطة نظام خارجي ثم استيراده إلى Apigee Edge، ويتم تحديد التطبيق من خلال client_id. وبالتالي، حتى في حال عدم تحقّق سياسة OAuthV2/GenerateAccessToken في Apigee Edge من تطابق client_id وclient_secret، ستتحقّق السياسة من أنّ client_id صالح وموجود ولم يتم إبطاله. لذا، كخطوة إعداد مسبقة، قد تحتاج إلى استيراد معرّفات العميل من خلال واجهة برمجة التطبيقات الإدارية في Edge.

مسار السياسة لبروتوكول OAuth التابع لجهات خارجية على Apigee

لاستخدام الرموز المميزة من أنظمة OAuth التابعة لجهات خارجية في Apigee Edge، يجب أن يتّبع مسار إنشاء رموز الدخول أحد النماذج التالية.

التحقّق من صحة بيانات اعتماد العميل

  1. ServiceCallout للتحقّق من بيانات اعتماد العميل الواردة والحصول على رمز مميّز خارجي
  2. ExtractVariables أو خطوة JavaScript لاستخراج الرمز المميز الذي تم إنشاؤه خارجيًا من الردّ.
  3. AssignMessage لضبط المتغيّر الخاص المعروف باسم oauth_external_authorization_status. يجب أن تكون القيمة صحيحة للإشارة إلى أنّ بيانات اعتماد العميل صالحة.
  4. ‫OAuthV2/GenerateAccessToken مع ضبط العنصر <ExternalAuthorization> على true، وتضمين قيمة واحدة على الأقل من <ExternalAccessToken> أو <ExternalRefreshToken> أو <ExternalAuthorizationCode>.

التحقّق الداخلي من صحة بيانات اعتماد العميل

  • ServiceCallout للحصول على رمز مميّز خارجي.
  • ExtractVariables أو خطوة JavaScript لاستخراج الرمز المميز الذي تم إنشاؤه خارجيًا من الردّ.
  • ‫OAuthV2/GenerateAccessToken مع ضبط العنصر <ExternalAuthorization> على false، وعنصر واحد على الأقل من <ExternalAccessToken> أو <ExternalRefreshToken> أو <ExternalAuthorizationCode>

ملاحظات حول مسار العمل وإعدادات السياسة

  • في حال أردت استخدام نظام خارجي للتحقّق من بيانات اعتماد العميل، يعود إليك أمر تطوير مسار سياسة ينفّذ الإجراءات اللازمة. في العادة، يمكنك استخدام سياسة ServiceCallout لإرسال بيانات الاعتماد المعترف بها خارجيًا إلى خدمة المصادقة الخارجية. عادةً ما تعرض خدمة المصادقة الخارجية استجابة، وإذا كانت بيانات الاعتماد صالحة، تعرض أيضًا رمز دخول.

  • بعد ServiceCallout، يجب أن يحلّل خادم وكيل واجهة برمجة التطبيقات الرد لاستخراج حالة الصلاحية، بالإضافة إلى رمز الدخول access_token الذي تم إنشاؤه خارجيًا وربما رمز التحديث refresh_token.

  • في سياسة OAuthV2/GenerateAccessToken، اضبط العنصر <StoreToken> على true، واضبط العنصر <ExternalAuthorization> على true أو false حسب الاقتضاء.

    عند تنفيذ سياسة OAuthV2/GenerateAccessToken، يتم قراءة المتغيّر oauth_external_authorization_status. إذا تم ضبط المتغيّر وكانت القيمة صحيحة، لن تحاول Apigee Edge التحقّق من صحة بيانات اعتماد العميل. في حال عدم ضبط المتغيّر أو عدم ضبط القيمة على "صحيح"، ستحاول Apigee Edge التحقّق من صحة بيانات اعتماد العميل.

  • تتضمّن سياسة OAuthV2 ثلاثة عناصر تتيح لك تحديد البيانات الخارجية التي تريد استيرادها، وهي: <ExternalAccessToken> و<ExternalRefreshToken> و<ExternalAuthorizationCode>. يقبل كل عنصر من هذه العناصر متغير تدفق. ستقرأ سياسة Edge هذا المتغير للعثور على رمز الدخول أو رمز التحديث المميز أو رمز التفويض الذي تم إنشاؤه خارجيًا. ويقع على عاتقك تنفيذ السياسات والمنطق لوضع الرموز المميزة أو الرموز الخارجية في المتغيرات المناسبة.

    على سبيل المثال، يطلب الإعداد التالي في سياسة OAuthV2 من Edge البحث عن الرمز المميّز في متغيّر سياق اسمه external_token.

    <ExternalAccessToken>external_token</ExternalAccessToken>

    يجب أن تتضمّن أيضًا خطوة سابقة تحدّد هذا المتغيّر.

  • في ما يتعلق بضبط المتغيّر oauth_external_authorization_status، إحدى التقنيات الشائعة لضبط هذا المتغيّر هي استخدام سياسة AssignMessage مع العنصر AssignVariable، على النحو التالي:

    <AssignMessage name="AssignMessage-SetVariable">
    <DisplayName>Assign Message - Set Variable</DisplayName>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

    تذكَّر أنّ هذه السياسة يجب أن تسبق سياسة OAuthV2 التي تتضمّن العملية GenerateAccessToken.

مثال على سياسة OAuthV2

تنشئ سياسة OAuthV2 التالية رمز دخول إلى Apigee Edge، وذلك إذا عثرت Edge على قيمة رمز مميز في متغير التدفق external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

من الناحية النظرية، يمكنك تطبيق هذا النمط مع أي خدمة ترخيص تابعة لجهة خارجية تستخدم OAuth2.