שילוב הקצה הקדמי של האפליקציה

בדף הזה מוסבר איך לשלב את הקצה הקדמי של האפליקציה עם Cloud Marketplace כדי להעניק ללקוחות חוויה חלקה כשהם עוברים מ-Cloud Marketplace למוצר שלכם.

ברמה גבוהה, אתם צריכים לספק כתובת URL להרשמה כדי לטפל ביצירת חשבונות משתמשים, שמנוהלים במסוף האינטרנט שלכם. צריך גם לספק כתובת URL שדרכה המשתמשים יכולים להתחבר. אפשר גם לשלב כניסה יחידה (SSO).

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

כדי לגשת לכל המידע שדרוש לשילוב הקצה הקדמי של האפליקציה עם Cloud Marketplace ממקום אחד, אפשר להשתמש בקטע Frontend integration (שילוב הקצה הקדמי) ב-Producer Portal.

הקישור הישיר ל-Producer Portal הוא:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

כדי לגשת לקטע Frontend integration:

  1. ברשימת המוצרים, לוחצים על שם המוצר.

  2. בדף סקירה כללית של המוצר, עוברים לקטע שילוב טכני ולוחצים על שילוב חזיתי.

הוספת כתובת URL להרשמה

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

אחרי שיוצרים את דף ההרשמה, מוסיפים אותו לפורטל היוצרים:

  1. ברשימת המוצרים, לוחצים על שם המוצר.

  2. בדף סקירה כללית של המוצר, עוברים אל הקטע שילוב טכני ולוחצים על שילוב קצה קדמי.

  3. מזינים את כתובת ה-URL של דף ההרשמה בשדה כתובת ה-URL של ההרשמה.

אימות פרטי ההרשמה של המשתמש

אם למשתמש עדיין אין חשבון במערכת שלכם, הוא צריך ללחוץ על הלחצן הרשמה ל-YOUR_COMPANY_NAME ב-Cloud Marketplace. כשלוחצים על הלחצן, Google Cloud נשלחת בקשת HTTP POST לדף ההרשמה, עם טוקן אינטרנט מסוג JSON‏ (JWT) בפרמטר x-gcp-marketplace-token. אסימון ה-JWT מכיל את מזהה חשבון הרכש של המשתמש, שמזהה אותו כמשתמש Google Cloud , ומזהה שעבר טשטוש, שמייצג את מזהה חשבון Google שלו. כדי לקשר את חשבון Google של המשתמש לחשבון שלו במערכת שלכם, אתם צריכים להשתמש גם במזהה חשבון הרכש וגם במזהה המוסתר.

אחרי אימות ה-JWT, דף ההרשמה צריך לשלוח בקשה לאישור החשבון אל Partner Procurement API, כפי שמתואר בשלבים לשילוב עם ה-Backend.

מידע מפורט על מטען ייעודי (payload) של ה-JWT ועל אופן האימות שלו מופיע בקטע אימות ה-JWT בהמשך.

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

הוספת כתובת ה-URL של הכניסה

חובה לציין את כתובת ה-URL של דף הכניסה לאפליקציה.

כדי להזין את כתובת ה-URL של דף ההתחברות לאפליקציה בפורטל של Producer:

  1. ברשימת המוצרים, לוחצים על שם המוצר.

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

  3. מזינים את כתובת ה-URL של דף הכניסה של האפליקציה בשדה כתובת ה-URL של הכניסה.

(אופציונלי) הפעלת כניסה יחידה (SSO) ללקוחות

כדי להפעיל SSO ב-Producer Portal:

  1. ברשימת המוצרים, לוחצים על שם המוצר.

    1. בדף סקירה כללית של המוצר, עוברים אל הקטע שילוב טכני ולוחצים על שילוב קצה קדמי.

    2. בקטע הפעלת כניסה באמצעות SSO?, בוחרים באפשרות כן.

אימות פרטי הכניסה של הלקוחות באמצעות SSO

כשלקוחות מתחברים לאפליקציה שלכם באמצעות SSO, Google Cloud שולחת בקשהHTTP POST לדף הכניסה של האפליקציה, עם טוקן אינטרנט בפורמט JSON‏ (JWT) באותו פורמט של ה-JWT שנשלח כשמשתמשים נרשמים לאפליקציה בפעם הראשונה.

