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

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

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

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

يتطلّب الاتصال بواجهة برمجة التطبيقات Apigee Edge إجراء مصادقة لنتأكّد من هويتك. تقول أنت. لمصادقتك، نطلب منك إرسال رمز الدخول 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 باستخدام رمز الدخول. تم إرفاق 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 باستخدام رمز الدخول. تم إرفاق acurl بالرمز المميز تلقائيًا. إذا كنت تستخدم أدوات أخرى، عليك إضافة الرمز المميّز يدويًا.
  2. تنفّذ Edge API طلبك وعادةً ما تعرض ردًا بالبيانات.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

استخدام acurl

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

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

يوضّح المثال التالي طلب acurl أوليًا يحصل على تفاصيل "أهاميلتون-إيفال" المؤسسة:

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 للوصول إلى Edge API. للقيام بذلك، يجب عليك أولاً الحصول على رموز الدخول والتحديث. يمكنك الحصول عليها باستخدام أداة مساعدة مثل 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