📘 תיעוד 14

כתובות URL של תבניות אסימוני API

השתמשו בכתובות URL של תבניות כדי ליצור אסימוני API של Cloudflare עם הרשאות שהוגדרו מראש. כתובות URL של תבניות מאפשרות לשתף דרישות אסימון עם משתמשים בלי לבחור הרשאות ידנית בלוח הבקרה.

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

Cloudflare תומכת בכתובות URL של תבניות גם עבור אסימוני API של משתמש וגם עבור אסימוני API של חשבון. למידע נוסף על ההבדל בין סוגי האסימונים האלה, עיינו באסימוני API של חשבון.

הערה

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

#פורמט כתובת URL לאסימון משתמש

כתובות URL של תבניות לאסימון משתמש פותחות את טופס יצירת האסימון ברמת פרופיל המשתמש (/profile/api-tokens). אסימונים שנוצרים כך בבעלות המשתמש.

מבנה כתובת ה-URL הבסיסי של התבנית הוא:

https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_PERMISSIONS]&accountId=*&zoneId=all&name=[TOKEN_NAME]

#רכיבי כתובת ה-URL

#פורמט כתובת URL לאסימון חשבון

כתובות URL של תבניות לאסימון חשבון פותחות את טופס יצירת האסימון ברמת החשבון. אסימונים שנוצרים כך בבעלות החשבון (אסימוני service principal) ואינם קשורים למשתמש מסוים. עיינו באסימוני API של חשבון לדרישות תפקיד והרשאה.

מבנה כתובת ה-URL הבסיסי של התבנית הוא:

https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_PERMISSIONS]&name=[TOKEN_NAME]

קטע :account הוא מציין מקום. כשמשתמש פותח את כתובת ה-URL, לוח הבקרה מבקש ממנו לבחור חשבון אם יש לו גישה ליותר מחשבון אחד.

#רכיבי כתובת ה-URL

הערה

כתובות URL של תבניות לאסימון חשבון אינן משתמשות בפרמטרים accountId או zoneId. היקף המשאבים לאסימוני חשבון מוגדר במהלך יצירת האסימון בלוח הבקרה.

#פורמט הרשאה

גם כתובות URL של תבניות לאסימון משתמש וגם כתובות URL של תבניות לאסימון חשבון משתמשות באותו קידוד הרשאות: מערך JSON עם המבנה הבא.

[{ "key": "permission_name", "type": "read|edit|revoke|run|purge" }]

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

עבור כתובות URL של אסימון חשבון, כל key יכול להיות מפתח הרשאה קצר (לדוגמה, dns) או מזהה קבוצת הרשאות. השימוש במזהה קבוצת ההרשאות הוא האפשרות האמינה ביותר, כי הוא ממופה בדיוק לקבוצה אחת. עיינו בשימוש במזהי קבוצות הרשאות.

עבור כתובות URL של אסימון משתמש, כל key חייב להיות מפתח הרשאה קצר שתואם בדיוק ל-name של קבוצה, וה-type חייב להיות edit (ולא write), read, revoke, run או purge. מזהי קבוצות הרשאות אינם נתמכים, וכל רשומה שאינה תואמת מושמטת בשקט.

#סוגי הרשאות

#שימוש במזהי קבוצות הרשאות

הערה

מזהי קבוצות הרשאות נתמכים רק בכתובות URL של אסימון חשבון. כתובות URL של אסימון משתמש חייבות להשתמש במפתחות קצרים.

כדי לפנות לכל קבוצת הרשאות בכתובת URL של אסימון חשבון, כולל קבוצות שאין להן מפתח קצר בהפניית ההרשאות, השתמשו במזהה קבוצת ההרשאות שלה בתור key:

[{ "key": "82e64a83756745bbbb1c9c2701bf816b", "type": "edit" }]

