שימוש באסימוני OAuth של צד שלישי

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

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

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

דוגמה

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

מה זה?

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

מעט רקע

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

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

הערך של המאפיין access_token הוא למעשה מפתח החיפוש של נתוני התגובה. אפליקציה יכולה לשלוח בקשה לשרת proxy של API שמתארח ב-Edge, שכולל את האסימון למוכ"ז zBC90HhCGmGlaMBWeZAai2s3za5j, ול-Edge – עם מדיניות OAuthV2 עם פעולה = ValidAccessToken – תחפש את האסימון, תאחזר את כל המידע ותשתמש במידע הזה כדי לקבוע אם האסימון חוקי או לא, עבור שרת ה-proxy המבוקש של ה-API. התהליך הזה נקרא אימות אסימונים. כל המידע שלמעלה מורכב מהאסימון. הערך access_token הוא הדרך למצוא את המידע הזה.

מצד שני, בעזרת השלבים שמתוארים כאן אפשר להגדיר את Edge כך שישמור אסימון כך שהערך שלו ב-access_token יהיה משהו שנוצר על ידי שירות חיצוני. יכול להיות שכל שאר המטא-נתונים יהיו זהים. לדוגמה, נניח שיש לך מערכת חיצונית ל-Apigee Edge שיוצרת אסימונים בצורה "TOKEN-<16 מספרים אקראיים>" . במקרה כזה, המטא-נתונים המלאים של האסימון המאוחסנים ב-Apigee Edge עשויים להיות:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

במקרה כזה, אפליקציה יכולה לשלוח בקשה לשרת proxy של API שמתארח ב-Edge, והוא מכיל את אסימון למוכ"ז TOKEN-1092837373654221. בנוסף, באמצעות מדיניות OAuthV2 עם פעולה = ValidAccessToken – תהיה אפשרות לאמת זאת. אפשר להחיל דפוס ייבוא דומה על קודי הרשאה ואסימוני רענון.

בואו נדבר על אימות פרטי הכניסה של הלקוח

אחת הדרישות המוקדמות ליצירת אסימון היא אימות הלקוח המבקש. כברירת מחדל, מדיניות OAuthV2/GenerateAccessToken ב-Apigee Edge מאמתת באופן לא מפורש את פרטי הכניסה של הלקוח. בדרך כלל בבקשה לאסימון OAuthV2, ה-client_id וה-client_secret מועברים בכותרת Authorization ומקודדים באמצעות HTTP Basic Authorization (בשרשור של נקודתיים ואז בקידוד base64). מדיניות OAuthV2/GenerateAccessToken ב-Apigee Edge מפענחת את הכותרת הזו, מחפשת את ה-client_id, ומאמתת שה-client_secret שהועבר תקף לגבי client_id הזה. הפעולה הזו פועלת אם פרטי הכניסה ידועים ל-Apigee Edge. במילים אחרות, יש אפליקציה למפתחים ששמורה ב-Apigee Edge ומכילה פרטי כניסה, שבעצם מכילים את client_id ו-client_secret שצוינו.

במקרים שבהם לא ניתן לאמת את פרטי הכניסה של הלקוח על ידי Apigee Edge, צריך לתכנן את שרת ה-proxy של ה-API לפני יצירת האסימון, כדי לאמת את הלקוח באופן מפורש באמצעים אחרים. בדרך כלל הסיבה לכך היא באמצעות מדיניות של ServiceCallout, שמתחברת לנקודת קצה מרוחקת ברשת.

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

אם רוצים שמדיניות OAuthV2/GenerateAccessToken ב-Apigee Edge תאמת את פרטי הכניסה של הלקוח מול חנות Edge, צריך להגדיר את הרכיב <ExternalAuthorization> לערך false בתוך הגדרת המדיניות, או להשמיט אותו לחלוטין. אם רוצים להשתמש בשירות הרשאות חיצוני כדי לאמת במפורש את פרטי הכניסה של הלקוח, צריך להגדיר את <ExternalAuthorization> לערך true.

יכול להיות ש-Apigee Edge לא מאמת את פרטי הכניסה של הלקוח, אבל עדיין צריך ש-client_id יהיה ידוע וינוהל על ידי Apigee Edge. כל access_token ב-Apigee Edge, שנוצר על ידי Apigee Edge, או שנוצר על ידי מערכת חיצונית ולאחר מכן מיובא אל Apigee Edge, חייב להיות משויך לאפליקציית לקוח – שמצוין על ידי client_id. לכן, גם במקרה שבו מדיניות OAuthV2/GenerateAccessToken ב-Apigee Edge לא מאמתת התאמה של client_id ו-client_secret, המדיניות תאמת שה-client_id חוקי, קיים, ולא מבוטל. לכן, כשלב הגדרה מקדים, ייתכן שיהיה צורך לייבא מזהי client_id דרך ממשק ה-API הניהולי של Edge.

