‫VerifyAPIKey policy

מדיניות ניתנת להרחבה

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

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

כשמפתח רושם אפליקציה ב-Apigee, המערכת יוצרת באופן אוטומטי זוג של טוקן צרכן וסוד. אפשר לראות את זוג המַפְתֵּחַ והסוד של האפליקציה בממשק המשתמש של Apigee או לגשת אליהם דרך Apigee API.

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

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

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

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

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

במאמר אבטחת API באמצעות דרישת מפתחות API יש הדרכה ליצירת שרת proxy ל-API שמשתמש במדיניות Verify API Key.

דוגמאות

מפתח בפרמטר של שאילתה

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

בדוגמה הזו, המדיניות מצפה למצוא את מפתח ה-API במשתנה של זרימת נתונים שנקרא request.queryparam.apikey. המשתנה request.queryparam.{name} הוא משתנה רגיל של Apigee flow שאוכלס בערך של פרמטר שאילתה שהועבר בבקשת הלקוח.

הפקודה הבאה של curl מעבירה את מפתח ה-API כפרמטר של שאילתה:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

מפתח בכותרת

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

בדוגמה הזו, המדיניות מצפה למצוא את מפתח ה-API במשתנה של זרימת נתונים שנקרא request.header.x-apikey. המשתנה request.header.{name} הוא משתנה רגיל של Apigee flow, שמאוכלס בערך של כותרת שעוברת בבקשת הלקוח.

בדוגמת ה-cURL הבאה אפשר לראות איך מעבירים את מפתח ה-API בכותרת:

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

מפתח במשתנה

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

המדיניות יכולה להתייחס לכל משתנה שמכיל את המפתח. המדיניות בדוגמה הזו מחילה את מפתח ה-API ממשתנה בשם requestAPIKey.key.

אתם קובעים איך המשתנה הזה יאוכלס. לדוגמה, אפשר להשתמש במדיניות Extract Variables כדי לאכלס את requestAPIKey.key מפרמטר שאילתה בשם myKey, כמו שמוצג בהמשך:

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

משתני זרימה של מדיניות הגישה

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

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

לכל המשתנים האלה יש קידומת:

verifyapikey.{policy_name}

בדוגמה הזו, שם המדיניות של Verify API key הוא verify-api-key. לכן, אתם צריכים להפנות לשם הפרטי של המפתח ששולח את הבקשה על ידי גישה למשתנה verifyapikey.verify-api-key.developer.firstName.

לומדים על Apigee

הפניה לרכיב

אלה האלמנטים והמאפיינים שאפשר להגדיר במדיניות הזו:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

מאפיינים של התג <VerifyAPIKey>

בדוגמה הבאה מוצגים המאפיינים בתג <VerifyAPIKey>:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:

מאפיין תיאור ברירת מחדל נוכחות
name

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

אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.

 לא רלוונטי חובה
continueOnError

מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המדיניות.

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

 FALSE אופציונלי
enabled

מגדירים את המדיניות למצב true כדי לאכוף אותה.

מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

 TRUE אופציונלי
async

המאפיין הזה הוצא משימוש.

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
ברירת מחדל

לא רלוונטי

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

אלמנט <APIKey>

רכיב זה מציין את משתנה הזרימה שמכיל את מפתח ה-API. בדרך כלל, הלקוח שולח את מפתח ה-API כפרמטר של שאילתה, ככותרת HTTP או כפרמטר של טופס. לדוגמה, אם המפתח נשלח בכותרת שנקראת x-apikey, המפתח יימצא במשתנה: request.header.x-apikey

ברירת מחדל לא זמין
נוכחות חובה
סוג String

מאפיינים

בטבלה הבאה מתוארים המאפיינים של הרכיב <APIKey>

מאפיין תיאור ברירת מחדל נוכחות
ref

הפניה למשתנה שמכיל את מפתח ה-API. מותר להשתמש רק במיקום אחד לכל מדיניות.

 לא רלוונטי חובה

דוגמאות

בדוגמאות האלה, המפתח מועבר בפרמטרים ובכותרת שנקראת x-apikey.

כפרמטר של שאילתה:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

ככותרת HTTP:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

כפרמטר של טופס HTTP:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

אלמנט <CacheExpiryInSeconds>

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

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
ברירת מחדל לא רלוונטי

