הטמעת סוג המענק של פרטי הכניסה של הלקוח

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

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

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

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

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

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

תפקידים

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

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

דוגמת קוד

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

תרשים זרימה

תרשים הזרימה הבא ממחיש את זרימת פרטי הכניסה של הלקוח כאשר Apigee Edge משמש כשרת ההרשאות. באופן כללי, Edge הוא גם שרת המשאבים בתהליך הזה, כלומר, שרתי proxy של ה-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 כפרמטרים של שאילתה, כפי שמתואר למעלה, כדאי להעביר אותם כמחרוזת מקודדת של כתובת URL מסוג base64 בכותרת Authorization. לשם כך, צריך להשתמש בכלי קידוד או בכלי קידוד base64 כדי לקודד את שני הערכים יחד עם נקודתיים שמפרידים ביניהם. כך: aBase64EncodeFunction(clientidvalue:clientsecret). כך, הדוגמה שלמעלה תקודד כך:

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // שימו לב לנקודתיים שמפרידות בין שני הערכים.

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

הגדרת תהליכי עבודה ומדיניות

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

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

הדרך הקלה ביותר להראות איך מוגדר התהליך של שרת ה-proxy של ה-API היא להציג את הגדרת התהליך ב-XML. בהמשך מוצגת דוגמה לתהליך של שרת proxy ל-API, שמיועד לעבד בקשה לאסימון גישה. לדוגמה, כאשר מתקבלת בקשה וסיומת הנתיב תואמת ל- /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 והיא כוללת כותרת הרשאה עם 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 באמצעות הפעולה verificationAccessToken. המדיניות הזו בודקת שלבקשות הנכנסות יש אסימון גישה תקין. אם האסימון תקין, 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 באופן הבא: שימו לב שאסימון הגישה נקרא גם 'אסימון נושא'.

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

למידע נוסף, ראו שליחת אסימון גישה.

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

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