בקשת אסימוני גישה וקודי הרשאה

מוצג המסמך של Apigee Edge.
עוברים אל מסמכי תיעוד של Apigee X. מידע

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

קוד לדוגמה

לנוחותך, כללי המדיניות ונקודות הקצה המוזכרים בנושא זה זמינים בכתובת GitHub בפרויקט oauth-doc-examples במאגר לדוגמה של Apigee api-platform-samples. אתם יכולים לפרוס את הקוד לדוגמה ולנסות את הבקשות לדוגמה שמוצגות בנושא הזה. לפרטים נוספים, אפשר לעיין ב-README של הפרויקט.

בקשת אסימון גישה: סוג ההרשאה של קוד ההרשאה

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

דוגמה בקשה

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

חובה פרמטרים

כברירת מחדל, הפרמטרים האלה חייבים להיות x-www-form-urlencoded וצריך לציין אותם גוף הבקשה (כפי שמוצג בדוגמה למעלה); אבל אפשר לשנות את ברירת המחדל הזאת להגדיר את <GrantType>, <Code> ואת רכיבי <RedirectUri> במדיניות OAuthV2 שמצורפת נקודת קצה /accesstoken. פרטים נוספים זמינים במאמר מדיניות OAuthV2.

  • grant_type – חייב להיות מוגדר לערך authorization_code.
  • code - קוד ההרשאה שהתקבל מה-/authorize נקודת קצה (או כל שם אחר שתבחרו). כדי לבקש אסימון גישה בהרשאה תהליך מסוג הענקת קוד, תחילה עליך לקבל קוד הרשאה. פרטים נוספים מופיעים בקטע בקשת קודי הרשאה שבהמשך. למידע נוסף, ניתן לעיין בקטע הטמעה סוג הענקת קוד ההרשאה.
  • redirect_uri – יש לספק את הפרמטר הזה אם הפרמטר redirect_uri נכלל בבקשת קוד ההרשאה הקודמת. אם המיקום הפרמטר redirect_uri לא נכלל בבקשת קוד ההרשאה, וגם אם לא מספקים את הפרמטר הזה, המדיניות הזו משתמשת בערך של כתובת ה-URL לקריאה חוזרת (callback) סופק כשאפליקציית המפתח נרשמה.

אופציונלי פרמטרים

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

אימות

עליך להעביר את Client-ID ואת סוד הלקוח ככותרת של אימות בסיסי (בקידוד Base64) או כפרמטרים של צורה client_id ו-client_secret. שלך להשיג את הערכים האלה מאפליקציית מפתחים רשומה. למידע נוסף, אפשר לעיין במאמר "קידוד בסיסי אימות פרטי כניסה.

נקודת קצה לדוגמה

דוגמה להגדרה של נקודת קצה ליצירת אסימון גישה. הוא יריץ את מדיניות GenerateAccessToken, שצריך להגדיר שתתמוך בהרשאה authorization_code מהסוג הזה.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

מדיניות לדוגמה

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

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

החזרות

כאשר <GenerateResponse> מופעל, המדיניות מחזירה תגובת JSON כולל את אסימון הגישה, כמו שמוצג בהמשך. סוג ההרשאה authorization_code יוצר אסימון גישה ואסימוני רענון, לכן התגובה עשויה להיראות כך:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

אם המדיניות <GenerateResponse> מוגדרת כ-False, המדיניות לא תחזיר תשובה. במקום זאת, הוא מאכלס את הקבוצה הבאה של משתני הזרימה בנתונים שקשורים הענקת אסימון גישה.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

לדוגמה:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

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

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

דוגמה בקשה

למידע על קידוד כותרת האימות הבסיסית בקריאה הבאה: "קידוד של פרטי כניסה לאימות בסיסי". 

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

חובה פרמטרים

כברירת מחדל, הפרמטר consent_type הנדרש חייב להיות x-www-form-urlencoded וגם שמצוין בגוף הבקשה (כפי שמוצג בדוגמה למעלה); עם זאת, עשויות לשנות כברירת מחדל על ידי הגדרת הרכיב <GrantType> במדיניות OAuthV2, מצורף לנקודת הקצה הזו /accesstoken. לדוגמה, אפשר לבחור להעביר את בפרמטר של שאילתה. פרטים נוספים זמינים במאמר מדיניות OAuthV2.

  • grant_type – חייב להיות מוגדר לערך client_credentials.

