חיבור תוסף Google Workspace לשירות צד שלישי

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

בדף זה מוסבר איך לאמת משתמשים באמצעות תהליך הרשאה (כמו OAuth), שכולל את השלבים הבאים:

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

אם לתוסף נדרשת רק זהות המשתמש, תוכלו לאמת משתמשים ישירות באמצעות מזהה Google Workspace או כתובת האימייל שלהם. במאמר אימות בקשות JSON מוסבר איך משתמשים בכתובת האימייל לאימות. אם יצרתם את התוסף באמצעות Google Apps Script, כדאי לקרוא את התיעוד של Apps Script כדי ללמוד איך לחבר את התוסף לשירות של צד שלישי.

בודקים שנדרשת הרשאה

בזמן השימוש בתוסף, יכול להיות שהמשתמשים לא יקבלו הרשאת גישה למשאב מוגן מסיבות שונות, למשל:

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

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

בקשה מהמשתמשים להיכנס לשירות

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

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

חשוב תמיד לאמת את התקינות של האסימון לפני קבלת מזהה המשתמש המאושר.

יצירה והחזרה של כרטיס כניסה

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

כרטיס הרשאה בסיסי

בתמונה הבאה מוצגת דוגמה לכרטיס ההרשאה הבסיסי של Google:

כדי להשתמש בכרטיס ההרשאה הבסיסי, צריך להחזיר את תגובת ה-JSON הבאה:

{
  "basic_authorization_prompt": {
    "authorization_url": "AUTHORIZATION_REDIRECT",
    "resource": "RESOURCE_DISPLAY_NAME"
  }
}

מחליפים את מה שכתוב בשדות הבאים:

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

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

כרטיס הרשאה בהתאמה אישית

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

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

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

כדי להשתמש בדוגמה הזו של כרטיס מותאם אישית, צריך להחזיר את תגובת ה-JSON הבאה:

{
  "custom_authorization_prompt": {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "sections": [
              {
                "widgets": [
                  {
                    "image": {
                      "imageUrl": "LOGO_URL",
                      "altText": "LOGO_ALT_TEXT"
                    }
                  },
                  {
                    "divider": {}
                  },
                  {
                    "textParagraph": {
                      "text": "DESCRIPTION"
                    }
                  },
                  {
                    "buttonList": {
                      "buttons": [
                        {
                          "text": "Sign in",
                          "onClick": {
                            "openLink": {
                              "url": "AUTHORIZATION_REDIRECT",
                              "onClose": "RELOAD",
                              "openAs": "OVERLAY"
                            }
                          },
                          "color": {
                            "red": 0,
                            "green": 0,
                            "blue": 1,
                            "alpha": 1,
                          }
                        }
                      ]
                    }
                  },
                  {
                    "textParagraph": {
                      "text": "TEXT_SIGN_UP"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

מחליפים את מה שכתוב בשדות הבאים:

• LOGO_URL: כתובת ה-URL של לוגו או תמונה. חייבת להיות כתובת אתר ציבורית.
• LOGO_ALT_TEXT: טקסט חלופי ללוגו או לתמונה, למשל Cymbal Labs Logo.
• DESCRIPTION: קריאה לפעולה למשתמשים להיכנס לחשבון, למשל Sign in to get started.
• כדי לעדכן את לחצן הכניסה:
  • AUTHORIZATION_REDIRECT: כתובת ה-URL של אפליקציית האינטרנט שמטפלת בהרשאה.
  • אופציונלי: כדי לשנות את צבע הלחצן, מעדכנים את הערכים הצפים של ה-RGBA בשדה color.
• TEXT_SIGN_UP: טקסט עם בקשה ליצור חשבון אם אין להם חשבון. לדוגמה, New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here.