אימות כפרויקט Apps Script באמצעות חשבונות שירות

במדריך הזה מוסבר איך לבצע אימות באמצעות חשבון שירות כשקוראים לממשקי API ב-Apps Script.

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

בסקירה הכללית על אימות של ממשקי Google Workspace API תוכלו לקרוא על יצירת פרטי גישה.

מתי כדאי להשתמש בחשבונות שירות ב-Apps Script

אלה כמה סיבות לשימוש באימות של חשבון שירות במקום בשיטות אימות אחרות, כמו ScriptApp.getOAuthToken():

• ביצועים טובים יותר עם ממשקי API ושירותים של Google Cloud: ממשקי API רבים של Google Cloud מיועדים לאימות של חשבונות שירות. חשבונות שירות יכולים גם לספק דרך משולבת, אמינה ומאובטחת יותר לאינטראקציה עם רוב ממשקי ה-API.
• הרשאות מנותקות: לחשבונות שירות יש הרשאות משלהם, נפרדות מההרשאות של משתמשים. שיטת האימות ScriptApp.getOAuthToken() עלולה להיכשל כשמשתפים את פרויקט Apps Script עם משתמשים אחרים. באמצעות חשבונות שירות, אתם יכולים לשתף סקריפטים ולפרסם אותם כתוספים ל-Google Workspace.
• סקריפטים אוטומטיים ומשימות שפועלות לאורך זמן: חשבונות שירות מאפשרים להריץ סקריפטים אוטומטיים, תהליכי אצווה או משימות ברקע ללא קלט מהמשתמש.
• אבטחה משופרת ועקרון ההרשאות המינימליות: אתם יכולים להעניק לחשבונות שירות הרשאות ספציפיות, וכך לתת גישה רק למשאבים שהם צריכים. הגישה הזו מבוססת על העיקרון של הרשאות מינימליות, וכך מצמצמת את סיכוני האבטחה. שימוש ב-ScriptApp.getOAuthToken() מעניק לרוב לסקריפט את כל הרשאות המשתמש, וזה יכול להיות רחב מדי.
• ניהול גישה מרכזי: חשבונות שירות מנוהלים באמצעות ניהול הזהויות והרשאות הגישה (IAM) של Google Cloud. ‫IAM יכול לעזור לארגונים ב-Google Workspace לנהל את הגישה לשירותים מאומתים בפרויקטים של Apps Script.

דרישות מוקדמות

• פרויקט ב-Google Cloud.
• בפרויקט ב-Cloud, מפעילים את כל ממשקי ה-API שרוצים לבצע אליהם אימות באמצעות פרטי כניסה של חשבון שירות.
• כדי להקצות תפקידים לחשבונות שירות, צריך הרשאות של סופר-אדמין.

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

יוצרים חשבון שירות בפרויקט Cloud:

מסוף Google Cloud

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. לוחצים על יצירת חשבון שירות.
3. ממלאים את פרטי חשבון השירות ולוחצים על יצירה והמשך.
   הערה: כברירת מחדל, Google יוצרת מזהה ייחודי לחשבון שירות. אם רוצים לשנות את המזהה, משנים אותו בשדה 'מזהה חשבון השירות'.
4. אופציונלי: מקצים תפקידים לחשבון השירות כדי לתת גישה למשאבים בפרויקט Google Cloud. פרטים נוספים זמינים במאמר הענקה, שינוי וביטול גישה למשאבים.
5. לוחצים על המשך.
6. אופציונלי: מזינים משתמשים או קבוצות שיכולים לנהל את חשבון השירות הזה ולבצע בו פעולות. פרטים נוספים מופיעים במאמר ניהול התחזות לחשבון שירות.
7. לוחצים על סיום. רושמים את כתובת האימייל של חשבון השירות.

CLI של gcloud

1. יוצרים את חשבון השירות:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

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

הקצאת תפקיד לחשבון שירות

צריך להקצות לחשבון שירות תפקיד מוגדר מראש או תפקיד בהתאמה אישית דרך חשבון סופר-אדמין.

1. במסוף Google Admin, נכנסים לתפריט > חשבון > תפקידי אדמין.

   מעבר אל תפקידי אדמין

2. מצביעים על התפקיד שרוצים להקצות ולוחצים על הקצאת אדמין.

3. לוחצים על בחירת חשבונות שירות לתפקיד.

4. מזינים את כתובת האימייל של חשבון השירות.

5. לוחצים על הוספה > הקצאת תפקיד.

יצירת פרטי כניסה לחשבון שירות

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

כדי לקבל פרטי כניסה לחשבון השירות:

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Service Accounts (חשבונות שירות).

   לדף Service accounts

