המדיניות של ValidAPIKey

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X.
מידע

מה

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

טעימות

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

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

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

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

ב-cURL הבא מוצג האופן שבו מעבירים את מפתח ה-API בכותרת:

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

מפתח במשתנה

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

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

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

כל המשתנים האלה מופיעים לפני:

verifyapikey.{policy_name}

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

למידת Edge


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

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

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

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

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

רכיב <DisplayName>

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

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

לא רלוונטי

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

נוכחות אופציונלי
תיאור מחרוזת

רכיב <APIKey>

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

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

מאפיינים

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

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

הפניה למשתנה שמכיל את מפתח ה-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.

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

  • כללי
  • אפליקציה
  • המפַתח
  • חברה
  • ניתוח נתונים

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

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

בטבלה הבאה מפורטים משתני הזרימה הכלליים שאוכלסו במדיניות 'אימות מפתח 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 לקריאה חוזרת (callback) של האפליקציה. בדרך כלל משמשת רק ל-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 חוקי. המשתנים האלה מאוכלסים רק במדיניות OAuth 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. מנהלי חשבון ארגוני יכולים לשנות את הסטטוס של אפליקציה למפתחים באמצעות ה-Management API. למידע נוסף, ראו אישור או ביטול של אפליקציה למפתחים.
oauth.v2.FailedToResolveAPIKey 401 המדיניות מצפה למצוא את מפתח ה-API במשתנה שצוין ברכיב <APIKey> של המדיניות. השגיאה הזו מתרחשת כשהמשתנה הצפוי לא קיים (לא ניתן לפתור אותו).
oauth.v2.InvalidApiKey 401 מפתח API התקבל על ידי Edge אבל הוא לא תקין. כש-Edge מחפש את המפתח במסד הנתונים שלו, הוא חייב להיות זהה בדיוק לערך שנשלח בבקשה. אם ה-API פעל בעבר, עליך לוודא שהמפתח לא נוצר מחדש. אם המפתח נוצר מחדש, תופיע השגיאה הזו אם תנסו להשתמש במפתח הישן. מידע נוסף מופיע במאמר רישום אפליקציות וניהול של מפתחות API.
oauth.v2.InvalidApiKeyForGivenResource 401 מפתח API התקבל על ידי Edge והוא תקין. עם זאת, הוא לא תואם למפתח שאושר באפליקציה למפתחים, שמשויך לשרת ה-API של ה-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>

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