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

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X. المعلومات

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

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

مثال

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

ما هذا؟

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

بعض المعلومات عن الخلفية

في الحالة المعتادة، تنشئ Apigee Edge رمزًا مميّزًا من خلال إنتاج سلسلة عشوائية من الأحرف والأرقام. وتربط Apigee Edge بهذا الرمز المميّز، وبيانات أخرى، مثل وقت إصدار الرمز المميّز، وانتهاء الصلاحية، وقائمة منتجات واجهة برمجة التطبيقات التي يكون الرمز المميّز صالحًا لها، والنطاق. يمكن عرض كل هذه المعلومات في استجابة يتم إنشاؤها تلقائيًا بواسطة سياسة OAuthV2 التي تم ضبطها باستخدام العملية = 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 مع العملية = تأكيدAccessToken - عن الرمز المميز ويسترد جميع المعلومات ويستخدم تلك المعلومات لتحديد ما إذا كان الرمز المميز صالحًا أم لا، للخادم الوكيل المطلوب لواجهة برمجة التطبيقات. تُعرف هذه العملية باسم التحقّق من صحة الرمز المميّز. تشتمل جميع المعلومات الواردة أعلاه على الرمز المميّز. وتُعدّ قيمة access_token طريقة للبحث عن تلك المعلومات.

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

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

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

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

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

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

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