2. בוחרים את חשבון השירות.
3. לוחצים על מפתחות > הוספת מפתח > יצירת מפתח חדש.
4. בוחרים באפשרות JSON ולוחצים על Create.

   זוג המפתחות הציבורי/הפרטי החדש נוצר ומורד למחשב שלכם כקובץ חדש. שומרים את קובץ ה-JSON שהורדתם בשם credentials.json בספריית העבודה. הקובץ הזה הוא העותק היחיד של המפתח. מידע על אחסון מאובטח של המפתח זמין במאמר ניהול מפתחות לחשבונות שירות.

5. לוחצים על סגירה.

מעתיקים את מספר הפרויקט ב-Cloud

1. במסוף Google Cloud, לוחצים על סמל התפריט > IAM & Admin > Settings (הגדרות).

   כניסה לדף IAM & Admin Settings

2. מעתיקים את הערך בשדה מספר הפרויקט.

הגדרת אימות של חשבון שירות בפרויקט Apps Script

בקטע הזה מוסבר איך להוסיף את פרטי הכניסה של חשבון השירות מפרויקט Cloud לפרויקט Apps Script.

הגדרת פרויקט Cloud ב-Apps Script

1. עוברים אל Apps Script כדי לפתוח או ליצור פרויקט:

   
   פתיחת Apps Script

2. בפרויקט Apps Script, לוחצים על הגדרות הפרויקט .

3. בקטע פרויקט Google Cloud Platform (GCP)‎, לוחצים על שינוי הפרויקט.

4. בקטע מספר הפרויקט ב-GCP, מדביקים את מספר הפרויקט ב-Google Cloud.

5. לוחצים על הגדרת פרויקט.

שמירת פרטי הכניסה כמאפיין סקריפט

כדי לאחסן את פרטי הכניסה של חשבון השירות בצורה מאובטחת, שומרים אותם כמאפיין סקריפט בהגדרות של פרויקט Apps Script:

1. מעתיקים את התוכן של קובץ ה-JSON של חשבון השירות (credentials.json) שיצרתם בקטע הקודם.
2. בפרויקט Apps Script, עוברים אל הגדרות הפרויקט .
3. בדף Project Settings (הגדרות הפרויקט), עוברים אל Script Properties (מאפייני הסקריפט), לוחצים על Add script property (הוספת מאפיין סקריפט) ומזינים את הפרטים הבאים:
   • בשדה מאפיין מזינים SERVICE_ACCOUNT_KEY.
   • בשדה Value (ערך), מדביקים את התוכן של קובץ מפתח ה-JSON.
4. לוחצים על שמירת מאפייני סקריפט.

הוספת ספריית OAuth2

כדי לטפל בתהליך האימות של OAuth2, אפשר להשתמש בספריית Apps Script‏ apps-script-oauth2.

כדי להוסיף את הספרייה לפרויקט Apps Script:

1. בצד ימין של עורך Apps Script, לצד ספריות, לוחצים על הוספת ספרייה .
2. בשדה Script ID (מזהה הסקריפט), מזינים את הערך 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF.
3. לוחצים על חיפוש.
4. בוחרים את הגרסה העדכנית ביותר ולוחצים על הוספה.

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

כדי להשתמש בפרטי הכניסה של חשבון השירות מפרויקט Apps Script, אפשר להשתמש בפונקציה הבאה getServiceAccountService():

/**
 * Get a new OAuth2 service for a given service account.
 */
function getServiceAccountService() {
  const serviceAccountKeyString = PropertiesService.getScriptProperties()
      .getProperty('SERVICE_ACCOUNT_KEY');

  if (!serviceAccountKeyString) {
    throw new Error('SERVICE_ACCOUNT_KEY property is not set. ' +
        'Please follow the setup instructions.');
  }

  const serviceAccountKey = JSON.parse(serviceAccountKeyString);

  const CLIENT_EMAIL = serviceAccountKey.client_email;
  const PRIVATE_KEY = serviceAccountKey.private_key;

  // Replace with the specific scopes required for your API.
  const SCOPES = ['SCOPE'];

  return OAuth2.createService('ServiceAccount')
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(PRIVATE_KEY)
      .setIssuer(CLIENT_EMAIL)
      .setPropertyStore(PropertiesService.getScriptProperties())
      .setScope(SCOPES);
}

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

אחר כך אפשר להשתמש בפרטי הכניסה האלה כדי לקרוא ל-API, כמו בדוגמה הבאה עם שירות UrlFetch:

function callApi() {
  const service = getServiceAccountService();

  // TODO(developer): Replace with the payload
  const payload = {};

  // TODO(developer): Replace with the API endpoint
  const response = UrlFetchApp.fetch('API_URL', {
    method: 'post',
    headers: {
      'Authorization': `Bearer ${service.getAccessToken()}`,
      'Content-Type': 'application/json',
    },
    payload: payload,
  });

  const result = JSON.parse(response.getContentText());

  return result;
}

מחליפים את API_URL בנקודת הקצה (endpoint) של HTTP שאליה מתבצעת הקריאה.

נושאים קשורים

• יצירת פרטי גישה
• אימות כאפליקציית Google Chat