Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

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

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

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

הערה: הגדרת המדיניות OAuthV2 בקטע הזה משתמשת בGenerateAccessToken פעולה. הפעולה הזו יוצרת פורמט טוקן מחרוזת אטום. אפשר גם ליצור אסימונים בפורמט JWT על ידי החלפת הפעולה GenerateJWTAccessToken. מידע נוסף זמין במאמר בנושא שימוש בפעולות של אסימוני JWT OAuth.

בקשה לדוגמה

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

בקטע הזה מוסבר איך לקבל אסימון גישה באמצעות תהליך של סוג הרשאה מסוג פרטי כניסה של לקוח. אפשר גם לעיין במאמר מהם סוגי הרשאות 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"
}

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

לדוגמה:

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

שימוש בסוג ההרשאה 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.

הרשאה

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

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

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

שימוש בסוג ההרשאה המרומזת (implicit grant)

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

הערה: הגדרת המדיניות OAuthV2 בקטע הזה משתמשת בGenerateAccessTokenImplicitGrant פעולה. הפעולה הזו יוצרת פורמט טוקן מחרוזת אטום. אפשר גם ליצור אסימונים בפורמט JWT על ידי החלפת הפעולה GenerateJWTAccessTokenImplicitGrant. מידע נוסף זמין במאמר בנושא שימוש בפעולות של אסימוני JWT OAuth.

בקשה לדוגמה

$ 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.

הרשאה

לא נדרשת כותרת הרשאה, אבל צריך להעביר 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

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

הערה: אפשר להגדיר מאפיינים מותאמים אישית גם במדיניות OAuthV2. מאפיינים מותאמים אישית יוחזרו באותו פורמט כמו שאר המשתנים: oauthv2.{policy_name}.{attribute_name}. כשיוצרים אסימון גישה מקוד אימות, אסימון הגישה יקבל בירושה את כל המשתנים המותאמים אישית שהוגדרו בקוד האימות. מידע נוסף זמין במאמר בנושא מדיניות OAuthV2.

רענון של טוקן גישה

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

הערה: הגדרת המדיניות OAuthV2 בקטע הזה משתמשת בRefreshAccessToken פעולה. הפעולה הזו מרעננת פורמט של טוקן מחרוזת אטום. אפשר גם לרענן טוקנים בפורמט JWT על ידי החלפת הפעולה RefreshJWTAccessToken. מידע נוסף זמין במאמר בנושא שימוש בפעולות של אסימוני JWT OAuth.

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

דוגמה לבקשה

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

$ 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 Authorization, כפי שמתואר ב-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 מאמתת אותם מול הגרסאות המוצפנות במסד הנתונים.

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

הטמעה של סוג ההרשאה client credentials
הטמעה של סוג ההרשאה קוד הרשאה
קורס אונליין בנושא אבטחת API (כולל OAuth)
‫OAuthV2 policy – כולל הרבה דוגמאות שמראות איך לשלוח בקשות לשרת ההרשאות ואיך להגדיר את מדיניות OAuthV2.

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

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

בקשה לדוגמה

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

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

הרשאה

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

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

החזרות

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

בקשה לדוגמה

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

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

הרשאה

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

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

החזרות

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

בקשה לדוגמה

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

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

הרשאה

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

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

החזרות

שימוש בסוג ההרשאה המרומזת (implicit grant)

בקשה לדוגמה

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

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

הרשאה

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

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

החזרות

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

בקשה לדוגמה

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

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

הרשאה

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

החזרות

רענון של טוקן גישה

דוגמה לבקשה

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

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

הרשאה

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

החזרות

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

דוגמאות

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

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

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