הטמעה של סוג ההרשאה client credentials grant

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

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

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

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

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

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

תפקידים

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

• אפליקציית לקוח – האפליקציה שצריכה גישה למשאבים המוגנים של המשתמש. בדרך כלל, בתהליך הזה האפליקציה פועלת בשרת ולא באופן מקומי במחשב הנייד או במכשיר של המשתמש.
• ‫Apigee Edge – בתהליך הזה, Apigee Edge הוא שרת ההרשאות ב-OAuth. התפקיד שלו הוא ליצור אסימוני גישה, לאמת אסימוני גישה ולהעביר בקשות מורשות למשאבים מוגנים לשרת המשאבים.
• שרת משאבים – שירות הקצה העורפי שבו מאוחסנים הנתונים המוגנים, שאפליקציית הלקוח צריכה הרשאה כדי לגשת אליהם. אם אתם מגנים על שרתי proxy של API שמתארחים ב-Apigee Edge, ‏ Apigee Edge הוא גם שרת המשאבים.

דוגמת קוד

ב-GitHub אפשר למצוא הטמעה לדוגמה של סוג ההרשאה client credentials. בקטע משאבים נוספים שבהמשך מופיעים קישורים לדוגמאות נוספות.

תרשים זרימה

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

שלבים בתהליך של פרטי כניסה של לקוח

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

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

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

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

לדוגמה:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'

הערה: למרות שאפשר להעביר את הערכים client_id ו-client_secret כפרמטרים של שאילתה כמו בדוגמה שלמעלה, מומלץ להעביר אותם כמחרוזת בקידוד Base64 URL בכותרת Authorization. כדי לעשות את זה, צריך להשתמש בכלי או בשירות לקידוד Base64 כדי לקודד את שני הערכים יחד, עם נקודתיים ביניהם. כך: aBase64EncodeFunction(clientidvalue:clientsecret). לכן, הדוגמה שלמעלה תיראה כך אחרי קידוד:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Note the colon separating the two values.

התוצאה של קידוד המחרוזת שלמעלה ב-Base64 היא: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

לאחר מכן שולחים את בקשת האסימון באופן הבא:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='

2. ‫Edge מאמת את פרטי הכניסה

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

3. ‫Edge מחזיר תשובה

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

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

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

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

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

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

הדרך הכי קלה להראות איך מוגדרת הזרימה של שרת proxy ל-API היא להציג את הגדרת הזרימה ב-XML. לפניכם דוגמה לתהליך של proxy ל-API שנועד לעבד בקשה לאסימון גישה. לדוגמה, כשמתקבלת בקשה והסיומת של נתיב כתובת ה-URL תואמת ל-‎ /accesstoken, מופעלת מדיניות GetAccessToken. במאמר הגדרת נקודות קצה ומדיניות של OAuth מופיעה סקירה כללית של השלבים שנדרשים ליצירת תהליך מותאם אישית כמו זה.

<Flows>
  <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>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

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

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

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

המדיניות הזו מצורפת לנתיב /accesstoken. היא משתמשת במדיניות OAuthV2 עם הפעולה GenerateAccessToken שצוינה.

<OAuthV2 name="GetAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse/>
</OAuthV2>

הקריאה ל-API כדי לקבל את אסימון הגישה היא POST וכוללת כותרת Authorization עם client_id + client+secret בקידוד base64 ופרמטר השאילתה grant_type=client_credentials. הוא יכול לכלול גם פרמטרים אופציונליים של היקף ומצב. לדוגמה:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

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

כדי להגן על ה-API באמצעות אבטחת OAuth 2.0, צריך להוסיף מדיניות OAuthV2 עם הפעולה VerifyAccessToken. המדיניות הזו בודקת אם לבקשות הנכנסות יש אסימון גישה תקין. אם האסימון תקף, Edge מעבד את הבקשה. אם הוא לא תקין, 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 

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

מקורות מידע נוספים

• פלטפורמת Apigee מציעה הדרכה אונליין למפתחי API, כולל קורס בנושא אבטחת API, שכולל OAuth.
• ‫OAuthV2 policy – כולל הרבה דוגמאות שמראות איך לשלוח בקשות לשרת ההרשאות ואיך להגדיר את מדיניות OAuthV2.