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

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

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

طريقة عمل OAuth2 (مع واجهة برمجة التطبيقات Apigee Edge)

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

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

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

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

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

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

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

تعرض الصورة التالية مسار OAuth2 عند الوصول إلى Edge API للمرة الأولى:

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

كما يوضّح الشكل 1، عند تقديم طلبك الأوّلي إلى Edge API:

  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 API باستخدام رمز الدخول. تُرفِق 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 API طلبك وتعرض عادةً ردًا يتضمّن بيانات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

الوصول إلى Edge API باستخدام OAuth2

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

يتم توضيح كيفية الوصول إلى Edge API باستخدام acurl وcurl في الأقسام التالية.

استخدام acurl

للوصول إلى Edge API باستخدام 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 API.

استخدام curl

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

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

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 APIs باستخدام مصادقة 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 على سلسلة فارغة إلى منع مطالبة مستخدم الآلة بإدخال رمز المصادقة المتعددة العوامل.