דף זה תורגם על ידי Cloud Translation API.

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

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

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

במקרה הרגיל, Apigee Edge ייצור ויאחסן אסימון OAuth ויחזיר אותו של האפליקציה לשיחות. לאחר מכן אפליקציית הקריאה תציג את האסימון בחזרה ל-Apigee Edge כשתוצג הבקשה ו-Apigee Edge – באמצעות מדיניות OAuthV2 עם Operation = VerifyAccessToken – לאמת שהאסימון חוקי. בנושא הזה מוסבר איך להגדיר את 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 מדיניות עם Operation = VerifyAccessToken - יחפש את האסימון, יאחזר את כל המידע, ולהשתמש במידע הזה כדי לקבוע אם האסימון תקף או לא, עבור שרת ה-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, ו-Edge - באמצעות מדיניות OAuthV2 עם פעולה = VerifyAccessToken – אפשר לאמת אותו. אפשר להחיל דפוס ייבוא דומה קודי הרשאה ואסימוני רענון.

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

דרישה מוקדמת אחת ליצירת אסימון היא אימות הלקוח ששלח את הבקשה. כברירת מחדל, מדיניות OAuthV2/GenerateAccessToken ב-Apigee Edge מאמתת באופן מרומז את פרטי הכניסה של הלקוח. בדרך כלל, בבקשה לאסימון OAuthV2, הפרמטרים client_id ו-client_secret מועברים כותרת ההרשאה, מקודדת באמצעות 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 Proxy שיוצרת אסימונים, קודם כל מאמת את פרטי הכניסה של הלקוח. חשוב לזכור שאימות הלקוח לא תלוי ביצירת אסימון הגישה. אפשר להגדיר ב-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 match, המדיניות תאמת שה-client_id חוקי, קיים ולא בוטל. לכן, כשלב הגדרה נדרש, ייתכן שיהיה עליכם לייבא מזהי client_id דרך Edge. ב-Admin API.

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

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

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

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

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

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

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

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

לדוגמה, ההגדרה הבאה במדיניות OAuthV2 מנחה את Edge לחפש את במשתנה הקשר בשם external_token.
```
<ExternalAccessToken>external_token</ExternalAccessToken>
```
אתם צריכים גם שלב קודם שמגדיר את המשתנה הזה.
לגבי הגדרת המשתנה oauth_external_authorization_status, להגדרת המשתנה הזה היא להשתמש במדיניות AssignMessage עם לרכיב 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 מכיוון ש-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>

בדרך כלל, אצל הלקוח סוג הענקת פרטי הכניסה, עליך לספק כותרת Basic Authentication עם הלקוח המקודד ו-Client Secret. עם זאת, במקרה כזה, לא צריך לספק את הפרטים האלה הכותרת. המדיניות עדיין מצפה שה-client_id יופיע בבקשה, וגם המדיניות תאמת אותה. Edge מצפה שה-client_id יישלח כחלק של נתוני טופס הבקשה, למשל ב-request.formparam.client_id.

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