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

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

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

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

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

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

  • get_token service: השירות ממיר את פרטי הכניסה ל-Apigee באסימוני גישה ורענון אסימוני גישה שאפשר להשתמש בהם כדי לקרוא ל-Edge API.
  • תוכנית השירות acurl: מספקת רכיב wrapper של נוחות סביב פקודת 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" ]

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

חשוב לשים לב ש-acurl מעביר באופן אוטומטי את אסימון הגישה בבקשה השנייה. אין צורך להעביר את פרטי הכניסה של המשתמש אחרי אסימוני OAuth2 שמורים ב-acurl. היא מקבלת את האסימון מ-~/.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 כדי לרענן את אסימון הגישה.
  • שירות OAuth2 של Edge: שליחת בקשה שכוללת:
    • רענון האסימון
    • פרמטר הטופס 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.