אימות והרשאה

בקטע הזה מוסבר על המושגים של אימות והרשאה בשילוב עם Fleet Engine.

אתם יכולים להגדיר את היכולות שמסופקות על ידי Last Mile Fleet Solution דרך מסוף Google Cloud. בערכות ה-SDK של Fleet Engine נדרש שימוש באסימוני JWT (JSON Web Tokens) שנחתמו על ידי חשבון שירות מתאים.

סקירה

הקצוות העורפיים של הלקוח לאימות ולהרשאה מול Fleet Engine צריכים להשתמש במנגנונים רגילים של Application Default Credentials.

Fleet Engine גם מקבל קריאות שמגיעות מסביבות עם רמת אמינות נמוכה, כמו סמארטפונים ודפדפנים. כדי להגן על מפתחות סודיים של חשבונות שירות שמתאימים רק לסביבות מהימנות, הקצה העורפי של הלקוחות אמור ליצור אסימוני JWT חתומים בפורמט JSON עם הצהרות נוספות שספציפיות ל-Fleet Engine, ואז אפשר להנפיק אותן לסביבות לא אמינות כמו טלפונים ניידים.

עקרונות לעיצוב אימות

תהליך האימות ב-Fleet Engine כולל את עקרונות התכנון הבאים.

  • תפקידי IAM מגדירים קבוצה של הרשאות למשאבים שמורשים לחשבון משתמש. לדוגמה, לתפקידים של אדמין יש הרשאה לעשות כל דבר עם Application Default Credentials. לעומת זאת, התפקיד 'נהג לא מהימן*' יכול לעדכן רק את מיקום הרכב ומוגבל לשימוש באסימוני JWT לאימות ולהרשאה.

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

  • כשקוד פועל בסביבה עם רמת אמון נמוכה, הוא צריך לקרוא קודם לקוד שרץ בסביבה מהימנה כדי להנפיק JWT.

  • Fleet Engine מבצע את בדיקות האבטחה הבאות בקריאות ל-API של משאב:

    1. לחשבון המשתמש ששולח את הקריאה יש את ההרשאות המתאימות (באמצעות הקצאת התפקיד) לפעולה במשאב.

    2. לתפקידים שאינם אדמין, הצהרות ה-JWT שמועברות בבקשה מספקות את ההרשאה הנדרשת למשאב.

תהליך האימות

תרשים הרצף הבא מדגים את הפרטים האלה של תהליך האימות.

  1. האדמין של הצי יוצר חשבונות שירות.

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

  3. האדמין של כלל המכשירים בארגון מגדיר את הקצה העורפי שלו עם חשבונות השירות ו-Application Default Credentials

  4. אפליקציית הלקוח מבקשת JWT מהקצה העורפי של הלקוח. מגיש הבקשה יכול להיות אפליקציית Drive, אפליקציית הצרכן או אפליקציית מעקב.

  5. הקצה העורפי של הלקוח חותם ומנפיק JWT עבור חשבון השירות הרלוונטי. אפליקציית הלקוח מקבלת את ה-JWT.

  6. אפליקציית הלקוח משתמשת ב-JWT כדי להתחבר ל-Fleet Engine כדי לקרוא או לשנות נתונים, בהתאם לתפקידי IAM שהוקצו לה בשלב ההגדרה.

תרשים רצף אימות

הגדרת פרויקט בענן

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

כדי ליצור את הפרויקט ב-Google Cloud:

  1. יוצרים פרויקט ב-Google Cloud באמצעות מסוף Google Cloud.
  2. באמצעות מרכז הבקרה של ממשקי ה-API והשירותים, מפעילים את Local Rides and Deliveries API.

חשבונות שירות ותפקידי IAM

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

ל-Last Mile Fleet Solution משתמשים בתפקידים הבאים:

תפקידתיאור
משתמש נהג מהימן למסירה ב-Fleet Engine

roles/fleetengine.deliveryTrustedDriver		 התפקיד הזה מאפשר ליצור ולעדכן רכבים ומשימות למשלוח, כולל עדכון המיקום והסטטוס של המשימה למשלוח רכבים למשלוח. אסימונים שנוצרו על ידי חשבון שירות עם התפקיד הזה משמשים בדרך כלל מהמכשירים הניידים של נהג ההעברה או מהשרתים העורפי שלך.
משתמש לא מהימן של נהג/ת לא מהימן למסירה ב-Fleet Engine