מידע מפורט על מטען ייעודי (payload) של ה-JWT ועל אופן האימות שלו מופיע בקטע אימות ה-JWT בהמשך.

אימות ה-JWT

חלק מהתהליכים, כמו הרשמה של לקוח חדש או התחברות של לקוח באמצעות כניסה יחידה (SSO), כוללים שליחה של בקשת HTTP POST עם אסימון JWT (‏JSON Web Token) שאולי תצטרכו לאמת.

בטבלה הבאה מפורטים:

  • אירועים שכוללים שליחת בקשת HTTP עם JWT.
  • סוג בקשת ה-HTTP שמעורבת.
  • האם צריך לאמת את ה-JWT.
אירוע סוג בקשת HTTP נדרש אימות JWT

רישום לקוח חדש

POST

כן

התחברות של לקוח, ללא SSO

GET

לא

התחברות של לקוחות באמצעות SSO

POST

כן

המטען הייעודי (payload) של ה-JWT

המטען הייעודי (payload) של ה-JWT הוא בפורמט הבא:

Header

{
  "alg": "RS256",
  "kid": "KEY_ID"
}

כאשר:

  • השעה בalg תמיד RS256.
  • ‫kid מציין את מזהה המפתח ששימש לאבטחת ה-JWT. משתמשים במזהה המפתח כדי לחפש את המפתח מאובייקט ה-JSON במאפיין iss במטען הייעודי (payload).

מטען ייעודי (payload)

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID
  }
}

כאשר:

  • ‫sub הוא מזהה חשבון Google של המשתמש. צריך להשתמש במזהה הזה כדי לקשר את חשבון Google של המשתמש לחשבון שלו במערכת שלכם.
  • ‫iss הוא המזהה של השולח של ה-JWT. כתובת ה-URL בiss טוענת קישורים למפתח ציבורי של Google.
  • ‫exp מציין את הזמן שבו יפוג תוקף האסימון, והוא מוגדר ל-5 דקות אחרי שליחת האסימון.
  • ‫aud הוא הדומיין שבו מתארח המוצר, למשל example.com.

  • ‫roles הוא מערך של מחרוזות שמייצגות את התפקידים של המשתמש. יכול להיות:

    • ‫account_admin, שמציין שהמשתמש הוא Billing Account Administrator (אדמין של הזמנה) בחשבון לחיוב שדרכו נרכש המוצר, או

    • ‫project_editor, שמציין שהמשתמש הוא בעל הרשאת עריכה (מנהל הרשאות) בפרויקט שמשויך לחשבון החיוב הזה, אבל לא אדמין לחיוב.

  • ‫user_identity הוא הפניה המוסתרת של המשתמש, שאפשר להשתמש בה כ-login_hint כדי להתחיל תהליך הסכמה של OAuth 2.0. פרטים נוספים זמינים במאמר בנושא הפעלת כניסה באמצעות חשבון Google עם login_hint.

מטען ייעודי (payload) לכמה הזמנות של אותו מוצר

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

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID,
    "orders": [ORDER_ID1, ORDER_ID2]
  }
}

כאשר:

  • ‫ORDER_ID היא רשימה של מזהי הזמנות ייחודיים לכל מזהה זכאות, שמציינים את המבצעים השונים על אותו מוצר. השדה הזה זמין רק אם מופעלת האפשרות לבצע כמה הזמנות של אותו מוצר.

מידע נוסף על הפעלת הזמנות מרובות של אותו מוצר זמין במאמר הפעלת הזמנות מרובות של אותו מוצר.

אימות המטען הייעודי (payload)

כשמקבלים את ה-JWT, צריך לאמת את הפרטים הבאים:

  1. מוודאים שהחתימה של ה-JWT משתמשת במפתח ציבורי מ-Google.

  2. בודקים את הצהרת exp כדי לוודא שתוקף ה-JWT לא פג.

  3. מוודאים שaud הדומיין שצוין הוא הדומיין הנכון של המוצר.

  4. מוודאים שהתביעה iss היא https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com.

  5. מוודאים שהשדה sub לא ריק.

