הטמעה של סוג ההרשאה Authorization Code Grant

אתם קוראים את מאמרי העזרה של Apigee Edge.
אפשר לעיין במסמכי התיעוד של Apigee X. מידע

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

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

בנושא הזה מוסבר על סוג ההרשאה OAuth 2.0, ומוצגת סקירה כללית של התהליך. בנוסף, מוסבר איך להטמיע את התהליך הזה ב-Apigee Edge.

וידאו

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

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

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

דוגמת קוד

במאגר api-platform-samples ב-GitHub אפשר למצוא הטמעה לדוגמה של סוג ההרשאה קוד הרשאה ב-Apigee Edge. אפשר לעיין בדוגמה 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

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

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

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

{redirect_uri}?code={authorization_code}&state={some_string}

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

עכשיו, כשיש ללקוח קוד הרשאה תקין, הוא יכול לבקש אסימון גישה מ-Edge. הוא עושה את זה באמצעות שליחת POST של מזהה הלקוח והמפתחות הסודיים של הלקוח (שהתקבלו כשנרשמה האפליקציה ב-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'

7. הלקוח מקבל טוקן גישה

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

8. הלקוח שולח קריאה ל-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 שבהמשך, לנקודת הקצה /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 לנקודות קצה של שרת proxy.

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

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

הקריאה ל-API כדי לבצע את הבקשה היא GET ונדרשים בה פרמטרים של שאילתה: client_id,‏ response_type,‏ redirect_uri,‏ scope ו-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 כדי לקבל את קוד ההרשאה היא POST, וצריך להעביר את הפרמטרים client_id,‏ response_type,‏ redirect_uri, וגם scope ו-state (אם רוצים) בגוף הבקשה כפרמטרים של טופס, כמו בדוגמה הזו:

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

קבלת טוקן גישה

המדיניות הזו מצורפת לנתיב /oauth/accesstoken. היא משתמשת במדיניות OAuthV2 עם הפעולה GenerateAccessToken שצוינה. במקרה הזה, הפרמטר 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=authorization_code, ואופציונלית, scope. לדוגמה:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'code={authorization_code}&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, צריך להציג אסימון גישה תקף. התבנית הנכונה היא לכלול את האסימון בכותרת Authorization, באופן הבא: הערה אסימון הגישה נקרא גם "אסימון bearer".

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

אפשר לעיין גם במאמר בנושא שליחת אסימון גישה.