roles/fleetengine.deliveryUntrustedDriver		 התפקיד הזה מאפשר לעדכן את מיקום הרכב למשלוח. אסימונים שנוצרו על ידי חשבון שירות עם התפקיד הזה משמשים בדרך כלל מהמכשירים הניידים של נהג/ת המסירה.
משתמש צרכן למשלוחי Fleet Engine

roles/fleetengine.deliveryConsumer		 התפקיד הזה מאפשר לחפש משימות באמצעות מזהה לצורכי מעקב ולקרוא את פרטי המשימה, אבל לא לעדכן אותם. אסימונים שנוצרו על ידי חשבון שירות עם התפקיד הזה משמשים בדרך כלל מדפדפן האינטרנט של צרכן ההעברה.
אדמין לאספקה של מנועי Fleet

roles/fleetengine.deliveryAdmin		 התפקיד הזה מאפשר לקרוא ולכתוב למשאבי ההעברה. חשבונות משתמשים עם התפקיד הזה לא צריכים להשתמש באסימוני JWT, ובמקום זאת הם צריכים להשתמש ב-Application Default Credentials המערכת מתעלמת מהצהרות JWT מותאמות אישית. התפקיד הזה צריך להיות מוגבל לסביבות מהימנות (הקצה העורפי של הלקוח).
סופר-משתמש ב-Fleet Engine Delivery **(הוצא משימוש)**

roles/fleetengine.deliverySuperUser		 התפקיד הזה מאפשר לכל ממשקי ה-API של משימות ורכבי משלוחים. אסימונים שנוצרו על ידי חשבון שירות עם התפקיד הזה משמשים בדרך כלל מהשרתים בקצה העורפי.
בעל הרשאת קריאה של כלל המכשירים לאספקה של Fleet Engine

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

ארגונים שיספקו לנהגים שלהם מכשירים שמנוהלים על ידי צוות ה-IT הארגוני, יכולים לנצל את הגמישות שהתפקיד 'משתמש נהג מהימן של Fleet Engine' יכול לבחור ולשלב באפליקציה לנייד חלק מהאינטראקציות של Fleet Engine או את כולן.

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

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

יצירת חשבון שירות

אפשר ליצור חשבון שירות באמצעות הכרטיסייה IAM & Admin > Service Accounts במסוף Google Cloud. בוחרים באפשרות Fleet Engine מהרשימה הנפתחת Role ומקצים אחד מהתפקידים לחשבון השירות. מומלץ לציין את החשבון שמשויך לכל תפקיד. לדוגמה, נותנים לחשבון השירות שם בעל משמעות.

מטעמי נוחות, אם אתם צריכים להנפיק אסימוני JWT ללקוחות לא מהימנים, הוספת משתמשים לתפקיד 'יצירת אסימונים בחשבון שירות' מאפשרת להם להנפיק אסימונים באמצעות כלי שורת הפקודה של gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

כאשר my-user@example.com הוא האימייל שמשמש לאימות מול gcloud (gcloud auth list --format='value(account)').

ספריית אימות של Fleet Engine

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

הספרייה מספקת את היתרונות הבאים:

  • מפשט את תהליך היצירה של אסימוני Fleet Engine.
  • מספקת מנגנוני חתימת אסימונים שאינם שימוש בקובצי פרטי כניסה (כמו התחזות לחשבון שירות).

יצירת אסימון רשת מבוסס JSON (JWT) להרשאה

אם לא משתמשים ב-Fleet Engine Auth, צריך ליצור את אסימוני ה-JWT ישירות בתוך ה-codebase. כדי לעשות את זה, צריכה להיות לכם הבנה עמוקה לגבי אסימוני JWT ואיך הם קשורים ל-Fleet Engine. לכן אנחנו ממליצים מאוד להשתמש ב-Fleet Engine Auth.

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

מקטע כותרת JWT מכיל את השדות הבאים:

שדהתיאור
alg האלגוריתם שבו צריך להשתמש. 'RS256'.
typ סוג האסימון. JWT.
kid מזהה המפתח הפרטי של חשבון השירות שלכם. אפשר למצוא את הערך הזה בשדה 'private_key_id' בקובץ ה-JSON של חשבון השירות. צריך להקפיד להשתמש במפתח מחשבון שירות עם רמת ההרשאות המתאימה.

קטע של הצהרות JWT מכיל את השדות הבאים:

שדהתיאור
iss כתובת האימייל של חשבון השירות שלכם.
sub כתובת האימייל של חשבון השירות שלכם.
aud SERVICE_NAME של חשבון השירות שלך, במקרה הזה https://fleetengine.googleapis.com/
iat חותמת הזמן שבה נוצר האסימון, צוינה בשניות שחלפו מ-1 בינואר 1970 ב-00:00:00 (שעון UTC). ממתינים 10 דקות להטיה. אם חותמת הזמן רחוקה מדי בעבר או בעתיד, השרת עשוי לדווח על שגיאה.
exp חותמת הזמן של תפוגת האסימון, צוינה בשניות שחלפו מ-1 בינואר 1970 ב-00:00:00 (שעון UTC). הבקשה תיכשל אם המועד של חותמת הזמן יהיה של יותר משעה אחת בעתיד.
authorization בהתאם לתרחיש לדוגמה, הוא עשוי להכיל את הערכים 'deliveryvehicleid', 'trackingid', 'taskid' או 'taskid'.

הטמעת אסימון JWT היא חתימה עליו. הוראות ודוגמאות קוד ליצירה ולחתימה של ה-JWT זמינות במאמר הרשאה לחשבון שירות ללא OAuth. לאחר מכן אפשר לצרף אסימון מוטמע לקריאות ל-gRPC או לשיטות אחרות שמשמשות לגישה ל-Fleet Engine.

הצהרות JWT

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

הפתרון של Last Mile Fleet Solution משתמש בהצהרות הפרטיות הבאות:

  • deliveryvehicleid - משמש בקריאה לממשקי API של כלי הרכב למשלוח.
  • taskid – לשימוש במהלך קריאה לממשקי API לכל משימה.
  • taskids - לשימוש במהלך התקשרות אל BatchCreateTasksAPI. ההצהרה הזו צריכה להיות בפורמט של מערך, והמערך צריך להכיל את כל מזהי המשימות שדרושים כדי להשלים את הבקשה. אל תכללו הצהרות delivervehicleid, trackingid או taskid.
  • trackingid - לשימוש כשמבצעים קריאה לGetTaskTrackingInfoAPI. ההצהרה חייבת להתאים למזהה לצורכי מעקב שבבקשה. לא לכלול הצהרות delivervehicleid, taskid או taskids.

האסימון צריך גם להכיל את ההצהרה המתאימה כשמפעילים ממשקי API משרת הקצה העורפי, אבל אפשר להשתמש בערך המיוחד של כוכבית ("*") להצהרות deliveryvehicleid, taskid ו-trackingid. אפשר להשתמש בכוכבית ("*") גם בהצהרה taskids, אבל היא חייבת להיות הרכיב היחיד במערך.

אם רוצים ליצור קובץ JSON ולחתום עליו ישירות כנושא אסימונים, במקום להשתמש באסימוני גישה מסוג OAuth 2.0, אפשר לקרוא את ההוראות להרשאה לחשבון שירות ללא OAuth בחומרי העזר של מפתחי זהויות.

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

בדוגמה הבאה מוצג אסימון לפעולה לכל משימה משרת הקצה העורפי:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

בדוגמה הבאה מופיע אסימון לפעולה של יצירת משימות באצווה משרת הקצה העורפי:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

בדוגמה הבאה מוצג אסימון לפעולה של כלי הרכב לשרת העורפי שלכם:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }

בדוגמה הבאה מוצג אסימון ללקוחות של משתמשי קצה:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

בדוגמה הבאה מוצג אסימון לאפליקציית הנהגים שלכם:

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }
  • בשדה kid בכותרת, מציינים את מזהה המפתח הפרטי של חשבון השירות. הערך הזה מופיע בשדה private_key_id בקובץ ה-JSON של חשבון השירות.
  • בשדות iss ו-sub, צריך לציין את כתובת האימייל של חשבון השירות. הערך הזה מופיע בשדה client_email בקובץ ה-JSON של חשבון השירות.
  • בשדה aud מציינים https://SERVICE_NAME/.
  • בשדה iat מציינים את חותמת הזמן של מועד יצירת האסימון, בשניות שחלפו מאז 00:00:00 (שעון UTC), 1 בינואר 1970. ממתינים 10 דקות להטיה. אם חותמת הזמן רחוקה מדי בעבר או בעתיד, השרת עשוי לדווח על שגיאה.
  • בשדה exp מציינים את חותמת הזמן של תפוגת האסימון, בשניות מ-00:00:00 UTC, 1 בינואר 1970. הערך המומלץ הוא iat + 3600.

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