מזהי קבוצות הרשאות הם המזהה היציב והקנוני של קבוצת הרשאות. אלה אותם מזהים שנקודת הקצה Create token וספק Terraform של Cloudflare מקבלים, כך שכתובת URL של תבנית יכולה לבחור מראש כל קבוצת הרשאות לפי מזהה. מכיוון שהמזהה מציין קבוצה מסוימת אחת, שדה type מתעלם כשמעבירים מזהה.

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

[
	{ "key": "e086da7e2179491d91ee5f35b3ca210a", "type": "edit" },
	{ "key": "7cf72faf220841aabcfdfab81c43c4f6", "type": "read" }
]

מכיוון שכתובות URL של אסימון חשבון יוצרות אסימונים בבעלות החשבון, חפשו את מזהי קבוצות ההרשאות שלהן באמצעות נקודת הקצה List permission groups בהיקף החשבון. הבקשה זקוקה לאסימון עם הרשאת החשבון API Tokens Read:

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/tokens/permission_groups" \
	--header "Authorization: Bearer <API_TOKEN>"

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

curl "https://api.cloudflare.com/client/v4/user/tokens/permission_groups" \
	--header "Authorization: Bearer <API_TOKEN>"

כל תוצאה כוללת את id ואת name של קבוצת ההרשאות. גם הפניית הרשאות אסימון API מפרטת את המזהים האלה.

#יצירת תבניות מותאמות

#1. זיהוי ההרשאות הנדרשות

פרטו את ההרשאות שמקרה השימוש שלכם צריך. עיינו בטבלת הפניית ההרשאות.

#2. יצירת ה-JSON של ההרשאות

עצבו את ההרשאות כמערך JSON:

[
	{ "key": "dns", "type": "edit" },
	{ "key": "analytics", "type": "read" }
]

#3. קידוד ה-JSON ל-URL

השתמשו במקודד URL כדי להמיר את מחרוזת ה-JSON:

%5B%7B%22key%22%3A%22dns%22%2C%22type%22%3A%22edit%22%7D%2C%7B%22key%22%3A%22analytics%22%2C%22type%22%3A%22read%22%7D%5D

#4. בניית כתובת ה-URL המלאה

עבור אסימון משתמש, שלבו את כל הרכיבים לכתובת ה-URL הסופית של התבנית:

https://dash.cloudflare.com/profile/api-tokens?permissionGroupKeys=[ENCODED_JSON]&accountId=*&zoneId=all&name=Custom%20Token

עבור אסימון חשבון, השתמשו במקום זאת בנתיב ברמת החשבון:

https://dash.cloudflare.com/?to=/:account/api-tokens&permissionGroupKeys=[ENCODED_JSON]&name=Custom%20Token

#הפניית הרשאות

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

#הרשאות חשבון

#הרשאות אזור

#הרשאות Access

#תבניות הרשאה נפוצות

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

#ניהול DNS

צרו אסימונים לניהול רשומות DNS.

#אסימון משתמש

#אסימון חשבון

#פיתוח Workers

צרו אסימונים עבור Workers, אחסון KV ושירותים קשורים.

#אסימון משתמש

#אסימון חשבון

#אנליטיקה וניטור

צרו אסימונים לגישה לאנליטיקה וליומנים.

#אסימון משתמש

#אסימון חשבון

#ניהול Zero Trust

צרו אסימונים לניהול Cloudflare Zero Trust.

#אסימון משתמש

#אסימון חשבון

#שיטות עבודה מומלצות

עקבו אחר ההנחיות האלה בעת יצירה ושיתוף של כתובות URL של תבניות.

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

#פתרון בעיות

עיינו ברשימת הבעיות הנפוצות והפתרונות.

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

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

בנוסף, עיינו ברשימת הבדיקה לפני שיתוף כתובת URL של תבנית.

• כל מפתחות ההרשאה נכונים
• תחביר ה-JSON תקין
• קידוד ה-URL תקין
• שם האסימון תיאורי
• ההרשאות עוקבות אחר עקרון ההרשאה המזערית

#משאבים קשורים

• הרשאות אסימון API
• יצירת אסימוני API
• אסימוני API של חשבון
• אימות API