אופציונלי פרמטרים

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

אימות

עליך להעביר את Client-ID ואת סוד הלקוח ככותרת של אימות בסיסי (בקידוד Base64) או כפרמטרים של צורה client_id וגם client_secret. הערכים האלה יתקבלו מאפליקציית המפתחים הרשומה שמשויכת לבקשה. למידע נוסף, ראו "קידוד אימות בסיסי" Credentials".

נקודת קצה לדוגמה

דוגמה להגדרה של נקודת קצה ליצירת אסימון גישה. הוא יריץ את מדיניות GenerateAccessToken, שצריך להגדיר שתתמוך בהרשאה client_credentials מהסוג הזה.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

מדיניות לדוגמה

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

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

החזרות

כאשר <GenerateResponse> מופעל, המדיניות מחזירה תגובת JSON. הערה שסוג ההענקת client_credentials אינו נתמך, אסימוני רענון לא נתמכים. רק נוצר אסימון גישה. לדוגמה:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

אם המדיניות <GenerateResponse> מוגדרת כ-False, המדיניות לא תחזיר תשובה. במקום זאת, הוא מאכלס את הקבוצה הבאה של משתני הזרימה בנתונים שקשורים הענקת אסימון גישה.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

לדוגמה:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

בקשת אסימון גישה: סוג הענקת סיסמה

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

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

דוגמה בקשה

למידע על קידוד כותרת האימות הבסיסית בקריאה הבאה: "קידוד של פרטי כניסה לאימות בסיסי". 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

חובה פרמטרים

כברירת מחדל, הפרמטרים האלה חייבים להיות x-www-form-urlencoded וצריך לציין אותם גוף הבקשה (כפי שמוצג בדוגמה למעלה); אבל אפשר לשנות את ברירת המחדל הזאת להגדיר את <GrantType>, <Username> ואת רכיבי <Password> במדיניות OAuthV2 שמצורפת נקודת קצה /token. פרטים נוספים זמינים במאמר מדיניות OAuthV2.

פרטי הכניסה של המשתמש בדרך כלל מאומתים מול מאגר פרטי כניסה באמצעות LDAP או מדיניות JavaScript.

  • grant_type – חייב להיות מוגדר לערך password.
  • username – שם המשתמש של בעלי המשאב.
  • password - הסיסמה של בעלי המשאב.

אופציונלי פרמטרים

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

אימות

עליך להעביר את Client-ID ואת סוד הלקוח ככותרת של אימות בסיסי (בקידוד Base64) או כפרמטרים של צורה client_id וגם client_secret. הערכים האלה יתקבלו מאפליקציית המפתחים הרשומה שמשויכת לבקשה. למידע נוסף, ראו "קידוד אימות בסיסי" Credentials".

נקודת קצה לדוגמה

דוגמה להגדרה של נקודת קצה ליצירת אסימון גישה. הוא יריץ את מדיניות GenerateAccessToken, שצריך להגדיר שתתמוך בסוג הענקת הסיסמה.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

מדיניות לדוגמה

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

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

החזרות

כאשר <GenerateResponse> מופעל, המדיניות מחזירה תגובת JSON. הערה שסוג הענקת הסיסמה יוצר גם אסימון גישה וגם אסימון רענון. עבור דוגמה:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

אם המדיניות <GenerateResponse> מוגדרת כ-False, המדיניות לא תחזיר תשובה. במקום זאת, הוא מאכלס את הקבוצה הבאה של משתני הזרימה בנתונים שקשורים הענקת אסימון גישה.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

לדוגמה:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

בקשה לאסימון גישה: הענקת גישה משתמעת ההמרה

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

דוגמה בקשה

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

חובה פרמטרים

כברירת מחדל, הפרמטרים האלה חייבים להיות פרמטרים של שאילתה (כפי שמוצג בדוגמה שלמעלה). עם זאת, אפשר לשנות את ברירת המחדל על ידי הגדרת <ResponseType>, רכיבי <ClientId> ו-<RedirectUri> ב-OAuthV2 שמצורפת לנקודת הקצה הזו של /token. פרטים נוספים זמינים במאמר מדיניות OAuthV2.

