גישה ל-Edge API עם SAML

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

SAML תומך בסביבת כניסה יחידה (SSO). באמצעות SAML עם Edge תוכלו לתמוך ב-SSO לממשק המשתמש של Edge ול-API, בנוסף לכל השירותים שאתם מספקים ושתומכים גם ב-SAML.

דרישה מוקדמת: כדי להשתמש ב-SAML כדי לגשת ל-Edge API, צריך להפעיל את SAML לפחות לארגון אחד.

ההבדלים בין SAML לבין OAuth2

אחרי שמגדירים את SAML, השימוש בו דומה מאוד לשימוש ב-OAuth2 כדי לגשת ל-Edge API. כשקוראים ל-Edge API, הבקשה כוללת אסימון גישה מסוג OAuth2.

ההבדל העיקרי בין SAML ל-OAuth2 בגישה ל-Edge API הוא האופן שבו אתם מקבלים אסימונים. ב-SAML צריך לכלול את הפרטים הבאים בזמן קבלת צמד האסימונים:

  1. אזורים: Edge למשתמשי Cloud 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

    תתבקש לעבור לכתובת האתר המוצגת כדי לקבל קוד גישה חד-פעמי:

    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.

    בדוגמה הזו מוצגים פרטים על הארגון הנתון. בחומר העזר בנושא Apigee Edge API תוכלו למצוא רשימה מלאה של נקודות הקצה של ה-API לניהול.

כשיפוג התוקף של אסימון הגישה, אפשר להפעיל שוב את get_token כדי לקבל אסימון גישה חדש. לדוגמה:

get_token -u me@example.com

לא תוצג לך בקשה להזין קוד סיסמה חדש עד שתוקף אסימון הרענון יפוג.

כשיפוג התוקף של אסימון הרענון, get_token יבקש ממך קוד סיסמה חדש. עליך ליצור קוד סיסמה חדש כדי ליצור אסימון גישה חדש מסוג OAuth2.

קבלת אסימוני גישה באמצעות שירות Edge OAuth2

אפשר להשתמש בשירות Edge OAuth2 כדי לקבל אסימוני גישה שמשמשים אותך עם SAML. כדי לאמת את עצמכם מול ה-API של Edge, צריך להשתמש בקוד גישה בבקשה הראשונית לקבלת זוג אסימוני גישה/רענון, ושוב כדי לקבל זוג אסימונים חדש.

כך מקבלים צמד אסימונים ל-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 הוא "סיסמה".
      • 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 היא "Basic ZWRnZWNsaTplZGdlY2xpc2VjcmV0" (יש להשתמש בערך הזה).
  • סוג הבקשה הוא POST.

גישה ל-Edge API באמצעות SAML

ניתן להשתמש בכלים כמו curl או כלי השירות הנוחות Apigee acurl כדי לגשת ל-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

הדוגמאות האלה קוראות לנקודת קצה (endpoint) של Edge API שמקבלת פרטים על הארגון הנתון. בחומר העזר בנושא Apigee Edge API תוכלו למצוא רשימה מלאה של נקודות הקצה של Edge API.

במאמר בנושא גישה ל-Edge API באמצעות OAuth2, תוכלו לקרוא על שיטות נוספות לקריאה ל-API, כולל דרכים לוודא שהאסימון שלכם עדכני.

משתמשים במכונות בתחומי SAML

אפשר להשתמש בכלים acurl ו-get_token כדי לכתוב סקריפטים לגישה אוטומטית לממשקי API של 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/...'