استخدام نطاقات OAuth2

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

يناقش هذا الموضوع كيفية استخدام نطاقات OAuth 2.0 في Apigee Edge.

ما المقصود بنطاق OAuth2؟

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

سوف نناقش في هذا الموضوع طريقة تعيين النطاقات لرموز الدخول وكيفية استخدام Apigee Edge. لفرض نطاقات OAuth 2.0. بعد قراءة هذا الموضوع، ستتمكن من استخدام النطاقات مع الثقة.

كيف يتم تعيين النطاقات لرموز الدخول؟

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

رمز الوصول هو سلسلة طويلة من الأحرف التي تبدو عشوائية يسمح لنظام Edge بالتحقّق من طلبات البيانات الواردة من واجهة برمجة التطبيقات (يمكنك اعتبارها خيارًا بديلاً عن بيانات اعتماد اسم المستخدم/كلمة المرور). من الناحية الفنية، الرمز المميز هو مفتاح يشير إلى مجموعة من بيانات التعريف التي تبدو كالتالي:

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

تتضمن البيانات الوصفية للرمز المميز سلسلة رمز الدخول الفعلي ومعلومات انتهاء الصلاحية تحديد تطبيق المطور والمطوّر والمنتجات المرتبطة بالرمز المميز. وسوف لاحظ أيضًا أن بيانات التعريف تتضمن أيضًا "النطاق".

كيف يحصل الرمز المميز على نطاقه؟

المفتاح الأول لفهم النطاق هو تذكر أن كل منتج في تطبيق المطور يمكن ألّا يكون لها أي نطاقات أو أكثر مُعيَّنة لها. يمكن تعيين هذه النطاقات عندما يكون المنتج أو يمكن إضافتها لاحقًا. وهي موجودة كقائمة أسماء ويتم تضمينها في "بيانات التعريف" المرتبطة بكل منتج.

عند إنشاء تطبيق مطوِّر وإضافة منتجات إليه، يفحص Edge جميع المنتجات في تطبيق المطور وينشئ قائمة بجميع النطاقات لتلك المنتجات (النطاق الرئيسي أو قائمة النطاقات العامة -- اتحاد جميع النطاقات المعروفة).

عندما يطلب تطبيق عميل رمز دخول من Apigee Edge، يمكنه اختياريًا تحديد النطاقات التي ترغب في ربطها بهذا الرمز. على سبيل المثال، يطلب الطلب التالي للنطاق "A". وهذا يعني أن العميل يطلب من خادم التفويض (Edge) إنشاء ملف رمز الدخول ذو النطاق "A" (مما يمنح التطبيق إذنًا لاستدعاء واجهات برمجة التطبيقات التي تشتمل على النطاق "A"). يرسل التطبيق طلب POST على النحو التالي:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A

الإجراء

عندما يتلقى Edge هذا الطلب، يعرف التطبيق الذي يقدم الطلب ويعرف أي تطبيق مطوّر البرامج الذي سجّله العميل (يتم ترميز معرِّف العميل ومفاتيح سر العميل بتنسيق عنوان المصادقة الأساسية). ولأنّ معلَمة طلب البحث "scope" مضمّنة، تحتاج Edge إلى تحديد ما إذا كان أي من منتجات واجهة برمجة التطبيقات المرتبطة بتطبيق المطوّر يتضمن النطاق "أ". إذا فعلت ذلك، ثم يتم إنشاء رمز الدخول بالنطاق "A". هناك طريقة أخرى للنظر إلى هذا وهي أن النطاق معلمة طلب البحث نوعًا من التصفية. إذا تعرّف تطبيق المطوّر على النطاقات "أ" و"ب" و"س" تحدد معلمة طلب البحث "scope=X Y Z"، ثم النطاق "X" فقط إلى الرمز المميز.

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

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

لنفترض أن تطبيقًا مطوِّرًا يتعرّف على هذه النطاقات: أ ب ج. هذه هي القائمة الرئيسية للتطبيق والنطاقات. قد يكون أحد المنتجات في التطبيق له النطاق "أ" و"ب"، والآخر له النطاق "ج" و D أو أي مزيج منهما. إذا لم يحدّد العميل مَعلمة scope (أو إذا فإنها تحدد معلمة نطاق بدون قيمة) سيتم منح الرمز المميز جميع النطاقات الأربعة: A، B، C، و د. مرة أخرى، يتلقّى الرمز المميّز مجموعة من النطاقات التي تمثّل اتحاد جميع النطاقات المعترَف بها بواسطة تطبيق مطوّر البرامج.