תהליך המדיניות בנושא OAuth של צד שלישי ב-Apigee

כדי להשתמש באסימונים ממערכות OAuth של צד שלישי ב-Apigee Edge, התהליך ליצירת אסימוני גישה צריך להיות מבוסס על אחת מהתבניות הבאות.

אימות חיצוני של פרטי כניסה של לקוח

  1. ServiceCallout (הסבר על השירות) כדי לאמת את פרטי הכניסה של הלקוח הנכנס ולקבל אסימון חיצוני.
  2. ExtractVariables או שלב ב-JavaScript כדי לחלץ מהתגובה את האסימון שנוצר באופן חיצוני.
  3. AssignMessage כדי להגדיר את המשתנה הידוע המיוחד שנקרא oauth_external_authorization_status. הערך חייב להיות true כדי לציין שפרטי הכניסה של הלקוח תקפים.
  4. OAuthV2/GenerateAccessToken עם הרכיב <ExternalAuthorization> מוגדר כ-true, ולפחות אחד מתוך <ExternalAccessToken>, <ExternalRefreshToken> או <ExternalAuthorizationCode>.

אימות פנימי של פרטי הכניסה של הלקוח

  • ServiceCallout – לקבלת אסימון חיצוני.
  • ExtractVariables או שלב ב-JavaScript כדי לחלץ מהתגובה את האסימון שנוצר באופן חיצוני.
  • OAuthV2/GenerateAccessToken עם הרכיב <ExternalAuthorization> מוגדר כ-false, ולפחות אחד מתוך <ExternalAccessToken>, <ExternalRefreshToken> או <ExternalAuthorizationCode>.

הערות לגבי התהליך והגדרת המדיניות

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

  • אחרי ה-ServiceCallout, שרת ה-Proxy של ה-API צריך לנתח את התגובה כדי לחלץ את סטטוס התקינות, וגם את ה-access_token שנוצר באופן חיצוני ואולי את ה-רענן_token.

  • במדיניות OAuthV2/GenerateAccessToken, מגדירים את הרכיב <StoreToken> לערך true ומגדירים את הרכיב <ExternalAuthorization> לערך true או false לפי הצורך.

    כשמדיניות OAuthV2/GenerateAccessToken מופעלת, הוא קורא את המשתנה oauth_external_authorization_status. אם המשתנה מוגדר והערך הוא True, Apigee Edge לא ינסה לאמת את פרטי הכניסה של הלקוח. אם המשתנה לא מוגדר או שהערך לא True, Apigee Edge ינסה לאמת את פרטי הכניסה של הלקוח.

  • מדיניות OAuthV2 כוללת שלושה רכיבים שמאפשרים לכם לציין את הנתונים החיצוניים לייבוא: <ExternalAccessToken>, <ExternalRefreshToken> ו-<ExternalAuthorizationCode>. בכל אחד מהאלמנטים האלה אפשר להזין משתנה מסוג flow. מדיניות Edge תקרא את המשתנה הזה כדי למצוא את אסימון הגישה שנוצר באופן חיצוני, אסימון הרענון או קוד ההרשאה. ההחלטה אם להטמיע את המדיניות והלוגיקה היא להציב את האסימונים או הקודים החיצוניים במשתנים המתאימים.

    לדוגמה, התצורה הבאה במדיניות OAuthV2 מורה ל-Edge לחפש את האסימון במשתנה הקשר בשם external_token.

    <ExternalAccessToken>external_token</ExternalAccessToken>
    

    צריך להיות לכם גם שלב קודם שמגדיר את המשתנה הזה.

  • בנוגע להגדרת המשתנה oauth_external_authorization_status, שיטה נפוצה להגדרת המשתנה הזה היא להשתמש במדיניות AssignedMessage עם הרכיב assignVariable, באופן הבא:

    <AssignMessage name="AssignMessage-SetVariable">
        <DisplayName>Assign Message - Set Variable</DisplayName>
        <AssignVariable>
            <Name>oauth_external_authorization_status</Name>
            <Value>true</Value>
        </AssignVariable>
        <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    </AssignMessage>
    

    חשוב לזכור שהמדיניות הזו חייבת לחול לפני מדיניות OAuthV2 עם הפעולה = GenerateAccessToken.

מדיניות OAuthV2 לדוגמה

בהתאם למדיניות OAuthV2 הבאה, אסימון הגישה של Apigee Edge מוצא ערך של אסימון במשתנה הזרימה external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

בתיאוריה, אפשר יהיה להחיל את התבנית הזו בכל שירות הרשאות OAuth2 של צד שלישי.