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

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

يتوافق SAML مع بيئة الدخول المُوحَّد (SSO). يتيح لك استخدام SAML مع Edge إمكانية دعم الدخول الموحّد لواجهة مستخدم Edge وواجهة برمجة التطبيقات في Edge بالإضافة إلى أي خدمات أخرى تقدمها وتتوافق أيضًا مع SAML.

شرط أساسي: يجب تفعيل SAML لمؤسسة واحدة على الأقل قبل أن تتمكّن من استخدامه للوصول إلى Edge API.

الاختلافات بين SAML وOAuth2

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

الفرق الرئيسي بين SAML وOAuth2 عند الدخول إلى Edge API هو في طريقة حصولك على الرموز المميّزة. باستخدام SAML، يجب تضمين ما يلي عند الحصول على زوج الرمز المميّز:

  1. المناطق: يجب أن يشير مستخدمو Edge إلى اسم المنطقة عند الحصول على رموز مميّزة.
  2. رمز المرور: يمكنك تضمين رمز مرور يُستخدم لمرة واحدة عند طلب زوج رمز مميّز للوصول/إعادة التحميل.

يستخدم SAML نقاط النهاية نفسها في خدمة Edge OAuth2، مع إضافة اسم المنطقة المناسب.

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

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

الحصول على رموز الدخول باستخدام get_token

يمكنك استخدام أداة get_token لاستبدال بيانات الاعتماد برموز الدخول إلى OAuth2 وإعادة التحميل التي تستخدمها مع SAML.

للحصول على رمز دخول من خلال get_token:

  1. اضبط متغيّر بيئة SSO_LOGIN_URL على عنوان URL لصفحة تسجيل الدخول. ويكون عنوان URL لصفحة تسجيل الدخول على النحو التالي:
    https://zoneName.login.apigee.com

    على سبيل المثال، بالنسبة إلى منطقة تُسمّى "acme"، اضبط SSO_LOGIN_URL على "https://acme.login.apigee.com"، على النحو الموضّح في المثال التالي:

    export SSO_LOGIN_URL=https://acme.login.apigee.com
  2. استدعِ get_token للحصول على رمز دخول OAuth2:
    get_token -u me@example.com

    سيُطلب منك الانتقال إلى عنوان URL المعروض للحصول على رمز مرور صالح لمرة واحدة:

    Get passcode from https://acme.login.apigee.com/passcode
    [Note:  Passcode can be used only time time and expires] Input passcode (no spaces) and then press ENTER:

    إذا لم تسجّل الدخول مؤخرًا من خلال موفِّر الهوية، سيُطلب منك تسجيل الدخول.

    يعرض عنوان URL هذا رمز مرور صالحًا لمرة واحدة يظل صالحًا إلى أن تعيد تحميل عنوان URL هذا للحصول على رمز مرور جديد، أو تستخدم رمز المرور مع get_token لإنشاء رمز دخول. مثلاً:

  3. أدخِل رمز المرور. تحصل الأداة المساعدة get_token على رموز OAuth2 المميزة، وتطبع رمز الدخول إلى stdout، وتكتب رموز الدخول وإعادة التحميل إلى ~/.sso-cli.

  4. يمكنك استدعاء واجهة برمجة تطبيقات Edge وتمرير رمز الدخول في العنوان Authorization: Bearer، على النحو الموضّح في المثال التالي:
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
      -H "Authorization: Bearer ACCESS_TOKEN"

    يمكن نسخ قيمة رمز الدخول من "stdout".

    يحصل هذا المثال على تفاصيل حول المؤسسة المحددة. للحصول على قائمة كاملة بنقاط نهاية واجهة برمجة التطبيقات للإدارة، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات Apigee Edge.

عند انتهاء صلاحية رمز الدخول، يمكنك الاتصال بـ get_token مرة أخرى للحصول على رمز دخول جديد. مثلاً:

get_token -u me@example.com

لن يُطلب منك إدخال رمز مرور جديد إلا بعد انتهاء صلاحية الرمز المميّز لإعادة التحميل.

عند انتهاء صلاحية الرمز المميز لإعادة التحميل، يطالبك get_token بتقديم رمز مرور جديد. يجب إنشاء رمز مرور جديد قبل أن تتمكن من إنشاء رمز دخول مميز جديد عبر OAuth2.

الحصول على رموز الدخول من خلال خدمة Edge OAuth2

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

للحصول على زوج رمز مميز مع واجهة برمجة تطبيقات Edge:

  1. في أحد المتصفحات، انتقِل إلى عنوان URL التالي للحصول على رمز مرور صالح لمرة واحدة:
    https://zoneName.login.apigee.com/passcode

    على سبيل المثال، بالنسبة إلى منطقة باسم "acme"، انتقِل إلى عنوان URL التالي:

    https://acme.login.apigee.com/passcode

    إذا لم تسجّل الدخول مؤخرًا من خلال موفِّر الهوية، سيُطلب منك تسجيل الدخول.

    يعرض عنوان URL هذا رمز مرور لمرة واحدة يكون بمثابة بيانات الاعتماد الخاصة بك للحصول على الرموز المميّزة، ويظل صالحًا إلى أن تعيد تحميل عنوان URL للحصول على رمز مرور جديد، أو يمكنك استخدام رمز المرور مع get_token لإنشاء رمز دخول. مثلاً:

  2. أرسِل طلبًا إلى واجهة برمجة تطبيقات Edge، كما يوضح المثال التالي:
    curl https://zoneName.login.apigee.com/oauth/token \
          -s \
          -H "Accept: application/json" \
          -d 'grant_type=password&response_type=token&passcode=passcode'

    يُستخدم passcode كبيانات اعتمادك للحصول على التفويض.

    المكان:

    • عنوان Authorization هو "أساسي ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (استخدِم هذه القيمة بالضبط).
    • نوع الطلب هو POST.
    • يتضمّن نص الطلب ما يلي:
      • اسم grant_type هو "كلمة المرور".
      • اسم response_type هو "الرمز المميّز".
      • passcode حيث يكون passcode هو رمز المرور الذي تم عرضه في الخطوة السابقة.

    تطبع المكالمة رموز الدخول وإعادة التحميل على الشاشة.

لإعادة تحميل رمز الدخول، يُرجى اتّباع الخطوات التالية:

أرسِل طلبًا إلى https://zoneName.login.apigee.com/oauth/token، على النحو الموضّح في المثال التالي:

curl https://zoneName.login.apigee.com/oauth/token \
      -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN'

المكان:

  • يتضمّن نص الطلب ما يلي:
    • قيمة grant_type هي "refresh_token".
    • refresh_token هي قيمة الرمز المميّز لإعادة التحميل.
  • عنوان Authorization هو "أساسي ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (استخدِم هذه القيمة بالضبط).
  • نوع الطلب هو POST.

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

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

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

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

مع acurl، لا تحتاج إلى تحديد عنوان Authorization. مثلاً:

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

تستدعي هذه الأمثلة نقطة نهاية واجهة برمجة تطبيقات Edge التي تحصل على تفاصيل حول المؤسسة المحددة. للحصول على قائمة كاملة بنقاط نهاية واجهة برمجة تطبيقات Edge، يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات Apigee Edge.

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

مستخدمو الجهاز في مناطق SAML

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

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

في المثال أعلاه، يؤدي ضبط قيمة -m على سلسلة فارغة إلى منع مستخدم الجهاز من طلب رمز MFA. سيؤدي استخدام العلامة --force-basic-auth إلى إلغاء الطلب العادي الذي يتعلّق برمز المرور الذي يتم تشغيله من خلال الطلبات التي تتضمّن مناطق SAML.

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

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