هناك حالة أخرى حيث يكون السلوك الافتراضي هو عرض رمز الدخول بجميع بشكل عام، وذلك عند تطبيق سياسة GenerateAccessToken (سياسة Apigee Edge التي (ينشئ رموز دخول) لا يحدد العنصر <Scope>. على سبيل المثال، في ما يلي سياسة GenerateAccessToken حيث يمكن استخدام <Scope> يتم تحديده. في حال كان عنصر <Scope> غير متوفّر (أو إذا كان موجودة ولكنها فارغة)، يتم تنفيذ السلوك الافتراضي.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

كيف يتم فرض النطاقات؟

تذكَّر أولاً أنّه في Apigee Edge، يتم التحقّق من رموز الدخول باستخدام سياسة OAuthV2. (يتم وضعها عادةً في بداية تدفق الخادم الوكيل). يجب أن تتضمن السياسة تم تحديد عملية VerifyAccessToken. لنلقِ نظرة على هذه السياسة:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

دوِّن العنصر <Scope>. ويتم استخدامه لتحديد النطاقات التي تنطبق عليها السياسة سيقبله المستخدمون.

في هذا المثال، لن تنجح السياسة إلا إذا كان رمز الدخول يتضمّن النطاق "A". إذا كان هذا <Scope> أو إذا لم يكن له أي قيمة، فستتجاهل السياسة نطاق .

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

لنفترض أنّ واجهة برمجة التطبيقات لديها مسار محدّد لنقطة النهاية /resourceA:

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

عند بدء هذا التدفق (يأتي الطلب مع /resourceA في المسار لاحقًا)، يتم استدعاء سياسة OAuthV2-VerifyAccessTokenA على الفور. وتتأكّد هذه السياسة من أنّ إذا كان رمز الدخول صالحًا ويبحث عن النطاقات التي يتوافق معها الرمز المميز. إذا كانت السياسة في المثال أدناه، باستخدام <Scope>A</Scope>، لن تنجح السياسة إلّا. إذا كان لرمز الدخول نطاق "A". وإلا، فسيعرض خطأ.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

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

أمثلة على الرموز البرمجية

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

الحالة التلقائية

لنفترض أن لديك تطبيقًا مطورًا يحتوي على منتجات، وأن اتحاد هذه المنتجات النطاقات هي: "أ" و"ب" و"ج". يطلب طلب البيانات من واجهة برمجة التطبيقات هذا رمز دخول، ولكن بدون تحديد طلب بحث لنطاق. .

curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials

في هذه الحالة، سيتم منح الرمز المميّز الذي تم إنشاؤه النطاقات "أ" و"ب" و"ج" (السلوك التلقائي). تشير رسالة الأشكال البيانية ستبدو البيانات الوصفية للرمز المميز على النحو التالي:

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

والآن، لنفترض أن لديك نقطة نهاية لواجهة برمجة تطبيقات ذات النطاق "A" (أي: CheckAccessToken يتطلب النطاق "A"). في ما يلي سياسة VerifyAccessToken:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

في ما يلي نموذج لطلب البيانات ونقطة النهاية التي تفرض النطاق "أ":

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA 

تم بنجاح اتصال GET هذا:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

وتنجح السياسة لأنّ سياسة VerifyAccessToken التي يتم تفعيلها عند استدعاء نقطة النهاية النطاق "أ"، وتم منح رمز الدخول النطاقات "أ" و"ب" و"ج" -- وهي النطاقات الافتراضية السلوك.

حالة الفلترة

لنفترض أن لديك تطبيق مطوّر يحتوي على منتجات لها النطاقات "أ" و"ب" و"ج" و"س". طلبك رمز دخول ويتضمن معلَمة طلب البحث scope، كما يلي:

curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'

في هذه الحالة، سيتم إعطاء الرمز المميّز الذي تم إنشاؤه النطاقَين A وX، لأن كلاً من A وX هما والنطاقات الصالحة. تذكر أن تطبيق المطور يتعرف على النطاقات "أ" و"ب" و"ج" و"س". وفي هذه الحالة، يمكنك فلترة قائمة منتجات واجهة برمجة التطبيقات استنادًا إلى هذه النطاقات. إذا كان المنتج له النطاق "أ" أو "س"، يمكنك إعداد نقاط نهاية واجهة برمجة التطبيقات التي ستفرض هذه النطاقات. إذا لم يكن للمنتج نطاق A أو X (لنفترض أنها تحتوي على B وC وZ)، لا يمكن استدعاء واجهات برمجة التطبيقات التي تفرض النطاق A أو X بالرمز المميز.

عند استدعاء واجهة برمجة التطبيقات التي تستخدم الرمز المميز الجديد:

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX

يتم التحقق من رمز الدخول باستخدام الخادم الوكيل لواجهة برمجة التطبيقات. على سبيل المثال:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

ينجح تشغيل طلب GET ويتم عرض استجابة. على سبيل المثال:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }
 

وتنجح السياسة لأن سياسة VerifyAccessToken تتطلّب النطاق A أو X، بالإضافة إلى رمز الدخول. تتضمن النطاقين "أ" و"س". وبالطبع، إذا تم ضبط العنصر <Scope> على B، فستفشل هذه المكالمة.

ملخّص

من المهم فهم كيفية تعامل Apigee Edge مع نطاقات OAuth 2.0. إليك نصيحة رئيسية النقاط:

• "يتعرف" تطبيق المطوّر على اتحاد جميع النطاقات المحددة لجميع منتجاتها.
• عندما يطلب أحد التطبيقات رمز دخول، تتوفر له فرصة تحديد النطاقات التي الحصول عليه. يعود الأمر إلى Apigee Edge (خادم الأذونات) لتحديد النطاقات التي سيتم تعيينه فعليًا لرمز الدخول استنادًا إلى (أ) النطاقات المطلوبة و(ب) لتلك التي يتعرف عليها تطبيق المطور.
• في حال عدم ضبط Apigee Edge للتحقّق من النطاق (عنصر <Scope>) لم يتم توفير سياسة VerifyAccessToken أو كانت فارغة، سيتم تنفيذ طلب البيانات من واجهة برمجة التطبيقات بنجاح طالما أن النطاق المضمن في رمز الدخول يتطابق مع أحد النطاقات التي تم التعرف عليها من خلال تطبيق المطوِّر المسجّل (أحد النطاقات في قائمة النطاقات "الرئيسية").
• في حال لم يكُن رمز الدخول مرتبطًا بأي نطاقات، لن ينجح إلا في الحالات التي لا يأخذ فيها Edge في الاعتبار النطاق (العنصر <Scope> غير متوفّر) من سياسة CheckAccessToken أو تكون فارغة).