استخدام OAuth2 للوصول إلى واجهة برمجة تطبيقات Edge

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

يتيح لك Apigee Edge إجراء مكالمات من واجهة برمجة تطبيقات Edge التي تتم مصادقتها باستخدام رموز OAuth2 المميزة. يتم تفعيل دعم OAuth2 تلقائيًا على Edge لحسابات Cloud. إذا كنت تستخدم Edge لخدمة "السحابة الإلكترونية الخاصة"، لا يمكنك استخدام OAuth2 بدون إعداد SAML أو LDAP أولاً.

طريقة عمل OAuth2 (باستخدام Apigee Edge API)

تتطلّب الاستدعاءات لواجهة برمجة تطبيقات Apigee Edge المصادقة حتى نتأكّد من هويتك. للمصادقة عليك، نطلب منك إرسال رمز دخول OAuth2 مع طلبك للوصول إلى واجهة برمجة التطبيقات.

على سبيل المثال، إذا كنت تريد الحصول على تفاصيل حول مؤسسة على Edge، يمكنك إرسال طلب إلى عنوان URL مثل ما يلي:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

ولكن لا يمكنك إرسال هذا الطلب دون إخبارنا بهويتك. وإلا قد يتمكّن أي شخص من الاطّلاع على تفاصيل مؤسستك.

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

يمكنك الحصول على رمز مميّز عن طريق إرسال بيانات الاعتماد إلى خدمة Edge OAuth2. تستجيب الخدمة برموز الدخول وإعادة التحميل.

مسار OAuth2: الطلب الأولي

توضّح الصورة التالية مسار OAuth2 عند الدخول إلى واجهة برمجة تطبيقات Edge لأول مرة:

مسار OAuth: الطلب الأول
الشكل 1: مسار OAuth: الطلب الأول

كما يوضح الشكل 1، عند تقديم طلبك الأولي إلى واجهة برمجة تطبيقات Edge:

  1. تطلب رمز الدخول. ويمكنك إجراء ذلك باستخدام Edge API أو acurl أو get_token. مثلاً: 
    get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456
  2. تستجيب خدمة Edge OAuth2 باستخدام رمز الدخول، وتطبعه على stdout. على سبيل المثال: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    تحفظ الأداتان acurl وget_token بشكل غير ملحوظ رموز الدخول وإعادة التحميل في ~/.sso-cli (لا تتم كتابة الرمز المميّز لإعادة التحميل في stdout.) إذا كنت تستخدم خدمة Edge OAuth2 للحصول على رموز مميزة، عليك حفظها لاستخدامها لاحقًا بنفسك.

  3. يمكنك إرسال طلب إلى واجهة برمجة تطبيقات Edge باستخدام رمز الدخول. ترفق acurl الرمز المميّز تلقائيًا، على سبيل المثال: 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    إذا كنت تستخدم برنامج HTTP آخر، تأكد من إضافة رمز الدخول. مثلاً:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. تنفِّذ واجهة برمجة تطبيقات Edge طلبك وعادة ما تعرض ردًا بالبيانات.

مسار OAuth2: الطلبات اللاحقة

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

مسار OAuth: الطلبات اللاحقة
الشكل 2: مسار OAuth: الطلبات اللاحقة

كما يوضح الشكل 2، إذا كان لديك رمز دخول:

  1. يمكنك إرسال طلب إلى واجهة برمجة تطبيقات Edge باستخدام رمز الدخول. ترفق acurl الرمز المميّز تلقائيًا. إذا كنت تستخدم أدوات أخرى، عليك إضافة الرمز المميّز يدويًا.
  2. تنفِّذ واجهة برمجة تطبيقات Edge طلبك وعادة ما تعرض ردًا بالبيانات.

مسار OAuth2: وقت انتهاء صلاحية رمز الدخول

عند انتهاء صلاحية رمز الدخول (بعد 12 ساعة)، يمكنك استخدام الرمز المميّز لإعادة التحميل للحصول على رمز دخول جديد:

مسار OAuth: إعادة تحميل رمز الدخول
الشكل 3: مسار OAuth: إعادة تحميل رمز الدخول

كما هو موضّح في الشكل 3، عند انتهاء صلاحية رمز الدخول:

  1. ترسل طلبًا إلى واجهة برمجة تطبيقات Edge، ولكن انتهت صلاحية رمز الدخول.
  2. ترفض واجهة برمجة تطبيقات Edge طلبك باعتباره غير مصرّح به.
  3. ترسل رمزًا مميزًا لإعادة التحميل إلى خدمة Edge OAuth2. إذا كنت تستخدم acurl، يتم إجراء ذلك تلقائيًا نيابةً عنك.
  4. تستجيب خدمة Edge OAuth2 برمز دخول جديد.
  5. يمكنك إرسال طلب إلى واجهة برمجة تطبيقات Edge باستخدام رمز الدخول الجديد.
  6. تنفِّذ واجهة برمجة تطبيقات Edge طلبك وعادة ما تعرض ردًا بالبيانات.

الحصول على الرموز المميّزة

للحصول على رمز دخول يمكنك إرساله إلى واجهة برمجة تطبيقات Edge، يمكنك استخدام أدوات Apigee التالية، بالإضافة إلى أداة مساعدة مثل curl:

  • أداة get_token: تتبادل بيانات اعتماد Apigee للوصول إلى الرموز المميزة وإعادة التحميل التي يمكنك استخدامها لاستدعاء واجهة برمجة تطبيقات Edge.
  • أداة acurl: توفر برنامج تضمين مريح حول أمر curl قياسي. تنشئ طلبات HTTP إلى واجهة برمجة تطبيقات Edge، وتحصل على رموز الدخول وإعادة التحميل من get_token، وتمرر رمز الدخول إلى Edge API.
  • نقاط نهاية الرموز المميّزة في خدمة Edge OAuth2: يمكنك تبديل بيانات اعتماد Apigee لرموز الوصول وإعادة التحميل من خلال طلب واجهة برمجة تطبيقات Edge.

