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

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

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

איך OAuth2 פועל (עם Apigee Edge API)

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

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

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

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

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

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

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

תהליך OAuth2: בקשות עוקבות

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

תהליך OAuth: בקשות עוקבות
איור 2: תהליך OAuth: בקשות עוקבות

כפי שמוצג באיור 2, אם כבר יש לכם אסימון גישה:

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

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

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

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

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

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

קבלת הטוקנים

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

  • ‫get_token utility: מחליף את פרטי הכניסה שלכם ב-Apigee באסימוני גישה ורענון שבהם אפשר להשתמש כדי לקרוא ל-Edge API.
  • כלי השירות acurl: מספק עטיפה נוחה סביב פקודת curl רגילה. יוצר בקשות HTTP ל-Edge API, מקבל אסימוני גישה ורענון מ-get_token ומעביר את אסימון הגישה ל-Edge API.
  • נקודות קצה של טוקנים בשירות Edge OAuth2: מחליפים את פרטי הכניסה של 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.

שימוש ב-acurl

כדי לגשת ל-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 ‏helloworld. בבקשה השנייה נעשה שימוש בקיצור "o" במקום "organizations" בכתובת ה-URL.

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

מידע נוסף זמין במאמר בנושא שימוש ב-acurl לגישה ל-Edge API.

שימוש ב-curl

אפשר להשתמש ב-curl כדי לגשת ל-Edge API. כדי לעשות את זה, קודם צריך לקבל את טוקני הגישה והרענון. אפשר לקבל אותם באמצעות כלי כמו get_token או שירות Edge 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 OAuth2: שולחים בקשה שכוללת:
    • טוקן רענון
    • הפרמטר של הטופס grant_type מוגדר ל-refresh_token

‫OAuth2 למשתמשים במחשב

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