פרטי הכניסה של המשתמש בדרך כלל מאומתים מול מאגר פרטי כניסה באמצעות שירות LDAP מדיניות יתרונות מרכזיים או JavaScript.

  • response_type – צריך להגדיר את הערך token.
  • client_id – מזהה הלקוח של אפליקציית פיתוח רשומה.
  • redirect_uri – הפרמטר הזה הוא חובה אם לא סופקו כשאפליקציית המפתח של הלקוח נרשמה. אם הוזנה כתובת URL לקריאה חוזרת (callback) אצל הלקוח שלו תשוו את הערך הזה לערך, וחייבת להתאים בדיוק.

אופציונלי פרמטרים

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

אימות

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

נקודת קצה לדוגמה

דוגמה להגדרה של נקודת קצה ליצירת אסימון גישה. הוא יריץ את המדיניות GenerateAccessTokenImplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

מדיניות לדוגמה

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

החזרות

כשהאפשרות <GenerateResponse> מופעלת, המדיניות מחזירה הפניה אוטומטית מסוג 302 למיקום בכותרת התשובה. ההפניה מפנה לכתובת ה-URL שצוינה ב-redirect_uri שמצורף אליו אסימון הגישה ומועד התפוגה של האסימון. שימו לב שהתנועה המשתמעת סוג ההענקה אינו תומך באסימוני רענון. לדוגמה:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

אם המדיניות <GenerateResponse> מוגדרת כ-False, המדיניות לא תחזיר תשובה. במקום זאת, הוא מאכלס את הקבוצה הבאה של משתני הזרימה בנתונים שקשורים הענקת אסימון גישה.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

לדוגמה:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

בקשת קוד הרשאה

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

בקשה לדוגמה

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

שבה מצורפת מדיניות OAuthV2 GenerateAuthorizationCode נקודת קצה (endpoint) של שרת proxy /oauth/authorize (ראו נקודת הקצה לדוגמה בהמשך).

חובה פרמטרים

כברירת מחדל, הפרמטרים האלה חייבים להיות פרמטרים של שאילתה (כפי שמוצג בדוגמה שלמעלה). עם זאת, אפשר לשנות את ברירת המחדל על ידי הגדרת <ResponseType>, רכיבי <ClientId> ו-<RedirectUri> ב-OAuthV2 שמצורפת לנקודת הקצה הזו של /authorize. פרטים נוספים זמינים במאמר מדיניות OAuthV2.

  • response_type – צריך להגדיר את הערך code.
  • client_id – מזהה הלקוח של אפליקציית פיתוח רשומה.

אופציונלי פרמטרים

  • redirect_uri – אם מצוין URI מלא (לא חלקי) להתקשרות חזרה אפליקציית הלקוח הרשומה. הפרמטר הזה הוא אופציונלי. אחרת, הוא חובה. הקריאה החוזרת (callback) היא כתובת ה-URL שאליה Edge שולח את קוד ההרשאה החדש שהוטמע. מידע נוסף זמין בקטע רישום אפליקציות וניהול API .
  • state – מחרוזת שתישלח בחזרה עם התגובה. בדרך כלל בשימוש למניעת התקפות זיוף של בקשות חוצה-אתרים.
  • Scope – מאפשר לסנן את הרשימה של מוצרי API שבהם ניתן להשתמש באסימון שהתקבל. מידע מפורט על ההיקף זמין במאמר עבודה עם היקפי הרשאות OAuth2.

אימות

לא נדרש אימות בסיסי, אבל מזהה הלקוח של אפליקציית הלקוח הרשומה צריך תצוין בבקשה.

נקודת קצה לדוגמה

דוגמה להגדרה של נקודת קצה ליצירת קוד הרשאה:


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

מדיניות לדוגמה

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

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

החזרות

כשהאפשרות <GenerateResponse> מופעלת, המדיניות מחזירה ?code פרמטר של שאילתה למיקום redirect_uri (URI של קריאה חוזרת) עם ההרשאה עם הקוד. היא נשלחת דרך הפניה אוטומטית של דפדפן 302 עם כתובת ה-URL בכותרת המיקום של תשובה. לדוגמה: ?code=123456.

