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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

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

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

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

וידאו

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

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

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

דוגמת קוד

אפשר למצוא הטמעה מלאה ופעילה לדוגמה של סוג ההרשאה קוד הרשאה ב-Apigee במאגר api-platform-samples ב-GitHub. אפשר לעיין בדוגמה oauth-advancedבספרייה api-platform-samples/sample-proxies. פרטים על הדוגמה מופיעים בקובץ README.

תרשים זרימה

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

תהליך OAuth של קוד הרשאה.

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

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

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

1. המשתמש מפעיל את התהליך

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

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

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

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

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

4. אפליקציית הכניסה שולחת בקשה ל-Apigee

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

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

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

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. ‫Apigee שולח את קוד ההרשאה בחזרה ללקוח

‫Apigee שולח הפניה אוטומטית מסוג 302 עם קוד האימות שמצורף כפרמטר שאילתה ללקוח.

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

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

$ 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. הלקוח מקבל טוקן גישה

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

‫9. הלקוח שולח קריאה ל-API המוגן

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

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

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

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

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

הגדרת תהליך בהתאמה אישית

בדרך כלל מגדירים את התהליך של סוג ההרשאה הזה כך שכל שלב או חלק בתהליך מוגדרים על ידי תהליך בשרת ה-proxy של Apigee. לכל תהליך יש נקודת קצה ומדיניות שמבצעת את המשימה הספציפית שנדרשת ל-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 או אמצעים אחרים.

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

$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=authorization_code, ואופציונלית, scope. לדוגמה:

$ 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 מוגן, כך שהיא מופעלת בכל פעם שמתקבלת בקשה למשאבים מוגנים. מערכת Apigee בודקת שלכל בקשה יש אסימון גישה תקין. אם לא, תוחזר שגיאה. השלבים הבסיסיים מפורטים במאמר אימות אסימוני גישה. 

<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

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