אם לא מציינים את הרכיב הזה, תקופת התפוגה של מפתח ה-API ששמור במטמון היא 180 שניות.
נוכחות אופציונלי
סוג מספר שלם
ערכים אפשריים מספר שלם בין 1 ל-180, כולל. מציינת את זמן התפוגה בשניות.

מאפיינים

בטבלה הבאה מתוארים המאפיינים של הרכיב <CacheExpiryInSeconds>

מאפיין תיאור ברירת מחדל נוכחות
ref

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

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

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

סכימות

משתני Flow

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

המדיניות מאכלסת כמה סוגים שונים של משתני זרימה, כולל:

  • כללי
  • אפליקציה
  • מפתח
  • Analytics
  • מונטיזציה

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

משתני זרימה כלליים

בטבלה הבאה מפורטים משתני הזרימה הכלליים שאוכלסו על ידי המדיניות Verify API Key (אימות מפתח API). לכל המשתנים האלה יש קידומת:

verifyapikey.{policy_name}

לדוגמה: verifyapikey.{policy_name}.client_id

המשתנים הזמינים כוללים:

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

המזהה של המפתח או של האפליקציה של AppGroup ששולחת את הבקשה.
developer.app.name שם האפליקציה של המפתח או AppGroup האפליקציה ששולחת את הבקשה.
developer.id

המזהה של המפתח או של AppGroup שרשומים כבעלים של האפליקציה ששולחת את הבקשה.
developer.{custom_attrib_name} כל המאפיינים המותאמים אישית שנגזרים מפרופיל מפתח האפליקציה.
DisplayName הערך של מאפיין ה-<DisplayName> של המדיניות.
failed הערך מוגדר כ-true כשאימות מפתח ה-API נכשל.
{custom_app_attrib} כל מאפיין בהתאמה אישית שנגזר מפרופיל האפליקציה. מציינים את השם של המאפיין המותאם אישית.
apiproduct.name* שם מוצר ה-API שמשמש לאימות הבקשה.
apiproduct.{custom_attrib_name}* כל מאפיין מותאם אישית שנגזר מפרופיל מוצר ה-API.
apiproduct.developer.quota.limit* מגבלת המכסה שמוגדרת במוצר ה-API, אם יש כזו.
apiproduct.developer.quota.interval* מרווח המכסה שמוגדר במוצר ה-API, אם יש כזה.
apiproduct.developer.quota.timeunit* יחידת הזמן של המכסה שמוגדרת במוצר ה-API, אם יש כזו.
* משתני מוצר API מאוכלסים באופן אוטומטי אם מוצרי ה-API מוגדרים עם סביבה, שרתי proxy ומשאבים תקינים (שנגזרים מ-proxy.pathsuffix). הוראות להגדרת מוצרי API זמינות במאמר ניהול מוצרי API.

משתנים של תהליך באפליקציה

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

verifyapikey.{policy_name}.app.

לדוגמה:

verifyapikey.{policy_name}.app.name

המשתנים הזמינים כוללים:

משתנה תיאור
name שם האפליקציה.
id מזהה האפליקציה.
accessType לא בשימוש ב-Apigee.
callbackUrl כתובת ה-URL של הקריאה החוזרת של האפליקציה. בדרך כלל משמשת רק ל-OAuth.
DisplayName השם המוצג של האפליקציה.
status סטטוס האפליקציה, למשל 'אושרה' או 'בוטלה'.
apiproducts מערך שמכיל את רשימת מוצרי ה-API שמשויכים לאפליקציה.
appFamily כל משפחת אפליקציות שמכילה את האפליקציה, או 'ברירת מחדל'.
appParentStatus הסטטוס של אפליקציית ההורה, למשל 'פעילה' או 'לא פעילה'
appType סוג האפליקציה הוא 'מפתח'.
appParentId המזהה של אפליקציית ההורה.
created_at חותמת התאריך והשעה שבהן נוצרה האפליקציה.
created_by כתובת האימייל של המפתח שיצר את האפליקציה.
last_modified_at חותמת התאריך והשעה שבה האפליקציה עודכנה לאחרונה.
last_modified_by כתובת האימייל של המפתח שעדכן לאחרונה את האפליקציה.
{app_custom_attributes} כל מאפיין מותאם אישית של אפליקציה. מציינים את השם של המאפיין המותאם אישית.

משתני זרימה של קבוצת אפליקציות

המשתנים הבאים של זרימת העבודה, שמכילים מידע על AppGroups, מאוכלסים על ידי המדיניות. המאפיינים האלה של AppGroup מאוכלסים רק אם הערך של verifyapikey.{policy_name}.app.appType הוא AppGroup.

