Skip to main content
השתמשו בפרטי הזיהוי של לקוח OAuth כאשר האינטגרציה בצד השרת שלכם זקוקה לאסימוני גישה קצרי טווח, או כאשר מדיניות האבטחה שלכם דורשת זאת. כל לקוח שייך לחשבון שירות אחד ולארגון אחד. השימוש ב-OAuth הוא אופציונלי: מפתח API בעל היקף מוגבל מספיק עבור אינטגרציה פרטית בצד השרת שיכולה לאחסן ולהחליף מפתח באופן מאובטח. ראו אימות כדי לבחור בין שתי השיטות ולהבין כיצד חשבונות שירות משתלבים.
יש להפעיל גישת OAuth עבור הארגון שלכם. תהליך ההגדרה שלכם מספק את נקודת הקצה האזורית של האסימונים, את המנפיק (issuer), את קהל היעד (audience) ואת שיטת האימות של הלקוח. אם אתם זקוקים להגדרות אלה או שאין לכם גישה לניהול לקוחות, פנו לתמיכה של Living Security.
מענק פרטי הזיהוי של הלקוח (client credentials grant) מייצג את חשבון השירות שלכם. הוא אינו מחבר אדם למערכת ואינו מבקש מלקוח לאשר יישום. הרשאה מואצלת באמצעות דפדפן היא יכולת OAuth נפרדת ואינה מוצעת בפעולות אלה.

לפני שמתחילים

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

יצירת לקוח

POST /v1/oauth_clients דורש service_account_id, רשימה לא ריקה של scopes מפורשים, ו-Idempotency-Key. תווים כלליים (wildcards) אינם מתקבלים. לקוח תומך בעד 100 היקפים (scopes), באורך כולל של עד 4,096 תווים. לכל חשבון שירות יכולים להיות לכל היותר 20 לקוחות או פעולות יצירה/ניקוי שטרם נפתרו. ביטול גישה שולל באופן מיידי את הגישה ל-API. לקוח או יצירה לא ודאית אצל הספק ממשיכים להיספר במסגרת המגבלה עד שהניקוי מרחוק יאושר. הזמנה שננטשה או יצירה שהוכח כי נכשלה לפני תחילת העבודה אצל הספק יכולות לשחרר את המקום שלהן בבטחה. מפתח הניסיון החוזר שלהן עדיין שייך לניסיון המקורי; שחזרו את אישור הקבלה שלו לפני שתחליטו אם ליצור לקוח חלופי. בחרו מפתח ניסיון חוזר אחד לניסיון יצירה זה ושמרו אותו לפני שליחת הבקשה. השתמשו ב-1 עד 255 תווי ASCII גלויים, ללא רווחים. השתמשו בו שוב עם אותו חשבון, אותם היקפים, אותו גורם ניהול, אותו אזור ואותה גרסת API לאחר אובדן תגובה. החלפת פרטי הזיהוי לניהול תחת אותו חשבון שירות אינה יוצרת זהות ניסיון חוזר חדשה. התקינו את חבילת requests של Python. טענו את ערכי הסביבה הבאים באמצעות ניהול הסודות וההגדרות הרגיל שלכם:
Python
הדוגמה שולחת בקשה אחת ושומרת את התוצאה בזיכרון. הוסיפו את פעולת הכתיבה של מנהל הסודות שלכם בנקודה המסומנת לפני ההרצה בסביבת ייצור. הדוגמה דורשת במכוון קבלת החלטה לאחר תוצאה לא ודאית, במקום ליצור בשקט לקוח נוסף. גם חריגות רשת מחייבות את שלבי ההתאוששות שלהלן. תגובות היצירה ואישור הקבלה משתמשות ב-201 וכוללות משאב oauth_client עם id, service_account_id, client_id, scopes, status, created_at ו- client_secret. התגובות מסומנות ב-Cache-Control: no-store.
  • id מזהה את משאב הפלטפורמה. שמרו אותו לצורך אחזור וביטול גישה.
  • client_id מזהה את הלקוח במהלך החלפת האסימונים. הוא אינו מזהה משאב הפלטפורמה. הוא יכול להיות null בזמן שהיצירה בהמתנה.
  • client_secret מוחזר רק לבקשה שמשלימה את היצירה. כל בקשת יצירה חוזרת מחזירה null, כולל ניסיון חוזר לאחר אובדן תגובת הצלחה. אחזור לעולם אינו מחזיר סוד.

התאוששות מתגובה שאבדה או שהופסקה

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

בדיקה וביטול גישה

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

החלפה ללא אובדן גישה

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