עבודה עם היקפי ההרשאות של OAuth2

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

הנושא הזה מסביר איך להשתמש בהיקפים של OAuth 2.0 ב-Apigee Edge.

מה זה היקף הרשאות OAuth2?

ההיקפים של OAuth 2.0 מאפשרים להגביל את כמות הגישה שניתנת לגישה ב-Assistant. לדוגמה, יכול להיות שאסימון גישה שהונפק לאפליקציית לקוח יקבל גישת הקראה וכתיבה. למשאבים מוגנים, או רק בגישת READ. תוכלו להטמיע את ממשקי ה-API שלכם כדי לאכוף כל היקף או כל ההיקפים הרצויים. לכן, אם לקוח מקבל אסימון שיש לו היקף READ, ינסה לקרוא לנקודת קצה ל-API שדורשת גישת כתיבה, הקריאה תיכשל.

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

איך מקצים היקפים לאסימוני גישה?

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

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

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

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

איך האסימון מקבל את ההיקף שלו?

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

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

כשאפליקציית לקוח מבקשת אסימון גישה מ-Apigee Edge, היא יכולה לציין את היקפי ההרשאות שהוא רוצה לשייך לאסימון הזה. לדוגמה, הבקשה הבאה תבקש עבור ההיקף "A". כלומר, הלקוח מבקש ששרת ההרשאות (Edge) ייצור אסימון גישה עם היקף "A" (מתן הרשאה לאפליקציה לקרוא לממשקי API בהיקף "A"). האפליקציה שולחת בקשת POST כמו זו:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A

מה קורה

כש-Edge מקבל את הבקשה, הוא יודע מאיזו אפליקציה נשלחה הבקשה והוא יודע איזו אפליקציה נשלחה. של האפליקציה למפתחים שהלקוח רשם (מזהה הלקוח והמפתחות הסודיים של הלקוח מקודדים כותרת אימות בסיסית). מכיוון שפרמטר השאילתה scope כלול, Edge צריך מחליטים אם למוצרי ה-API שמשויכים לאפליקציה למפתחים יש היקף "A". אם כן, ואז נוצר אסימון גישה עם היקף 'A'. דרך נוספת להסתכל על זה היא שההיקף פרמטר של שאילתה הוא סוג של מסנן. אם האפליקציה למפתחים מזהה את ההיקפים A, B, X, פרמטר השאילתה מציין "scope=X Y Z", ואז רק היקף "X" יוקצה ב-Assistant.

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

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

נניח שאפליקציה למפתחים מזהה את ההיקפים הבאים: A B C D. זו הרשימה הראשית של האפליקציה לתחומים שונים. יכול להיות שמוצר אחד באפליקציה מוגדר בהיקף א' ו-ב', ומוצר שני מוגדר בהיקף ג'. ו-D, או כל שילוב שהוא. אם הלקוח לא מציין פרמטר scope (או אם מציין פרמטר של היקף ללא ערך) האסימון יקבל את כל ארבעת ההיקפים: A , B , C וד. שוב, האסימון מקבל קבוצת היקפים שהיא האיחוד של כל ההיקפים שמזוהים על ידי האפליקציה למפתחים.

יש מקרה אחד נוסף שבו התנהגות ברירת המחדל היא להחזיר אסימון גישה עם כל ניתן לזהות היקפים מוכרים, ואז המדיניות GenerateAccessToken (מדיניות Apigee Edge). יוצר אסימוני גישה) לא מציין רכיב <Scope>. לדוגמה, הנה מדיניות GenerateAccessToken שבה <Scope> הפרמטר is צוין. אם רכיב ה-<Scope> חסר (או אם הוא חסר קיים אבל ריק), תתבצע התנהגות ברירת המחדל.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

איך אוכפים היקפים?

קודם כל, צריך לזכור שב-Apigee Edge, אסימוני הגישה מאומתים באמצעות מדיניות OAuthV2 (ממוקם בדרך כלל בתחילת התהליך של שרת proxy). המדיניות חייבת לכלול את הפרטים צוינה פעולת VerifyAccessToken. נסתכל על המדיניות הזו:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

חשוב לשים לב לרכיב <Scope>. היא משמשת כדי לציין אילו היקפים המדיניות יקבל.

בדוגמה הזו, המדיניות תצליח רק אם אסימון הגישה כולל את ההיקף "A". אם <Scope> חסר או אם אין לו ערך, המדיניות מתעלמת מההיקף של אסימון גישה.

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

נניח שלממשק ה-API שלכם מוגדר זרימה עבור נקודת הקצה /resourceA:

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

כשהתהליך הזה מופעל (בקשה מגיעה עם /resourceA בנתיב סיומת), תתבצע קריאה מיידית למדיניות OAuthV2-VerifyAccessTokenA. המדיניות הזו מאמתת אסימון הגישה תקין, והוא בודק אילו היקפים נתמכים באסימון. אם המדיניות מוגדרת כמו בדוגמה הבאה, עם <Scope>A</Scope>, המדיניות תצליח רק אם אסימון הגישה כולל היקף 'A'. אחרת, תחזיר שגיאה.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

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

דוגמאות לקוד

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

גודל ברירת המחדל

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

curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials

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

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

עכשיו נניח שיש לכם נקודת קצה ל-API עם היקף A (כלומר, צריך להזין את ה-VerifyAccessToken נדרש היקף "A"). זוהי המדיניות VerifyAccessToken:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

הנה דוגמה לקריאה ולנקודת קצה (endpoint) שאוכפת את היקף A:

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA 

הפעלת GET הזו מצליחה:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

היא מצליחה כי המדיניות VerifyAccessToken שמופעלת כשמתבצעת קריאה לנקודת הקצה נדרש היקף א', ואסימון הגישה קיבל את ההיקפים A, B ו-C – ברירת המחדל או התנהגות המשתמשים.

תרחיש סינון

נניח שיש לכם אפליקציה למפתחים עם מוצרים שהוגדרו בהיקפים A, B, C ו-X. הבקשה שלך אסימון גישה וכוללים את פרמטר השאילתה scope, כך:

curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'

במקרה הזה, האסימון שנוצר יקבל את ההיקפים A ו-X, כי גם A וגם X הם היקפים תקינים. חשוב לזכור שאפליקציית הפיתוח מזהה את היקפים A, B, C ו-X. במקרה הזה, אתם מסננים את הרשימה של מוצרי ה-API לפי ההיקפים האלה. אם למוצר יש היקף A או X, אפשר להגדיר נקודות קצה ל-API שיאכפו את ההיקפים האלה. אם למוצר אין היקף A או X (נניח שיש להם B, C ו-Z), אז לא ניתן לקרוא לממשקי ה-API שאוכפים את היקפי ההרשאות A או X באמצעות האסימון.

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

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX

אסימון הגישה מאומת על ידי שרת ה-proxy של ה-API. לדוגמה:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

טריגרי הקריאה ל-GET פועלים בהצלחה ומחזירים תשובה. לדוגמה:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }
 

הפעולה מצליחה כי המדיניות VerifyAccessToken דורשת את היקף A או X, ואת אסימון הגישה כולל את היקף A ו-X. כמובן, אם הרכיב <Scope> הוגדר ל-'B', השיחה תיכשל.

סיכום

חשוב להבין איך Apigee Edge מטפלת בהיקפים של OAuth 2.0. הנה המסקנות המרכזיות נקודות:

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