התחלת כניסה באמצעות חשבון Google עם login_hint

אם אתם רוצים שהמשתמשים יעברו תהליך מתן הסכמה ב-OAuth 2.0 באתר שלכם, אתם יכולים להשתמש בפרטי הזהות ממטען הייעודי (payload) כדי להפעיל את התהליך הזה בחשבון Google שבו הם השתמשו ב-Google Cloud לפני ההפניה האוטומטית. כדי לעשות את זה, צריך לספק את user_identity שמופיע ב-JWT בתור login_hint. מידע נוסף זמין בתיעוד של Google OAuth 2.0.

אחרי שהמשתמש משלים את הרשאה באמצעות OAuth 2.0 באתר שלכם, אתם צריכים לוודא שהוא המשתמש שציפיתם שישלים את תהליך OAuth. כדי לעשות את זה, משתמשים באסימון הגישה מסוג OAuth 2.0 כדי לקרוא ל-Google UserInfo API ולאחזר את פרטי המשתמש הבסיסיים. הפונקציה מחזירה מזהה שאמור להיות זהה לערך של השדה user_identity מ-JWT.

יצירת חשבונות שירות עבור הלקוחות

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

  • הקצאת חשבונות שירות ללקוחות, ו
  • מגדירים דף לניהול חשבונות שירות כדי שהלקוחות יוכלו להעניק לחשבונות השירות את התפקידים הנדרשים בניהול זהויות והרשאות גישה (IAM).

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

הקצאת חשבונות שירות

כדי להקצות את חשבונות השירות, צריך לפנות למהנדס השותף ולכלול את הפרטים הבאים:

  • שם השירות: מזהה מוצר ייחודי שמבדיל את המוצר שלכם ממוצרים אחרים. מומלץ להשתמש בשם השירות שיצרתם כשהוספתם את המוצר.

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

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

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

שילוב של דף ניהול חשבונות השירות במסוף של המוצר

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

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

צריך להוסיף לכתובת ה-URL שני פרמטרים:

  • ‫service-name: זהו שם השירות שסיפקתם למהנדס השותף.

  • ‫service-account-email: כתובת האימייל של חשבון השירות שיצרתם עבור הלקוח. לכל לקוח יש חשבון שירות ייחודי.

בדוגמה הבאה מוצגת כתובת URL עם הפרמטרים הנדרשים:

https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email

אפשר להוסיף פרמטרים נוספים בהתאם לצרכים של הלקוחות. לדוגמה:

https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email;single=true;redirect=https%3A%2F%2Fexample.com

הפרמטרים של כתובת ה-URL מציינים שהמוצר שלכם דורש גישה לפרויקט יחיד Google Cloud ושהלקוח יכול לחזור למסוף שלכם.

רשימה של פרמטרים של כתובות URL

זו רשימה של פרמטרים של כתובות URL שאפשר לשלוח לדף הניהול של חשבון השירות:

פרמטרתיאור
service-nameזהו שדה חובה. זהו שם השירות שסיפקתם למהנדס השותף.
service-account-emailזהו שדה חובה. זו כתובת האימייל של חשבון השירות שיצרתם עבור הלקוח.
singleאם הערך הוא true, המשמעות היא שהמוצר שלכם דורש גישה לפרויקט יחיד.
hints=project-id-1מגדירים את הפרויקט שאליו רוצים שלחשבון השירות תהיה גישה. כדי להפריד בין הפרויקטים, משתמשים בפסיקים.
filter=role1מגביל את התפקידים שניתנים לחשבון השירות לקבוצת משנה של התפקידים שסיפקתם למהנדס השותף. לא כוללים את roles/ כשמשתמשים במסנן.
redirectמספק קישור ללקוח כדי לחזור למסוף הניהול. כדי להשתמש בפרמטר הזה, צריך לרשום את שם הדומיין אצל מהנדס השותפים.
הקודם
שילוב האפליקציה
הבא
מעקב אחר צריכה שמשויכת למוצרים