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

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

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

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

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

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

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

  1. المناطق: على مستخدمي Edge for Public Cloud الإشارة إلى اسم المنطقة عند الحصول على الرموز المميّزة.
  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 API ومرِّر رمز الدخول في Authorization: Bearer العنوان، كما هو موضّح في المثال التالي: 
    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

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

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

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

get_token -u me@example.com

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

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

الحصول على رموز الدخول باستخدام خدمة Edge OAuth2

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

للحصول على زوج من الرموز المميّزة باستخدام Edge API، اتّبِع الخطوات التالية:

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

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

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

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

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

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

    يعمل passcode كبيانات اعتماد للتفويض.

    المكان:

    • العنوان Authorization هو "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (استخدِم هذه القيمة بالضبط).
    • نوع الطلب هو POST.
    • يحتوي نص الطلب على ما يلي:
      • grant_type هو "password".
      • response_type هو "token".
      • 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 هو "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (استخدِم هذه القيمة بالضبط).
  • نوع الطلب هو POST.

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

يمكنك استخدام أدوات مثل curl أو الأداة المريحة acurl من Apigee للوصول إلى Edge API.

باستخدام curl، يمكنك استدعاء Edge API وتمرير رمز الدخول في العنوان 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 API التي تحصل على تفاصيل حول المؤسسة المحدّدة. للحصول على قائمة كاملة بنقاط نهاية Edge API، يُرجى الاطّلاع على مرجع Apigee Edge API.

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

مستخدمو الآلات في مناطق SAML

يمكنك استخدام الأداتَين acurl وget_token لبرمجة الوصول التلقائي إلى Edge APIs لمستخدمي الآلات في مناطق 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 على سلسلة فارغة إلى منع مطالبة مستخدم الآلة بإدخال رمز التحقّق بخطوتَين. سيؤدي استخدام العلامة --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/...'