שימוש ב-OAuth2 כדי לגשת לממשק ה-API של Edge

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

איך OAuth2 עובד (עם ה-API של Apigee Edge)

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

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

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

אבל לא ניתן לשלוח את הבקשה בלי לספר לנו מי אתה. אחרת, כולם יוכל לראות את פרטי הארגון שלך.

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

למרבה המזל, באפשרותך לקבל אסימון על ידי שליחת פרטי הכניסה שלך לשירות Edge2. השירות מגיב עם אסימוני גישה ורענון.

תהליך 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. שולחים בקשה ל-API של 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. שולחים בקשה ל-API של Edge עם אסימון הגישה. acurl מצורפים את האסימון באופן אוטומטי. אם משתמשים בכלים אחרים, צריך להוסיף את האסימון באופן ידני.
  2. Edge API מריץ את הבקשה ובדרך כלל מחזיר תשובה עם נתונים.

תהליך OAuth2: כשפג התוקף של אסימון הגישה

כשפג התוקף של אסימון הגישה (אחרי 12 שעות), אפשר להשתמש באסימון הרענון כדי לקבל אסימון גישה:

תהליך OAuth: רענון אסימון הגישה
איור 3: תהליך OAuth: רענון אסימון הגישה

כפי שמוצג באיור 3, כשפג התוקף של אסימון הגישה:

  1. שלחתם בקשה ל-API של Edge, אבל פג התוקף של אסימון הגישה שלכם.
  2. הבקשה ב-Edge API נדחתה כי היא לא מורשית.
  3. שולחים אסימון רענון לשירות Edge2 של Edge. אם משתמשים ב-acurl, לא צריך באופן אוטומטי.
  4. התגובה של שירות Edge2 ב-OAuth2 מתבצעת עם אסימון גישה חדש.
  5. שולחים בקשה ל-API של Edge עם אסימון הגישה החדש.
  6. Edge API מריץ את הבקשה ובדרך כלל מחזיר תשובה עם נתונים.

לקבלת האסימונים

כדי לקבל אסימון גישה שאפשר לשלוח ל-Edge API, אפשר להשתמש כלי עזר של Apigee, בנוסף לכלי שירות כמו curl:

  • הכלי get_token: החלפת פרטי הכניסה שלכם ב-Apigee לגישה ואסימוני רענון שבהם ניתן להשתמש כדי לקרוא ל-Edge API.
  • כלי עזר של acurl: מספק wrapper נוחות סביב תקן הפקודה curl. בניית בקשות HTTP ל-Edge API, מקבל אסימוני גישה ורענון מ-get_token, ומעביר את אסימון הגישה אל ל-Edge API.
  • נקודות קצה של אסימונים בשירות Edge22: מחליפים את פרטי כניסה ב-Apigee לאסימוני הגישה והרענון באמצעות קריאה ל-Edge API.

השירותים האלו מחליפים את פרטי הכניסה שלכם לחשבון Apigee (כתובת אימייל סיסמה) לאסימונים באורך הבא:

  • התוקף של אסימוני הגישה פג אחרי 12 שעות.
  • התוקף של אסימוני הרענון יפוג אחרי 30 יום.

כתוצאה מכך, אחרי שמבצעים בהצלחה קריאה ל-API עם acurl או get_token, תוכלו להמשיך להשתמש בצמד האסימונים במשך 30 יום. אחרי פקיעת התוקף, צריך להזין מחדש את את ההרשאות האלה ולקבל אסימונים חדשים.

גישה ל-Edge API עם OAuth2

כדי לגשת ל-Edge API, צריך לשלוח בקשה לנקודת קצה ל-API ולכלול את אסימון הגישה. אפשר לעשות זאת באמצעות כל לקוח HTTP, כולל כלי שורת פקודה כמו curl, ממשק משתמש מבוסס דפדפן כמו Postman, או כלי עזר של Apigee כמו acurl.

הגישה ל-Edge API עם acurl ועם curl מתוארת ב: בקטעים הבאים.

שימוש בכתובת אתר

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

בבקשות הבאות, acurl משתמש באסימונים השמורים ב-~/.sso-cli, כך שלא תצטרכו לכלול שוב את פרטי הכניסה שלכם עד שהתוקף של האסימונים יפוג.

בדוגמה הבאה מוצגת בקשת acurl ראשונית שמקבלת פרטים על 'ahamilton-eval' ארגון:

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" ]

בנוסף לקבלת פרטים על הארגון, בדוגמה הזו מוצגת גם בקשה שנייה שהוא מקבל רשימה של כללי מדיניות שרת proxy ל-API. הבקשה השנייה משתמשת באופרטור קיצור של o עבור 'ארגונים' בכתובת ה-URL.

לתשומת ליבך, acurl מעביר את אסימון הגישה באופן אוטומטי בבקשה השנייה. שלך לא נדרשים להעביר את פרטי הכניסה של המשתמש אחרי ש-acurl מאחסן את אסימוני ה-OAuth2. הוא מקבל את האסימון מ-~/.sso-cli לקריאות הבאות.

למידע נוסף אפשר לקרוא את המאמר שימוש בכתובת אתר כדי לגשת ל-Edge API.

שימוש ב-curl

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

אחרי ששומרים את אסימון הגישה בהצלחה, מעבירים אותו הכותרת Authorization של הקריאות ל-Edge API, כמו בדוגמה הבאה מציג:

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

אסימון הגישה תקף למשך 12 שעות לאחר ההנפקה. אחרי שתוקף אסימון הגישה יפוג, אפשר יהיה להשתמש באסימון הרענון במשך 30 יום כדי להנפיק אותו אסימון גישה אחר ללא צורך בפרטי כניסה. ההמלצה של Apigee היא לבקש אסימון גישה חדש רק אחרי שיפוג התוקף של אסימון ההפניה, במקום לבקש אסימון גישה חדש הזנת פרטי כניסה ושליחה של בקשה חדשה בכל קריאה ל-API.

תפוגת האסימון

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

האופן שבו מרעננים את אסימון הגישה תלוי בכלי שבו משתמשים:

  • acurl: לא נדרשת כל פעולה. acurl מרענן באופן אוטומטי את אסימון הגישה כששולחים בקשה שמכילה בקשה מיושנת.
  • get_token: קריאה ל-get_token כדי לרענן את אסימון הגישה.
  • Edge Service OAuth2: שליחת בקשה שכוללת:
    • רענון האסימון
    • הפרמטר grant_type של הטופס מוגדר ל-"refresh_token"

OAuth2 למשתמשים במכונות

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