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

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

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

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

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

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

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

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

תפקידים

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

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

דוגמת קוד

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

תרשים זרימה

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

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

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

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

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

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

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

לדוגמה:

curl -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

אפשר גם לעיין במאמר בנושא שימוש בסוג ההרשאה Client Credentials Grant.

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

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

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

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

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

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

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

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

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

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

<Flows>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/token. Publish this URL to app developers
         to use when obtaining an access token using an auth code
         -->
    <Condition>proxy.pathsuffix == "/oauth/token"</Condition>
    <Request>
        <Step><Name>GetAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

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

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

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

המדיניות הזו מצורפת לנתיב /oauth/token. היא משתמשת במדיניות 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. המדיניות הזו בודקת אם לבקשות הנכנסות יש אסימון גישה תקין. אם האסימון תקף, Apigee מעבד את הבקשה. אם הוא לא תקין, 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

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

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

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