אם המדיניות <GenerateResponse> מוגדרת לערך false, המדיניות לא להחזיר תשובה. במקום זאת, הוא מאכלס את הקבוצה הבאה של משתני הזרימה בנתונים שקשורים לקוד ההרשאה.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

לדוגמה:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

רענון של אסימון גישה

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

כדי לבקש אסימון גישה חדש באמצעות אסימון רענון:

בקשה לדוגמה

למידע על קידוד כותרת האימות הבסיסית בקריאה הבאה: "קידוד של פרטי כניסה לאימות בסיסי". 

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

פרמטרים נדרשים

  • grant_type – חייב להיות מוגדר לערך refresh_token.
  • refresh_token – אסימון הרענון שמשויך לאסימון הגישה שאתם ברצונך לחדש את המינוי.

כברירת מחדל, המדיניות מחפשת את הפרמטרים האלה בתור x-www-form-urlencoded שמצוין בגוף הבקשה, כמו בדוגמה שלמעלה. כדי להגדיר מיקום חלופי אפשר להשתמש בפונקציה <GrantType> רכיבי <RefreshToken> במדיניות OAuthV2. פרטים נוספים זמינים במאמר מדיניות OAuthV2.

פרמטרים אופציונליים

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

אימות

  • client_id
  • client_secret

עליך להעביר את Client-ID ואת סוד הלקוח ככותרת של אימות בסיסי (בקידוד Base64) או כפרמטרים של צורה client_id ו-client_secret. צפייה וגם את "קידוד פרטי כניסה לאימות בסיסי".

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

דוגמה להגדרה של נקודת קצה (endpoint) ליצירת אסימון גישה באמצעות אסימון רענון. תתבצע הפעלה של המדיניות RefreshAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

מדיניות לדוגמה

זוהי מדיניות בסיסית של RefreshAccessToken שמוגדרת לקבל את סוג ההרשאה refresh_token. למידע על רכיבי תצורה אופציונליים שאפשר להגדיר באמצעות המדיניות הזו, ראו מדיניות OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

החזרות

כאשר <GenerateResponse> מופעל, המדיניות מחזירה תגובת JSON שמכיל את אסימון הגישה החדש. סוג המענק refresh_token תומך בהנפקה של נתונים משני הסוגים גישה ואסימוני רענון חדשים. לדוגמה:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

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

התגובה שלמעלה היא מה שמקבלים אם מגדירים את הערך של <GenerateResponse> כ-True. אם המדיניות <GenerateResponse> מוגדרת כ-False, המדיניות לא תחזיר תגובה. במקום זאת, הוא מאכלס את הקבוצה הבאה של משתני הקשר (זרימה) בנתונים שקשורים הענקת אסימון גישה.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

לדוגמה:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

קידוד פרטי כניסה לאימות בסיסי

כשמבצעים קריאה ל-API כדי לבקש אסימון או קוד אימות, זו שיטה מומלצת מומלץ לפי מפרט OAuth 2.0 להעביר את ערכי client_id ו-client_secret כ- כותרת HTTP-Basic Authentication, כפי שמתואר ב-IETF RFC 2617. כדי לעשות את זה צריך מקודד ב-base64 את התוצאה של איחוד שני הערכים יחד עם נקודתיים שמפרידה ביניהם.

בפסאודו-קוד:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

בדוגמה הזו, ns4fQc14Zg4hKFCNaSzArVuwszX95X הוא client_id ו- ZIjFyTsNgQNyxI הוא סוד הלקוח.

בלי קשר לשפת התכנות שבה אתם משתמשים כדי לחשב את הערך בקידוד base64, בעקבות פרטי הכניסה של הלקוח, התוצאה בקידוד base64 היא: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

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

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

הכלי curl ייצור בפועל את הכותרת HTTP Basic אם משתמשים האפשרות -u. הערך הבא מקביל לפועל:

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

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

גיבוב (hashing) של האסימונים במסד הנתונים

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

המאפיינים הבאים ברמת הארגון שולטים בגיבוב של אסימוני OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

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

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

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

נושאים קשורים