גישה ל-Edge API עם SAML

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

ההבדלים בין 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.

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

כשפג התוקף של אסימון הגישה, אפשר להתקשר שוב אל 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 הוא 'סיסמה'.
      • 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 או בכלי הנוחות של 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

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

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

משתמשים במכשירים באזורי 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/...'