המדיניות של ValidAPIKey

אתם קוראים את מאמרי העזרה של Apigee Edge.
כדאי לעיין במסמכי העזרה בנושא Apigee X. מידע

מה

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

דוגמאות

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

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

בדוגמה הזו, המדיניות מצפה למצוא את מפתח ה-API במשתנה של זרימת נתונים שנקרא request.queryparam.apikey. המשתנה request.queryparam.{name} הוא משתנה רגיל של Edge 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} הוא משתנה רגיל של Edge 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>

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

מידע על Edge

מידע על המדיניות בנושא אימות מפתח API

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

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

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

‫Edge מאכלס באופן אוטומטי קבוצה של משתני זרימה כשמבצעים את מדיניות Verify API Key (אימות מפתח API). מידע נוסף מופיע בקטע משתני זרימה שבהמשך.

הפניה לרכיב

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

<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"/>
</VerifyAPIKey>

מאפיינים של <VerifyAPIKey>

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

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

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

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

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

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

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

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

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

 false אופציונלי
enabled

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

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

 true אופציונלי
async

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

 false הוצא משימוש

&lt;DisplayName&gt; רכיב

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

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

לא רלוונטי

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

אלמנט <APIKey>

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

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

מאפיינים

בטבלה הבאה מתוארים המאפיינים של רכיב <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>

סכימות

משתני תהליך

כשמחילים מדיניות של אימות מפתח API על מפתח API תקין, Edge מאכלס קבוצה של משתני זרימה. המשתנים האלה זמינים למדיניות או לקוד שמופעלים בהמשך התהליך, ולרוב משתמשים בהם כדי לבצע עיבוד בהתאמה אישית על סמך מאפיינים של מפתח ה-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

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

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

משתני זרימה למפתחים

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

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} כל מאפיין מותאם אישית למפתחים. מציינים את השם של המאפיין המותאם אישית.
Company שם החברה, אם יש כזו, שמשויכת למפתח.

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

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

verifyapikey.{policy_name}.company

לדוגמה:

verifyapikey.{policy_name}.company.name

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

משתנה תיאור
name שם החברה.
displayName השם המוצג של החברה.
id

מזהה החברה.
apps מערך שמכיל את רשימת האפליקציות של החברה.
appOwnerStatus
הסטטוס של בעל האפליקציה: פעיל, לא פעיל או login_lock.
created_at חותמת התאריך והשעה שבהם החברה נוצרה.
created_by כתובת האימייל של המשתמש שיצר את החברה.
last_modified_at חותמת הזמן של התאריך והשעה שבהם בוצע השינוי האחרון בחברה.
last_modified_by כתובת האימייל של המשתמש שערך את השינוי האחרון בחברה.
{company_custom_attributes} כל מאפיין מותאם אישית של החברה. מציינים את השם של המאפיין המותאם אישית.

משתנים ב-Analytics

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

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

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

הפניה לשגיאה

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

שגיאות זמן ריצה

השגיאות האלה עשויות להתרחש כשהמדיניות מופעלת.

קוד תקלה סטטוס HTTP סיבה
keymanagement.service.CompanyStatusNotActive 401 לחברה המשויכת לאפליקציית המפתח, שיש לה את מפתח ה-API שבו השתמשת, יש סטטוס לא פעיל. כשסטטוס של חברה מוגדר כלא פעיל, לא ניתן לגשת מפתחים או אפליקציות שמשויכים לאותה חברה. מנהל חשבון ארגוני יכול לשנות את הסטטוס של חברה באמצעות ממשק ה-API לניהול. למידע נוסף, ראו הגדרת הסטטוס של חברה מסוימת.
keymanagement.service.DeveloperStatusNotActive 401

המפתח שיצר את האפליקציה למפתחים שיש לו את מפתח ה-API שבו השתמשת סטטוס לא פעיל. כשהסטטוס של מפתח אפליקציות מוגדר כלא פעיל, כל האפליקציות למפתחים שנוצרו על ידי אותו מפתח יושבתו. משתמש עם הרשאת אדמין עם ההרשאות המתאימות (למשל, אדמין ארגוני) יכול לשנות את הסטטוס של מפתח בדרכים הבאות דרכים:
keymanagement.service.invalid_client-app_not_approved 401 האפליקציה למפתחים שמשויכת למפתח ה-API מבוטלת. אפליקציה שבוטלה לא יכולה לגשת למוצרי API ולא להפעיל אף ממשק API שמנוהל על ידי Apigee Edge. מנהל חשבון ארגוני יכול לשנות את הסטטוס של אפליקציה למפתחים באמצעות ממשק ה-API לניהול. ראו אישור או ביטול של אפליקציית המפתחים.
oauth.v2.FailedToResolveAPIKey 401 המדיניות מצפה למצוא את מפתח ה-API במשתנה שמצוין במדיניות &lt;APIKey&gt; רכיב. השגיאה הזו מתרחשת כשהערך צפוי אינו קיים (לא ניתן לפענח אותו).
oauth.v2.InvalidApiKey 401 Edge התקבל מפתח API, אבל הוא לא תקין. כש-Edge מחפש את המפתח הוא חייב להתאים בדיוק לנתונים שנשלחו בבקשה. אם ה-API פעל קודם צריך לוודא שהמפתח לא נוצר מחדש. אם המפתח נוצר מחדש, יוצגו לך השגיאה הזו מופיעה אם מנסים להשתמש במפתח הישן. מידע נוסף זמין במאמר רישום אפליקציות וניהול API .
oauth.v2.InvalidApiKeyForGivenResource 401 התקבל מפתח API על ידי Edge, והוא תקין. עם זאת, הוא לא תואם מפתח שאושר באפליקציה למפתחים המשויך לשרת ה-proxy ל-API דרך מוצר.

שגיאות פריסה

השגיאות האלו עשויות להתרחש כאשר פורסים שרת proxy שמכיל את המדיניות הזו.

שם השגיאה סיבה
SpecifyValueOrRefApiKey לא צוינו ערך או מפתח ברכיב <APIKey>.

משתני כשל

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

משתנים איפה דוגמה
fault.name="fault_name" fault_name הוא שם השגיאה, כפי שמצוין בטבלה שגיאות זמן ריצה שלמעלה. שם השגיאה הוא החלק האחרון בקוד השגיאה. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לבעיה. oauthV2.VK-VerifyAPIKey.failed = true

דוגמאות לתשובות שגיאה

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

דוגמה לכלל שגוי

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

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