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

אתם צופים במסמכי התיעוד של 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 (או כל שם אחר שתבחרו). כדי לבקש אסימון גישה בתהליך של סוג ההרשאה באמצעות קוד, קודם צריך לקבל קוד הרשאה. מידע נוסף זמין בקטע בקשת קודי הרשאה בהמשך. כדאי לעיין גם במאמר בנושא הטמעה של סוג ההרשאה Authorization Code Grant.
  • ‫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 grant type. מידע נוסף על סוגי הרשאות 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'

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

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

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

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

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

אימות

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

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

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

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

אימות

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

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

זוהי דוגמה להגדרת נקודת קצה ליצירת טוקן גישה. המערכת תבצע את המדיניות 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://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 – הפרמטר הזה הוא חובה אם לא צוין URI של קריאה חוזרת כשנרשמה אפליקציית הלקוח של המפתח. אם צוינה כתובת URL של קריאה חוזרת בזמן רישום הלקוח, המערכת תשווה אותה לערך הזה, והן צריכות להיות זהות.

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

  • ‫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

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

אם אתם משתמשים בתהליך של סוג ההרשאה authorization code grant type, אתם צריכים לקבל קוד הרשאה לפני שתוכלו לבקש אסימון גישה.

בקשה לדוגמה

$ 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 מצורפת לנקודת הקצה של ה-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 בכותרת 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://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

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

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

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

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

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

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

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

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

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

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

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