לכל המשתנים האלה יש קידומת:

verifyapikey.{policy_name}.appgroup.

לדוגמה:

verifyapikey.{policy_name}.appgroup.name

המשתנים הזמינים כוללים:

משתנה תיאור
name השם של קבוצת האפליקציות.
id מזהה קבוצת האפליקציות.
displayName השם המוצג של קבוצת האפליקציות.
appOwnerStatus הסטטוס של בעל האפליקציה: active,‏ inactive או login_lock.
created_at חותמת התאריך והשעה שבהן נוצרה קבוצת האפליקציות.
created_by כתובת האימייל של המפתח שיצר את קבוצת האפליקציות.
last_modified_at חותמת התאריך והשעה שבה בוצע השינוי האחרון ב-AppGroup.
last_modified_by כתובת האימייל של המפתח שביצע את השינוי האחרון ב-AppGroup.
{appgroup_custom_attributes} כל מאפיין מותאם אישית של קבוצת אפליקציות. מציינים את השם של המאפיין המותאם אישית.

משתנים בתהליך העבודה של מפתחים

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

verifyapikey.{policy_name}.developer

לדוגמה:

verifyapikey.{policy_name}.developer.id

המשתנים הזמינים כוללים:

משתנה תיאור
id הפונקציה מחזירה {org_name}@@@{developer_id}
userName שם המשתמש של המפתח.
firstName השם הפרטי של המפתח.
lastName שם המשפחה של המפתח.
email כתובת האימייל של המפתח.
status הסטטוס של המפתח: פעיל, לא פעיל או login_lock.
apps מערך של אפליקציות שמשויכות למפתח.
created_at חותמת התאריך והשעה שבהם נוצר חשבון המפתח.
created_by כתובת האימייל של המשתמש שיצר את המפתח.
last_modified_at חותמת התאריך והשעה שבה בוצע השינוי האחרון במפתח.
last_modified_by כתובת האימייל של המשתמש ששינה את פרטי המפתח.
{developer_custom_attributes} כל מאפיין מותאם אישית למפתחים. מציינים את השם של המאפיין המותאם אישית.

משתנים ב-Analytics

המשתנים הבאים מאוכלסים אוטומטית ב-Analytics כשמחילים מדיניות של אימות מפתח API על מפתח API תקין. המשתנים האלה מאוכלסים רק על ידי המדיניות Verify API Key (אימות מפתח API) ומדיניות OAuth.

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

  • apiproduct.name
  • developer.app.name
  • client_id
  • developer.id

משתנים בתהליך המונטיזציה

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

משתנה תיאור
mint.mintng_is_apiproduct_monetized ‫true אם נמצאה תוכנית פעילה לפרסום מחירים.
mint.mintng_rate_plan_id מזהה תוכנית התמחור.
mint.rateplan_end_time_ms תאריך התפוגה של תוכנית התמחור. לדוגמה: 1619433556408
mint.rateplan_start_time_ms שעת ההפעלה של תוכנית התמחור. לדוגמה: 1618433956209

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause
keymanagement.service.consumer_key_missing_api_product_association 400

The application credential is missing an API product association. Please associate the key's application with an API product. Note that this applies for all application types, such as developer apps and AppGroup apps.
keymanagement.service.DeveloperStatusNotActive 401

The developer who created the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive, any Developer Apps created by that developer are deactivated. An admin user with appropriate permissions (such as Organization Administrator) can change a developer's status in the following ways:
keymanagement.service.invalid_client-app_not_approved 401 The Developer App associated with the API key is revoked. A revoked app cannot access any API products and cannot invoke any API managed by Apigee. An org admin can change the status of a Developer App using the Apigee API. See Generate Key Pair or Update Developer App Status.
oauth.v2.FailedToResolveAPIKey 401 The policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (it cannot be resolved).
oauth.v2.InvalidApiKey 401 An API key was received by Apigee, but it is invalid. When Apigee looks up the key in its database, it must exactly match the one that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Controlling access to your APIs by registering apps.
oauth.v2.InvalidApiKeyForGivenResource 401 An API key was received by Apigee, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
SpecifyValueOrRefApiKey The <APIKey> element does not have a value or key specified.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.VK-VerifyAPIKey.failed = true

Example error responses

{
   "fault":{
      "faultstring":"Invalid ApiKey",
      "detail":{
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}
 
{
   "fault":{
      "detail":{
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>