הטמעה של סוג המענק של קוד ההרשאה

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

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

מידע על נושא זה

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

וידאו

כדאי לצפות בסרטון קצר שבו מוסבר איך משתמשים בהרשאת OAuth 2.0 כדי לאבטח את ממשקי ה-API.

תרחישים לדוגמה

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

דוגמת קוד

ניתן למצוא הטמעה מלאה ופעילה של דוגמה של סוג הענקת קוד הרשאה ב- Apigee Edge במאגר api-platform-samples ב-GitHub. מידע נוסף זמין בהסבר על oauth-Advanced דוגמה בספרייה api-platform-samples/sample-proxies. README לקבלת פרטים על הטעימה.

תרשים זרימה

תרשים הזרימה הבא ממחיש את תהליך OAuth של קוד ההרשאה עם Apigee Edge שמשמש כשרת ההרשאות.

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

השלבים בתהליך קוד ההרשאה

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

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

1. המשתמש מתחיל את התהליך

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

2. המשתמש מזין פרטי כניסה

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

3. המשתמש מביע הסכמה

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

4. אפליקציית ההתחברות שולח בקשה ל-Apigee Edge

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

5. Apigee Edge יצירת קוד הרשאה

כש-Edge מקבל בקשת GET מאפליקציית ההתחברות בנקודת הקצה /permissioncode שלו, קורים דברים. דבר ראשון, דפדפן Edge קובע שההתחברות בוצעה בהצלחה (על ידי בדיקת סטטוס HTTP או אמצעים אחרים). הבא: Edge ייבדקו כדי לוודא שה-URI של ההפניה האוטומטית נשלח מאפליקציית ההתחברות תואם ל-URI להפניה מחדש שצוין כשהאפליקציה נרשמה ב-Apigee Edge. אם המיקום הכול בסדר, Edge יוצר קוד הרשאה. לדוגמה:

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. קצה שולח את קוד ההרשאה חזרה ללקוח

Edge שולח הפניה אוטומטית 302 כשקוד ההרשאה מצורף כפרמטר של שאילתה הלקוח.

7. הלקוח מאחזר את קוד ההרשאה ומבקש קוד גישה מ-Edge

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

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. הלקוח מקבל אסימון גישה

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

9. הלקוח קורא ל API מוגן

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

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

הגדרת תהליכים וכללי מדיניות

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

• יצירת תהליכי עבודה בהתאמה אישית
• הוספה והגדרה של כללי מדיניות OAuthV2

הגדרה של תהליך מותאם אישית

בדרך כלל אתם מגדירים את התהליך של סוג ההענקה כך שכל שלב או "שלב" בתהליך הגדרת באמצעות תהליך בשרת ה-proxy של Apigee Edge. לכל תהליך יש נקודת קצה ומדיניות שמבצעת את נדרשת משימה ספציפית ל-OAuth, כמו יצירת קוד הרשאה או אסימון גישה. עבור לדוגמה, כפי שאפשר לראות ב-XML הבא, לנקודת הקצה (endpoint) /oauth/authorizationcode יש משויכת למדיניות משויכת בשם GenerateAuthCode (שהיא מדיניות OAuthV2 עם צוינה הפעולה GenerateAuthorizationCode).

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

לצפייה גם בדוגמה ב-GitHub.

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

הגדרת התהליכים באמצעות כללי מדיניות

לכל נקודת קצה משויכת מדיניות. בואו נראה דוגמאות של המדיניות. צפייה בנוסף, הגדרת OAuth נקודות קצה וכללי מדיניות כדי לקבל סקירה כללית מהירה של השלבים הנדרשים להוספת כללי מדיניות OAuthV2 לנקודות קצה (endpoints) של proxy.

הפניה אוטומטית להתחברות

זהו הנתיב /oauth/authorize. המדיניות המצורפת אחראית להפנות את המשתמשים לאפליקציית התחברות, שבה משתמש הקצה יכול לאמת ולאשר בבטחה לאפליקציית לקוח לגשת למשאבים המוגנים שלה בלי לחשוף את שם המשתמש והסיסמה שלה את אפליקציית הלקוח. אפשר לעשות זאת באמצעות מדיניות בנושא יתרונות מרכזיים של שירות, JavaScript, Node.js או באמצעים אחרים.

הקריאה ל-API לביצוע הבקשה היא GET ומחייבת את הפרמטרים של השאילתה client_id, response_type, redirect_uri, היקף ו-State.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

קבלת קוד הרשאה

זהו הנתיב /oauth/authorizationcode. הוא משתמש במדיניות OAuthV2 עם צוינה הפעולה GenerateAuthorizationCode.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

הקריאה ל-API לקבלת קוד ההרשאה היא GET ומחייבת את הפרמטרים של השאילתה client_id, response_type והיקף ומצב אופציונלי, כמו בדוגמה הזו:

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

קבלת אסימון גישה

המדיניות הזו מצורפת לנתיב /oauth/accesstoken. היא משתמשת ב-OAuthV2 המדיניות עם הפעולה GenerateAccessCode שצוינה. במקרה הזה, הפרמטרGrant_type הוא הצפוי כפרמטר של שאילתה:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

הקריאה ל-API לקבלת קוד הגישה היא POST והיא חייבת לכלול את הפרמטר client_id, client_secret, Grant_type=permission_code, ובאופן אופציונלי, היקף. לדוגמה:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

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

צירוף המדיניות לאימות אסימון הגישה

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

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

שליחת קריאה ל-API המוגן

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

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282 

ראה גם שליחת אסימון גישה.