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

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

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

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

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

וידאו

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

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

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

דוגמת קוד

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

תרשים זרימה

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

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

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

הנה סיכום של השלבים הנדרשים להטמעה של סוג ההרשאה authorization code grant, שבו 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 (הפרוקסי), ו-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

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