קבלת טוקנים מסוג OAuth 2.0

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

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

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

שימוש בסוג ההרשאה Authorization Code Grant

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

בקשה לדוגמה

curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://apitest.acme.com/oauth/token' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

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

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

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

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

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

הרשאה

צריך להעביר את מזהה הלקוח ואת סוד הלקוח ככותרת הרשאה בסיסית (בקידוד 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

שימוש בסוג ההרשאה client credentials

בקטע הזה מוסבר איך לקבל אסימון גישה באמצעות תהליך ההרשאה מסוג client credentials. אפשר גם לעיין במאמר מהם סוגי הרשאות OAuth 2.0.

בקשה לדוגמה

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"

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

  • grant_type – צריך להגדיר את הערך client_credentials.

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

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

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

הרשאה

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

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

זוהי דוגמה להגדרת נקודת קצה ליצירת טוקן גישה. המדיניות 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

שימוש בסוג ההרשאה password

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

בקשה לדוגמה

curl -v -k -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=password&username=a_username&password=a_password"

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

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

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

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

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

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

הרשאה

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

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

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

...
       <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 (יצירת אסימון גישה) שמוגדרת לקבל את סוג ההרשאה password (סיסמה). מידע על רכיבי הגדרה אופציונליים שאפשר להגדיר באמצעות המדיניות הזו זמין במאמר מדיניות 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.

בקשה לדוגמה

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

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

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

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

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

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

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

הרשאה

לא נדרשת כותרת Authorization, אבל צריך להעביר Client ID כפרמטר בקשה.

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

זוהי דוגמה להגדרת נקודת קצה ליצירת טוקן גישה. המדיניות 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

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

בתהליך של סוג ההרשאה באמצעות קוד, נדרש קוד הרשאה כדי לקבל אסימון גישה. איך משתמשים בסוג ההרשאה Authorization Code Grant אפשר גם לעיין במאמר מהם סוגי הרשאות OAuth 2.0.

בקשה לדוגמה

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  "https://apitest.acme.com/oauth/authorize?response_type=code&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://my-callback.com"

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

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

  • ‫redirect_uri – אם צוין URI מלא (לא חלקי) של קריאה חוזרת באפליקציית הלקוח הרשומה, הפרמטר הזה הוא אופציונלי. אחרת, הוא נדרש. ה-callback הוא כתובת ה-URL שאליה Apigee שולח את קוד ההרשאה החדש. אפשר גם לעיין במאמר בנושא רישום אפליקציות וניהול מפתחות API.
  • response_type – צריך להגדיר את הערך code.
  • ‫client_id – מזהה הלקוח של אפליקציית מפתחים רשומה.

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

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

הרשאה

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

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

זוהי מדיניות בסיסית של GenerateAuthorizationCode. אפשרויות הגדרה נוספות מפורטות במאמר בנושא מדיניות OAuthV2:

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

החזרות

אם האפשרות <GenerateResponse> מופעלת, המדיניות מחזירה את פרמטר השאילתה ?code למיקום redirect_uri (URI של קריאה חוזרת) עם קוד ההרשאה המצורף. היא נשלחת באמצעות הפניה אוטומטית של דפדפן מסוג 302 עם כתובת ה-URL בכותרת Location של התגובה. לדוגמה: ?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://apitest.acme.com/oauth/refresh \
  -d "grant_type=refresh_token&refresh_token=yVSL38WpuN3Kzn1UTMoE6AQ4ANZM"

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

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

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

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

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

הרשאה

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

כשמרעננים טוקן גישה, המשתמש לא מאומת מחדש.

הנה דוגמה להגדרת נקודת קצה ליצירת אסימון גישה באמצעות אסימון רענון. המערכת תבצע את המדיניות 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 כדי לבקש אסימון או קוד הרשאה, מומלץ להעביר את הערכים client_id ו-client_secret ככותרת הרשאה מסוג HTTP-Basic, כמו שמתואר ב-IETF RFC 2617. זו שיטה מומלצת שמופיעה במפרט של OAuth 2.0. כדי לעשות את זה, צריך לקודד בפורמט Base64 את התוצאה של צירוף שני הערכים יחד, עם נקודתיים להפרדה ביניהם.

בקוד מדומה:

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

כאשר: ns4fQc14Zg4hKFCNaSzArVuwszX95X הוא client_id ו-ZIjFyTsNgQNyxI הוא סוד הלקוח.

דוגמאות

הפקודה לדוגמה הזו פועלת ב-Linux וב-MacOS:

export CREDENTIALS=$(echo -n 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' | base64)

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

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

גיבוב טוקנים במסד הנתונים

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

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