تتبادل هذه البرامج المساعدة بيانات اعتماد حسابك على Apigee (عنوان البريد الإلكتروني وكلمة المرور) للحصول على رموز مميّزة خلال المُدد التالية:

  • تنتهي صلاحية رموز الدخول بعد 12 ساعة.
  • تنتهي صلاحية الرموز المميَّزة لإعادة التحميل بعد 30 يومًا.

نتيجةً لذلك، بعد إجراء طلب بيانات من واجهة برمجة التطبيقات بنجاح باستخدام acurl أو get_token، يمكنك مواصلة استخدام الرمز المميّز لمدة 30 يومًا. بعد انتهاء الصلاحية، يجب إعادة إدخال بيانات الاعتماد والحصول على رموز مميّزة جديدة.

الوصول إلى واجهة برمجة تطبيقات Edge من خلال OAuth2

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

يمكن الاطّلاع على كيفية الوصول إلى واجهة برمجة تطبيقات Edge باستخدام acurl وcurl في الأقسام التالية.

استخدام acurl

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

في الطلبات اللاحقة، يستخدم acurl الرموز المميّزة المحفوظة في ~/.sso-cli لعدم الحاجة إلى تضمين بيانات الاعتماد مرة أخرى إلى أن تنتهي صلاحية الرموز المميّزة.

يعرض المثال التالي طلب acurl أولي يحصل على تفاصيل لمؤسسة "ahamilton-eval":

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

بالإضافة إلى الحصول على تفاصيل حول المؤسسة، يعرض هذا المثال أيضًا طلبًا ثانيًا يحصل على قائمة بالسياسات داخل الخادم الوكيل لواجهة برمجة التطبيقات "helloworld". ويستخدم الطلب الثاني الاختصار "o" للإشارة إلى "المؤسسات" في عنوان URL.

لاحظ أن acurl يمرر رمز الدخول تلقائيًا في الطلب الثاني. لن تحتاج إلى تمرير بيانات اعتماد المستخدم بعد تخزين acurl للرموز المميزة لبروتوكول OAuth2. ويحصل الجهاز على الرمز المميّز من ~/.sso-cli لإجراء المكالمات اللاحقة.

لمزيد من المعلومات، يُرجى الاطّلاع على استخدام acurl للوصول إلى واجهة برمجة تطبيقات Edge.

استخدام ثنيات

يمكنك استخدام curl للوصول إلى واجهة برمجة تطبيقات Edge. لإجراء ذلك، عليك أولاً الحصول على الرمزين المميّزين للوصول وإعادة التحميل. يمكنك الحصول عليها باستخدام أداة مثل get_token أو خدمة Edge OAuth2.

بعد حفظ رمز الدخول بنجاح، يمكنك تمريره في العنوان Authorization لمكالماتك إلى واجهة برمجة تطبيقات Edge، على النحو الموضّح في المثال التالي:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

يكون رمز الدخول صالحًا لمدة 12 ساعة بعد إصداره. بعد انتهاء صلاحية رمز الدخول، يمكن استخدام الرمز المميّز لإعادة التحميل لمدة 30 يومًا لإصدار رمز دخول آخر بدون الحاجة إلى إدخال بيانات اعتماد. لا تنصح Apigee بطلب رمز دخول جديد إلا بعد انتهاء صلاحية الرمز المميّز للإحالة، بدلاً من إدخال بيانات الاعتماد وتقديم طلب جديد مع كل طلب من واجهة برمجة التطبيقات.

انتهاء صلاحية الرمز المميّز

بعد انتهاء صلاحية رمز الدخول، يمكنك استخدام الرمز المميّز لإعادة التحميل للحصول على رمز دخول جديد بدون الحاجة إلى إرسال بيانات الاعتماد مرة أخرى.

تعتمد كيفية إعادة تحميل رمز الدخول على الأداة التي تستخدمها:

  • acurl: ليس عليك اتّخاذ أي إجراء. يعمل acurl تلقائيًا على إعادة تحميل رمز الدخول عندما ترسل طلبًا يحتوي على رمز قديم.
  • get_token: يمكنك طلب الرقم get_token لإعادة تحميل رمز الدخول.
  • خدمة Edge OAuth2: إرسال طلب يتضمّن ما يلي:
    • إعادة تحميل الرمز المميّز
    • تم ضبط مَعلمة النموذج grant_type على "refresh_token".

OAuth2 لمستخدمي الجهاز

يمكنك استخدام الأداتين acurl وget_token لكتابة نص برمجي للوصول المبرمَج إلى واجهات برمجة تطبيقات Edge مع مصادقة OAuth2 لمستخدمي الأجهزة. يوضح المثال التالي كيفية استخدام get_token لطلب رمز دخول، ثم إضافة قيمة الرمز المميز إلى طلب curl:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

وبدلاً من ذلك، يمكنك الجمع بين طلب الرمز المميز واستدعاء curl باستخدام الأداة المساعدة acurl. مثلاً:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

في كلا المثالَين، يؤدي ضبط قيمة -m على سلسلة فارغة إلى منع مستخدم الجهاز من الطلب من خلاله تقديم رمز MFA.